impr: Radiance Cascades v2

[reczkok]

• Better cascade sizing with per-layer info
• Handles non-square render targets better
• Adds configurable ray density
• Uses Morton ray order for nicer sampling
• Adds fast and higher-quality merge modes
• Makes ray tracing aspect-correct
• Lets users plug in custom ray march / trace logic (properly)
• Adds tuning knobs for ray marching quality/perf
• Supports custom output textures/views
• Lets RC run inside an existing command encoder
• Uses (much) less memory by default with 2D ping-pong textures
• Exposes more useful helpers/types from the package

[github-actions]

pkg.pr.new

packages
Ready to be installed by your favorite package manager ⬇️

https://pkg.pr.new/software-mansion/TypeGPU/eslint-plugin-typegpu@275424a3ddba786ed1501705d34f90464f9898a6

https://pkg.pr.new/software-mansion/TypeGPU/tgpu-gen@275424a3ddba786ed1501705d34f90464f9898a6

https://pkg.pr.new/software-mansion/TypeGPU/tinyest-for-wgsl@275424a3ddba786ed1501705d34f90464f9898a6

https://pkg.pr.new/software-mansion/TypeGPU/typegpu@275424a3ddba786ed1501705d34f90464f9898a6

https://pkg.pr.new/software-mansion/TypeGPU/@typegpu/cli@275424a3ddba786ed1501705d34f90464f9898a6

https://pkg.pr.new/software-mansion/TypeGPU/@typegpu/color@275424a3ddba786ed1501705d34f90464f9898a6

https://pkg.pr.new/software-mansion/TypeGPU/@typegpu/gl@275424a3ddba786ed1501705d34f90464f9898a6

https://pkg.pr.new/software-mansion/TypeGPU/@typegpu/noise@275424a3ddba786ed1501705d34f90464f9898a6

https://pkg.pr.new/software-mansion/TypeGPU/@typegpu/radiance-cascades@275424a3ddba786ed1501705d34f90464f9898a6

https://pkg.pr.new/software-mansion/TypeGPU/@typegpu/react@275424a3ddba786ed1501705d34f90464f9898a6

https://pkg.pr.new/software-mansion/TypeGPU/@typegpu/sdf@275424a3ddba786ed1501705d34f90464f9898a6

https://pkg.pr.new/software-mansion/TypeGPU/@typegpu/three@275424a3ddba786ed1501705d34f90464f9898a6

https://pkg.pr.new/software-mansion/TypeGPU/unplugin-typegpu@275424a3ddba786ed1501705d34f90464f9898a6

benchmark
view benchmark

commit
view commit

[github-actions]

Bundle size comparison (import * as ... in PR vs import * as ... in target):

🟢 Decreased	➖ Unchanged	🔴 Increased	❔ Unknown
0	322	0	0

import { ... } in PR vs import * as ... in PR (is the library tree-Shakeable?):

Test	tsdown
tgpu_init.ts	260.04 kB ($${\color{green}-3.2\%}$$)
tgpu_initFromDevice.ts	259.51 kB ($${\color{green}-3.4\%}$$)
tgpu_resolve.ts	165.41 kB ($${\color{green}-38.4\%}$$)
tgpu_resolveWithContext.ts	165.35 kB ($${\color{green}-38.4\%}$$)
tgpu_bindGroupLayout.ts	69.27 kB ($${\color{green}-74.2\%}$$)
tgpu_mutableAccessor.ts	66.27 kB ($${\color{green}-75.3\%}$$)
tgpu_accessor.ts	66.26 kB ($${\color{green}-75.3\%}$$)
tgpu_privateVar.ts	65.61 kB ($${\color{green}-75.6\%}$$)
tgpu_workgroupVar.ts	65.60 kB ($${\color{green}-75.6\%}$$)
tgpu_const.ts	64.85 kB ($${\color{green}-75.9\%}$$)
tgpu_fn.ts	38.45 kB ($${\color{green}-85.7\%}$$)
tgpu_fragmentFn.ts	38.45 kB ($${\color{green}-85.7\%}$$)
tgpu_vertexFn.ts	38.27 kB ($${\color{green}-85.8\%}$$)
tgpu_computeFn.ts	37.97 kB ($${\color{green}-85.9\%}$$)
tgpu_vertexLayout.ts	27.08 kB ($${\color{green}-89.9\%}$$)
tgpu_comptime.ts	14.77 kB ($${\color{green}-94.5\%}$$)
tgpu_unroll.ts	1.66 kB ($${\color{green}-99.4\%}$$)
tgpu_slot.ts	1.54 kB ($${\color{green}-99.4\%}$$)
tgpu_lazy.ts	1.19 kB ($${\color{green}-99.6\%}$$)

If you wish to run a comparison for other, slower bundlers, run the 'Tree-shake test' from the GitHub Actions menu.

[github-actions]

Resolution Time Benchmark

---
config:
  themeVariables:
    xyChart:
      plotColorPalette: "#E63946, #3B82F6, #059669"
---
xychart
  title "Random Branching (🔴 PR | 🔵 main | 🟢 release)"
  x-axis "max depth" [1, 2, 3, 4, 5, 6, 7, 8]
  y-axis "time (ms)"
  line [0.84, 1.68, 3.27, 5.50, 6.23, 10.50, 19.33, 21.60]
  line [0.79, 1.70, 3.52, 5.38, 6.27, 10.40, 19.90, 21.48]
  line [0.85, 1.69, 3.93, 5.37, 6.33, 10.10, 20.54, 21.59]

Loading

