Shader Variants

Real-world engines need to support thousands of shader permutations (e.g., “Shadows On/Off”, “Skinning On/Off”). EntropyPortal manages this via the ShaderVariantSet.

Concepts

Keywords

A Keyword is a toggle (boolean) or enumeration that affects code generation.

• Example: ENABLE_SHADOWS, USE_NORMAL_MAP.
• Defined in C++ code and mapped to preprocessor defines in Slang.

Keyword Definition

Keywords are defined using standard #pragma directives, similar to other engines:

// Defines a keyword that is either defined or not (boolean)
#pragma multi_compile _ ENABLE_SHADOWS

// Defines an enumeration of mutually exclusive keywords
#pragma multi_compile _ QUALITY_LOW QUALITY_MEDIUM QUALITY_HIGH

• _ (underscore) represents the default variant (no keyword active).
• Multi-Compile: All permutations are compiled.
• Shader Feature: Only used permutations are compiled (useful for material keywords).

Variant Set

A ShaderVariantSet represents a single .slang file and all its possible permutations.

• Storage: Internally manages a cache of compiled GpuShader objects, keyed by a bitmask of active keywords.
• Warmup: Can asynchronously compile all valid permutations at load time to prevent hitching.

Async Pipeline Creation

To prevent “stutter” when a new variant is needed: 3. Completion: On a future frame, processPendingShaders() finalizes the pipeline, and the renderer automatically switches to the correct shader.

graph TD
    Req[Request Pipeline] --> Cache{In Cache?}
    Cache -->|Yes| Return[Return Pipeline]
    Cache -->|No| Fallback[Return Fallback]

    Fallback --> Async[Async Compilation]
    Async --> Compile[Slang Compiler]
    Compile --> Ready[Mark Ready]

    Ready --> Swap["Next Frame:<br/>Swap to Final"]