From configuration to a frame
A shader pack must answer two kinds of questions: how GLSL computes color, and when those computations run, what they read and where they write. JSON describes the latter and connects shader programs through executable resource and command relationships.
Five core concepts
| Concept | Role | What to look for in configuration |
|---|---|---|
| Phase | Identifies an execution point provided by the host | Which scene phase does this work belong to? |
| Pass | Declares work together with its Stage, programs and commands | What are its dependencies, conditions and execution position? |
| Command | Describes an operation | Does it draw geometry, draw fullscreen, dispatch compute, copy or clear? |
| Program | Specifies shader entry points and compilation settings | Which GLSL files and compilation modes does it use? |
| Resource | Declares storage that operations can read or write | What are its format, size, lifetime and producer? |
A Provider supplies host geometry submission or another public capability. A Service handles the corresponding host service and state. Their IDs and versions come from the current Catalog; inventing a string with a similar name does not create a new capability.
From declarations to execution
Read a pack along this path:
Manifest and composition files
↓ Loading, reference resolution and semantic checks
Dependencies between resources / Programs / Passes / Commands
↓ Build a candidate generation
Invoke Stages and commands at host execution points
↓
Read resources → run shaders or host operations → write targetsResource and program declarations provide objects to reference; commands determine how to use them. The same Program can serve different call configurations. Configuration must also describe the read and write relationships explicitly.
Within a dawnlight:command_list@1 Stage, commands execute in Manifest order. Dependencies between Passes, read/write hazards and phase direction still require loading and graph analysis. The order of one text block is not a universal scheduling rule for every stage.
Seven generic command types
type | Operation | program rule |
|---|---|---|
fullscreen | Draw fullscreen to a named target | Required |
compute | Dispatch compute and declare barriers | Required |
copy | Copy framebuffer resources | Not allowed |
clear | Clear a named target or the default framebuffer | Not allowed |
present | Draw the final fullscreen output to the default framebuffer | Required |
engineDraw | Invoke a host geometry Provider | Optional |
historyCommit | Mark a History resource as complete for the frame | Not allowed |
Commands without a Program still participate in resource or ordering analysis. For example, copy needs an actual source read and destination write. historyCommit is a lifecycle event; it cannot stand in for a texture write.
Source: Generic Command contracts and History constraints · f8aaa5c4
How JSON, GLSL and the host work together
Suppose you want to apply color grading to a rendered scene:
- A resource stores scene color; configuration determines its size, format and lifetime.
- A Program references a fullscreen vertex shader and a color-grading fragment shader.
- A Command binds scene color to a shader input and selects the output target.
- GLSL samples the input and computes a new color.
- The host schedules the work at the appropriate execution point and manages graphics resources and state.
This explanation establishes responsibilities. A valid complete external pack must also handle host scene takeover, whole-frame targets and fallback paths. Having a post-processing shader alone does not establish a complete scene setup.
Where to start when reading a pack
Find scene color and depth in the resource list, then find the commands that produce them. Follow the post-processing chain to the final output. Check the input ID, target, format and lifetime at each connection.
If you cannot find a producer, check the current enable conditions and BuiltIn fallback, then use Analyzer to explain the active graph. Continue with Resources, targets and drawBuffers to separate the different parts of choosing an output destination.