Skip to content

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 ​

ConceptRoleWhat to look for in configuration
PhaseIdentifies an execution point provided by the hostWhich scene phase does this work belong to?
PassDeclares work together with its Stage, programs and commandsWhat are its dependencies, conditions and execution position?
CommandDescribes an operationDoes it draw geometry, draw fullscreen, dispatch compute, copy or clear?
ProgramSpecifies shader entry points and compilation settingsWhich GLSL files and compilation modes does it use?
ResourceDeclares storage that operations can read or writeWhat 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:

text
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 targets

Resource 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 ​

typeOperationprogram rule
fullscreenDraw fullscreen to a named targetRequired
computeDispatch compute and declare barriersRequired
copyCopy framebuffer resourcesNot allowed
clearClear a named target or the default framebufferNot allowed
presentDraw the final fullscreen output to the default framebufferRequired
engineDrawInvoke a host geometry ProviderOptional
historyCommitMark a History resource as complete for the frameNot 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:

  1. A resource stores scene color; configuration determines its size, format and lifetime.
  2. A Program references a fullscreen vertex shader and a color-grading fragment shader.
  3. A Command binds scene color to a shader input and selects the output target.
  4. GLSL samples the input and computes a new color.
  5. 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.

Author documentation · Manifest v5 / Scene ABI v2