Shadows

sun

-140

°

filter149

size25610242048

Set 256 texels and compare one, four or nine shadow comparisons. The map spans 9 units around a 0.3-unit-wide pillar; extra comparisons soften its stepped shadow.

Without shadows, a floating block can appear to rest on the floor. A lighting with a shadow group creates light.shadow, which records depth from the sun. Add each caster to it as you add drawings to the scene, and record it each frame before the passes that shade:

const light = lighting.create(root, {
  settings: { sunDirection: [-0.6, 1, -0.7] },
  shadow: { extent: 9 },
});
const scene = passes
  .create(root, screen, { hdr: passes.color, depth: passes.depth })
  .pipe(view.inject())
  .beneath(light.inject());
const renderer = things.renderer();
const drawn = scene.add(renderer);
const cast = light.shadow.add(renderer);

frames.animate(
  frames.create(root, (frame) => {
    things.flush();
    light.shadow.record(frame, cast);
    scene.record(frame, drawn);
  }),
);

• light.shadow.add(renderer) builds depth pipelines with bias against self-shadowing. cast.destroy() removes the caster and frees them.
• await light.shadow.initAsync() while loading compiles every caster added.
• The map covers a square extent world units wide, centred on center. Outside it, surfaces are lit. Wider coverage spreads each texel over more ground: Blockfall covers its well with 2048 texels across 16 units, about 1/128 of a block per texel.
• The shadow follows sunDirection. A direction written to light.settings turns it at its next record. Call aim(direction) to cast from elsewhere.
• Time the pass with a profiler as record(frame, casters, { timestampWrites: shadow.writes() }). A frame that draws no cascade writes the timer from an empty compute pass.
• A layer of the map takes size² × 2 bytes in depth16unorm and size² × 4 in the other formats.

Cascades fitted to the view

stampede4 096 horses under sun cascades, skinned nearby and cards farther off, easing into a gallop when frightened.

PauseOpen the full example

Click a horse to ride beside it. Its legs cast sharp shadows from the nearest cascade while the trees on the far slopes cast theirs from the last.

One square sharp enough for a horse’s legs covers a few dozen metres. Give the shadow an eye and it splits the view into cascades, each a layer of one map. The nearest covers the first metres in front of the camera, and each later one covers more ground with the same texels. record fits them to the camera each frame:

const view = cameras.orbit(root, { size: surface, target: [0, 1, 0], distance: 12 });
const light = lighting.create(root, {
  settings: { sunDirection: [0.6, 0.35, 0.3] },
  shadow: { eye: view, cascades: 3, far: 120 },
});
const scene = passes
  .create(root, screen, { hdr: passes.color, depth: passes.depth })
  .pipe(view.inject())
  .beneath(light.inject());
const renderer = things.renderer();
const drawn = scene.add(renderer);
const cast = light.shadow.add(renderer);

frames.animate(
  frames.create(root, (frame) => {
    view.update(frame.dt);
    things.flush();
    light.shadow.record(frame, cast); // a depth pass per cascade
    scene.record(frame, drawn);
  }),
);

• eye takes a camera with a CPU view: cameras.orbit, cameras.flat or cameras.custom. Update it before record.
• The split after cascade k lies at far × (k / cascades)², 11% and 44% of far for three. splits: [0.08, 0.3] places them as fractions of far instead.
• record fits a sphere around each slice of the view and snaps its centre to whole texels. The sphere keeps its size as the camera turns, so shadow edges hold still.
• reach is how far each cascade reaches towards the sun beyond its slice. A caster farther towards the sun casts nothing.
• cascades, far and splits need an eye, and extent and center take none. Type checking refuses the other combinations, and create throws for them. cascades: 1 fits one map to the view.

Casters draw once per cascade through the pipelines a single map builds. An instances renderer with cull: true culls every cascade in one pair of dispatches. Shading picks the first cascade whose square holds the point and switches cascades without a blend. A finished look for model scenes sizes two cascades for a scene of glTF models.

Drawing less

record clears and draws every cascade each frame. Casters that hold still under a still sun draw the same depth again. Pass redraw to choose the cascades that draw this frame. The others keep the layer they drew last:

// Set when a caster moves, from your own game state
let stirred = true;

frames.create(root, (frame) => {
  light.shadow.record(frame, cast, { redraw: () => stirred });
  stirred = false;
});

