008 — Shadow Maps: Atlas, Cascades, a Sun That Moves, and a Big Cleanup
Cascaded shadow maps in ARAL from the first depth-only pass to several views sharing one atlas, the debug tools that made it possible, an 800-line function cut into passes, and the same scene rendered by the old engine for comparison
2026-11-11 → 2026-11-14
This is the biggest piece of ARAL so far — the longest step, the most code touched, and the longest post.
The previous post was all decisions and no picture. This one is the other half: the shadows are in. The sun casts them, they follow the time of day, they work in several views at once, and they fit in the frame budget with a lot of room left. On the way, the function that records the whole frame had grown past 800 lines; it was cut into passes before the last shadow step was written on top of it.

Bluish shadows against a warm, lit stone: the look the sky ambient of devlog 005 was preparing. The shadowed parts are not black, they are lit by the sky only — exactly what the shadow is supposed to remove: the sun, nothing else.
This post is long. In order:
- the atlas and the first map (14.b, 14.c)
- reading it in the shader (14.d)
- cascades (14.e)
- the sun driving the shadow (14.f)
- debug tools
- the refactor
- several views, packing and budget (14.g)
- the comparison with the old engine
- a bonus: the scene no longer waits for the screen (step 15)
One image for all the shadows: the atlas
Every shadow map of the frame lives in one depth image, the atlas: D16_UNORM, 4096² by default
(SAralCreateInfo::shadowAtlasSize), so 32 MiB. Each cascade of each view gets a square tile in it.
- 16-bit depth, not 32. A cascade is an orthographic projection: depth is linear, and 65536 levels over the depth of a cascade is far more than enough. Half the memory, half the bandwidth — and bandwidth is what a shadow pass mostly spends.
- Tile sizes are the game's data:
shadowTileSizes[4], 256 / 512 / 1024 / 2048 by default, changed at runtime withsetShadowQuality(atlasSize, tileSizes, count)(the atlas is reallocated: an options-menu thing, not a per-frame one). - A comparison sampler, bound as
sampler2DShadow: the hardware does the depth test and the bilinear filter of the four results in one read. Its border is white: outside the map means lit. - The atlas is created in
SHADER_READ_ONLY_OPTIMALand goes back to that layout at the end of every shadow pass, so the scene can always read it — even on a frame where no shadow was rendered.
The first map
The shadow pass is a depth-only pipeline: no color attachment, no fragment shader work, and a vertex shader that is as small as it can be:
layout(push_constant) uniform AralShadowPC { mat4 viewProj; } pc;
layout(location = 0) in vec3 inPosition;
void main()
{
uint drawIdx = frame.visible.i[gl_InstanceIndex];
Instance inst = frame.instances.i[drawIdx];
Transform t = frame.transforms.t[inst.node & 0xFFFFu];
gl_Position = pc.viewProj * vec4(toWorld(t, inPosition), 1.0);
}
Same instance and transform buffers as the scene pass, same mega vertex buffer: the shadow pass uploads no extra
mesh or transform. The depth bias is dynamic (vkCmdSetDepthBias), so it can be tuned at the console without
rebuilding a pipeline.
The casters go through the same culling and radix sort as the scene (devlog 004), but against the light's
volume, never against the camera: an object behind you can still throw a shadow in front of you. The culling of a
shadow pass also doesn't record anything for the culling debug view (kCullNoTrace): that view is about what the
camera sees.
Each pass renders into its tile only: renderArea, viewport and scissor are set on the tile, so the clear at the
start of the pass doesn't wipe the other tiles of the atlas.
Reading the shadow in pbr.frag
On the CPU, every cascade gets one matrix that already contains everything: light view, orthographic projection, and the move into its tile of the atlas. The shader does one matrix multiply and gets atlas UVs and a depth directly.
float shadowVisibility(vec3 worldPos, vec3 N, uint view)
{
const float d = -(frame.cameras[view].view * vec4(worldPos, 1.0)).z; // view depth
const uint cascade = shadowCascade(d, view);
if(cascade >= uint(frame.shadowViewInfo[view].x)) return 1.0; // beyond the shadows
const uint idx = view * 4u + cascade;
vec3 p = worldPos + N * frame.shadowNormalOffset[view][cascade]; // out of its own surface
vec4 s = frame.shadowMat[idx] * vec4(p, 1.0); // ortho: no divide by w
if(s.z > 1.0) return 1.0;
vec4 r = frame.shadowTileRect[idx]; // never read a neighbour tile
if(s.x < r.x || s.x > r.z || s.y < r.y || s.y > r.w) return 1.0;
// PCF: n × n reads of sampler2DShadow, each one already a bilinear 2×2
float sum = 0.0;
for(uint y = 0u; y < n; ++y)
for(uint x = 0u; x < n; ++x)
{
vec2 off = (vec2(x, y) - 0.5 * float(n - 1u)) * texel;
sum += texture(gShadowAtlas, vec3(clamp(s.xy + off, r.xy, r.zw), s.z));
}
// fade over the last 10 % before the end of the last cascade
const float D = frame.shadowViewInfo[view].w;
return mix(sum / float(taps), 1.0, clamp((d - 0.9 * D) / (0.1 * D), 0.0, 1.0));
}
A few details that matter:
- Picking the cascade is branch-free:
dot(vec4(greaterThan(vec4(d), splits)), vec4(1.0))counts how many split distances the pixel is beyond. The four splits of a view are onevec4— that's whykMaxAralCascades = 4. - The normal offset is in texels, not meters (
shadowNormalOffset = 1.5by default). The CPU converts it per cascade: a far cascade has big texels and needs a bigger push. One setting that is right for every cascade. - The tile rectangle is shrunk by the PCF radius: a PCF read at the edge of a tile would otherwise sample the next tile — which belongs to another cascade, or another view.
- PCF taps: 1, 4, 9 or 16 (
setShadowPcfTaps), 4 by default — foursampler2DShadowreads, 16 texels compared and filtered. - Only the light that casts reads the shadow: one comparison per light in the loop, uniform over the draw.
And the toon rule from devlog 007, now real code: in toon mode the shadow is quantized on its own, with the same anti-aliasing as the bands, so a soft PCF edge never shows as a gradient in the middle of hard bands:
float sv = mix(1.0, shadowVisibility(inWorldPos, n, view), shadowStrength);
if(bands >= 2.0)
{
float w = max(fwidth(sv), softness);
sv = smoothstep(0.5 - w, 0.5 + w, sv);
}
float k = toonNdotL(NdL, bands, softness) * sv; // PBR: NdL * sv
The shadow removes the specular too; the sky ambient is not shadowed.
Cascades
One map over 100 m of view at 2048² is ~5 cm per texel everywhere — blurry at your feet, wasted in the distance. Cascades cut the view depth in slices, each with its own map: small near the camera, large far away.
The splits mix a logarithmic and a linear distribution:
f = min(cameraFar, shadowDistance) // 100 m by default
log_i = n · (f / n)^(i / N)
lin_i = n + (f − n) · i / N
split_i = λ · log_i + (1 − λ) · lin_i // λ = cascadeSplitLambda = 0.7
Pure log gives tiny near cascades and huge far ones; pure linear wastes resolution near the camera. 0.7 is the usual compromise.
One bounding sphere per slice. The eight corners of the slice are interpolated from the camera frustum corners, and the cascade covers their bounding sphere, not their bounding box. A box changes size when the camera rotates; a sphere doesn't. A constant size is the first half of stable shadows. The radius is also rounded up to 1/16 m so float noise doesn't change it from one frame to the next.
Texel snapping is the second half. The center of the cascade, in light space, is snapped to the texel grid:
const F32 texelWorld = 2.0f * rayonT / tileSize;
Vec3 cl = (lightView * Vec4(centerT, 1.0f)).xyz();
cl.x = floorf(cl.x / texelWorld) * texelWorld;
cl.y = floorf(cl.y / texelWorld) * texelWorld;
When the camera moves, the map moves by whole texels: every shadow edge falls on the same texels as before, nothing crawls.
The near plane is pulled back to the scene's bounding sphere, on the sun's side. That's the lesson from greydog (the old engine, devlog 007): a pillar standing between the sun and the slice is outside the slice, but its shadow lands inside. Clip it, and its shadow vanishes.
const F32 zNear = -(sceneCenterLS.z + sceneRadius); // everything between the sun and the slice
const F32 zFar = -(cl.z - rayonT); // back edge of the slice
const Mat4 proj = ortho(cl.x - rayonT, cl.x + rayonT, cl.y - rayonT, cl.y + rayonT, zNear, zFar);
The depth range gets longer, which is fine: 16 bits over a few hundred meters is still a few millimeters.
The sun drives the shadow
Since devlog 006 the sun follows the clock; the shadow follows the sun, with three twists.

