Skip to content

05 · Options and settings ​

Make grading genuinely optional and expose its strength in settings. Prerequisites: chapter 04 target topology, chapter 02 producers/readers and chapter 03 Terrain routes. Explain how one switch changes the active Program, resource and command closure.

Changes and complete download ​

Continue from the chapter 03 color pipeline. Remove chapter 04’s RT1/RT2 teaching attachments: frameTarget and opaque return to RT0 + depth. Keep the complete Terrain vertex declaration. Add settings.json, a grade switch, a strength define and two mutually exclusive present Passes. The previous ZIP is useful for comparison; this ZIP is self-contained.

Previous chapter download · This complete ZIP, source inventory and receipt

Resource flow ​

Terrain + world → scene/color + scene/depth → [grade=true: grade → post/color → present-grade] / [grade=false: present-raw] → screen

course:grade declares pipeline/resources impact. grade and present-grade require grade=true; present-raw requires false. Disabling only the producer while keeping present reading post/color would leave an unwritten resource. Ordering belongs to the matching chain; the disabled branch has no dependency on grade.

course:strength is a number in 0–1 with program impact, injected through defines.GRADE_STRENGTH. float(GRADE_STRENGTH) accepts the endpoint compilation literals. A compile-time constant requires recompilation; the next chapter supplies a data-driven uniform. Impact describes invalidation, without promising a particular update cost.

Press U, choose Options, and edit the authored Amber course page. Settings UI presents Manifest options: exactly one control per option, without changing its type, hard bounds or default. The strength slider uses UI enabledWhen to disable editing while grading is off. This is separate from rendering conditions. Apply the settings and wait for frame-boundary publication; check failures while retaining the previous valid generation.

Active branch matrix ​

Source and freshly extracted ZIP agree for every row. Counts include only active nodes; resources include the material buffer where present.

VariantOverridesResourcesCommands
default{}36
grade-off{"course:grade":false}25
strength-max{"course:strength":1}36
Exact active closure

default

resource:course:post/color, resource:course:scene/color, resource:course:scene/depth

command:course:grade:0, command:course:present-grade:0, command:course:terrain_alpha_tested:0, command:course:terrain_opaque:0, command:course:terrain_sorted_translucent:0, command:course:terrain_transparent:0

program:course:post/grade, program:course:post/present, program:course:scene/terrain, program:dawnlight:scene_fallback/terrain_alpha_tested, program:dawnlight:scene_fallback/terrain_sorted_translucent, program:dawnlight:scene_fallback/terrain_transparent

Active services: 0

grade-off

resource:course:scene/color, resource:course:scene/depth

command:course:present-raw:0, command:course:terrain_alpha_tested:0, command:course:terrain_opaque:0, command:course:terrain_sorted_translucent:0, command:course:terrain_transparent:0

program:course:post/present, program:course:scene/terrain, program:dawnlight:scene_fallback/terrain_alpha_tested, program:dawnlight:scene_fallback/terrain_sorted_translucent, program:dawnlight:scene_fallback/terrain_transparent

Active services: 0

strength-max

resource:course:post/color, resource:course:scene/color, resource:course:scene/depth

command:course:grade:0, command:course:present-grade:0, command:course:terrain_alpha_tested:0, command:course:terrain_opaque:0, command:course:terrain_sorted_translucent:0, command:course:terrain_transparent:0

program:course:post/grade, program:course:post/present, program:course:scene/terrain, program:dawnlight:scene_fallback/terrain_alpha_tested, program:dawnlight:scene_fallback/terrain_sorted_translucent, program:dawnlight:scene_fallback/terrain_transparent

Active services: 0

Complete shader sources ​

