@typegpu/radiance-cascades

@typegpu/radiance-cascades computes lighting for 2D scenes. You describe the scene with GPU functions, and the package gives you back a texture holding the light that reaches every pixel. All that is left is to sample it in your own rendering shader.

There are two runners to choose from:

• Holographic (@typegpu/radiance-cascades/holographic) lights a grid of pixels that emit and absorb light. It suits raster scenes, thin occluders and participating media such as fog or smoke.
• SDF (@typegpu/radiance-cascades) traces rays through a signed distance function. It suits analytic shapes and custom tracing.

The same scene as a grid of materials and as a distance function

Both runners share the same lifecycle, which is described in Updating lighting.

Holographic radiance cascades

The holographic runner traces short segments through the pixel grid and merges them into longer paths, so it does not need a distance function at all.

Basic usage

This scene has a warm, opaque emitter on the left and a wall with a gap in the middle:

import * as hrc from '@typegpu/radiance-cascades/holographic';
import { tgpu, d, std } from 'typegpu';

const root = await tgpu.init();

const runner = hrc.create({
  root,
  size: { width: 512, height: 512 },
  medium: (pixel) => {
    'use gpu';
    const position = d.vec2f(pixel) + 0.5;
    if (std.length(position - d.vec2f(128, 256)) < 12) {
      return { emission: d.vec3f(16, 8, 4), extinction: 16 };
    }
    if (pixel.x === 256 && (pixel.y < 240 || pixel.y > 272)) {
      return { emission: d.vec3f(), extinction: 16 };
    }
    return { emission: d.vec3f(), extinction: 0 };
  },
});

runner.run();

const lightView = runner.output.createView(d.texture2d());

runner.run() submits the lighting update. Afterwards, runner.output holds the light reaching each pixel: the wall at x = 256 blocks it everywhere except the gap between rows 240 and 272. Using the lighting shows how to combine it with your scene.

Scene inputs

The medium callback receives integer pixel coordinates and describes what that single pixel is made of.

Input	Meaning
size	Material grid and lighting texture dimensions in pixels
medium(pixel)	Emitted light and extinction of one pixel
transmission	'scalar' (default) for one extinction value, or 'rgb' for one per channel
source(pixel, incident)	Optional extra emission; see Sources and scattering
tracedLevels	Cascade levels traced directly before merging; see Quality and cost

Emission is linear radiance added per pixel of travel. Extinction controls how quickly light fades while it travels through a pixel. It is a nonnegative value in inverse pixels: after s pixels, a fraction of the light is left. In other words, every 1 / extinction pixels, the light drops to about 37% of what it was.

How much light is left after traveling through each medium

A few common materials look like this:

Material	Emission	Extinction
Empty	[0, 0, 0]	0
Nearly opaque wall	[0, 0, 0]	16
Nearly opaque warm emitter	[16, 8, 4]	16
Transparent glowing gas	[0.01, 0.005, 0]	0

An opaque emitter appears with radiance emission / extinction, so the warm emitter above shows up as [1, 0.5, 0.25]. Extinction 16 lets through about 10⁻⁷ of the light crossing one pixel, which is opaque for all practical purposes. (Use finite values, since infinity is not treated as fully opaque.)

The medium callback runs many times per pixel, so for anything more expensive than a few shapes, it is worth rasterizing the scene into a texture first and reading it back:

const runner = hrc.create({
  root,
  size: { width: 512, height: 512 },
  medium: (pixel) => {
    'use gpu';
    const material = std.textureLoad(materialView.$, pixel, 0);
    return { emission: material.rgb, extinction: material.a };
  },
});

Colored transmission

By default, extinction is a single number, so every color channel fades at the same rate. With transmission: 'rgb', extinction becomes a vec3f and each channel is attenuated separately:

