| name | renderer-implementation-roadmap |
| description | Sequence a nanoUSD renderer build from nothing into a correct, scalable backend using only the renderer skill set. Use when Codex starts a new renderer or backend, plans renderer milestones and phase order, decides what must be correct before the next layer, or needs the contracts-first build order and reduced-fixture corpus that turn the other renderer skills into a buildable plan with no reference renderer to copy from. |
Renderer Implementation Roadmap
Purpose
The other renderer skills are aspect skills — scene extraction, PBR validation,
performance, parity triage. This is the sequencing skill. It orders them into a
build a fresh agent can follow with no reference renderer to copy from, and it
states the gate that must hold before each next layer. Contracts before backends;
one coherent vertical slice before breadth; every phase has a correctness gate.
This is the renderer counterpart to a spec implementation roadmap: the build order
is itself a deliverable, because the wrong order forces rewrites.
Read this first. Each phase below names its goal, the skill(s) that drive it, the
gate that closes it, and the failure you cause by skipping or reordering it —
so the order is self-justifying, not arbitrary.
Build order
Phase 0 — Map and target. Skills: agentic-codebase-cartography,
renderer-target-architecture-design. Write down target scene scale, resolution,
frame time, sample/noise budget, memory budget, supported features, the reference
renderer, and the architecture class (hardware RT vs raster, resident scene,
render graph, temporal accumulation, …).
Gate: a written target and a named reference exist.
Skip-failure: you build a brute-force/flattened path you will throw away before
the goal is reachable — the exact trap renderer-target-architecture-design exists
to prevent.
Phase 1 — Freeze the contracts before any backend. Skills:
renderer-capability-abi, contract-first-ffi, nanousd-renderer-scene-extraction.
Define, as one canonical copy each: the public C ABI (capability bitmask +
backend-info query); the RHI seam that separates the platform-agnostic core from
the backend; the scene-extraction structs; and the cross-cutting conventions
(coordinate/transform convention, vertex layout, color-space policy).
Gate: the ABI conformance check is green and a stub backend links against all
three contracts.
Skip-failure: backend #2 forces a rewrite of the core, and the "shared" files
drift apart (observed in practice: a scene loader that diverged thousands of lines
between backends, and a capability ABI present in only one of three headers).
Phase 2 — Backend skeleton, portable build, headless triangle. Skills:
portable-build-runtime-paths, renderer-backend-port. The smallest end-to-end
path: init the device, compile one shader, draw one triangle, read pixels back
headless.
Gate: a deterministic headless image (known clear color + triangle) that renders
after relocation — no cwd, absolute-path, username, or display assumptions.
Skip-failure: you debug GPU bring-up and scene bugs simultaneously with nothing
reproducible to bisect.
Phase 3 — Scene extraction (CPU, no shading). Skill:
nanousd-renderer-scene-extraction. Compose USD into the renderer scene structs
with counts, bounds, instancing preserved, and unsupported-feature diagnostics —
kept separate from GPU upload.
Gate: load counts, bounds, and diagnostics match the reference on the reduced
corpus before any shading.
Skip-failure: white or exploded scenes you misdiagnose as shader bugs (see that
skill's failure signatures) — the cost of shading on top of a wrong scene.
Phase 4 — Raster vertical slice. Forward-raster the extracted meshes with one
light.
Gate: a tiny fixture renders nonblank with correct silhouette and a correct
normals AOV.
Skip-failure: you start ray tracing with no known-good geometry/transform path to
diff against.
Phase 5 — Hardware ray tracing (if in target). Skills:
renderer-performance-architecture (acceleration-structure section),
renderer-backend-port. BLAS-per-prototype, TLAS over instances, refit rather than
rebuild.
Gate: RT primary matches the raster slice on the same fixture, plus a refit smoke
test (move one instance, re-render, verify it moved).
Skip-failure: raster and RT silently disagree about which geometry exists — the
renderer-performance-architecture anti-pattern.
Phase 6 — Lights, materials, IBL. Skills:
nanousd-renderer-scene-extraction (materials/lights),
physically-based-renderer-validation. UsdLux lights, UsdPreviewSurface/MaterialX,
dome/IBL.
Gate: per-term AOVs (base color, normal, roughness, metallic, direct, shadow) are
validated independently before any beauty comparison.
Skip-failure: you tune exposure or material defaults to hide a broken term — the
core anti-pattern of physically-based-renderer-validation and graphics-debugging-lab.
Phase 7 — Validation harness (continuous from here). Skills:
renderer-image-comparison-testing, renderer-feature-validation-matrix. Stand up
the golden-image harness and the feature matrix as the live ledger.
Gate: backend goldens exist and, where parity is a contract, reference deltas —
with term AOVs stored beside beauty.
Skip-failure: "looks better" progress with no regression net.
Phase 8 — Performance architecture for scale. Skill:
renderer-performance-architecture. Instancing, residency, async batched uploads,
draw batching, pass gating, telemetry; readback off the interactive path.
Gate: a representative-scale probe is within budget and the correctness fixtures
are still green.
Skip-failure: a fast path that omits geometry/shadows/GI and a "speedup" that is
really a correctness regression.
Continuous spines (not phases)
renderer-feature-validation-matrix — track every capability's status, owner,
fixture, and reference from Phase 1 onward; it is the ledger the gates write to.renderer-stalled-parity-triage — invoke the moment beauty/metrics stop improving.verification-led-development — the smallest meaningful build/test/screenshot at
each gate.graphics-debugging-lab — when one stage misbehaves, isolate it before tuning.- Defer features by precondition, not by date: when a phase's technique has no
cost-justifying trigger yet (a denoiser on noise-free output, intersection-function
buffers with one intersection function, BLAS compaction on small scenes), record the
exact condition that should revive it — "deferred" without its trigger becomes either
gold-plating or a forgotten gap.
- The no-sacred-cows rule from
renderer-target-architecture-design overrides the
whole order: if a gate keeps failing with the same residual, pivot the
architecture — do not shrink scope and retry.
Canonical reduced-fixture corpus
Build these tiny, deterministic fixtures early and keep them as regression cases.
Record what each one proves, not expected pixel counts (those move with sampling
and tone mapping; a frozen count rots). Mirror the reference corpus that ships under
the renderer repos' tests/assets/ rather than re-inventing names.
| Fixture | Proves |
|---|
| reset-xform-stack scene | resetXformStack composition and transform order |
| z-up + centimeters scene | up-axis and metersPerUnit applied exactly once at the boundary |
| face-varying UV seam | face-varying attribute vertex expansion and seam handling |
| typed-gprim (cube/cone/capsule) | procedural-primitive coverage and axis convention |
| MaterialX UV-tiling bind | material binding + UV transform/tiling resolution |
| white diffuse room + one analytic light | direct lighting and shadow visibility |
| metallic/roughness grid | BRDF response under neutral light |
| ORM + normal + UV-transform case | texture packing, tangent space, color-space classification |
| alpha-cutout blocker between light and surface | transparent/cutout shadow transport |
| emissive mesh behind a blocker | emitter sampling and visibility (not indirect-only discovery) |
| instanced/prototype with material override | instancing, per-instance transform and material override |
| one large authored scene (warehouse/vehicle) | integration and scale, opt-in and telemetry-first |
Anti-Patterns
- Standing up a backend before the public ABI, RHI seam, and scene structs exist —
guarantees a rewrite at backend #2.
- Shading before load counts, bounds, and AOVs are proven on the reduced corpus.
- Treating the phases as independent parallel tasks instead of gated layers.
- Copying contract values into a plan document instead of pointing at the canonical
header — recreates the drift this roadmap is built to avoid.
- Shrinking scope after a gate repeatedly fails instead of pivoting the architecture.
Handoff
Report the current phase, which gates pass on which backends, the feature-matrix
link, the reduced-fixture results, and the single smallest command that advances the
next gate.