A cascade draws anyway the first time record runs and whenever its place changes: when a fitted shadow’s eye moves, when the sun turns, after aim, follow, setExtent, setFar or resize, and after a frame with the shadow off. A skipped cascade shows casters where they stood when it last drew.

Casters that never move, such as terrain or a reef, need no state of their own. A redraw that always answers false draws the shadow once and again only when its place changes:

const still = { redraw: () => false };

frames.create(root, (frame) => {
  light.shadow.record(frame, cast, still);
});

Your own casters

Add a custom caster as a drawing to light.shadow. Supply a Vertex with a clip-space position, an at function producing it and a draw function. The shadow fills the kit’s cameras.current with the sun’s view, so scene vertex functions cast without changes:

const statue = meshes.unindexed(meshes.box());
const Corner = d.struct({ position: d.vec4f });

const cast = light.shadow.add({
  Vertex: Corner,
  at: (vertexIndex: number, _instanceIndex: number) => {
    'use gpu';
    const world = statue.vertexAt(vertexIndex).position + d.vec3f(0, 1, 0);
    return Corner({ position: cameras.current.$.viewProjection * d.vec4f(world, 1) });
  },
  draw: (pass) => pass.draw(statue.vertexCount),
});

light.shadow.record(frame, cast); // each frame

• Depth-only drawings need neither surfaceOf nor color, and build no fragment stage. With surfaceOf and depthOf, a drawing can supply another point’s depth, as impostors do.
• A drawing with cutout, such as a sprite whose texture is clear around its figure, casts the figure’s shadow. The shadow pass runs cutout alone, so the same drawing goes into the shadow map even when its surfaceOf reads the lighting.
• Instances cut out by masked meshes or by their kind’s coverage cast through it the same way, at their own depth.
• Supply an index buffer as indices for drawIndexed and fill shader dependencies with inject().

Your own sun shadow

shade takes the share of sunlight at a point from the sunShadow hook. The default, shadows.filtered, compares the point with the map: it moves the point lift texels along its normal, makes 1, 4 or 9 comparisons as filter sets, and returns their mean, from 0 in shadow to 1 in light. A hook of your own can change that share. The fishtank multiplies shadows.filtered(point) by its caustics. This one blends across the edge of a cascade:

const blended: shading.SunShadowHook = (point) => {
  'use gpu';
  const at = shadows.cascadeOf(point); // index -1 outside every cascade
  const lit = shadows.cascaded(point, at.index);
  if (at.edge <= 0) return lit;
  return std.mix(lit, shadows.cascaded(point, at.index + 1), at.edge);
};
const light = lighting.create(root, {
  shadow: { eye: view, cascades: 3 },
  shading: { sunShadow: blended },
});

• cascadeOf(point) returns the first cascade holding the point, inset by the filter’s half width and lift, and an edge rising from 0 to 1 over the outer 10% of its square.
• cascaded(point, index) filters cascade index. It returns 1 for a point outside that cascade and for an index outside the cascades, so the last cascade blends into sunlight.
• shading.sunShare(point) returns what the hook gives, for shaders that don’t call shade. The domino run’s dust brightens in sunlight with it.

Turning it off

The shadow group’s enabled callback turns the shadow on and off each frame, as for other pass descriptions. A quality menu can change its value without a second lighting:

const menu = { shadows: true };
const light = lighting.create(root, { shadow: { enabled: () => menu.shadows } });

• While it is off, record records no pass, culling lists stay empty and shadows.filtered returns 1 without sampling the map.
• The map and pipelines stay allocated, so shadows draw on the first frame after it turns on.

Resizing the map

resize(size) replaces the map between frames:

• Put light.shadow.part in a shared layout before creating pipelines, as bindings.share(root, { shadow: light.shadow.part }), and give it to the lit description as shared.
• The next frame then makes one bind group and no pipelines. The shadow’s own passes don’t read the map, so they need no group.
• Without a shared layout, shading pipelines bind the map as fixed resources, and resize throws before it changes anything.

Point and spot shadows

night-marketA seller raises her lantern for a customer out of the rain; the potions are in focus and the market's lights blur into discs.

PauseOpen the full example

Turn shadows off to let the lamps shine through the table onto the cobbles beneath it. The seller's lamp throws the potions' shadows along the table. Raise the wind to swing the lantern under the string of lights; its shadows swing with it.

