Falling-Metal-Interactive/Blacksite
2
0
Fork 0
Code Issues 28 Pull Requests Actions Packages Projects Releases Wiki Activity
11b0df2b5f
Blacksite/docs/adr/0016-unified-rendering-contract.md
Rbanh 2054fa2558
Some checks are pending
CI / Format, lint, test, build (push) Waiting to run
Details
Advance M0 scene and rendering foundations
2026-06-06 03:50:03 -04:00

3.3 KiB
Raw Blame History

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.