feat(renderer): distance-impostor reflection probes — raymarched probe reflections with real depth (#705)

[drsnuggles8]

Closes #705 (already closed with the acceptance evidence; this lands the implementation).

What

Reflection probes bake a linear radial-distance cubemap alongside colour, and the lit passes raymarch reflection rays against it per pixel (Szirmay-Kalos et al., Approximate Ray-Tracing on the GPU with Distance Impostors, Eurographics 2005 — re-derived from the paper, no GPL reference code used). A wall two metres away and the sky no longer reflect identically, and the reflection ladder is now SSR (on-screen) → distance-impostor probes → global sky prefilter — emerging from existing pass order with zero SSR changes (SSR composites later by confidence lerp; the ambient term it lerps over IS the probe/sky fallback).

How

• Bake — ReflectionProbeBaker::CaptureDistanceField rasterizes the scene's opaque casters (borrowed from the DDGI caster enumeration via a new Renderer3D::SetAuxCasterSink, collected during the existing warm-up render) into an RG32F cube-face target with the new ReflectionProbe_Distance.glsl; readback builds a CPU ReflectionProbeDistanceField — R32F @ 128², far-plane miss sentinel, hand-built MAX-mip chain (the cheap reject needs an upper bound), per-probe dMax — stored on the probe's EnvironmentMap. Encoding contract documented in ReflectionProbeDistanceField.h and regex-pinned against the GLSL twin.
• GPU arrays — new TextureCubemapArray (engine interface + GL impl with glCopyImageSubData layer copies); ReflectionProbeArray (a TiledForwardPlus-shaped manager) owns the radiance/distance arrays, the probe UBO (binding 58), the per-cluster probe bitmask SSBO (53) and ReflectionProbeCull.comp on the existing 32×18×24 froxel grid — with its own copy of the slice params so probes keep working when Forward+ is off.
• Shading — include/ReflectionProbes.glsl: cheap max-mip visibility reject → 32-step coarse march + 6 bisections (the paper's reflection budget) → parallax-corrected prefilter lookup, blended across covering probes (m_BlendDistance is finally consumed). Consumed by both deferred variants and both forward PBR shaders through new calculateIBLPrefiltered / calculateCombinedAmbientPrefiltered seams — the BRDF split is untouched, so probe and sky pixels stay photometrically consistent. The cube-array slots (TEX 14/15) stay slot-based in every variant via PublishTextureOffsetAndBind (the DDGI-atlas pattern; allowlisted in BindlessShaderPipelineTest).
• Selection — Scene::ApplyReflectionProbeOverride becomes diffuse-only when a global environment exists (Renderer3D::OverrideGlobalIrradiance), keeping the specular miss fallback the live sky; the full-trio override is kept for no-sky scenes so indoor-only setups still get a BRDF LUT + prefilter source. Stated per the issue: the two mechanisms now split by domain (per-camera diffuse, per-pixel specular) rather than silently disagreeing.

Three raymarch traps, found by the tests/evidence and pinned

1. Far-sentinel crossing reported as a hit — an all-sky probe "hit" the far sphere and shaded from stale captured sky; the refined hit's stored distance is now re-checked against the miss threshold (AllSkyEnvironmentIsAMissNotAFarPlaneHit).
2. March bound one inside-bias short — the triangle-inequality bound ends a bias before the crossing test can fire, so head-on rays silently missed; kProbeMarchSlackRel/Abs (ConvergesToTheAnalyticHitAcrossASphereRoom failed on exactly this first).
3. Occluded starts bogus-hit the occluder shell — surfaces the probe cannot see start the march outside the impostor surface and instantly "hit" the captured occluder (dark crescents across the evidence sphere's probe-hidden lower half). The march now skips leading outside samples until the ray re-enters the visible region (OccludedStartSkipsTheOccluderAndHitsTheRealSurface).

Verification (rendering rule: all three layers)

• CPU contracts (ReflectionProbeDistanceFieldTest.cpp, L1): raymarch convergence vs closed-form sphere/box intersections, miss cases, occluded starts, MAX-mip conservatism, GL cube addressing, std140 layout, GLSL↔C++ constant parity.
• Visual evidence (ReflectionProbeParallaxVisualEvidenceTest, L8): corridor with colour-coded walls (RED −X / GREEN +X / BLUE −Z / YELLOW +Z) + roughness-0.08 mirror floor, 4 poses × 3 probe states, PNGs committed under OloEditor/assets/tests/visual/ReflectionProbeParallax_*.png. Reflections land under their walls (left strip RGB 176/63/62, right strip 63/176/63); the off-screen yellow wall reflects at (178,178,61) vs (51,51,51) probe-off — the SSR-failure case; positional split 224.7 vs 7.6 with the distance field stripped (the pre-Renderer: distance-impostor reflection probes — raymarched probe reflections with real depth #705 path), asserted golden-free. The pre-existing ReflectionProbeVisualEvidenceTest stays green; both evidence tests now disable the editor's gizmo/grid/axis chrome so the PNGs show reflections, not authoring overlays.
• Live editor: olo_shader_errors = 0 after all shader edits; new sandbox scene Scenes/ReflectionProbeCorridor.olo loads (11 entities) and renders with a clean unbaked-probe fallback.
• Full suite: 5586 / 5587 — the only failure is the known-red AtmosphereVisualEvidenceTest (AtmosphereVisualEvidenceTest: NightClear/NightOvercast goldens drift (RMSE 13.08 / 9.40 vs threshold 8) — permanently red #754) baseline. The 71 regenerated evidence PNGs were pixel-diffed against HEAD per the photometric-parity rule: same-binary reruns are bit-stable (0-pixel diff), diffs vs HEAD are FP-level drift from the hoisted specular fetch (max RMSE 2.8 outside the two intentionally-changed probe images; signed means ≤0.22/255; no structured shifts).

Known limitations (documented in docs/agent-rules/distance-impostor-reflection-probes.md)

Distance impostors assume the environment is piecewise-representable from the probe centre — rooms/corridors/open terrain work; densely self-occluding scenes (forests) alias at silhouettes; probe placement matters. Diffuse still uses the per-camera dominant-probe override; terrain/water keep the global reflection source.

Follow-up logged on #607: an olo_reflection_probe_bake MCP tool (the bake is inspector-button-only, so live agents can't exercise the raymarched path end-to-end).

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Added distance-impostor reflection probes with parallax-aware reflections.
  • Probes support baked distance fields, clustered selection, and efficient cubemap storage.
  • Added a corridor scene demonstrating colored reflections and fallback behavior.

• Bug Fixes

  • Preserved global specular environment resources when applying probe irradiance overrides.

• Documentation

  • Added guidance on reflection-probe setup, integration, limitations, and troubleshooting.

• Tests

  • Added visual and mathematical validation for probe parallax, distance fields, bindings, and raymarching.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 7e0ed365-a026-4336-b707-39928bc43849

📥 Commits

Reviewing files that changed from the base of the PR and between f10321e and 362453b.

📒 Files selected for processing (2)

• OloEngine/src/OloEngine/Renderer/ReflectionProbeArray.cpp
• OloEngine/tests/Rendering/PropertyTests/ReflectionProbeParallaxVisualEvidenceTest.cpp

---

📝 Walkthrough

Walkthrough

Added distance-impostor reflection probes with CPU distance fields, probe baking, GPU cubemap arrays, clustered culling, renderer integration, corridor visual evidence, and contract tests.

Changes

Distance-impostor reflection probes

Layer / File(s)	Summary
Distance-field contract and raymarching OloEngine/src/OloEngine/Renderer/ReflectionProbeDistanceField.*, OloEngine/tests/Rendering/ReflectionProbeDistanceFieldTest.cpp, docs/agent-rules/distance-impostor-reflection-probes.md	Added distance-field encoding, max-mip generation, cube-map sampling, raymarching, validation tests, and integration documentation.
Probe baking and caster collection OloEngine/src/OloEngine/Renderer/ReflectionProbeBaker.*, OloEngine/src/OloEngine/Renderer/EnvironmentMap.h, OloEngine/src/OloEngine/Renderer/Renderer3D.*	Probe baking now collects casters, captures distance fields, attaches successful fields to environment maps, and supports auxiliary caster sinks and irradiance overrides.
Cubemap-array storage OloEngine/src/OloEngine/Renderer/TextureCubemapArray.*, OloEngine/src/Platform/OpenGL/OpenGLTextureCubemapArray.*, OloEngine/src/CMakeLists.txt	Added cubemap-array resources with OpenGL allocation, mip uploads, cubemap copying, readback, binding, and memory reporting.
Probe arrays and clustered runtime OloEngine/src/OloEngine/Renderer/ReflectionProbeArray.*, OloEditor/assets/shaders/compute/ReflectionProbeCull.comp, OloEngine/src/OloEngine/Renderer/ShaderBindingLayout.h, OloEngine/src/OloEngine/Scene/Scene.cpp, OloEngine/src/OloEngine/Renderer/Passes/*	Added per-frame probe submission, resource uploads, UBO and SSBO bindings, clustered culling, lifecycle management, and deferred and scene-pass resource binding.
Visual evidence and binding validation OloEditor/SandboxProject/Assets/Scenes/ReflectionProbeCorridor.olo, OloEngine/tests/Rendering/PropertyTests/*, OloEngine/tests/Rendering/Shader*Test.cpp	Added a corridor scene, GPU parallax evidence captures, shader binding allowlists, and binding uniqueness checks.

Sequence Diagram(s)

sequenceDiagram
  participant Scene
  participant ReflectionProbeBaker
  participant ReflectionProbeArray
  participant ReflectionProbeCull
  participant DeferredLightingPass
  Scene->>ReflectionProbeBaker: Bake probe cubemap and collect casters
  ReflectionProbeBaker->>ReflectionProbeBaker: Capture six-face distance field
  Scene->>ReflectionProbeArray: Submit probe render data
  ReflectionProbeArray->>ReflectionProbeCull: Dispatch clustered probe culling
  ReflectionProbeArray->>DeferredLightingPass: Bind radiance, distance, UBO, and grid resources
  DeferredLightingPass->>ReflectionProbeArray: Republish resources before lighting draw

Loading

🚥 Pre-merge checks | ✅ 4

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly identifies the renderer feature: distance-impostor reflection probes with raymarched reflections and real depth.
Linked Issues check	✅ Passed	The changes address issue #705 through distance baking, raymarching, clustered culling, fallbacks, visual evidence, tests, and documentation.
Out of Scope Changes check	✅ Passed	The scene, tests, documentation, shader bindings, and renderer changes directly support the distance-impostor reflection-probe objectives.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[sonarqubecloud]

Quality Gate passed

Issues
67 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.8% Duplication on New Code

See analysis details on SonarQube Cloud