Photon — native hybrid radiance-cascade GI
Real-time global illumination without hardware ray tracing: screen-anchored radiance cascades, interval merge and a sky/ambient far field.
Photon is a native engine system: it is compiled into caffeine-core and used by
the editor and runtime. It is not loaded as a plugin. It provides real-time global illumination
without hardware ray tracing.
v0.1 scope#
| Photon spec | v0.1 status |
|---|---|
| Screen-anchored near field | Implemented: K exponentially growing intervals traced against the depth buffer |
| Interval merge | Implemented: front-to-back radiance accumulation |
| Far field | Approximated: sky + ambient fallback when a ray leaves the screen |
| World-anchored probe field | Not yet |
| Multi-bounce feedback | Not yet |
| Glossy reflection pass | Not yet |
| Temporal denoiser | Provided by the engine's TAA: Photon runs before it |
The full specification is the design target. This native slice is intentionally labelled v0.1 wherever it differs from the reference design.
Presets#
| Preset | Quality | Cascades | Radius |
|---|---|---|---|
| Performance | Low | 3 | 10 m |
| Balanced | Medium | 4 | 14 m |
| High | High | 5 | 22 m |
| Cinematic | High | 6 | 32 m |
Parameters#
| Parameter | Meaning |
|---|---|
| Intensity | Indirect-light multiplier |
| Cascades | Number of distance intervals |
| Radius | Near-field reach in world units |
| Thickness | Depth tolerance for accepting a screen hit |
| Sky intensity | Far-field fallback when a ray leaves the screen |
| Ambient | Constant bounce term |
| Tint RGB | Albedo approximation applied to gathered radiance |
| Debug | Lit scene, GI only, or fallback only |
Use it#
- Open a scene with a Camera 3D and geometry.
- Open View → Photon Global Illumination, or run Photon GI in the command palette.
- Press Create Photon GI if the scene has no component yet.
- Pick a preset and tune radius/thickness for the scene scale.
- Switch Debug → GI only to inspect the cascade result.
The component is ECS::PhotonGIComponent; the Inspector has a full drawer as well.
Baked ambient occlusion (no RTX)#
The native Baked ambient occlusion section precomputes static AO into the selected mesh material:
- Select a static mesh entity (or use Bake scene).
- Choose resolution (256/512/1024), rays, max distance and bias.
- Press Bake selected mesh.
The baker uses GPU compute when the render device exposes compute, and falls back to the CPU BVH otherwise. The CPU only rasterises UVs and builds the triangle list; the expensive ray tests run on the GPU. Scenes above 8192 triangles use the CPU path.
The baker:
- gathers every static mesh triangle as an occluder,
- rasterises the target mesh in UV space,
- casts cosine-weighted rays,
- writes an ORM PNG with AO in R (roughness/metallic preserved in G/B),
- updates the material's
orm_mapandao_strength.
The runtime shader already samples ORM.R as ambient occlusion, so the result is applied with no ray-tracing hardware and no screen-space noise. Re-bake after changing static geometry.
Baked AO is for static meshes. Moving objects should keep using the screen-space Photon pass. Meshes with overlapping UVs average their faces; use unique UVs for per-face AO.
Troubleshooting the bake#
| Message | Cause / fix |
|---|---|
| Select a mesh entity in the Hierarchy | The bake targets a mesh (MeshFilterComponent). Select a mesh entity, not the environment or a light. |
| Selected entity has no mesh | The entity has no MeshFilterComponent, or its custom mesh path is invalid. |
| Mesh has no usable UV coverage | The mesh has no UVs, or all UVs are degenerate. Unwrap the mesh before baking. |
| Could not read material | customMaterialPath points to a missing or invalid .mat. Fix the path or clear it so the baker creates a new material. |
| Bake scene: N failed | Hover the status/log; the first failing entity and reason are shown. Other meshes are baked normally. |
| GPU compute unavailable | The device does not expose compute; the baker automatically uses the CPU BVH. |
| ORM generated but viewport unchanged | The material must be assigned to the mesh and the ORM path must resolve under the project root. Re-select the entity or reload the material. |
The bake is queued by the panel and executed between frames (after the editor frame is submitted). This keeps the GPU command buffer independent from the in-flight frame.
Performance#
- Low: 4 rays × 2 steps per interval
- Medium: 8 rays × 2 steps
- High: 12 rays × 3 steps
Photon runs before TAA, so the temporal resolve cleans the stochastic ray pattern. Start at Balanced for editing and High/Cinematic for captures.
Limitations#
- No world-anchored radiance probe field: off-screen light falls back to a constant sky + ambient term.
- Single bounce: the previous frame's indirect irradiance is not fed back yet.
- Screen-space occlusion can leak on thin geometry; raise Thickness or use a smaller Radius.
- Glossy reflections are not part of v0.1.