const runner = hrc.create({
  root,
  size: { width: 512, height: 512 },
  transmission: 'rgb',
  medium: (pixel) => {
    'use gpu';
    return {
      emission: std.textureLoad(emissionView.$, pixel, 0).rgb,
      extinction: std.textureLoad(extinctionView.$, pixel, 0).rgb,
    };
  },
});

To get transmission T through a thickness of s pixels, use extinction = -log(T) / s per channel. For example, [0.9, 0.1, 0.01] over 10 pixels gives roughly [0.0105, 0.2303, 0.4605], which turns white light red:

Each channel fades at its own rate, so white light comes out red

Light still travels in straight lines (there is no refraction or dispersion).

Sources and scattering

A medium emits the same light no matter how brightly it is lit. For light that depends on the lighting itself, such as fog glowing where a beam passes through it, add a source callback. It receives a pixel and incident (the light arriving at that pixel) and returns extra emission for it.

The arriving light is not known until the lighting is computed, so run({ iterations }) computes it several times. On the first pass, source receives zero incident, so fog adds nothing and only direct light appears. Each later pass gives source the previous pass’s lighting (the same values as runner.output), which adds one more bounce:

Each pass feeds the previous pass's lighting to source as incident

Every run() starts over from darkness, so bounces do not carry over between runs.

A scattering medium, such as fog or smoke, does two things: it takes light out of every beam passing through it, and sends that light out again in new directions. For isotropic scattering, where light leaves equally in all directions, we cover the first part by adding the scattering coefficient to extinction, and the second by returning it multiplied by incident from source:

const runner = hrc.create({
  root,
  size: { width: 512, height: 512 },
  transmission: 'rgb',
  medium: (pixel) => {
    'use gpu';
    const material = std.textureLoad(mediumView.$, pixel, 0);
    return {
      emission: std.textureLoad(emissionView.$, pixel, 0).rgb,
      extinction: material.rgb + material.a,
    };
  },
  source: (pixel, incident) => {
    'use gpu';
    return std.textureLoad(mediumView.$, pixel, 0).a * incident;
  },
});

runner.run({ iterations: 3 });

Here mediumView stores absorption in .rgb and scattering in .a, both in inverse pixels like extinction. Three iterations give direct light plus two bounces; thick media need more iterations before the result stops changing.

incident is averaged over all directions, so source cannot tell where the light came from. That is enough for isotropic scattering, but not for media that scatter mostly forward or backward. Neither callback may read runner.output or runner.sectors; use incident instead.

Caution

The runner does not check that energy is conserved. If source returns more light than the medium removes, the scene gets brighter with every iteration.

Using the lighting

runner.output is a texture covering the whole grid, holding the light that reaches each pixel. To use it, sample it with the same uv as your scene: solid parts of the scene keep their own color, and the light shows everywhere else.

const lightView = runner.output.createView(d.texture2d());
const sampler = root.createSampler({ magFilter: 'linear', minFilter: 'linear' });

const fragment = tgpu.fragmentFn({ in: { uv: d.vec2f }, out: d.vec4f })(({ uv }) => {
  'use gpu';
  const scene = std.textureSampleLevel(sceneView.$, sampler.$, uv, 0);
  const light = std.textureSampleLevel(lightView.$, sampler.$, uv, 0).rgb;
  return d.vec4f(scene.rgb + light * (1 - scene.a), 1);
});

Here sceneView holds what you drew, with alpha 1 on solid pixels. The light values are linear and can go above 1 near bright emitters, so if they look blown out, scale them down or apply tone mapping before returning.

Light from each direction

Most scenes only need output. When you also need to know which way the light comes from (for example, to shade a surface by its normal), use runner.sectors. It is a texture array whose four layers each hold the light arriving from one side (+Y points down):

Each layer holds the light arriving from one side

const sectorsView = runner.sectors.createView(d.texture2dArray());

// in a shader
const fromAbove = std.textureSampleLevel(sectorsView.$, sampler.$, uv, 3, 0).rgb;

