SDF Raymarcher for Unity URP

Production preview (ValidationScene capture):

Direct video link: Movie_002.mp4

Problem Statement and Business Value

Teams that need stylized volumetric materials in URP usually choose between slow custom effects, one-off scene hacks, or assets that are hard to maintain in production. This project solves that gap by delivering a deterministic SDF raymarch module with explicit QA and CI gates. The primary use-case is client-facing real-time scenes that require art-directable translucent materials with predictable runtime behavior. Business value comes from reduced rendering risk, repeatable performance baselines, and faster handover to downstream teams. Key trade-off: this is a screen-space URP solution optimized for reliability and control, not a physically exact offline renderer. Second trade-off: advanced features (PBR, AO, SSS, temporal skip) improve quality but require disciplined profiling and configuration governance.

Delivery Scope

In Scope

• URP renderer feature and pass integration (SDFRaymarcherRendererFeature, SDFRaymarcherPass).
• Runtime shape registry, immutable frame snapshots, GPU payload upload.
• SDF primitives: sphere, box, capsule, torus.
• CSG operations: union, subtract, intersect, plus smooth variants.
• Volumetric controls: density, shell, absorption, scatter, phase.
• Feature slices: PBR direct, AO, SSS, half-resolution path, temporal skip.
• CI checks: hygiene, license policy, shader compile smoke, EditMode/PlayMode gates.

Out of Scope

• Built-in RP and HDRP support.
• Physically exact path tracing equivalence.
• Global cross-platform visual parity guarantees outside validated matrix.

One-Page Architecture

flowchart LR
    A[Scene SdfShape Components] --> B[Main Thread Registry]
    B --> C[Immutable Frame Snapshot]
    C --> D[Snapshot Builder and Culling]
    D --> E[StructuredBuffer Upload]
    E --> F[Raymarch Intermediate Pass]
    F --> G[Composite Pass]
    G --> H[URP Camera Color Output]
    V[SDFRaymarcherVolume Controls] --> F
    L[Scene Depth and Main Light] --> F

Loading

Acceptance Criteria and Definition of Done

Definition of Done: docs/DEFINITION_OF_DONE.md

Criterion	Target	Current Evidence
Deterministic shape ordering and snapshot stability	Stable ordering across static input	Editor tests under Assets/VavLabs/SDF_Raymarcher/Editor/Tests
CI pipeline health	Required checks green on merge branch	.github/workflows/ci.yml
Shader compile reliability	Zero shader compiler messages in smoke tests	SDFRaymarcherShaderCompilationTests
Static scene overhead	Delta tracked with 3-run CI95 envelope	+9.26% ±1.693 (Artifacts/profiler/aggregate_3run_report.md)
Benchmark reproducibility	Third party can rerun via documented command lines	BENCHMARKING.md + artifacts links
Release hygiene	Tagged release + changelog + compatibility matrix	v1.0.0, CHANGELOG.md, matrix below

Compatibility Matrix

Component	Version
Unity	6000.3.8f1
URP	17.3.0
Render Pipeline	URP only

Test Quality Signaling

Test Gate	What It Covers	Why It Exists
Shader Compile Smoke	Shader import/compile validity and key feature symbols	Prevent shader regressions from reaching runtime
EditMode Tests	Registry, snapshot/layout, volume validation contracts	Protect deterministic CPU-side behavior
PlayMode Tests	Runtime integration smoke path (assembly + scene-driven checks)	Catch scene/runtime wiring issues
CI Hygiene Checks	Artifact noise, license policy, deterministic test artifacts	Keep repository and release process production-safe

Performance and Benchmark Evidence

Primary reports:

• PERF.md
• Artifacts/profiler/static_on_off_report.md
• Artifacts/profiler/pbr_direct_delta_report.md
• Artifacts/profiler/aggregate_3run_report.md

Note: existing benchmark artifacts were captured on Unity 6000.3.4f1; rerun BENCHMARKING.md after engine upgrades to refresh published numbers.

Quality evidence:

• Recordings/Movie_002.mp4
• Artifacts/quality/full_res.png
• Artifacts/quality/half_res.png
• Artifacts/quality/diff_abs_x4.png

Reproducibility entry point:

• BENCHMARKING.md (contains exact command lines and expected output artifacts)

Temporal Skip

TemporalSkip is an optimization toggle that reuses previously generated raymarch intermediates when frame inputs are considered unchanged.

• Input key includes camera state, shape snapshot hash, and volume-controlled render parameters.
• It is useful for static shots and UI-heavy scenes where SDF content is mostly unchanged.
• It can become visually stale if your scene has frequent occluder/light changes not captured by the invalidation key on a given platform path.
• Recommendation: keep it OFF by default, enable only after A/B profiling with your target scene and hardware.

Known Limits and Production Risks

• URP-only implementation.
• Screen-space effect; depth ordering and camera path directly affect output.
• Refraction/distortion sampling relies on camera depth; transparent objects not writing depth can produce non-physical blending artifacts.
• Tree traversal depth is bounded (SDF_TREE_MAX_DEPTH = 32).
• High step/quality values can become ALU and fill-rate bound.
• Temporal skip is a correctness/performance trade-off and must be validated per scene.
• Moving occluders and lighting can invalidate caches and increase per-frame cost.

Release Hygiene

• Current public release tag: v1.0.0
• Changelog: CHANGELOG.md
• Pinned release note: docs/releases/v1.0.0.md
• Public license mode: MIT (LICENSE-MIT)
• Release policy: docs/LICENSE_POLICY.md

Repository Structure

• Assets/VavLabs/SDF_Raymarcher/Core/Runtime: shape data, registry, snapshots.
• Assets/VavLabs/SDF_Raymarcher/Rendering/Runtime: feature/pass orchestration.
• Assets/VavLabs/SDF_Raymarcher/Rendering/Shaders: shader entry and includes.
• Assets/VavLabs/SDF_Raymarcher/Editor: tests, diagnostics, perf tooling.
• docs/adr: architecture decisions.

Additional Docs

• QUICKSTART.md
• ARCHITECTURE.md
• CONTRIBUTING.md
• DEFINITION_OF_DONE.md

License

MIT. See LICENSE-MIT.