008 — Shadow Maps: Atlas, Cascades, a Sun That Moves, and a Big Cleanup

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.

The reference scene made in Blender, rendered by ARAL with the sun's shadows

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:

  1. the atlas and the first map (14.b, 14.c)
  2. reading it in the shader (14.d)
  3. cascades (14.e)
  4. the sun driving the shadow (14.f)
  5. debug tools
  6. the refactor
  7. several views, packing and budget (14.g)
  8. the comparison with the old engine
  9. 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 with setShadowQuality(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_OPTIMAL and 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 one vec4 — that's why kMaxAralCascades = 4.
  • The normal offset is in texels, not meters (shadowNormalOffset = 1.5 by 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 — four sampler2DShadow reads, 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.

Low light, long shadows

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. With c, 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 a sampler2DShadow you 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.

Cascades tinted (red, green, blue) and the atlas in the corner: the near cascade in the big tile, the farther ones in smaller tiles

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.

The atlas at dusk, earlier in the week, before the per-view packing

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.flush 83–84 → 88–96 µs, aral.flush.shadow 25–26 → 28–30 µs (minimums identical, 23–24 µs), gpu.aral.scene 258–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:

  1. sort the requests from largest to smallest;
  2. walk the atlas as a grid of the smallest tile, in Morton (Z-order), with one cursor;
  3. for each request of side s cells, round the cursor up to a multiple of s², place the tile there, move the cursor by s².

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 at f = min(far, shadowDistance). The shader now fades towards f, passed in the UBO.

Cost

Release Profile, RX 6800, same window as the refactor A/B:

aral.flusharal.flush.shadowaral.flush.scene
ProjectO, 1 view, before 14.g85–89 µs26–28 µs—
ProjectO, 1 view, after 14.g81–86 µs25–27 µs—
InGaTester, 1 view215–230 µs110–118 µs37–40 µs
InGaTester, 4 views515–518 µs333–336 µs113–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:

Sponza in ARAL with the sun's shadows

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:

greydogARAL, same settingsARAL, defaults
shadow settings4 × 4096², 400 m4 × 4096², 400 m3 × 2048², 100 m
fps2303–231631504470
CPU frame work115–11762–6462–64
CPU shadows55–571818
CPU scene19–2088
GPU shadows242–24512333
GPU scene142142139
GPU sky2211
GPU final / tonemap1732 (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:

batchcommand buffercontainswaits for the image?
1cmdRendershadows, scene, sky, resolveno
2cmdPosttonemap, screenshot, overlay, barrier to PRESENTyes

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 continue on a missing mesh skipped the increment of the loop index. Same INGA_ASSERT as 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.vert only 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 2

Tested 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.