Add a spotlight with inner/outer cone angles, projected gobo texture, and a
single 2D shadow map. The spotlight's view-projection matrix serves triple
duty — shadow mapping, gobo UV projection, and cone masking. Based on
Lesson 24.
When to use
- You need a focused light source with a defined cone (not omnidirectional)
- You want to project a pattern (window, foliage, abstract) through a light
- You need shadows from a spotlight (simpler than point light cube maps)
- You are building theatrical, cinematic, or stage-style lighting
- You already have an HDR rendering pipeline and Blinn-Phong lighting
Key API calls
SDL_CreateGPUTexture — shadow depth map (D32_FLOAT, 2D, SAMPLER | DEPTH_STENCIL_TARGET)
SDL_CreateGPUTexture — gobo texture (R8G8B8A8_UNORM, 2D, SAMPLER)
SDL_CreateGPUSampler — NEAREST + CLAMP for shadow, LINEAR + CLAMP for gobo
SDL_CreateGPUGraphicsPipeline — shadow pipeline (depth-only, no color targets)
SDL_BeginGPURenderPass — shadow pass with depth-only attachment
SDL_BindGPUFragmentSamplers — bind diffuse + shadow + gobo textures in scene pass
Correct order
- Define spotlight parameters — position, target, inner/outer cone angles, color, intensity
- Compute light view-projection —
mat4_look_at(pos, target, up) + mat4_perspective(2 * outer_angle, 1.0, near, far)
- Create shadow depth texture — D32_FLOAT, same resolution for shadow map (e.g. 1024x1024)
- Create shadow sampler — NEAREST filter, CLAMP_TO_EDGE
- Load gobo texture — grayscale PNG as UNORM (not sRGB), LINEAR sampler, CLAMP_TO_EDGE
- Create shadow pipeline — vertex shader transforms by light_mvp, empty fragment shader, depth-only
- Create scene pipeline — increase
num_samplers to include shadow + gobo (e.g. 3 total)
- Each frame:
a. Shadow pass: render shadow casters from spotlight's perspective (depth-only)
b. Scene pass: bind shadow map + gobo texture, fragment shader applies cone + gobo + shadow
Key concepts
- Spotlight cone:
smoothstep(cos_outer, cos_inner, cos_angle) — cosine decreases with angle, so outer < inner
- Gobo projection: light_vp transforms world pos → clip → NDC → UV for gobo texture sampling
- Triple-duty matrix: the same light_vp handles shadow mapping, gobo UV mapping, and cone bounds
- Single 2D shadow map: a spotlight's perspective frustum captures everything in one pass (unlike cube maps for point lights)
- UNORM gobo texture: the gobo is a linear attenuation mask, not a color — use UNORM to avoid sRGB gamma
- Cone masking via UV bounds: fragments projecting outside [0,1] UV get zero light via
step() functions
Common mistakes
- Using sRGB format for the gobo texture — the gobo is a light attenuation mask sampled linearly. sRGB applies an unwanted gamma curve. Use
R8G8B8A8_UNORM.
- Wrong smoothstep parameter order — cosine is decreasing, so
smoothstep(cos_outer, cos_inner, ...) with outer < inner. Swapping them inverts the cone.
- Forgetting the Y-flip in UV remapping — texture V increases downward; NDC Y increases upward. Always flip:
gobo_uv.y = 1.0 - gobo_uv.y.
- Shadow acne from insufficient bias — add a small constant bias (0.002) when comparing depths in the shadow test.
- Including the light source model as a shadow caster — the searchlight/lamp model sits at the light position and would block its own light. Exclude it from the shadow pass.
- FOV not matching outer cone angle — the shadow/projection FOV must be
2 * outer_angle to cover the full spotlight cone. Too narrow clips shadows; too wide wastes resolution.
Spotlight definition
#define SPOT_INNER_DEG 20.0f /* full-intensity inner cone half-angle */
#define SPOT_OUTER_DEG 30.0f /* falloff-to-zero outer cone half-angle */
#define SPOT_INTENSITY 5.0f /* HDR brightness */
#define SPOT_NEAR 0.5f
#define SPOT_FAR 30.0f
#define SHADOW_MAP_SIZE 1024
/* Compute spotlight view-projection (static light). */
vec3 spot_pos = vec3_create(6.0f, 5.0f, 4.0f);
vec3 spot_target = vec3_create(0.0f, 0.0f, 0.0f);
vec3 spot_up = vec3_create(0.0f, 1.0f, 0.0f);
mat4 light_view = mat4_look_at(spot_pos, spot_target, spot_up);
float outer_rad = SPOT_OUTER_DEG * FORGE_DEG2RAD;
mat4 light_proj = mat4_perspective(2.0f * outer_rad, 1.0f, SPOT_NEAR, SPOT_FAR);
mat4 light_vp = mat4_multiply(light_proj, light_view);
vec3 spot_dir = vec3_normalize(vec3_sub(spot_target, spot_pos));
Shadow depth texture
SDL_GPUTextureCreateInfo ti;
SDL_zero(ti);
ti.type = SDL_GPU_TEXTURETYPE_2D;
ti.format = SDL_GPU_TEXTUREFORMAT_D32_FLOAT;
ti.width = SHADOW_MAP_SIZE;
ti.height = SHADOW_MAP_SIZE;
ti.layer_count_or_depth = 1;
ti.num_levels = 1;
ti.usage = SDL_GPU_TEXTUREUSAGE_SAMPLER
| SDL_GPU_TEXTUREUSAGE_DEPTH_STENCIL_TARGET;
SDL_GPUTexture *shadow_depth = SDL_CreateGPUTexture(device, &ti);
Gobo texture loading
/* Use UNORM (not sRGB) — the gobo is a linear attenuation mask. */
SDL_GPUTextureCreateInfo tex_info;
SDL_zero(tex_info);
tex_info.type = SDL_GPU_TEXTURETYPE_2D;
tex_info.format = SDL_GPU_TEXTUREFORMAT_R8G8B8A8_UNORM;
tex_info.width = w;
tex_info.height = h;
tex_info.layer_count_or_depth = 1;
tex_info.num_levels = 1;
tex_info.usage = SDL_GPU_TEXTUREUSAGE_SAMPLER;
/* Gobo sampler — linear filtering for smooth projection, clamp to edge. */
SDL_GPUSamplerCreateInfo si;
SDL_zero(si);
si.min_filter = SDL_GPU_FILTER_LINEAR;
si.mag_filter = SDL_GPU_FILTER_LINEAR;
si.address_mode_u = SDL_GPU_SAMPLERADDRESSMODE_CLAMP_TO_EDGE;
si.address_mode_v = SDL_GPU_SAMPLERADDRESSMODE_CLAMP_TO_EDGE;
si.address_mode_w = SDL_GPU_SAMPLERADDRESSMODE_CLAMP_TO_EDGE;
Fragment shader — spotlight with gobo and shadow
/* Direction from spotlight to fragment. */
float3 to_frag = world_pos - spot_pos;
float dist = length(to_frag);
float3 L_frag = to_frag / dist;
/* Cone falloff. */
float cos_angle = dot(L_frag, normalize(spot_dir));
float cone = smoothstep(cos_outer, cos_inner, cos_angle);
if (cone > 0.0)
{
/* Transform fragment into spotlight clip space. */
float4 light_clip = mul(light_vp, float4(world_pos, 1.0));
float3 light_ndc = light_clip.xyz / light_clip.w;
/* Gobo texture projection — remap NDC to UV space. */
float2 gobo_uv = light_ndc.xy * 0.5 + 0.5;
gobo_uv.y = 1.0 - gobo_uv.y;
/* Cone masking — clamp to spotlight bounds. */
float in_bounds = step(0.0, gobo_uv.x) * step(gobo_uv.x, 1.0) *
step(0.0, gobo_uv.y) * step(gobo_uv.y, 1.0);
/* Sample gobo pattern (grayscale). */
float gobo = gobo_tex.Sample(gobo_smp, gobo_uv).r;
/* Shadow test with PCF. */
float shadow = sample_shadow(light_ndc, texel_size);
/* Blinn-Phong from spotlight. */
float3 L = normalize(spot_pos - world_pos);
float NdotL = max(dot(N, L), 0.0);
float3 H = normalize(L + V);
float NdotH = max(dot(N, H), 0.0);
/* Quadratic attenuation. */
float atten = 1.0 / (1.0 + 0.09 * dist + 0.032 * dist * dist);
total_light += (albedo * NdotL + spec) * cone * gobo * shadow *
in_bounds * atten * spot_intensity * spot_color;
}
Shadow pass — depth-only render
/* Shadow pipeline: no color targets, depth-only. */
SDL_GPUDepthStencilTargetInfo shadow_depth_info;
SDL_zero(shadow_depth_info);
shadow_depth_info.texture = shadow_depth_texture;
shadow_depth_info.load_op = SDL_GPU_LOADOP_CLEAR;
shadow_depth_info.store_op = SDL_GPU_STOREOP_STORE;
shadow_depth_info.clear_depth = 1.0f;
SDL_GPURenderPass *shadow_pass = SDL_BeginGPURenderPass(
cmd, NULL, 0, &shadow_depth_info);
SDL_BindGPUGraphicsPipeline(shadow_pass, shadow_pipeline);
/* Draw shadow casters (exclude the light source model). */
draw_model_shadow(shadow_pass, cmd, &truck, &truck_mat, &light_vp);
for (int i = 0; i < BOX_COUNT; i++) {
draw_model_shadow(shadow_pass, cmd, &box, &box_mat[i], &light_vp);
}
SDL_EndGPURenderPass(shadow_pass);
Scene pass texture bindings
/* Bind 3 samplers: diffuse, shadow depth, gobo pattern. */
SDL_GPUTextureSamplerBinding tex_binds[3];
tex_binds[0] = (SDL_GPUTextureSamplerBinding){
.texture = diffuse_tex, .sampler = sampler };
tex_binds[1] = (SDL_GPUTextureSamplerBinding){
.texture = shadow_depth_texture, .sampler = shadow_sampler };
tex_binds[2] = (SDL_GPUTextureSamplerBinding){
.texture = gobo_texture, .sampler = gobo_sampler };
SDL_BindGPUFragmentSamplers(pass, 0, tex_binds, 3);
1---2name: forge-gobo-spotlight-23description: Add a projected-texture (gobo/cookie) spotlight with cone falloff, shadow map, and pattern projection to an SDL GPU project4metadata:5 source: https://skillmd.com/skills/majiayu000/forge-gobo-spotlight-26---78Add a spotlight with inner/outer cone angles, projected gobo texture, and a9single 2D shadow map. The spotlight's view-projection matrix serves triple10duty — shadow mapping, gobo UV projection, and cone masking. Based on11Lesson 24.1213## When to use1415- You need a focused light source with a defined cone (not omnidirectional)16- You want to project a pattern (window, foliage, abstract) through a light17- You need shadows from a spotlight (simpler than point light cube maps)18- You are building theatrical, cinematic, or stage-style lighting19- You already have an HDR rendering pipeline and Blinn-Phong lighting2021## Key API calls2223- `SDL_CreateGPUTexture` — shadow depth map (D32_FLOAT, 2D, `SAMPLER | DEPTH_STENCIL_TARGET`)24- `SDL_CreateGPUTexture` — gobo texture (R8G8B8A8_UNORM, 2D, `SAMPLER`)25- `SDL_CreateGPUSampler` — NEAREST + CLAMP for shadow, LINEAR + CLAMP for gobo26- `SDL_CreateGPUGraphicsPipeline` — shadow pipeline (depth-only, no color targets)27- `SDL_BeginGPURenderPass` — shadow pass with depth-only attachment28- `SDL_BindGPUFragmentSamplers` — bind diffuse + shadow + gobo textures in scene pass2930## Correct order31321. **Define spotlight parameters** — position, target, inner/outer cone angles, color, intensity332. **Compute light view-projection** — `mat4_look_at(pos, target, up)` + `mat4_perspective(2 * outer_angle, 1.0, near, far)`343. **Create shadow depth texture** — D32_FLOAT, same resolution for shadow map (e.g. 1024x1024)354. **Create shadow sampler** — NEAREST filter, CLAMP_TO_EDGE365. **Load gobo texture** — grayscale PNG as UNORM (not sRGB), LINEAR sampler, CLAMP_TO_EDGE376. **Create shadow pipeline** — vertex shader transforms by light_mvp, empty fragment shader, depth-only387. **Create scene pipeline** — increase `num_samplers` to include shadow + gobo (e.g. 3 total)398. **Each frame:**40 a. Shadow pass: render shadow casters from spotlight's perspective (depth-only)41 b. Scene pass: bind shadow map + gobo texture, fragment shader applies cone + gobo + shadow4243## Key concepts44451. **Spotlight cone**: `smoothstep(cos_outer, cos_inner, cos_angle)` — cosine decreases with angle, so outer < inner462. **Gobo projection**: light_vp transforms world pos → clip → NDC → UV for gobo texture sampling473. **Triple-duty matrix**: the same light_vp handles shadow mapping, gobo UV mapping, and cone bounds484. **Single 2D shadow map**: a spotlight's perspective frustum captures everything in one pass (unlike cube maps for point lights)495. **UNORM gobo texture**: the gobo is a linear attenuation mask, not a color — use UNORM to avoid sRGB gamma506. **Cone masking via UV bounds**: fragments projecting outside [0,1] UV get zero light via `step()` functions5152## Common mistakes5354- **Using sRGB format for the gobo texture** — the gobo is a light attenuation mask sampled linearly. sRGB applies an unwanted gamma curve. Use `R8G8B8A8_UNORM`.55- **Wrong smoothstep parameter order** — cosine is decreasing, so `smoothstep(cos_outer, cos_inner, ...)` with outer < inner. Swapping them inverts the cone.56- **Forgetting the Y-flip in UV remapping** — texture V increases downward; NDC Y increases upward. Always flip: `gobo_uv.y = 1.0 - gobo_uv.y`.57- **Shadow acne from insufficient bias** — add a small constant bias (0.002) when comparing depths in the shadow test.58- **Including the light source model as a shadow caster** — the searchlight/lamp model sits at the light position and would block its own light. Exclude it from the shadow pass.59- **FOV not matching outer cone angle** — the shadow/projection FOV must be `2 * outer_angle` to cover the full spotlight cone. Too narrow clips shadows; too wide wastes resolution.6061## Spotlight definition6263```c64#define SPOT_INNER_DEG 20.0f /* full-intensity inner cone half-angle */65#define SPOT_OUTER_DEG 30.0f /* falloff-to-zero outer cone half-angle */66#define SPOT_INTENSITY 5.0f /* HDR brightness */67#define SPOT_NEAR 0.5f68#define SPOT_FAR 30.0f69#define SHADOW_MAP_SIZE 10247071/* Compute spotlight view-projection (static light). */72vec3 spot_pos = vec3_create(6.0f, 5.0f, 4.0f);73vec3 spot_target = vec3_create(0.0f, 0.0f, 0.0f);74vec3 spot_up = vec3_create(0.0f, 1.0f, 0.0f);7576mat4 light_view = mat4_look_at(spot_pos, spot_target, spot_up);77float outer_rad = SPOT_OUTER_DEG * FORGE_DEG2RAD;78mat4 light_proj = mat4_perspective(2.0f * outer_rad, 1.0f, SPOT_NEAR, SPOT_FAR);79mat4 light_vp = mat4_multiply(light_proj, light_view);80vec3 spot_dir = vec3_normalize(vec3_sub(spot_target, spot_pos));81```8283## Shadow depth texture8485```c86SDL_GPUTextureCreateInfo ti;87SDL_zero(ti);88ti.type = SDL_GPU_TEXTURETYPE_2D;89ti.format = SDL_GPU_TEXTUREFORMAT_D32_FLOAT;90ti.width = SHADOW_MAP_SIZE;91ti.height = SHADOW_MAP_SIZE;92ti.layer_count_or_depth = 1;93ti.num_levels = 1;94ti.usage = SDL_GPU_TEXTUREUSAGE_SAMPLER95 | SDL_GPU_TEXTUREUSAGE_DEPTH_STENCIL_TARGET;9697SDL_GPUTexture *shadow_depth = SDL_CreateGPUTexture(device, &ti);98```99100## Gobo texture loading101102```c103/* Use UNORM (not sRGB) — the gobo is a linear attenuation mask. */104SDL_GPUTextureCreateInfo tex_info;105SDL_zero(tex_info);106tex_info.type = SDL_GPU_TEXTURETYPE_2D;107tex_info.format = SDL_GPU_TEXTUREFORMAT_R8G8B8A8_UNORM;108tex_info.width = w;109tex_info.height = h;110tex_info.layer_count_or_depth = 1;111tex_info.num_levels = 1;112tex_info.usage = SDL_GPU_TEXTUREUSAGE_SAMPLER;113114/* Gobo sampler — linear filtering for smooth projection, clamp to edge. */115SDL_GPUSamplerCreateInfo si;116SDL_zero(si);117si.min_filter = SDL_GPU_FILTER_LINEAR;118si.mag_filter = SDL_GPU_FILTER_LINEAR;119si.address_mode_u = SDL_GPU_SAMPLERADDRESSMODE_CLAMP_TO_EDGE;120si.address_mode_v = SDL_GPU_SAMPLERADDRESSMODE_CLAMP_TO_EDGE;121si.address_mode_w = SDL_GPU_SAMPLERADDRESSMODE_CLAMP_TO_EDGE;122```123124## Fragment shader — spotlight with gobo and shadow125126```hlsl127/* Direction from spotlight to fragment. */128float3 to_frag = world_pos - spot_pos;129float dist = length(to_frag);130float3 L_frag = to_frag / dist;131132/* Cone falloff. */133float cos_angle = dot(L_frag, normalize(spot_dir));134float cone = smoothstep(cos_outer, cos_inner, cos_angle);135136if (cone > 0.0)137{138 /* Transform fragment into spotlight clip space. */139 float4 light_clip = mul(light_vp, float4(world_pos, 1.0));140 float3 light_ndc = light_clip.xyz / light_clip.w;141142 /* Gobo texture projection — remap NDC to UV space. */143 float2 gobo_uv = light_ndc.xy * 0.5 + 0.5;144 gobo_uv.y = 1.0 - gobo_uv.y;145146 /* Cone masking — clamp to spotlight bounds. */147 float in_bounds = step(0.0, gobo_uv.x) * step(gobo_uv.x, 1.0) *148 step(0.0, gobo_uv.y) * step(gobo_uv.y, 1.0);149150 /* Sample gobo pattern (grayscale). */151 float gobo = gobo_tex.Sample(gobo_smp, gobo_uv).r;152153 /* Shadow test with PCF. */154 float shadow = sample_shadow(light_ndc, texel_size);155156 /* Blinn-Phong from spotlight. */157 float3 L = normalize(spot_pos - world_pos);158 float NdotL = max(dot(N, L), 0.0);159 float3 H = normalize(L + V);160 float NdotH = max(dot(N, H), 0.0);161162 /* Quadratic attenuation. */163 float atten = 1.0 / (1.0 + 0.09 * dist + 0.032 * dist * dist);164165 total_light += (albedo * NdotL + spec) * cone * gobo * shadow *166 in_bounds * atten * spot_intensity * spot_color;167}168```169170## Shadow pass — depth-only render171172```c173/* Shadow pipeline: no color targets, depth-only. */174SDL_GPUDepthStencilTargetInfo shadow_depth_info;175SDL_zero(shadow_depth_info);176shadow_depth_info.texture = shadow_depth_texture;177shadow_depth_info.load_op = SDL_GPU_LOADOP_CLEAR;178shadow_depth_info.store_op = SDL_GPU_STOREOP_STORE;179shadow_depth_info.clear_depth = 1.0f;180181SDL_GPURenderPass *shadow_pass = SDL_BeginGPURenderPass(182 cmd, NULL, 0, &shadow_depth_info);183SDL_BindGPUGraphicsPipeline(shadow_pass, shadow_pipeline);184185/* Draw shadow casters (exclude the light source model). */186draw_model_shadow(shadow_pass, cmd, &truck, &truck_mat, &light_vp);187for (int i = 0; i < BOX_COUNT; i++) {188 draw_model_shadow(shadow_pass, cmd, &box, &box_mat[i], &light_vp);189}190191SDL_EndGPURenderPass(shadow_pass);192```193194## Scene pass texture bindings195196```c197/* Bind 3 samplers: diffuse, shadow depth, gobo pattern. */198SDL_GPUTextureSamplerBinding tex_binds[3];199tex_binds[0] = (SDL_GPUTextureSamplerBinding){200 .texture = diffuse_tex, .sampler = sampler };201tex_binds[1] = (SDL_GPUTextureSamplerBinding){202 .texture = shadow_depth_texture, .sampler = shadow_sampler };203tex_binds[2] = (SDL_GPUTextureSamplerBinding){204 .texture = gobo_texture, .sampler = gobo_sampler };205SDL_BindGPUFragmentSamplers(pass, 0, tex_binds, 3);206```