Module reflection_probe 

Reflection probe capture math: the six cube-face view-projection matrices a probe renders the scene through, plus the load-time conversion of the captured faces into the prefiltered IBL payload the environment sampler consumes. Backend-agnostic; the Metal backend drives the actual scene render into each face (see metal/probe.rs). DirectX / Vulkan can reuse this math.

Face order and orientation match the engine’s cube convention (the build-time concinnity-cook::hdr equirect resampler and core environment_map’s private cube_texel_dir): 0:+X 1:-X 2:+Y 3:-Y 4:+Z 5:-Z, with a face texel at (u,v) in [-1,1] looking along cube_texel_dir(face, u, v). Each face’s view-projection is built so that direction projects to NDC (u, -v) (screen-down is +v), which the orientation test pins exactly.

Structs

ProbeBakeQueue

Tracks how far a staggered probe bake has progressed. Baking every probe on one frame stalls proportionally to the probe count; instead the renderer bakes a bounded budget per frame and walks this cursor, so the load cost is spread and unbaked probes fall back to the sky until their turn. Indices are handed out in order so the baked cube array stays aligned with the placement list.

ProbePlacement

Where one reflection probe is captured from and the influence box it serves. Backend-agnostic: the renderer bakes a cube at position and, for a surface inside [box_min, box_max], selects this probe and parallax-corrects against the box. Derived from a declared ReflectionProbe asset or auto_seed_probes.

Enums

BakeAction

What the renderer should do this frame to advance the asynchronous bake. The renderer maps each variant to a side effect: StartNext builds the next placement’s capture buffers + targets (no face submitted yet), RenderFace submits one cube face (the six are spread one-per-frame so no single frame pays the whole capture), Readback copies the finished faces back and kicks the off-thread convolution, Install uploads the convolved cube and advances the queue, Idle does nothing.

BakePhase

Phase of the single in-flight asynchronous bake. Exactly one probe is baked at a time, walking three phases across frames so the render thread never blocks on the capture: Rendering (six faces submitted, GPU running), Converting (faces read back, the prefilter convolution running off the render thread), and Idle (nothing in flight). The renderer holds the GPU resources for the in-flight probe; this enum only names which phase it is in.

Functions

auto_seed_probes

Auto-seed probes from the scene bounds, used when a world declares no ReflectionProbe. Convenience wrapper over auto_seed_probes_with_geometry with no triangle geometry: interior detection uses object AABB occupancy (the coarse path).

auto_seed_probes_with_geometry

Auto-seed probes from the scene bounds. First places a probe INSIDE each enclosed interior region (a room / walled courtyard, where a local capture is most valuable), then fills the remaining AUTO_SEED_BUDGET with a seed_grid_probes grid for broad / open coverage. An open scene finds no interiors, so it falls straight through to the grid (unchanged); a fully-enclosed scene is mostly rooms; a mixed scene gets both, cross-faded by the partition-of-unity blend. When triangles is non-empty, interior detection surface-voxelises them (so a watertight single mesh’s hollow is found); when empty, it falls back to the coarse AABB occupancy. The grid fill always uses the AABB occupancy for its open-vantage capture-point nudge. Approximate – authored probes give per-space control – but better than one global cube. Returns empty for a degenerate (non-finite or zero-area) scene.

build_probe_payload

Convert six captured cube faces (each face_size*face_size RGBA f32, row major, in the FACE_BASIS order) into the serialised ENVM payload the environment sampler consumes: a cosine-convolved irradiance cube + a GGX prefilter mip chain. Reuses the exact build-time convolutions (including the firefly clamp), so a scene-captured probe and an imported HDR produce byte-compatible payloads that flow through the same upload_environment_map. scheduler runs each convolution’s independent output rows; the engine hands in its job pool.

face_view_matrix

The world->view matrix alone for cube face face, captured from eye. The main pass needs both the combined view-projection (vertex clip transform) and the bare view matrix (some shaders reconstruct view-space data), so the probe capture builds a ViewUniforms from this plus face_view_projection.

face_view_projection

The view-projection for cube face face (0..6) captured from eye.

fold_world_bounds

Union the world-space AABBs of every scene object into one bounds, skipping any box with a non-finite corner (a degenerate / sentinel AABB). Returns None for an empty scene. The probe eye is then probe_eye_point of this.

next_bake_action

Decide the next action for the single-in-flight asynchronous bake. Pure so the transition table is locked by unit tests without a GPU:

reflector_bounds

The world-space AABB an auto-seed pass should count for a flat reflector: a water surface or a glass pane.