50 lines
2.7 KiB
Markdown
50 lines
2.7 KiB
Markdown
# ADR 0016: Unified rendering contract
|
|
|
|
## Status
|
|
|
|
Accepted
|
|
|
|
## Context
|
|
|
|
Rendering state crossed settings, hydration, game runtime, Solari readiness, editor viewport
|
|
ownership, and diagnostics. The project already had `ActiveCameraRenderProfile` for project and
|
|
volume intent, but GI fallback decisions were repeated across camera sync, Solari systems, and UI.
|
|
|
|
Bevy 0.18 Solari is still experimental. It needs raytracing-capable hardware, eligible
|
|
`Mesh3d + MeshMaterial3d<StandardMaterial>` scene geometry, Solari-compatible mesh assets
|
|
(TriangleList, POSITION/NORMAL/UV_0/TANGENT, U32 indices), a render-scene bind group, and a
|
|
compatible directional or emissive light source. It also does not replace Forward PBR local
|
|
point/spot shadow lighting.
|
|
|
|
## Decision
|
|
|
|
- `settings` owns the neutral render-stack contract:
|
|
`ActiveCameraRenderProfile` is requested intent, and `EffectiveRenderStack` records requested GI,
|
|
effective GI, Solari readiness, local shadow-light state, and fallback reason.
|
|
- `game_hot` owns runtime application of the stack. Camera systems call the shared resolver and
|
|
mirror the result into `RenderingCapabilities` for renderer method selection and diagnostics.
|
|
- Requested Solari and effective Solari are distinct. Requested Solari keeps eligible project
|
|
geometry tagged for raytracing and attaches Bevy Solari as soon as RT support is available, unless
|
|
local-shadow fallback is required.
|
|
- Effective Solari forces an HDR camera target regardless of authored HDR settings, because Bevy
|
|
Solari requires `STORAGE_BINDING` on the camera main texture and wgpu rejects storage usage on
|
|
sRGB target formats.
|
|
- Hybrid Auto remains the default policy: use Solari for directional/emissive scenes, surface
|
|
readiness diagnostics while it warms up, and fall back to Forward PBR when local point/spot shadow
|
|
correctness or unavailable RT features require it.
|
|
- Material authoring includes emissive color, intensity, and texture fields so scenes can create
|
|
Solari-compatible emissive contributors without Rust changes.
|
|
|
|
## Consequences
|
|
|
|
- Diagnostics must report requested GI, effective GI, and fallback reason from
|
|
`EffectiveRenderStack` rather than deriving labels independently.
|
|
- Solari mesh eligibility is based on hydrated project geometry under `LevelObject` ancestry with
|
|
`RaytracingExcluded` helpers filtered out. Built-in primitive hydration generates tangents for
|
|
Solari compatibility; imported/custom meshes remain visible in diagnostics when they lack
|
|
required Solari mesh attributes or U32 indices.
|
|
- Existing scenes and material assets remain compatible through serde defaults for new emissive
|
|
fields.
|
|
- Bevy 0.19+ rendering upgrades remain a separate migration track under ADR 0002, not part of this
|
|
contract change.
|