The four layers add up to output before its smoothing. The Holographic Global Illumination example uses them to light surfaces by their normals.

Both textures are rgba16float and are owned by the runner, which destroys them when you call destroy().

Quality and cost

size controls both the material grid and the lighting resolution. Intermediate intervals are kept for the reconstruction, so memory grows as O(N² log N). For scalar transmission without a source:

Resolution	Memory
256×256	9 MiB
512×512	38 MiB
1024×1024	160 MiB
2048×2048	672 MiB

RGB transmission stores 12 bytes per interval instead of 8, and a source adds 8 bytes per pixel and one dispatch per iteration. runner.byteSize reports the exact allocation for the current configuration.

Light is gathered along intervals that double in length from one cascade level to the next. tracedLevels sets how many of the shortest levels read the medium directly; each longer interval is joined from two intervals of the level below. The default of 3 traces spans of 1, 2 and 4 pixels:

Short intervals read the medium; longer ones are joined from two shorter ones

Shorter intervals end only on every other pixel row. A join is exact when the straight path’s midpoint lands on one of those ends; otherwise, the runner averages two bent paths through the ends on either side:

Where the straight path misses an interval end, two bent paths stand in for it

Each extra traced level doubles the longest traced span, which means more medium reads and fewer approximate joins, for the same memory.

Limitations

• The domain is finite, with a black exterior.
• Emission is isotropic, and surface reflection and refraction are not built in.
• Long paths and the reconstruction are approximate, and half-precision storage limits accuracy in very dim and high-dynamic-range scenes.
• Both dimensions must be at least 2 pixels.

SDF radiance cascades

The SDF runner traces rays through a signed distance function. The built-in tracer treats surfaces as opaque, so surface reflection and additional light bounces are up to your application logic.

Basic usage

This scene has two glowing shapes, a disk and a wall, whose emission blends from warm on the left to cool on the right:

import * as rc from '@typegpu/radiance-cascades';
import * as sdf from '@typegpu/sdf';
import { tgpu, d, std } from 'typegpu';

const root = await tgpu.init();
const previewSize = { width: 512, height: 512 };

const sceneSdf = tgpu.fn([d.vec2f], d.f32)((uv) => {
  'use gpu';
  const circle = sdf.sdDisk(uv - d.vec2f(0.5), 0.18);
  const wall = sdf.sdRoundedBox2d(uv - d.vec2f(0.5, 0.82), d.vec2f(0.42, 0.03), 0.01);
  return sdf.opUnion(circle, wall);
});

const emission = tgpu.fn([d.vec2f], d.vec3f)((uv) => {
  'use gpu';
  return std.mix(d.vec3f(1, 0.82, 0.5), d.vec3f(0.28, 0.52, 1), uv.x);
});

const runner = rc.create({
  root,
  size: previewSize,
  sdfResolution: { width: 1024, height: 1024 },
  sdf: sceneSdf,
  emission,
});

runner.run();

const radianceView = runner.output.createView(d.texture2d());
const sampler = root.createSampler({ magFilter: 'linear', minFilter: 'linear' });

const renderPreview = tgpu.fn([d.vec2f], d.vec4f)((uv) => {
  'use gpu';
  const dist = sceneSdf(uv);
  const edge = std.max(std.fwidth(dist), 0.001);
  const surface = 1 - std.smoothstep(-edge, edge, dist);
  const radiance = std.textureSampleLevel(radianceView.$, sampler.$, uv, 0).xyz;

  const bg = std.mix(d.vec3f(0.04, 0.05, 0.07), d.vec3f(0.11, 0.15, 0.22), uv.y);
  const lit = bg + radiance * 1.55;
  const color = std.mix(lit, emission(uv), surface);

  return d.vec4f(std.min(color, d.vec3f(1)), 1);
});

Just like in Using the lighting, renderPreview draws the shapes with their own color and shows the light everywhere else.