shaders/fullscreen.vsh
glsl
#version 320 es
precision highp float;
out vec2 v_uv;
void main() {
    const vec2 corners[4] = vec2[4](vec2(-1.0, -1.0), vec2(1.0, -1.0), vec2(-1.0, 1.0), vec2(1.0, 1.0));
    vec2 position = corners[gl_VertexID & 3];
    v_uv = position * 0.5 + 0.5;
    gl_Position = vec4(position, 0.0, 1.0);
}
shaders/grade.psh
glsl
#version 320 es
precision highp float;
uniform sampler2D u_sceneColor;
in vec2 v_uv;
layout(location = 0) out vec4 o_color;
void main() {
    vec3 source = texture(u_sceneColor, v_uv).rgb;
    vec3 amber = (source - 0.5) * 1.06 + 0.5;
    amber *= vec3(1.06, 1.0, 0.93);
    o_color = vec4(clamp(mix(source, amber, float(GRADE_STRENGTH)), 0.0, 1.0), 1.0);
}
shaders/present.psh
glsl
#version 320 es
precision highp float;
uniform sampler2D u_postColor;
in vec2 v_uv;
layout(location = 0) out vec4 o_color;
void main() {
    o_color = texture(u_postColor, v_uv);
}
shaders/terrain.psh
glsl
#version 320 es
// <Sampler Name='u_samplerState' Texture='u_texture' />
precision highp float;
precision highp int;
uniform sampler2D u_texture;
in vec2 v_texcoord;
in vec4 v_color;
layout(location = 0) out vec4 o_sceneColor;
void main() {
    vec4 albedo = texture(u_texture, v_texcoord) * v_color;
    o_sceneColor = vec4(albedo.rgb * vec3(0.92, 1.0, 0.92), albedo.a);
}
shaders/terrain.vsh
glsl
#version 320 es
// <Semantic Name='TEXCOORD' Attribute='a_texcoord' />
// <Semantic Name='POSITION' Attribute='a_position' />
// <Semantic Name='COLOR' Attribute='a_color' />
// <Semantic Name='IDENTIFIER' Attribute='a_identifier' />
// <Semantic Name='NORMAL' Attribute='a_normal' />
// <Semantic Name='LIGHTLEVEL' Attribute='a_lightLevel' />
// <Semantic Name='PURELIGHT' Attribute='a_pureLight' />
// <Semantic Name='HEIGHTDATA' Attribute='a_heightData' />
uniform mat4 u_viewProjectionMatrix;
uniform vec2 u_origin;
uniform float u_lightTable[96];
layout(location = 0) in vec2 a_texcoord;
layout(location = 1) in vec3 a_position;
layout(location = 2) in vec4 a_color;
layout(location = 3) in uint a_identifier;
layout(location = 4) in vec3 a_normal;
layout(location = 5) in float a_lightLevel;
layout(location = 6) in float a_pureLight;
layout(location = 7) in float a_heightData;
out vec2 v_texcoord;
out vec4 v_color;
out vec3 v_normalEncoded;
flat out highp uint v_identifier;
void main() {
    int lightIndex = clamp(int(a_lightLevel) - 1, 0, 95);
    float light = clamp(u_lightTable[lightIndex], 0.0, 1.0);
    v_texcoord = a_texcoord;
    v_color = vec4(a_color.rgb * light, a_color.a);
    v_normalEncoded = clamp(a_normal / 255.0, 0.0, 1.0);
    v_identifier = a_identifier;
    vec3 relativePosition = vec3(a_position.x - u_origin.x, a_position.y, a_position.z - u_origin.y);
    gl_Position = u_viewProjectionMatrix * vec4(relativePosition, 1.0);
    OPENGL_POSITION_FIX;
}

Complete Manifest and settings ​