Its strength fades with the light. The light of the sun is the visible fraction of its disk above the
horizon (the area of the segment, so half the disk = half the light), and the shadow strength follows a
smoothstep from "disk just set" to 1° above the horizon. When the light reaches 0 there is no shadow pass at
all: the sun → moon switch happens with nothing to render, and nothing jumps.
Its direction moves in steps. Texel snapping fixes the shimmering when the camera moves, not when the light rotates. A sun that turns continuously makes every shadow edge crawl, all the time. So the shadow direction is quantized — the lighting stays continuous, only the map moves in steps:
const F32 tq = floorf(timeOfDay * stepsPerDay) / stepsPerDay; // 3600 steps a day = 0.1°
setAstroShadowStep(deg) (0 = continuous, 4° max), or inga:shadowStep 1 0.5 at the console to judge by eye.
The strength is computed on the quantized direction, not the real one. That one came from a review: at sunrise, the quantized direction lags one step behind, and could still be below the horizon while the shadow was at full strength.
Seeing what the GPU sees: the debug tools
A shadow bug is hard to see from its result: a missing shadow, a light halo, acne — what caused it? Three commands were added (all Debug-only), written by Claude Code right after the CSM, to check it before going further.
inga:shadowDebug <id> <view> cascades [c]tints the scene by cascade: 0 red, 1 green, 2 blue, 3 yellow, blended at 50 % so the shadows stay readable underneath. Withc, only that cascade.inga:shadowMap <id> <view> [c]draws the atlas (or one tile, enlarged) in a corner of the window, in grey levels. It needs a second, non-comparison sampler on the atlas: through asampler2DShadowyou only get 0 or 1.inga:debugMode shadow <vp> <srcWin>draws the cascade boxes and the light direction in wireframe in the SOLID debug window.

