2.0 Help

Shader Render State

The state of the rendering pipeline can only be set through shaders. There is no way to change its state other than to select a shader which includes that specific state.

Use shader permutations to create variants of a shader. Each variant may incorporate a different render state. By setting shader permutation variables at runtime, you select the specific shader variant (permutation) and thus also get its render state.

This design follows what rendering APIs such as DirectX 12 and Vulkan require.

The Shader Render State Section

Each shader is made up of several sections:

[PLATFORMS] ALL DEBUG [PERMUTATIONS] ALPHATEST WIREFRAME [RENDERSTATE] #if WIREFRAME == 1 WireFrame = true #endif [VERTEXSHADER] VS_OUT main(VS_IN Input) { ... } [PIXELSHADER] ...

The render pipeline state associated with the shader is defined in the [RENDERSTATE] section. It may use permutation variables just like the shader code. To have different state for different permutations, use standard C preprocessor syntax.

Render States

The following variables are available in the [RENDERSTATE] section. Simply overwrite them with the desired value.

Rasterizer States

  • bool FrontCounterClockwise = false

    When false, triangles with clockwise winding order are considered front-facing. When true, counter-clockwise triangles are front-facing. This affects culling and two-sided stencil operations.

  • bool ScissorTest = false

    When true, fragments outside the scissor rectangle are discarded. The scissor rectangle is set by the rendering code, not the shader.

  • bool WireFrame = false

    When true, renders only the edges of triangles instead of filled polygons. Useful for debugging geometry.

  • bool ConservativeRasterization = false

    When true, a pixel is considered covered if the triangle touches any part of the pixel. This is useful for voxelization and collision detection algorithms.

  • enum CullMode = CullMode_Back

    CullMode = CullMode_None // Render both front and back faces CullMode = CullMode_Back // Don't render back faces (default) CullMode = CullMode_Front // Don't render front faces

  • float DepthBiasClamp = 0.0

    Maximum depth bias value. Clamps the computed depth bias to prevent excessive offset.

  • float SlopeScaledDepthBias = 0.0

    Depth bias that scales with the polygon's slope. Useful for shadow mapping to reduce shadow acne on angled surfaces.

  • int DepthBias = 0

    Constant depth bias added to each fragment's depth value. Used together with SlopeScaledDepthBias for techniques like shadow mapping.

Depth-Stencil State

Depth Testing

  • bool DepthEnable = true

    When true, depth testing is performed. Fragments are compared against the depth buffer using DepthTestFunc. For backwards compatibility, DepthTest is also supported but deprecated.

  • bool DepthWrite = true

    When true, fragments that pass the depth test write their depth value to the depth buffer. Typically disabled for transparent objects rendered after opaque geometry.

  • enum DepthTestFunc = CompareFunc_Less

    Comparison function used for depth testing. The fragment passes if this comparison succeeds.

    DepthTestFunc = CompareFunc_Never // Never pass (no fragments rendered) DepthTestFunc = CompareFunc_Less // Pass if closer than depth buffer (default) DepthTestFunc = CompareFunc_Equal // Pass if equal to depth buffer DepthTestFunc = CompareFunc_LessEqual // Pass if closer or equal DepthTestFunc = CompareFunc_Greater // Pass if farther than depth buffer DepthTestFunc = CompareFunc_NotEqual // Pass if not equal DepthTestFunc = CompareFunc_GreaterEqual // Pass if farther or equal DepthTestFunc = CompareFunc_Always // Always pass (ignores depth buffer)

Stencil Testing

  • bool StencilEnable = false

    When true, stencil testing is performed. Fragments are compared against the stencil buffer, and operations can modify the stencil buffer based on test results.

  • int StencilReadMask = 255

    Bitmask applied when reading from the stencil buffer during comparison. Use 255 (all bits) to compare the full stencil value.

  • int StencilWriteMask = 255

    Bitmask applied when writing to the stencil buffer. Use 255 (all bits) to write the full stencil value.

  • int StencilRefValue = 0

    The reference value used for stencil comparisons and operations. When comparing, this value (masked by StencilReadMask) is compared against the stencil buffer value. When using StencilOp_Replace, this value (masked by StencilWriteMask) is written to the stencil buffer.

    Set this to -1 to use a dynamic stencil reference value provided by the rendering code at runtime, rather than the fixed value from the shader.

  • bool UseUserStencilRef = false

    When true, the stencil reference value is provided dynamically by the rendering code at runtime. When false, the shader's StencilRefValue is used. Setting StencilRefValue to -1 implicitly enables this option.

