57 lines
3.3 KiB
Markdown
57 lines
3.3 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 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.
|
|
- Point/spot `LightDesc` components are runtime-disabled while Solari is active. They stay authored
|
|
and editable enough to switch kind, but hydration strips/skips their Bevy `PointLight`/`SpotLight`
|
|
components and the inspector explains the limitation on the component.
|
|
- Effective Solari and atmosphere force an HDR camera target regardless of authored HDR settings.
|
|
Bevy Solari requires `STORAGE_BINDING` on the camera main texture, and Bevy sky/atmosphere
|
|
pipelines must not be carried onto an SDR swapchain render pass.
|
|
- Runtime changes that alter the active render target or effective Solari/Forward path rebuild the
|
|
active camera stack instead of incrementally patching it. This
|
|
prevents stale pipelines from surviving texture-format transitions.
|
|
- 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 only when RT features are
|
|
unavailable.
|
|
- 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.
|
|
- Project settings can disable user-authored HDR, but the active camera still receives `Hdr` when
|
|
atmosphere or effective Solari requires an HDR target.
|
|
- 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.
|