### Goal Add a global-illumination solution so indirect light — bounce lighting, contact/ambient occlusion, local reflections — is computed from the scene itself rather than approximated by a single distant environment probe. Today the only indirect term is the IBL ambient added in `subsystems/render/shaders/scene.frag.glsl`: ```glsl vec3 irradiance = evalSH(N, ubo.env_sh) * intensity; // distant env, 9 SH coefficients vec3 diffuse_ibl = irradiance * albedo / PI * (1.0 - metallic); vec3 prefiltered = textureLod(env_prefiltered, R, roughness * max_lod).rgb * intensity; ``` That is a *distant* environment only. It has no notion of the scene occluding itself, so: - **No occlusion.** Every crevice, every surface under an awning or table, receives the full hemisphere of sky irradiance. Comparing the Bistro sample against the [ORCA reference render](https://d29g4g2dyqv443.cloudfront.net/sites/default/files/akamai/Bistro_Exterior_1.png), this is the single largest perceptual difference — the reference is defined by its contact darkening. `occlusion_map` cannot rescue this: the Bistro `*_Specular` maps have an identically-zero red (occlusion) channel across all 633 textures, so there is no baked AO in the dataset to bind. - **No bounce.** Light does not carry colour between surfaces: no red spill from the awnings onto the stucco, no green bounce from the storefront onto the pavement. - **No local reflection.** `env_prefiltered` is the distant HDRI, so every reflective surface mirrors the sky regardless of what is actually in front of it. This is why the Bistro storefront glass shows a blurred HDRI skyline instead of the street and interior (see #156). - **Shadowed surfaces get no indirect light of their own** — only the directional light is shadowed (`shadowFactor`, primary directional, 3x3 PCF); ambient is unshadowed and flat. ### Scope This is deliberately an umbrella issue: "GI" is several separable techniques, and they do not have to land together. Rough ordering by cost/benefit for a raster engine: 1. **~~Screen-space ambient occlusion~~ — done.** Shipped as a depth+normal prepass plus a 24-tap hemisphere SSAO with a depth-aware blur (`subsystems/render/{prepass,ssao}.zig`), modulating the ambient term. Bistro visual-fidelity phase 3. 2. **~~Screen-space reflections~~ — done.** Shipped in `subsystems/render/ssr.zig`, reading the same prepass and resolving against last frame's composited `hdr_color` via temporal reprojection, falling back to `env_prefiltered` on miss and roughness-gated in `scene.frag.glsl`. Phase 5. 3. **~~Reflection probes~~ — done.** Shipped as `ReflectionProbeComponent` + `subsystems/render/reflection_probes.zig`, baked once into GGX-prefiltered local cubemaps through the same machinery the global HDRI uses, resolved per submesh and blended ahead of SSR's env fallback. Design: **ADR-0017**. Phase 6. 4. **Diffuse GI proper — designed, filed as #166.** Decided: **baked irradiance volumes**. Design in **ADR-0018** (`docs/ADR/ADR-0018-diffuse-gi-irradiance-volumes.md`). The other three options were ruled out on evidence, not preference: - *DDGI-style dynamic probes* — needs hardware ray tracing; SDL3 GPU exposes none on any backend, the same constraint that decided ADR-0017. - *Lightmaps* — need a second UV set and an atlas. Bistro ships no lightmap UVs and the importer has no unwrapper; building one is a larger project than the GI itself. - *Voxel cone tracing* — expensive and aliasing-prone, and adds a voxelization pass to a renderer already submission-bound at Bistro scale (#158). This issue tracked the overall direction and the choice of diffuse-GI approach. Both are now settled; the remaining implementation lives in #166. ### Decisions made - **Static vs. dynamic** — static. ADR-0017 made the call for reflection probes and ADR-0018 follows it for diffuse: bake-once, editor-side tooling, new versioned asset types. - **Ray tracing** — unavailable. Confirmed against the vendored `SDL_gpu.h`: no ray-tracing API on Vulkan, Metal or D3D12. - **Where it lives** — SSAO/SSR/probes landed in `subsystems/render/`; the irradiance-volume bake is an editor `TaskManager` job (ADR-0016) producing a new `.irradiance` asset. ### Original open questions (kept for context) - **Static vs. dynamic.** A bake-based approach (lightmaps / irradiance volumes) is far cheaper at runtime and fits the current renderer, but needs a bake pipeline in the editor, a new baked-data asset type, and it forecloses runtime-modified geometry. - **Ray tracing availability.** SDL3 GPU exposes no ray-tracing API today, which rules out hardware-RT approaches (DDGI, RTXGI) for now and pushes toward screen-space + baked techniques. - **Where it lives.** SSAO/SSR are post-process passes and belong with the existing HDR pipeline (`subsystems/render/postprocess_pipeline.zig`, #136). Probes/lightmaps need editor-side bake tooling and new asset types, closer to #16 (Asset Database). ### Prerequisites - SSAO and SSR both need a **depth + normal prepass** (or a G-buffer). The renderer is currently forward-only with an HDR colour target; some form of depth/normal buffer is a shared prerequisite for both, and is the natural first piece of work. ### Related - #132 Bistro sample — the driving use case and the visual benchmark - #144 Prefiltered cubemap IBL — the distant-environment specular this would extend - #136 HDR post-processing pipeline — where screen-space passes would slot in - ADR-0010 Lighting and shadows ### Scheduling note Items 1–3 shipped. Item 4 (#166) is scheduled **after** the performance epic #158 — it adds frame cost to a scene that can't afford it yet, and should land behind one of #160's feature toggles.