A pointShadow group creates light.pointShadow, which gives up to count lights of the lighting’s table a shadow each. cast picks the lights:

import { lighting, table } from '@typegpu/kit';

const lamps = table.create(root, lighting.SpotLight, {
  capacity: 16,
  defaults: { ...lighting.WHITE_SPOT },
});
const light = lighting.create(root, { points: { table: lamps }, pointShadow: { count: 2 } });
const fire = lamps.add({ position: [0, 0.8, 0], color: [1, 0.45, 0.15], intensity: 8, range: 14 });
const sign = lamps.add({
  position: [3, 4, 1],
  aim: [0, -1, 0.3],
  cone: lighting.cone(0.3, 0.45),
  intensity: 30,
  range: 10,
});
light.pointShadow.cast([fire, sign]); // six faces for the fire, one layer for the sign

const scene = passes
  .create(root, screen, { hdr: passes.color, depth: passes.depth })
  .pipe(view.inject())
  .beneath(light.inject());
const renderer = things.renderer();
const drawn = scene.add(renderer);
const casters = light.pointShadow.add(renderer);

frames.animate(
  frames.create(root, (frame) => {
    things.flush();
    lamps.flush();
    light.pointShadow.record(frame, casters); // seven depth passes
    scene.record(frame, drawn);
  }),
);

• Each shadow holds six layers of one texture_depth_2d_array.
• cast(lights) gives a shadow to each light in the list, at most count. A light that already casts keeps its shadow, a light left out frees its own, and a new one takes a free shadow. Casting the same lights again writes nothing, so you can cast from the lamps nearest the eye every frame.
• A spot whose outer half-angle is at most 60° draws one layer, a perspective view along its aim. A wider spot or a point light draws six faces. Each face covers 90° plus the filter’s half width, so the filter at a face’s edge stays inside that face.
• record places each shadow at its light’s row in the table, so a light moved on the CPU needs no other call. A removed light frees its shadow.
• Near is 2% of the light’s range and far is range.
• filter, format, bias, enabled and resize work as the sun’s do. lift moves the shaded point along its normal by that many texels at its distance from the light. Share light.pointShadow.part as bindings.share(root, { pointShadow: light.pointShadow.part }) to resize without new pipelines.
• A layer takes size² × 2 bytes in depth16unorm and size² × 4 in the other formats.

The default attenuation, shading.reaching, multiplies in shadows.shadowed(point, toLight, distance, slot), which a hook of your own can call too. For each light in range, shading compares its slot with each of the count shadows. A shadowed light picks a face from the direction to the point, takes one matrix product and makes the filter’s comparisons.

Lights that hold still

Each layer is a depth pass that draws every caster, so seven layers cost seven passes each frame. A lamp that holds still over casters that hold still draws the same layers again. Pass redraw to choose the lights that draw this frame. The others keep the layers they drew last:

// Lamps with a caster that moved within their range this frame, from your own game state
const stirred = new Set<unknown>();

frames.create(root, (frame) => {
  lamps.flush();
  light.pointShadow.record(frame, casters, { redraw: (lamp) => stirred.has(lamp) });
  stirred.clear();
});

• A light draws anyway on the frame it gains a shadow, when its row moves, turns or changes range, after resize, and after a frame with the shadows off. A light whose flicker jitters its position draws every frame; flicker its intensity alone to keep its layers.
• A frame that draws no layer writes a timer passed in timestampWrites from an empty compute pass, so a profiler timer can stay on record.

Limits

• A fixed map’s depth spans twice reach. At an extent of 20, a depth16unorm step is about 0.001 world units. A cascade’s depth spans its sphere’s width plus reach.
• Cascades fit the camera’s view, not the casters. A caster beyond reach towards the sun casts nothing, and nothing beyond far is shadowed.
• The filter is fixed at creation. A menu offering different filters needs a separate lighting for each.
• Only lights placed on the CPU cast. lighting.create throws for pointShadow without points.table, or with a table of lighting.MovingPointLight or MovingSpotLight.
• Each layer that draws draws all its casters: six passes for a point light and one for a narrow spot.
• count is at most 42 at WebGPU’s minimum of 256 layers. Shading compares every in-range light with every shadow, so its cost grows with count.