Scene inputs

The scene callbacks receive uv coordinates from 0 to 1 on each axis.

Input	Meaning
size	Lighting texture dimensions in pixels; these can be smaller than the canvas
sdf(uv)	Distance to the nearest surface: positive outside, zero on the surface, negative inside
emission(uv)	Emitted light in linear RGB, not material color; zero for a non-emitting obstacle, with values above 1 allowed
sdfResolution	Dimensions of the distance texture; for an analytic function, use the resolution at which you want to resolve surface detail

Distances are positive outside, 0 on the surface and negative inside

While uv runs from 0 to 1 along both axes, distances are measured in units of the shorter side, so in a 1024 × 512 scene, 10 pixels is 10 / 512. Generated distance textures use the same units. sdfResolution sets the minimum hit tolerance and step size (it does not allocate a distance texture).

For rectangular scenes, the scene aspect defaults to the output texture’s width divided by its height. Set renderAspect if your lighting texture has a different aspect from the scene; for example, a square lighting texture covering a 1024 × 512 scene needs renderAspect: 2.

Output textures

By default, runner.output is an rgba16float texture with storage and sampled usage. You can also bring your own output texture or storage view. The runner destroys its own output when you call destroy(), but caller-supplied output remains yours to release.

const output = root
  .createTexture({
    size: [width, height],
    format: 'rgba16float',
  })
  .$usage('storage', 'sampled');

const runner = rc.create({
  root,
  output,
  sdfResolution,
  sdf: sceneSdf,
  emission,
});

When a storage view cannot provide its size, pass size explicitly alongside output.

Image-based scenes

For scenes drawn into an image, @typegpu/sdf can generate the distance texture for you. In this example, alpha marks solid pixels and RGB stores their emitted light.

import * as rc from '@typegpu/radiance-cascades';
import * as sdf from '@typegpu/sdf';
import { tgpu, d, std } from 'typegpu';

const root = await tgpu.init();
const floodSize = { width: 2048, height: 2048 };
const previewSize = { width: 512, height: 512 };

const sourceTexture = root
  .createTexture({
    size: [floodSize.width, floodSize.height],
    format: 'rgba8unorm',
  })
  .$usage('storage', 'sampled');

// Fill sourceTexture with the scene before running the lighting update
const sourceView = sourceTexture.createView();

const floodRunner = sdf.createJumpFlood({
  root,
  size: floodSize,

  classify: (coord) => {
    'use gpu';
    return std.textureLoad(sourceView.$, coord, 0).w > 0.5;
  },

  getSdf: (_coord, size, signedDist) => {
    'use gpu';
    return signedDist / d.f32(std.min(size.x, size.y));
  },

  getColor: (_coord, _size, _signedDist, insidePx) => {
    'use gpu';
    const source = std.textureLoad(sourceView.$, insidePx, 0);
    return d.vec4f(source.xyz, 1);
  },
});

const floodSdfView = floodRunner.sdfOutput.createView();
const floodColorView = floodRunner.colorOutput.createView();
const sampler = root.createSampler({ magFilter: 'linear', minFilter: 'linear' });

const runner = rc.create({
  root,
  size: previewSize,
  sdfResolution: floodSize,

  sdf: (uv) => {
    'use gpu';
    return std.textureSampleLevel(floodSdfView.$, sampler.$, uv, 0).x;
  },

  emission: (uv) => {
    'use gpu';
    return std.textureSampleLevel(floodColorView.$, sampler.$, uv, 0).xyz;
  },
});

function updateLighting() {
  floodRunner.run();
  runner.run();
}

updateLighting();

Call updateLighting() again whenever you edit the source image.

Quality and cost

size controls the lighting resolution. A smaller texture costs less, but resolves less spatial detail. baseStoredRayDim sets how many directions each lighting sample traces, independently of that resolution:

Directions traced by each probe at the finest lighting resolution

