docs: Radiance cascade examples + usage - #2915
Conversation
Bundle size comparison (
|
| 🟢 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.09 kB ( |
| tgpu_initFromDevice.ts | 262.55 kB ( |
| tgpu_resolve.ts | 161.75 kB ( |
| tgpu_resolveWithContext.ts | 161.68 kB ( |
| tgpu_bindGroupLayout.ts | 62.32 kB ( |
| tgpu_mutableAccessor.ts | 57.04 kB ( |
| tgpu_accessor.ts | 57.04 kB ( |
| tgpu_privateVar.ts | 55.73 kB ( |
| tgpu_workgroupVar.ts | 55.73 kB ( |
| tgpu_const.ts | 55.15 kB ( |
| tgpu_lazy.ts | 54.95 kB ( |
| tgpu_fragmentFn.ts | 39.68 kB ( |
| tgpu_fn.ts | 39.62 kB ( |
| tgpu_vertexFn.ts | 39.50 kB ( |
| tgpu_computeFn.ts | 39.20 kB ( |
| tgpu_vertexLayout.ts | 28.33 kB ( |
| tgpu_comptime.ts | 15.93 kB ( |
| tgpu_unroll.ts | 1.75 kB ( |
| tgpu_slot.ts | 1.70 kB ( |
If you wish to run a comparison for other, slower bundlers, run the 'Tree-shake test' from the GitHub Actions menu.
|
pkg.pr.new packages benchmark commit |
![pullfrog[bot]](https://avatars.githubusercontent.com/in/1768019?s=60&v=4){kind=small}
There was a problem hiding this comment.
✅ 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.outputTexturesemantics, 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 andtraceSegmentoverride explanation. - Drawing example refactor: replaced the single-line uniform-driven draw with a persistent
drawSegmentsbuffer (MAX_DRAW_SEGMENTS = 256) +segmentCountuniform, a pending-segments queue, and encoder-batched recording of draw-compute → flood → radiance intoroot['~unstable'].createCommandEncoder(). - Radiance example ray indexing: added
part1By1/compact1By1/morton2D/unmorton2Dhelpers; the cascade store pass and the overlay-debug read path now address rays by morton z-order instead of row-major;std.intdivfor the overlay ray step. drawInteraction.ts: dropped the now-unneededonStophook andstopreturn 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.
DeepSeek Flash (free via Pullfrog for OSS) ｜ 𝕏
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.92, 1.84, 3.60, 5.90, 6.48, 11.18, 20.79, 23.31]
line [0.81, 1.63, 3.65, 5.84, 7.34, 10.70, 21.00, 23.56]
line [0.89, 1.66, 3.36, 5.99, 6.89, 11.44, 20.15, 23.03]
---
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.34, 0.53, 0.67, 0.75, 1.01, 1.06, 1.27, 1.43]
line [0.34, 0.57, 0.65, 0.77, 1.06, 1.15, 1.35, 1.48]
line [0.26, 0.43, 0.63, 0.73, 0.98, 1.11, 1.31, 1.42]
---
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.81, 1.91, 3.52, 5.90, 10.86, 23.21, 50.99, 101.46]
line [0.86, 2.01, 3.90, 6.90, 11.22, 23.47, 50.29, 101.40]
line [0.79, 1.95, 2.95, 6.18, 10.59, 23.17, 48.86, 101.27]
|
eb5ed42 to
b4d4b76
Compare
There was a problem hiding this comment.
Pull request overview
This PR expands the Radiance Cascades documentation and updates the docs-site examples to demonstrate (1) batching run() calls into a caller-owned command encoder and (2) additional configuration/quality options, while also improving the interactive drawing example’s update pipeline.
Changes:
- Documented passing a
TgpuCommandEncoderintorun()to batch work into a single submission (README + docs MDX). - Added a “scene contract” section and detailed “quality and memory options” guidance (README + docs MDX).
- Updated docs examples: introduced Morton-order ray indexing for the from-scratch RC example, and refactored the drawing example to record draw + flood + radiance work into a single encoder per frame.
Reviewed changes
Copilot reviewed 5 out of 5 changed files in this pull request and generated no comments.
Show a summary per file
| File | Description |
|---|---|
| packages/typegpu-radiance-cascades/README.md | Adds usage guidance for encoder batching, scene expectations, and key tuning options. |
| apps/typegpu-docs/src/examples/rendering/radiance-cascades/index.ts | Improves example ray indexing (Morton/unmorton) and adjusts debug overlay sampling accordingly. |
| apps/typegpu-docs/src/examples/rendering/radiance-cascades-drawing/index.ts | Refactors the drawing workflow to queue segments, batch compute passes in a shared encoder, and centralize scene updates. |
| apps/typegpu-docs/src/examples/rendering/radiance-cascades-drawing/drawInteraction.ts | Simplifies the interaction API by removing the unused external onStop callback/return surface. |
| apps/typegpu-docs/src/content/docs/ecosystem/typegpu-radiance-cascades.mdx | Adds encoder batching documentation, option guidance, and updates the “Advanced exports” list. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
No description provided.