Front-Face Stencil Operations

These operations apply to front-facing polygons (see FrontCounterClockwise to configure winding order).

  • enum StencilCompareFunc = CompareFunc_Always

    Comparison function for stencil testing on front faces.

    StencilCompareFunc = CompareFunc_Never // Never pass StencilCompareFunc = CompareFunc_Less // Pass if (ref & mask) < (stencil & mask) StencilCompareFunc = CompareFunc_Equal // Pass if (ref & mask) == (stencil & mask) StencilCompareFunc = CompareFunc_LessEqual // Pass if (ref & mask) <= (stencil & mask) StencilCompareFunc = CompareFunc_Greater // Pass if (ref & mask) > (stencil & mask) StencilCompareFunc = CompareFunc_NotEqual // Pass if (ref & mask) != (stencil & mask) StencilCompareFunc = CompareFunc_GreaterEqual // Pass if (ref & mask) >= (stencil & mask) StencilCompareFunc = CompareFunc_Always // Always pass (default)

  • enum StencilFailOp = StencilOp_Keep

    Operation performed when the stencil test fails.

    StencilFailOp = StencilOp_Keep // Keep current value (default) StencilFailOp = StencilOp_Zero // Set to 0 StencilFailOp = StencilOp_Replace // Replace with reference value StencilFailOp = StencilOp_IncrementSaturated // Increment, clamp to max StencilFailOp = StencilOp_DecrementSaturated // Decrement, clamp to 0 StencilFailOp = StencilOp_Invert // Bitwise invert StencilFailOp = StencilOp_Increment // Increment, wrap to 0 StencilFailOp = StencilOp_Decrement // Decrement, wrap to max

  • enum StencilDepthFailOp = StencilOp_Keep

    Operation performed when the stencil test passes but the depth test fails.

    StencilDepthFailOp = StencilOp_Keep StencilDepthFailOp = StencilOp_Zero StencilDepthFailOp = StencilOp_Replace StencilDepthFailOp = StencilOp_IncrementSaturated StencilDepthFailOp = StencilOp_DecrementSaturated StencilDepthFailOp = StencilOp_Invert StencilDepthFailOp = StencilOp_Increment StencilDepthFailOp = StencilOp_Decrement

  • enum StencilPassOp = StencilOp_Keep

    Operation performed when both stencil and depth tests pass.

    StencilPassOp = StencilOp_Keep StencilPassOp = StencilOp_Zero StencilPassOp = StencilOp_Replace StencilPassOp = StencilOp_IncrementSaturated StencilPassOp = StencilOp_DecrementSaturated StencilPassOp = StencilOp_Invert StencilPassOp = StencilOp_Increment StencilPassOp = StencilOp_Decrement

Back-Face Stencil Operations

