Start documenting the new shader loading process

1_21_2_model.md

@@ -0,0 +1,87 @@
+# Minecraft Shader Loading
+
+`ShaderLoader` loads every file in the `shaders` directory
+ending in `.json`, `.fsh`, `.vsh`, or `.glsl`
+
+- `.glsl` extensions are exclusively used for common shader includes
+- `.fsh` and `.vsh` files are loaded as strings and compiled later
+- `.json` files are loaded as `ShaderProgramDefinition`
+
+```mermaid
+---
+title: Shader data classes
+---
+classDiagram
+    ShaderLoader --> Definitions
+    Definitions "1" *-- "*" ShaderProgramDefinition
+    Definitions "1" *-- "*" PostEffectPipeline
+    Definitions : +string[id] shaderSources
+    ShaderProgramDefinition : +id vertex
+    ShaderProgramDefinition : +id fragment
+    ShaderProgramDefinition "1" *-- "1" Defines
+    ShaderProgramDefinition "1" *-- "1..*" Sampler
+    ShaderProgramDefinition "1" *-- "*" Uniform
+    Defines : +values
+    Defines : +flags
+    Sampler : +string name
+    Uniform : +string name
+    Uniform : +string type
+    Uniform : +int count
+    Uniform : +float[] values
+    PostEffectPipeline "1" *-- "1..*" Target
+    PostEffectPipeline "1" *-- "1..*" Pass
+    Target <|-- CustomSized
+    Target <|-- ScreenSized
+    Target : ~id
+    Pass : ~id
+    Pass : +id program
+    Pass : +id output
+    Pass "1" *-- "1..*" Input
+    Pass "1" *-- "1..*" UniformValues
+    Input : +string samplerName
+    Input <|-- TargetSampler
+    Input <|-- TextureSampler
+    TargetSampler : +bool useDepthBuffer
+    TargetSampler : +bool bilinear
+    TextureSampler : +id location
+    TextureSampler : +int width
+    TextureSampler : +int height
+    TextureSampler : +bool bilinear
+    UniformValues : +string name
+    UniformValues : +float[] values
+    TargetSampler ..> Target : "targetId"
+```
+
+Core shaders are referenced in `ShaderProgramKeys.ALL`. These shaders are all
+preloaded in the `ShaderLoader`'s `apply` stage, at which point any failure causes a crash.
+
+Post-process effects (also called "post chains") are loaded lazily.
+
+```mermaid
+---
+title: Shader Live Objects
+---
+classDiagram
+    Cache o-- CompiledShader
+    Cache o-- ShaderProgram
+    Cache o-- PostEffectProcessor
+    ShaderProgram ..> CompiledShader : "created using"
+    PostEffectProcessor *-- PostEffectPass
+    PostEffectProcessor "1" *-- "1..*" Target
+    Target : ~id
+    Target <|-- CustomSized
+    Target <|-- ScreenSized
+    PostEffectPass : +id id
+    PostEffectPass --> ShaderProgram
+    PostEffectPass ..> Target : "outputTargetId"
+    PostEffectPass "1" *-- "1..*" Sampler
+    Sampler: +string samplerName
+    Sampler <|-- TextureSampler
+    Sampler <|-- TargetSampler
+    TargetSampler : +bool depthBuffer
+    TargetSampler : +bool bilinear
+    TargetSampler ..> Target : "targetId"
+    TextureSampler : +texture
+    TextureSampler : +int width
+    TextureSampler : +int height
+```

changelog.md

@@ -1,3 +1,16 @@
+------------------------------------------------------
+Version 3.0.0
+------------------------------------------------------
+Updated to MC 1.21.2
+
+**Changes**
+- Post process shaders are now loaded from `post_effect` and `shaders`
+  instead of respectively `shaders/post` and `shaders/program`.
+  By convention, files previously in `shaders/program` should go to the `shaders/post` subdirectory.
+- Includes (loaded from `shaders/include`) are now available in post process shaders
+- Post-process effect format has changed:
+  - `inputs` take a `sampler_name`, which will be suffixed with "Sampler" (e.g. `"sampler_name": "In"` becomes `"name": "InSampler"` in the shader definition)
+
 ------------------------------------------------------
 Version 2.0.0
 ------------------------------------------------------

src/main/java/org/ladysnake/satin/impl/ResettableManagedCoreShader.java

@@ -68,6 +68,11 @@ public void setup(int newWidth, int newHeight) {
         this.initCallback.accept(this);
     }
 
+    @Override
+    protected void doRelease(ShaderProgram shader) {
+        shader.close();
+    }
+
     @Override
     public ShaderProgram getProgram() {
         return this.shader;

src/main/java/org/ladysnake/satin/impl/ResettableManagedShaderBase.java

@@ -44,7 +44,7 @@
 
 import static org.apiguardian.api.API.Status.INTERNAL;
 
-public abstract class ResettableManagedShaderBase<S extends AutoCloseable> implements UniformFinder {
+public abstract class ResettableManagedShaderBase<S> implements UniformFinder {
     /**Location of the shader json definition file*/
     private final Identifier location;
     private final Map<String, ManagedUniform> managedUniforms = new HashMap<>();
@@ -82,7 +82,7 @@ public void release() {
         if (this.isInitialized()) {
             try {
                 assert this.shader != null;
-                this.shader.close();
+                this.doRelease(shader);
                 this.shader = null;
             } catch (Exception e) {
                 throw new RuntimeException("Failed to release shader " + this.location, e);
@@ -91,6 +91,8 @@ public void release() {
         this.errored = false;
     }
 
+    protected abstract void doRelease(S shader);
+
     protected Collection<ManagedUniformBase> getManagedUniforms() {
         return this.allUniforms;
     }