settings.json
json
{
  "schemaVersion": 1,
  "defaultLocale": "en-US",
  "translations": {
    "zh-CN": {
      "page.amber": "琥珀课程",
      "course:grade": "调色",
      "course:strength": "调色强度(重新编译)"
    },
    "en-US": {
      "page.amber": "Amber course",
      "course:grade": "Color grade",
      "course:strength": "Grade strength (recompile)"
    }
  },
  "pages": [
    {
      "id": "amber",
      "title": "page.amber",
      "groups": [
        {
          "id": "look",
          "controls": [
            {
              "id": "grade",
              "option": "course:grade",
              "widget": "toggle",
              "label": "course:grade"
            },
            {
              "id": "strength",
              "option": "course:strength",
              "widget": "slider",
              "label": "course:strength",
              "min": 0,
              "max": 1,
              "step": 0.05,
              "format": "0.00",
              "enabledWhen": [
                {
                  "option": "course:grade",
                  "equals": true
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}
shaderpack.json
json
{
  "manifestVersion": 5,
  "sceneAbiVersion": 2,
  "expectedCatalogSha256": "4bc28c17beffea2311a422fff9f633d2e4f03784460d0254adda8af2e766d84c",
  "id": "course:05-options",
  "name": "Dawnlight Course · Amber 05-options",
  "version": "1.0.0",
  "author": "EltanceX",
  "description": "Website-authored Amber course snapshot; see README for tested scope.",
  "shaderRoot": "shaders",
  "options": [
    {
      "id": "course:grade",
      "type": "boolean",
      "default": true,
      "impact": [
        "pipeline",
        "resources"
      ]
    },
    {
      "id": "course:strength",
      "type": "number",
      "default": 0.65,
      "min": 0,
      "max": 1,
      "impact": [
        "program"
      ]
    }
  ],
  "resources": [
    {
      "id": "course:scene/color",
      "kind": "texture2D",
      "lifetime": "persistent",
      "size": {
        "mode": "viewport"
      },
      "format": "rgba8"
    },
    {
      "id": "course:scene/depth",
      "kind": "texture2D",
      "lifetime": "persistent",
      "size": {
        "mode": "viewport"
      },
      "format": "depth24"
    },
    {
      "id": "course:post/color",
      "kind": "texture2D",
      "lifetime": "persistent",
      "size": {
        "mode": "viewport"
      },
      "format": "rgba8"
    }
  ],
  "programs": [
    {
      "id": "course:scene/terrain",
      "kind": "graphics",
      "vertex": "terrain.vsh",
      "fragment": "terrain.psh",
      "compileMode": "officialCompatible"
    },
    {
      "id": "course:post/grade",
      "kind": "graphics",
      "vertex": "fullscreen.vsh",
      "fragment": "grade.psh",
      "compileMode": "manifestDriven",
      "defines": {
        "GRADE_STRENGTH": {
          "option": "course:strength"
        }
      }
    },
    {
      "id": "course:post/present",
      "kind": "graphics",
      "vertex": "fullscreen.vsh",
      "fragment": "present.psh",
      "compileMode": "manifestDriven"
    }
  ],
  "frameTarget": {
    "targets": {
      "colors": [
        {
          "location": 0,
          "resource": "course:scene/color",
          "loadOp": "clear",
          "storeOp": "store",
          "clearValue": [
            0,
            0,
            0,
            1
          ]
        }
      ],
      "depth": {
        "resource": "course:scene/depth",
        "loadOp": "clear",
        "storeOp": "store",
        "clearValue": 1
      }
    }
  },
  "passes": [
    {
      "id": "course:terrain_opaque",
      "enabled": true,
      "stage": {
        "template": "dawnlight:command_list",
        "version": 1,
        "target": "world",
        "phase": "opaque"
      },
      "services": [],
      "programs": [
        "course:scene/terrain"
      ],
      "commands": [
        {
          "type": "engineDraw",
          "sceneProvider": {
            "id": "dawnlight:scene_draw/terrain_opaque",
            "version": 2
          },
          "targets": {
            "colors": [
              {
                "location": 0,
                "resource": "course:scene/color",
                "loadOp": "load",
                "storeOp": "store"
              }
            ],
            "depth": {
              "resource": "course:scene/depth",
              "loadOp": "clear",
              "storeOp": "store",
              "clearValue": 1
            }
          },
          "state": {
            "blend": "opaque",
            "depth": "default",
            "rasterizer": "cullCounterClockwiseScissor"
          },
          "viewport": {
            "source": "target",
            "restore": "frame",
            "synchronizeScissor": true
          },
          "program": "course:scene/terrain",
          "sceneBindings": [
            {
              "symbol": "u_viewProjectionMatrix",
              "contract": "dawnlight:scene_binding/view_projection",
              "version": 1,
              "frequency": "view"
            },
            {
              "symbol": "u_origin",
              "contract": "dawnlight:scene_binding/terrain_origin",
              "version": 1,
              "frequency": "view"
            },
            {
              "symbol": "u_lightTable",
              "contract": "dawnlight:scene_binding/light_table",
              "version": 1,
              "frequency": "batch"
            },
            {
              "symbol": "u_texture",
              "contract": "dawnlight:scene_binding/block_texture",
              "version": 1,
              "frequency": "draw",
              "binding": 0
            }
          ]
        }
      ],
      "inputs": [
        "course:scene/color",
        "course:scene/depth"
      ],
      "outputs": [
        "course:scene/color",
        "course:scene/depth"
      ]
    },
    {
      "id": "course:terrain_alpha_tested",
      "enabled": true,
      "stage": {
        "template": "dawnlight:command_list",
        "version": 1,
        "target": "world",
        "phase": "opaque",
        "ordering": {
          "after": [
            "course:terrain_opaque"
          ]
        }
      },
      "services": [],
      "programs": [],
      "commands": [
        {
          "type": "engineDraw",
          "sceneProvider": {
            "id": "dawnlight:scene_draw/terrain_alpha_tested",
            "version": 2
          },
          "targets": {
            "colors": [
              {
                "location": 0,
                "resource": "course:scene/color",
                "loadOp": "load",
                "storeOp": "store"
              }
            ],
            "depth": {
              "resource": "course:scene/depth",
              "loadOp": "load",
              "storeOp": "store"
            }
          },
          "state": {
            "blend": "opaque",
            "depth": "default",
            "rasterizer": "cullCounterClockwiseScissor"
          },
          "viewport": {
            "source": "target",
            "restore": "frame",
            "synchronizeScissor": true
          }
        }
      ],
      "inputs": [
        "course:scene/color",
        "course:scene/depth"
      ],
      "outputs": [
        "course:scene/color",
        "course:scene/depth"
      ]
    },
    {
      "id": "course:terrain_transparent",
      "enabled": true,
      "stage": {
        "template": "dawnlight:command_list",
        "version": 1,
        "target": "world",
        "phase": "transparent"
      },
      "services": [],
      "programs": [],
      "commands": [
        {
          "type": "engineDraw",
          "sceneProvider": {
            "id": "dawnlight:scene_draw/terrain_transparent",
            "version": 2
          },
          "targets": {
            "colors": [
              {
                "location": 0,
                "resource": "course:scene/color",
                "loadOp": "load",
                "storeOp": "store"
              }
            ],
            "depth": {
              "resource": "course:scene/depth",
              "loadOp": "load",
              "storeOp": "store"
            }
          },
          "state": {
            "blend": "alphaBlend",
            "depth": "default",
            "rasterizer": "cullCounterClockwiseScissor"
          },
          "viewport": {
            "source": "target",
            "restore": "frame",
            "synchronizeScissor": true
          }
        }
      ],
      "inputs": [
        "course:scene/color",
        "course:scene/depth"
      ],
      "outputs": [
        "course:scene/color",
        "course:scene/depth"
      ]
    },
    {
      "id": "course:terrain_sorted_translucent",
      "enabled": true,
      "stage": {
        "template": "dawnlight:command_list",
        "version": 1,
        "target": "world",
        "phase": "transparent",
        "ordering": {
          "after": [
            "course:terrain_transparent"
          ]
        }
      },
      "services": [],
      "programs": [],
      "commands": [
        {
          "type": "engineDraw",
          "sceneProvider": {
            "id": "dawnlight:scene_draw/terrain_sorted_translucent",
            "version": 2
          },
          "targets": {
            "colors": [
              {
                "location": 0,
                "resource": "course:scene/color",
                "loadOp": "load",
                "storeOp": "store"
              }
            ],
            "depth": {
              "resource": "course:scene/depth",
              "loadOp": "load",
              "storeOp": "store"
            }
          },
          "state": {
            "blend": "alphaBlend",
            "depth": "default",
            "rasterizer": "cullCounterClockwiseScissor"
          },
          "viewport": {
            "source": "target",
            "restore": "frame",
            "synchronizeScissor": true
          }
        }
      ],
      "inputs": [
        "course:scene/color",
        "course:scene/depth"
      ],
      "outputs": [
        "course:scene/color",
        "course:scene/depth"
      ]
    },
    {
      "id": "course:grade",
      "enabled": true,
      "stage": {
        "template": "dawnlight:command_list",
        "version": 1,
        "target": "afterDraw",
        "phase": "afterDraw"
      },
      "services": [],
      "programs": [
        "course:post/grade"
      ],
      "commands": [
        {
          "type": "fullscreen",
          "program": "course:post/grade",
          "bindings": [
            {
              "kind": "sampler2D",
              "symbol": "u_sceneColor",
              "binding": 0,
              "resource": "course:scene/color"
            }
          ],
          "state": {
            "blend": "opaque",
            "depth": "disabled",
            "rasterizer": "cullNoneScissor"
          },
          "viewport": {
            "source": "target",
            "restore": "frame",
            "synchronizeScissor": true
          },
          "targets": {
            "colors": [
              {
                "location": 0,
                "resource": "course:post/color",
                "loadOp": "dontCare",
                "storeOp": "store"
              }
            ]
          }
        }
      ],
      "inputs": [
        "course:scene/color"
      ],
      "outputs": [
        "course:post/color"
      ],
      "enabledWhen": [
        {
          "option": "course:grade",
          "equals": true
        }
      ]
    },
    {
      "id": "course:present-grade",
      "enabled": true,
      "stage": {
        "template": "dawnlight:command_list",
        "version": 1,
        "target": "afterDraw",
        "phase": "screenOutput",
        "ordering": {
          "after": [
            "course:grade"
          ]
        }
      },
      "services": [],
      "programs": [
        "course:post/present"
      ],
      "commands": [
        {
          "type": "present",
          "program": "course:post/present",
          "bindings": [
            {
              "kind": "sampler2D",
              "symbol": "u_postColor",
              "binding": 0,
              "resource": "course:post/color"
            }
          ],
          "state": {
            "blend": "opaque",
            "depth": "disabled",
            "rasterizer": "cullNoneScissor"
          },
          "viewport": {
            "source": "frame",
            "restore": "none",
            "synchronizeScissor": true
          }
        }
      ],
      "inputs": [
        "course:post/color"
      ],
      "outputs": [],
      "enabledWhen": [
        {
          "option": "course:grade",
          "equals": true
        }
      ]
    },
    {
      "id": "course:present-raw",
      "enabled": true,
      "stage": {
        "template": "dawnlight:command_list",
        "version": 1,
        "target": "afterDraw",
        "phase": "screenOutput"
      },
      "services": [],
      "programs": [
        "course:post/present"
      ],
      "commands": [
        {
          "type": "present",
          "program": "course:post/present",
          "bindings": [
            {
              "kind": "sampler2D",
              "symbol": "u_postColor",
              "binding": 0,
              "resource": "course:scene/color"
            }
          ],
          "state": {
            "blend": "opaque",
            "depth": "disabled",
            "rasterizer": "cullNoneScissor"
          },
          "viewport": {
            "source": "frame",
            "restore": "none",
            "synchronizeScissor": true
          }
        }
      ],
      "inputs": [
        "course:scene/color"
      ],
      "outputs": [],
      "enabledWhen": [
        {
          "option": "course:grade",
          "equals": false
        }
      ]
    }
  ],
  "sceneCategories": [
    {
      "id": "dawnlight:scene/terrain_opaque",
      "version": 1,
      "mode": "override",
      "stage": "course:terrain_opaque"
    },
    {
      "id": "dawnlight:scene/terrain_alpha_tested",
      "version": 1,
      "mode": "builtin"
    },
    {
      "id": "dawnlight:scene/terrain_transparent",
      "version": 1,
      "mode": "builtin"
    },
    {
      "id": "dawnlight:scene/terrain_sorted_translucent",
      "version": 1,
      "mode": "builtin"
    }
  ],
  "settings": "settings.json"
}

Validation and game observations ​

Extract into a new direct child of shaderpacks. From that pack root, use the pinned Analyzer installed in environment setup. Zero diagnostics and exit code 0 are expected. With materials but no world snapshot, deferred mapping is expected. Apply the settings inside a creative world, reload, resize and restore BuiltIn.

powershell
$analyzer = "C:\Tools\Dawnlight\shaderpack-analyzer.exe"
& $analyzer pack validate . --format json
& $analyzer scene explain . --include-inactive --format json
& $analyzer graph dump . --contract 2 --include-inactive
& $analyzer program interface . --program course:scene/terrain --contract 2
& $analyzer program interface . --program course:post/grade --contract 2
& $analyzer program interface . --program course:post/present --contract 2
& $analyzer data explain . --format json

These graph CLI commands check defaults. The committed branch receipt uses JSON-RPC with explicit inputs.options; see the branch table and maintenance procedure.

Actual game observations · W6

Observed 3 option branches, loading/switching, same-pack reload, actual window resizing and return to BuiltIn in the isolated creative world. Programs linked and framebuffers were complete. This chapter declares no custom data.

9b79e19737d998178227184552c9221bf12b05fa1b27f9d551519cfbf7293770

Branch and lifecycle evidence summary

Actual game window with defaults; title bar cropped and image resized. This image is not performance or numeric evidence.

Host, method and unverified scopes →

Troubleshooting ​

Black output after disabling: check that present-raw binds and declares scene/color. Exactly one present must be active. An unchanged slider result calls for Apply and a check of the define option ID and impact. UI enabledWhen cannot replace a Pass condition.

Exercise ​

Apply grade=false/true and strength=0.0/1.0. Predict the resource count before checking the branch table. In a copy, deliberately point present-raw at post/color, observe validation failure and restore it. Explain why a declared resource is different from an active allocation.

options · settings-ui · programs

Next chapter: 06 · Time, weather and custom data

Author documentation · Manifest v5 / Scene ABI v2