These operations apply to back-facing polygons. If not explicitly set, they default to the front-face values, allowing separate stencil operations for two-sided geometry.

  • enum StencilBackFaceCompareFunc = CompareFunc_Always

    Comparison function for stencil testing on back faces. Falls back to StencilCompareFunc if not set.

    StencilBackFaceCompareFunc = CompareFunc_Never StencilBackFaceCompareFunc = CompareFunc_Less StencilBackFaceCompareFunc = CompareFunc_Equal StencilBackFaceCompareFunc = CompareFunc_LessEqual StencilBackFaceCompareFunc = CompareFunc_Greater StencilBackFaceCompareFunc = CompareFunc_NotEqual StencilBackFaceCompareFunc = CompareFunc_GreaterEqual StencilBackFaceCompareFunc = CompareFunc_Always

  • enum StencilBackFaceFailOp = StencilOp_Keep

    Operation when stencil test fails on back faces. Falls back to StencilFailOp if not set.

    StencilBackFaceFailOp = StencilOp_Keep StencilBackFaceFailOp = StencilOp_Zero StencilBackFaceFailOp = StencilOp_Replace StencilBackFaceFailOp = StencilOp_IncrementSaturated StencilBackFaceFailOp = StencilOp_DecrementSaturated StencilBackFaceFailOp = StencilOp_Invert StencilBackFaceFailOp = StencilOp_Increment StencilBackFaceFailOp = StencilOp_Decrement

  • enum StencilBackFaceDepthFailOp = StencilOp_Keep

    Operation when stencil passes but depth fails on back faces. Falls back to StencilDepthFailOp if not set.

    StencilBackFaceDepthFailOp = StencilOp_Keep StencilBackFaceDepthFailOp = StencilOp_Zero StencilBackFaceDepthFailOp = StencilOp_Replace StencilBackFaceDepthFailOp = StencilOp_IncrementSaturated StencilBackFaceDepthFailOp = StencilOp_DecrementSaturated StencilBackFaceDepthFailOp = StencilOp_Invert StencilBackFaceDepthFailOp = StencilOp_Increment StencilBackFaceDepthFailOp = StencilOp_Decrement

  • enum StencilBackFacePassOp = StencilOp_Keep

    Operation when both tests pass on back faces. Falls back to StencilPassOp if not set.

    StencilBackFacePassOp = StencilOp_Keep StencilBackFacePassOp = StencilOp_Zero StencilBackFacePassOp = StencilOp_Replace StencilBackFacePassOp = StencilOp_IncrementSaturated StencilBackFacePassOp = StencilOp_DecrementSaturated StencilBackFacePassOp = StencilOp_Invert StencilBackFacePassOp = StencilOp_Increment StencilBackFacePassOp = StencilOp_Decrement

Blend State

  • bool AlphaToCoverage = false

    When true, uses the alpha channel to determine per-pixel coverage in MSAA rendering. Useful for rendering foliage and other alpha-tested geometry with smoother edges.

  • bool IndependentBlend = false

    When true, each render target (0-7) can have independent blend settings. When false, all render targets use the settings from render target 0.

Per-Render-Target Blend Settings

The following variables configure blending for individual render targets. You can specify them without a suffix (e.g., BlendingEnabled) to configure render target 0, or with a suffix 0-7 (e.g., BlendingEnabled0, BlendingEnabled1) to configure specific targets.