---
config:
  themeVariables:
    xyChart:
      plotColorPalette: "#E63946, #3B82F6, #059669"
---
xychart
  title "Linear Recursion (🔴 PR | 🔵 main | 🟢 release)"
  x-axis "max depth" [1, 2, 3, 4, 5, 6, 7, 8]
  y-axis "time (ms)"
  line [0.29, 0.43, 0.62, 0.68, 0.98, 0.99, 1.23, 1.36]
  line [0.30, 0.51, 0.58, 0.70, 1.01, 1.01, 1.26, 1.36]
  line [0.28, 0.52, 0.59, 0.72, 1.06, 1.08, 1.35, 1.43]

Loading

---
config:
  themeVariables:
    xyChart:
      plotColorPalette: "#E63946, #3B82F6, #059669"
---
xychart
  title "Full Tree (🔴 PR | 🔵 main | 🟢 release)"
  x-axis "max depth" [1, 2, 3, 4, 5, 6, 7, 8]
  y-axis "time (ms)"
  line [0.89, 1.77, 3.97, 6.08, 10.47, 23.47, 47.76, 96.71]
  line [0.67, 1.81, 3.01, 5.74, 10.49, 22.57, 48.52, 95.53]
  line [0.73, 1.79, 3.52, 5.44, 11.38, 23.04, 48.41, 100.25]

Loading

[reczkok]

@pullfrog pls review

[pullfrog]

✅ No new issues found.

Reviewed changes — v2 rewrite of the radiance cascades package with better cascade sizing, Morton ray ordering, configurable merge modes, encoder support, and memory optimization.

• Add getCascadeInfo with per-layer metadata — replaces the flat getCascadeDim with a rich CascadeInfo structure carrying per-layer probe counts, UV ranges, and valid dimensions. The old getCascadeDim is kept as a convenience wrapper.
• Morton Z-order ray ordering — replaces linear ray indexing with Morton encoding for more uniform angular sampling. part1By1 and morton2D are defined in cascades.ts and used in makeCascadePassCompute.
• Aspect-correct ray directions — rayDirection and segmentMetricLength use renderAspectSlot to produce correct ray distributions on non-square render targets. rayBoxExitUv clips rays to the unit box.
• Configurable cascade layers — support for baseStoredRayDim (1/2/4), mergeMode (hardware or bilinear-fix), per-layer uniform buffers (CascadeLayerParams), and exposure of common slots (maxRayStepsSlot, rayMarchStepSafetySlot, traceSegmentSlot).
• Encoder support — run() accepts an optional GPUCommandEncoder so cascade and jump-flood passes can be batched with surrounding work. When omitted, run() creates and submits its own encoder.
• 2D ping-pong cascade textures by default — reduces memory usage significantly. 3D array textures are used only when keepCascadeLayers: true.
• Prebuilt JFA pipelines — createJumpFlood now prebuilds one pipeline per JFA step instead of writing offsetUniform at runtime. Fixes destroy() to clean up offset buffers and uniforms.

  ^{｜ View workflow run ｜ Using DeepSeek Pro (free via Pullfrog for OSS) ｜ 𝕏}

[reczkok]

@pullfrog could you estimate how much less gpu memory we allocate for a couple given resolutions?

[pullfrog]

The biggest memory win comes from the cascade ping-pong textures switching from 3D arrays to 2D (the default keepCascadeLayers: false). The output texture format in jumpFlood also goes from rgba16float (8 B/texel) to r32float (4 B/texel) — a separate 50% saving on the SDF output.

Cascade texture memory: old vs new (default baseStoredRayDim=2)

The old path allocates 2 × 3D textures at rgba16float (8 B/texel): [cascadeDimX × cascadeDimY × cascadeCount].
The new default allocates 2 × 2D ping-pong textures: [cascadeDimX × cascadeDimY] — same rgba16float but no layer dimension, so savings factor ≈ cascadeCount : 1.

Resolution	Cascade Dim	Old Layers	Old Memory (2×3D)	New Memory (2×2D)	Savings
4K (2160p)	8192×4608	8	4.50 GB	576 MB	3.94 GB
1440p	4096×2304	7	1008 MB	144 MB	864 MB
1080p	4096×2304	7	1008 MB	144 MB	864 MB
720p	2048×1152	7→6	252 MB	36 MB	216 MB
1024×768	2048×1536	7→6	336 MB	48 MB	288 MB
800×600	1024×768	6	72 MB	12 MB	60 MB

(1080p and 1440p share the same cascade dim because the closest-power-of-two diagonal rounds to the same value.)

Tuning baseStoredRayDim (new path, 2×2D only)

Lower values reduce cascade dimensions further at the cost of ray angular resolution:

Resolution	baseStoredRayDim=1	baseStoredRayDim=2 (default)	baseStoredRayDim=4
4K	144 MB	576 MB	2.25 GB
1080p / 1440p	36 MB	144 MB	576 MB
720p	9 MB	36 MB	144 MB

Uniform buffers

A negligible per-layer uniform buffer (CascadeLayerParams, ~48 B each) replaces the old single CascadeStaticParams + layerBuffer — about the same total, just split per-layer so no layerBuffer.write() is needed during dispatch.

Task list (4/4 completed)

• Explore codebase to understand GPU memory allocation patterns
• Find resolution-dependent buffer/texture allocations
• Calculate and estimate memory savings for given resolutions
• Report findings via pullfrog_report_progress

  ^{｜ View workflow run ｜ via Pullfrog ｜ Using DeepSeek Pro (free via Pullfrog for OSS) ｜ 𝕏}