Forge Cascaded Shadow Maps

Add directional-light cascaded shadow maps (CSM) with 3x3 PCF soft shadows to an SDL3 GPU application. Based on Lesson 15.

When to use

• You need directional light shadows covering a large area
• Single shadow maps lack resolution for your scene
• You want soft shadow edges without expensive techniques

Key API calls

• SDL_CreateGPUTexture — shadow map textures (D32FLOAT, DEPTHSTENCIL_TARGET | SAMPLER)
• SDL_CreateGPUSampler — NEAREST filter, CLAMPTOEDGE for shadow map sampling
• SDL_CreateGPUGraphicsPipeline — shadow pipeline (depth-only, front-face cull, depth bias)
• SDL_BeginGPURenderPass / SDL_EndGPURenderPass — one pass per cascade (depth only)
• SDL_BindGPUFragmentSamplers — bind shadow maps + sampler for scene pass
• SDL_PushGPUVertexUniformData / SDL_PushGPUFragmentUniformData — per-draw uniforms

Correct order

1. Create shadow map textures + sampler (in SDL_AppInit)
2. Create shadow pipeline — depth-only, front-face culling, depth bias
3. Create scene pipeline — binds shadow maps as fragment samplers
4. Each frame:

a. Compute cascade split depths (logarithmic-linear blend) b. Compute light VP matrix per cascade (frustum corners → light-space AABB) c. Shadow pass: render all casters into each cascade's depth map d. Scene pass: render with shadow maps bound, fragment shader selects cascade by view-space depth

Key concepts

1. Shadow map textures need DEPTH_STENCIL_TARGET | SAMPLER usage flags
2. Depth-only render pass: no color targets, only depth attachment
3. Cascade splits: logarithmic-linear blend for practical depth ranges
4. Light VP matrices: tight orthographic projection from frustum corners
5. PCF sampling: 3x3 grid averages shadow/lit for soft edges
6. Store op MUST be STORE (not DONT_CARE) for shadow map depth passes

Pipeline setup

Shadow pipeline (depth-only)

/* No color targets — depth only */
pipe.target_info.num_color_targets        = 0;
pipe.target_info.has_depth_stencil_target = true;
pipe.target_info.depth_stencil_format     = SDL_GPU_TEXTUREFORMAT_D32_FLOAT;

/* Front-face culling reduces peter-panning */
pipe.rasterizer_state.cull_mode = SDL_GPU_CULLMODE_FRONT;

/* Depth bias reduces shadow acne */
pipe.rasterizer_state.depth_bias_constant_factor = 2;
pipe.rasterizer_state.depth_bias_slope_factor    = 2.0f;

Shadow map texture

SDL_GPUTextureCreateInfo info;
SDL_zero(info);
info.type   = SDL_GPU_TEXTURETYPE_2D;
info.format = SDL_GPU_TEXTUREFORMAT_D32_FLOAT;
info.usage  = SDL_GPU_TEXTUREUSAGE_DEPTH_STENCIL_TARGET |
              SDL_GPU_TEXTUREUSAGE_SAMPLER;  /* key: both flags */
info.width  = 2048;
info.height = 2048;
info.layer_count_or_depth = 1;
info.num_levels           = 1;

Shadow sampler

SDL_GPUSamplerCreateInfo smp;
SDL_zero(smp);
smp.min_filter     = SDL_GPU_FILTER_NEAREST;
smp.mag_filter     = SDL_GPU_FILTER_NEAREST;
smp.address_mode_u = SDL_GPU_SAMPLERADDRESSMODE_CLAMP_TO_EDGE;
smp.address_mode_v = SDL_GPU_SAMPLERADDRESSMODE_CLAMP_TO_EDGE;

Cascade split algorithm

/* Lengyel's logarithmic-linear blend */
for (int i = 0; i = current_depth - bias) ? 1.0 : 0.0;
        }
    }
    return shadow / 9.0;
}

Common mistakes

• Forgetting SAMPLER usage flag on shadow map texture — it will not be

readable in fragment shaders without it

• Using DONTCARE for shadow pass storeop — depth data is discarded

and shadow maps will be empty

• Not flipping Y when converting NDC to UV: shadow_uv.y = 1.0 - shadow_uv.y
• Missing depth bias — causes shadow acne (moire self-shadowing pattern)
• Culling back faces in shadow pass — should cull FRONT faces instead

to reduce peter-panning

• Not expanding Z range of the light AABB — shadow casters behind the

frustum slice won't cast shadows into it

HLSL register map

Vertex uniform slot 0 → register(b0, space1)
Vertex uniform slot 1 → register(b1, space1)
Fragment sampler slot N → register(tN, space2) + register(sN, space2)
Fragment uniform slot 0 → register(b0, space3)

Reference

See: [Lesson 15 — Cascaded Shadow Maps](../../../lessons/gpu/15-cascaded-shadow-maps/)

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Nebulavenus
• Source: Nebulavenus/forge-gpu
• License: Zlib

Install and usage instructions live in the source repository linked above.