renderer ยท diff
git:20261020.f831c43 to git:20261020.dc8f546
21 added, 61 removed. Audit A to A.
---
name: renderer
description: Architecture rules for GPU rendering with TypeGPU/WebGPU. Use when adding or changing render passes, shaders, frame orchestration, GPU resources, culling, terrain, shadows, or visual performance work.
---
# GPU renderer
- The renderer is TypeGPU over WebGPU. It consumes plain frame inputs from the
- application and owns pass ordering, GPU resources, and presentation of those
- inputs. It never reaches into simulation or app state.
-
- ## Workflow
-
- 1. Find the existing owner for the frame, camera, depth convention, targets,
- resource registry, culling, and timing. Extend that owner instead of adding
- a parallel path.
- 2. State the work bound before changing code. For a fixed camera and render
- size, screen-space passes must be bounded by pixels; world geometry and
- shadow work must be bounded by the camera and fitted shadow regions, not by
- total map extent. A huge map must not submit a map-sized terrain mesh or
- off-view shadow casters for a fixed view.
- 3. Measure the current frame with an interleaved A/B on the real GPU. Isolate
- terrain, shadows, models, scenery, fog, post, and overlays where possible;
- whole-frame timestamps overlap on tile GPUs, so do not add individual deltas
- as if they were independent.
- 4. Choose the pass by semantics: depth prepass for opaque geometry, lit colour
- after depth, translucency after opaque, screen-space work on resolved
- targets, and overlays/UI last. Keep one frame function as the orchestrator.
- 5. Update resources at their natural frequency. Allocate through the registry,
- use scoped replacement for resize or pipeline changes, and prove repeated
- rebuild/reset returns allocation counts and bytes to baseline.
- 6. Verify the narrowest real scene on hardware, then run the owning package
- checks. Treat validation warnings, device errors, and visual regressions as
- failures.
-
- ## Architectural rules
-
- - **One owner per contract.** Camera projection, reverse-Z depth, frame targets,
- culling bounds, lighting, and resource lifetime each have one authoritative
- owner shared by all passes and clients.
- - **Bound submitted work, not only rasterized pixels.** Frustum clipping does
- not make vertices free. Tile terrain and large static populations; select
- shadow casters against the fitted receiver; keep per-frame lists bounded by
- visible/casting regions.
- - **Keep map size out of fixed-view cost.** Terrain, props, and scenery may be
- stored map-wide, but draw submission and shadow casting must use spatial
- chunks or equivalent bounded selection. Post-processing and composites should
- scale with target dimensions only.
- - **Preserve depth and lighting contracts.** Reverse-Z comparison, clear value,
- format, multisample count, and shared vertex positioning change together.
- World materials read the shared lighting/shadow function; do not introduce
- per-layer lighting shortcuts.
- - **Respect GPU lifetime.** Every buffer and texture has a registry owner.
- Async rebuilds install a complete replacement, release overtaken builds, and
- remain safe after disposal.
- - **Keep output authority in presentation.** The renderer draws the records it
- receives; optimizations may cull or change detail only through the existing
- presentation/quality contract and must preserve deterministic output.
- - **Judge pixels as well as counters.** Pair draw/GPU statistics with a real
- screenshot or crop that proves the subject, framing, fog, depth, and shadows
- remain correct. Use an unprimed visual review for player-facing changes.
-
- ## Performance acceptance
+ The renderer is TypeGPU over WebGPU. It draws plain frame inputs the
+ application hands it and never reaches into simulation or app state. These are
+ the flaws that sink a 3D experience; check a change against each before
+ writing it.
- Record the trigger, amplification, owner, A/B evidence, and remaining bound in
- the active performance spec before promoting an optimization. A candidate is
- not accepted because one pass became cheaper if the frame, image, or resource
- contract regressed. Keep rejected experiments out of production code and
- document only the durable reason for rejecting them.
+ - **Fixed-view cost never grows with world size.** For a fixed camera and
+ render size, submitted geometry, shadow casters, and per-frame lists are
+ bounded by what the view can see or cast into, and screen-space work by
+ pixels. Store the world map-wide; select from it spatially. Frustum clipping
+ does not make vertices free.
+ - **One owner per contract.** Frame orchestration, camera, depth convention,
+ targets, culling, lighting, timing, and resource lifetime each have one
+ owner every pass shares. Extend it; a second copy drifts.
+ - **Shared contracts change together.** Depth and lighting are engine-wide:
+ every pass reads the same convention and every material the same shading
+ path. A per-pass exception is a future visual bug.
+ - **No GPU resource without a lifetime owner.** Everything is allocated
+ through the registry, rebuilds swap in whole, and repeated
+ resize/rebuild/reset returns to baseline.
+ - **Pixels prove correctness, not counters.** An optimization is accepted
+ only with an interleaved A/B on the real GPU and an image that shows the
+ subject still drawn correctly.