When IndependentBlend is false, all render targets use the settings from target 0.

  • bool BlendingEnabled = false

    When true, enables blending for this render target. The source color from the pixel shader is combined with the destination color in the render target using the blend operation and factors.

  • enum BlendOp = BlendOp_Add

    The operation used to combine source and destination RGB values.

    BlendOp = BlendOp_Add // result = src + dest (default) BlendOp = BlendOp_Subtract // result = src - dest BlendOp = BlendOp_RevSubtract // result = dest - src BlendOp = BlendOp_Min // result = min(src, dest) BlendOp = BlendOp_Max // result = max(src, dest)

  • enum BlendOpAlpha = BlendOp_Add

    The operation used to combine source and destination alpha values. Often the same as BlendOp.

    BlendOpAlpha = BlendOp_Add BlendOpAlpha = BlendOp_Subtract BlendOpAlpha = BlendOp_RevSubtract BlendOpAlpha = BlendOp_Min BlendOpAlpha = BlendOp_Max

  • enum SourceBlend = Blend_One

    Factor applied to the source RGB color before blending.

    SourceBlend = Blend_Zero // (0, 0, 0) SourceBlend = Blend_One // (1, 1, 1) - use source color as-is (default) SourceBlend = Blend_SrcColor // (Rs, Gs, Bs) SourceBlend = Blend_InvSrcColor // (1-Rs, 1-Gs, 1-Bs) SourceBlend = Blend_SrcAlpha // (As, As, As) - common for transparency SourceBlend = Blend_InvSrcAlpha // (1-As, 1-As, 1-As) SourceBlend = Blend_DestAlpha // (Ad, Ad, Ad) SourceBlend = Blend_InvDestAlpha // (1-Ad, 1-Ad, 1-Ad) SourceBlend = Blend_DestColor // (Rd, Gd, Bd) SourceBlend = Blend_InvDestColor // (1-Rd, 1-Gd, 1-Bd) SourceBlend = Blend_SrcAlphaSaturated // (f, f, f) where f = min(As, 1-Ad) SourceBlend = Blend_BlendFactor // Constant blend factor SourceBlend = Blend_InvBlendFactor // 1 - constant blend factor

  • enum DestBlend = Blend_One

    Factor applied to the destination RGB color (current render target value) before blending.

    DestBlend = Blend_Zero // (0, 0, 0) - ignore destination DestBlend = Blend_One // (1, 1, 1) - use destination as-is (default) DestBlend = Blend_SrcColor // (Rs, Gs, Bs) DestBlend = Blend_InvSrcColor // (1-Rs, 1-Gs, 1-Bs) - common for transparency DestBlend = Blend_SrcAlpha // (As, As, As) DestBlend = Blend_InvSrcAlpha // (1-As, 1-As, 1-As) DestBlend = Blend_DestAlpha // (Ad, Ad, Ad) DestBlend = Blend_InvDestAlpha // (1-Ad, 1-Ad, 1-Ad) DestBlend = Blend_DestColor // (Rd, Gd, Bd) DestBlend = Blend_InvDestColor // (1-Rd, 1-Gd, 1-Bd) DestBlend = Blend_SrcAlphaSaturated // (f, f, f) where f = min(As, 1-Ad) DestBlend = Blend_BlendFactor // Constant blend factor DestBlend = Blend_InvBlendFactor // 1 - constant blend factor

  • enum SourceBlendAlpha = Blend_One

    Factor applied to the source alpha value before blending.

    SourceBlendAlpha = Blend_Zero SourceBlendAlpha = Blend_One SourceBlendAlpha = Blend_SrcColor SourceBlendAlpha = Blend_InvSrcColor SourceBlendAlpha = Blend_SrcAlpha SourceBlendAlpha = Blend_InvSrcAlpha SourceBlendAlpha = Blend_DestAlpha SourceBlendAlpha = Blend_InvDestAlpha SourceBlendAlpha = Blend_DestColor SourceBlendAlpha = Blend_InvDestColor SourceBlendAlpha = Blend_SrcAlphaSaturated SourceBlendAlpha = Blend_BlendFactor SourceBlendAlpha = Blend_InvBlendFactor

  • enum DestBlendAlpha = Blend_One

    Factor applied to the destination alpha value before blending.

    DestBlendAlpha = Blend_Zero DestBlendAlpha = Blend_One DestBlendAlpha = Blend_SrcColor DestBlendAlpha = Blend_InvSrcColor DestBlendAlpha = Blend_SrcAlpha DestBlendAlpha = Blend_InvSrcAlpha DestBlendAlpha = Blend_DestAlpha DestBlendAlpha = Blend_InvDestAlpha DestBlendAlpha = Blend_DestColor DestBlendAlpha = Blend_InvDestColor DestBlendAlpha = Blend_SrcAlphaSaturated DestBlendAlpha = Blend_BlendFactor DestBlendAlpha = Blend_InvBlendFactor

  • int ColorWriteMask = 255

    Bitmask controlling which color channels are written to the render target. Use 255 to write all channels (RGBA), or combine bits: R=1, G=2, B=4, A=8. For example, use 7 to write only RGB (1+2+4). The deprecated name WriteMask is also supported.

Common Configuration Examples

Standard Alpha Blending (Transparency)

For typical transparent objects:

[RENDERSTATE] BlendingEnabled = true SourceBlend = Blend_SrcAlpha DestBlend = Blend_InvSrcAlpha DepthWrite = false // Don't write to depth buffer for transparent objects

Additive Blending (Particles, Effects)

For light-emitting particles and effects:

[RENDERSTATE] BlendingEnabled = true SourceBlend = Blend_One DestBlend = Blend_One BlendOp = BlendOp_Add DepthWrite = false

Wireframe Rendering

For debugging mesh geometry:

[RENDERSTATE] WireFrame = true CullMode = CullMode_None // Show both front and back faces

Depth Pre-Pass

For early depth rejection optimization:

[RENDERSTATE] DepthEnable = true DepthWrite = true ColorWriteMask = 0 // Only write depth, no color output

See Also

Last modified: 24 January 2026
Shaders ResourcesShader Permutation Variables