More directions can help with small lights and thin obstacles, but the improvement depends on the scene, so compare the result before increasing this setting. Each step also doubles the internal textures on each axis: at 4, a lighting texture with a diagonal of 4096 pixels or more exceeds the default 8192-pixel texture size limit.

mergeMode offers a separate quality/cost trade-off:

• 'hardware' (default) uses the faster interpolation path.
• 'bilinear-fix' performs additional visibility checks, which can reduce light leaking around obstacles at a higher cost.

Advanced usage

Tracing controls

These settings adjust how the built-in tracer finds surfaces:

Option	Default	Effect
maxRaySteps	64	Maximum steps along each ray; raising it permits more tracing work
stepSafety	1	Step multiplier in (0, 1]; smaller values take shorter steps and may need a larger step budget
erodeBiasProbes	1	Shrinks every obstacle by this distance before tracing, which reduces self-shadowing but can lose thin features
epsProbes	0.25	Surface hit tolerance; increasing it accepts hits farther from the surface
minStepProbes	0.125	Minimum step length; above epsProbes × stepSafety it reduces work near surfaces but can skip thin features

Each circle reaches the nearest shrunk obstacle, and the ray steps to its edge

The three distances ending in Probes use lighting-sample spacing as their unit: 1 is the distance between neighboring samples at the finest lighting resolution. The hit tolerance and minimum step are also limited by sdfResolution, so going below the source texture’s detail level has no effect.

Custom tracing

When you need different light transport, such as attenuation or partial transmission, you can replace the built-in tracer with a rayMarch callback. It is used in both merge modes and receives a ray and the segment to trace:

rayMarch(origin, direction, startT, endT, eps, minStep, bias);

Trace positions with origin + direction * t, for t between startT and endT. The distances use the same scene units as sdf. The runner supplies eps, minStep and bias from the tracing controls above. The diagram in that section shows how the built-in tracer uses them, but your callback may use them differently or ignore them altogether. maxRaySteps and stepSafety only control the built-in tracer.

Return rc.RayMarchResult({ color, transmittance }):

• color is the linear RGB light accumulated over that segment.
• transmittance is the fraction of light that passes through the segment: 1 for fully transparent, 0 for fully opaque, or a value between them.

Tracing utilities

These exports are useful when writing a custom tracer:

Export	Purpose
defaultRayMarch	The built-in ray marcher used by the runner
RayMarchResult	Return struct for custom ray marchers
sdfSlot, emissionSlot, rayMarchSlot	Scene functions used by the built-in tracer
maxRayStepsAccess, rayMarchStepSafetyAccess	Built-in tracing controls

The package source contains the implementation.

Updating lighting

Create a runner once and call run() whenever the buffers or textures read by its scene callbacks change. Each call submits a lighting update. If the size or configuration changes, call destroy() and create a new runner.

To prepare the GPU pipelines ahead of the first update, use await runner.initAsync(). This is optional (initSync() provides a synchronous alternative).

To record an update without submitting it, pass a command encoder and submit it yourself after recording the rest of your frame. The SDF runner takes run(encoder). The holographic runner takes run({ encoder }), or run({ pass }) to record into an open compute pass, and also accepts raw WebGPU encoders and passes:

const encoder = root['~unstable'].createCommandEncoder();
const pass = encoder.beginComputePass();
producer.with(pass).dispatchWorkgroups(64, 64);
runner.run({ pass });
pass.end();
encoder.submit();

If a callback uses an explicit bind group layout, attach its resources with runner.with(bindGroup) and use the returned runner. Captured TypeGPU views, samplers and accessors are bound automatically.

Examples

• Holographic Radiance Cascades (with drawing) paints emitters and occluders into a texture that serves as the medium.
• Holographic Global Illumination lights surfaces from sectors and adds diffuse bounces.
• Radiance Cascades is a from-scratch implementation of the algorithm, independent of this package.