docs: Radiance cascade examples + usage

[reczkok]

No description provided.

[github-actions]

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

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

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

Test	tsdown
tgpu_init.ts	263.10 kB ($${\color{green}-3.5\%}$$)
tgpu_initFromDevice.ts	262.56 kB ($${\color{green}-3.7\%}$$)
tgpu_resolve.ts	161.75 kB ($${\color{green}-40.7\%}$$)
tgpu_resolveWithContext.ts	161.68 kB ($${\color{green}-40.7\%}$$)
tgpu_bindGroupLayout.ts	62.32 kB ($${\color{green}-77.1\%}$$)
tgpu_mutableAccessor.ts	57.04 kB ($${\color{green}-79.1\%}$$)
tgpu_accessor.ts	57.04 kB ($${\color{green}-79.1\%}$$)
tgpu_privateVar.ts	55.73 kB ($${\color{green}-79.6\%}$$)
tgpu_workgroupVar.ts	55.73 kB ($${\color{green}-79.6\%}$$)
tgpu_const.ts	55.15 kB ($${\color{green}-79.8\%}$$)
tgpu_lazy.ts	54.95 kB ($${\color{green}-79.8\%}$$)
tgpu_fragmentFn.ts	39.68 kB ($${\color{green}-85.4\%}$$)
tgpu_fn.ts	39.62 kB ($${\color{green}-85.5\%}$$)
tgpu_vertexFn.ts	39.50 kB ($${\color{green}-85.5\%}$$)
tgpu_computeFn.ts	39.20 kB ($${\color{green}-85.6\%}$$)
tgpu_vertexLayout.ts	28.33 kB ($${\color{green}-89.6\%}$$)
tgpu_comptime.ts	15.93 kB ($${\color{green}-94.2\%}$$)
tgpu_unroll.ts	1.75 kB ($${\color{green}-99.4\%}$$)
tgpu_slot.ts	1.70 kB ($${\color{green}-99.4\%}$$)

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

[github-actions]

pkg.pr.new

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

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

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

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

benchmark
view benchmark

commit
view commit

[pullfrog]

✅ No new issues found.

Reviewed changes

• Docs — mdx & README additions: new "Batching into your own encoder", "Quality and memory options" (options table), "Reading the output", and "Scene contract" sections covering run(encoder), all tuning options, runner.output/runner.outputTexture semantics, and expanded Advanced-exports table.
• New "Quality and memory options" table: baseStoredRayDim, mergeMode, keepCascadeLayers, renderAspect, maxRaySteps, stepSafety, intervalOverlapProbes, plus the *Probes-are-probe-spacings note and traceSegment override explanation.
• Drawing example refactor: replaced the single-line uniform-driven draw with a persistent drawSegments buffer (MAX_DRAW_SEGMENTS = 256) + segmentCount uniform, a pending-segments queue, and encoder-batched recording of draw-compute → flood → radiance into root['~unstable'].createCommandEncoder().
• Radiance example ray indexing: added part1By1/compact1By1/morton2D/unmorton2D helpers; the cascade store pass and the overlay-debug read path now address rays by morton z-order instead of row-major; std.intdiv for the overlay ray step.
• drawInteraction.ts: dropped the now-unneeded onStop hook and stop return value.

Every documentation claim was checked against the source: all cited exports exist in the package barrel (defaultTraceSegment, getCascadeInfo, traceSegmentSlot, maxRayStepsAccess, rayMarchStepSafetyAccess), option names/types match the runner (e.g. stepSafety asserted within (0, 1], baseStoredRayDim: 1 | 2 | 4, intervalOverlapProbes accepts 'upperProbeSpacing'), run(commandEncoder?) records into a supplied encoder without submitting, and renderAspect defaults to the output aspect. The example's morton helpers are byte-for-byte identical to the library's internal implementation (cascades.ts:242-260), so the store and overlay-debug read paths operate on the same Z-order permutation and stay consistent. Encoder/pipeline API usage matches existing docs examples (render-bundles, simple-shadow).

One observation, not a defect: the drawing example re-patches and re-stamps the entire accumulated segment buffer (and recomputes flood + radiance) on every dirty frame while the pointer is held, where the previous code drew a single line and recomputed only on stroke end. This is bounded by MAX_DRAW_SEGMENTS = 256, the writes are idempotent, and it makes the radiance update visible live while painting — so it reads as intentional for an example.

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

[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.97, 1.99, 4.29, 6.51, 7.43, 12.23, 23.84, 24.68]
  line [1.00, 1.95, 4.32, 7.27, 7.84, 12.52, 25.15, 26.51]
  line [1.00, 2.02, 4.54, 6.36, 8.34, 11.74, 23.36, 23.38]

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.33, 0.57, 0.71, 0.81, 1.23, 1.24, 1.42, 1.55]
  line [0.30, 0.48, 0.69, 0.91, 1.13, 1.21, 1.41, 1.59]
  line [0.27, 0.54, 0.70, 0.81, 1.15, 1.19, 1.41, 1.57]

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, 2.14, 4.17, 7.24, 12.62, 26.28, 56.53, 115.46]
  line [0.86, 2.34, 3.45, 7.25, 12.77, 27.79, 56.90, 116.48]
  line [0.86, 2.10, 3.39, 7.46, 12.58, 27.01, 55.29, 114.29]

Loading