In the atlas, the near cascade covers a few meters and shows the columns large; the far ones cover the whole island. Dark = close to the sun.

Also added along the way: inga:shadows on|off, inga:shadowBias <id> <depth> <slope> <normal>,
inga:shadowQuality <id> <atlas> <tile0> [tile1…], and log errors shown on screen — a refused setter used to be
visible only in the log file; now any LERROR (and warnings that ask for it) shows up under the FPS line, with
repeats muted.
The big cleanup: flush() from 800 lines to a list of passes
CRendererAral::flush() records the whole frame. After CSM, its shadow part alone was 871 lines. The next
step, 14.g (views × cascades, atlas packing, budget), was going to change exactly that part. Writing 14.g inside the
densest block, and then undoing it in a refactor, would have been twice the work. So the order was decided: CSM →
refactor → 14.g.
The rules of the refactor:
- pure extraction, no behavior change, no new feature during it;
- one function per pass, inputs and outputs explicit;
flush()becomes a readable list of calls; - barriers built from the state the previous pass left (
SImageState), as the tonemap pass already did; - no render graph: the order of the passes stays written in plain code, readable top to bottom.
Today flush() reads like this (simplified):
void CRendererAral::flush()
{
updateFrameUbo();
beginFrameRecording(cmdRender, shadowPass);
// upload: matrices + instances
SShadowPlan plan;
if(shadowPass)
{
prepareShadowPasses(fr, &plan); // splits, tiles, budget, matrices
for(U32 p = 0; p < plan.passCount; ++p)
recordShadowPass(cmdRender, fr, plan, p, ...);
finishShadowPasses(cmdRender, plan); // barrier → SHADER_READ, warnings
}
beginScenePass(cmdRender);
// per view: buildSceneKeys → recordSortedRuns; then the sky
// ...
SImageState state = recordTonemapPass(cmdPost, sc, kSwapchainAcquired);
state = screenshot->recordCopy(cmdPost, sc, ..., state);
state = recordDebugOverlayPass(cmdPost, sc, ..., state);
// barrier → PRESENT, submit
}
The profiler got a tool for it on the way: INGA_PROFILE_SECTIONS / INGA_PROFILE_NEXT split one long function
into successive zones without adding blocks — aral.flush.setup, .upload, .shadow, .scene, .post, .submit.
Proving nothing changed
"Pure extraction" has to be checked, not believed. Claude Code ran the A/B:
- two throw-away git worktrees, before and after, the same test patch in ProjectO: fixed camera, frozen time of day, capture at 5 s, quit at 35 s;
- a Release Profile build, GPU clock forced high, same window size on both sides;
tools/imgdiff.py before/ after/: identical to the bit;- profiler medians over 15 reports of 2 s, two runs in reverse order:
aral.flush83–84 → 88–96 µs,aral.flush.shadow25–26 → 28–30 µs (minimums identical, 23–24 µs),gpu.aral.scene258–266 → 260–261 µs. No regression established.
A first reference, taken the same morning, said aral.flush.shadow was 180–200 µs. It was a Debug build
(-O0 + ASan) with the clock running, so neither the images nor the timings were reproducible. New rule for every
A/B since: Release Profile and frozen time.
Several views, atlas packing and the pass budget
Step 14.g, written on top of the clean flush(). Each view (split screen, minimap, rear-view mirror) has its own
camera, so its own cascades. They all share one atlas and one budget.
Tile size follows the view
A quarter-screen view doesn't need a 2048 tile. The tile level is the smallest one that covers the largest side of the view in pixels; the first cascade gets it, the others one level below:
U32 CRendererAral::viewTileLevel(U32 view) const
{
const U32 dim = maxOf(viewWidthPx, viewHeightPx);
U32 level = shadowTileLevelCount - 1;
while(level > 0 && shadowTileSizes[level - 1] >= dim) { --level; }
return level;
}
A view without a camera gets no cascade and no pass.
Packing: one cursor in Morton order
Every tile size is a power of two that divides the atlas. That makes packing exact with a very small algorithm:
- sort the requests from largest to smallest;
- walk the atlas as a grid of the smallest tile, in Morton (Z-order), with one cursor;
- for each request of side
scells, round the cursor up to a multiple ofs², place the tile there, move the cursor bys².
In Z-order, any aligned square block of side s (a power of two) is exactly s² consecutive indices starting at a
multiple of s². So rounding the cursor up is enough to get an aligned tile, and with the sizes sorted, there is
never a hole or an overlap.
const U32 side = shadowTileSizes[r.level] / minTile; // in cells, power of 2
const U32 area = side * side;
const U32 start = (cursor + area - 1) / area * area; // aligned on its size
if(start + area <= cellCount)
{
mortonDecode(start, mortonBits, &p.x, &p.y); // cell → tile position
cursor = start + area;
}
else { /* drop one tile level and retry; at level 0, the pass is cut */ }
Nothing is ever freed: the whole layout is rebuilt every frame. It is a handful of tiles (96 at most), negligible next to the culling. When the atlas is full, the request drops one tile level; at the smallest level and still full, the pass is cut, with a warning in Debug. That's the same rule the local lights will use later.
The budget, and why a cut cascade can't be in the middle
One cascade = one pass, counted over all views: shadowPassBudget (32 by default). The order is view 0 first, then
cascades from near to far, so the far cascades of secondary views go first.
There is a catch: the shader picks its cascade from the pixel's depth, then reads that tile. If cascade 1 of a view was cut but cascade 2 was placed, a pixel in the middle distance would read a tile that doesn't exist. So for each view, only the prefix of placed cascades is kept (0, 0–1, 0–1–2…), and the shader is told how many there are. Beyond the prefix: no shadow, cleanly.
Two fixes from the CSM review
- The cascade border. The slice's sphere is inscribed in its tile; after snapping (up to 1 texel) and with the
PCF radius (up to 2 texels), an extreme point could read outside the tile rectangle — lit by mistake, a thin light
line at the cascade boundary. The radius is now inflated before projection:
rayonT *= tile / (tile − 2 · (pcfRadius + 1)). - The fade went towards
shadowDistance, but the last cascade ends atf = min(far, shadowDistance). The shader now fades towardsf, passed in the UBO.
Cost
Release Profile, RX 6800, same window as the refactor A/B:
aral.flush | aral.flush.shadow | aral.flush.scene | |
|---|---|---|---|
| ProjectO, 1 view, before 14.g | 85–89 µs | 26–28 µs | — |
| ProjectO, 1 view, after 14.g | 81–86 µs | 25–27 µs | — |
| InGaTester, 1 view | 215–230 µs | 110–118 µs | 37–40 µs |
| InGaTester, 4 views | 515–518 µs | 333–336 µs | 113–114 µs |
No regression on one view, and about 25 µs of CPU per shadow pass in the test world (2000 objects around Sponza). With the ×3 CPU factor from devlog 004, four views would be ~1 ms of shadow CPU on the Steam Deck — not measured yet. That's where the multithreaded recording of devlog 007 will matter.
In the test world
InGaTester again, with the shadows on: the 2000 generated objects around Sponza, and a whole day in a few seconds
(skyDuration 10 in the tester's console). The shadows sweep across the ground with the sun, the moon takes over
at night, and the camera goes inside Sponza and down among the objects.
Inside Sponza: the sun lights the upper part of the far wall, the building's own shadow cuts across it, and everything below is lit by the sky only:

Less memory for the visible lists
Each shadow pass culls and sorts its own list of visible objects, written into a GPU buffer. The first version
reserved one full slice per budgeted pass: 25.6 MiB with the defaults. Now all the shadow passes of a frame share one
region, shadowVisibleCapacity (131072 entries, 1.5 MiB). A pass that doesn't fit stays empty (its tile is just
cleared: no shadow, but nothing wrong drawn) and Debug says which value to raise.
The same scene in the old engine
Devlog 007 promised a comparison with greydog, my previous engine (PBR, 4-cascade CSM). Claude Code rebuilt greydog's
demo scene in InGa — ground, red cube, spheres, street lamps, sun at 25° — as a project kept in the repo,
GreydogBench. It will follow ARAL from step to step as a performance reference.
One fun detail: greydog draws everything mirrored horizontally (a left-handed frame on screen). To get the same image, the InGa scene sits under a node scaled by (−1, 1, 1). And greydog itself needed fixes to run in Release and to give numbers: a profiler by zones, and a camera that didn't copy its projection into the UBO after a resize.
Measured on the RX 6800, same window, MAILBOX, GPU saturated on both sides (so the GPU clock is at its max), two
runs of 20 s identical within ±2 %. Averages in µs:
| greydog | ARAL, same settings | ARAL, defaults | |
|---|---|---|---|
| shadow settings | 4 × 4096², 400 m | 4 × 4096², 400 m | 3 × 2048², 100 m |
| fps | 2303–2316 | 3150 | 4470 |
| CPU frame work | 115–117 | 62–64 | 62–64 |
| CPU shadows | 55–57 | 18 | 18 |
| CPU scene | 19–20 | 8 | 8 |
| GPU shadows | 242–245 | 123 | 33 |
| GPU scene | 142 | 142 | 139 |
| GPU sky | 22 | 1 | 1 |
| GPU final / tonemap | 17 | 32 (ACES) | 32 |
| GPU total | ~425 | ~298 | ~206 |
ARAL is faster everywhere except the last pass, and that one does more: greydog copies an LDR image with a gamma, ARAL tonemaps HDR, applies two LUTs and dithers. The GPU shadow time is halved at equal settings, for two reasons: casters culled per cascade (greydog draws everything in every cascade), and a D16 atlas instead of D32. The sky: greydog draws it full screen first, ARAL after the opaque objects, only where nothing was drawn (devlog 005).
It's not a final verdict — lighting and HDR formats are not aligned — but the shadow part, which is what this step was about, is a fair comparison. And no shadow disappears in ARAL where greydog lost them.
Bonus: the scene no longer waits for the screen
Step 15, small and done the same day. Until now, a frame was one command buffer: shadows, scene, sky, MSAA resolve, then tonemap and overlay into the swapchain image. It waited on the "image available" semaphore at the color output stage — for all of its commands. But only the tonemap and the overlay write the swapchain image. The scene was waiting for a screen image it doesn't touch.
Now the frame is two command buffers in one vkQueueSubmit2, with two VkSubmitInfo2:
| batch | command buffer | contains | waits for the image? |
|---|---|---|---|
| 1 | cmdRender | shadows, scene, sky, resolve | no |
| 2 | cmdPost | tonemap, screenshot, overlay, barrier to PRESENT | yes |
Two submit infos of the same submit run in order on the queue, so the barriers of batch 2 still see the writes of
batch 1. The second command buffer already existed: it was the old cmd_world, unused since devlog 007 dropped the
static / dynamic split.
Results: images identical to the bit in FIFO and MAILBOX, 14 / 14 tests pass with synchronization validation on
(and the validation does complain if the two batches are swapped on purpose, which proves it was watching).
On the RX 6800 the gain doesn't show: in FIFO it's the CPU that waits, 16.5 ms in vk.acquire, and by the time the
GPU gets the work, the image is free (a new GPU zone, gpu.aral.acquire, measures ~6 µs). The gain is for
machines where the GPU arrives before the image: on the StarLite, a small Intel laptop, gpu.aral.scene was 3375 µs in FIFO against
1262 µs without vsync — the difference was waiting, counted as scene. The Deck measurement of the next step would
have been wrong without this.
Little problems
- A stale direction. Turning slot 0 off kept the old shadow direction alive: the validity flag is now reset every frame.
- A hang on a null mesh. In the shadow draw loop, a
continueon a missing mesh skipped the increment of the loop index. SameINGA_ASSERTas the scene pass now. - Shadow strength at sunrise — computed on the quantized direction, see above.
- View 0 without a camera crashed the shadow setup: tested per view now.
- A validation warning still open: the shadow pipeline reuses the PBR vertex description (4 attributes) while
shadow.vertonly reads location 0. Harmless (the image is right), one line to fix, and it was found thanks to the on-screen warnings above. - Debug numbers are not numbers: see the refactor A/B.
The console, for shadows
inga:shadows 1 off
inga:shadowStep 1 0.5
inga:shadowBias 1 1.25 1.75 1.5
inga:shadowQuality 1 8192 512 1024 2048 4096
inga:shadowDebug 1 0 cascades
inga:shadowMap 1 0 2Tested on
AMD RX 6800 (RADV), Linux / Wayland. The Steam Deck is the next step.
Next step
Step 16, the milestone (it was "14.h" in devlog 007): the Steam Deck measurement with shadows off / one cascade / three cascades, the comparison with the Blender capture of the reference scene — lit on both sides at last — and the greydog scene checked for lost shadows.