Rbanh
0798aa5d57
Add dedicated skinned rendering, pose restoration, shared Material and Material Instance slots, registry-driven components, Surface/Solari integration, transactional schema upgrades, navigation authoring, documentation, and evaluation evidence.
73 lines
4.3 KiB
Markdown
73 lines
4.3 KiB
Markdown
# ADR 0036: Surface ABI v1 and Solari Evaluator Parity
|
|
|
|
## Status
|
|
|
|
Accepted
|
|
|
|
## Context
|
|
|
|
Arbitrary full-pipeline WGSL cannot be carried safely between Bevy's raster pipelines and Solari's
|
|
ray-hit shaders. A custom fragment shader may own bindings, entry points, derivatives, discard, or
|
|
other stage-specific behavior that has no direct ray-tracing equivalent. Treating such a shader as
|
|
a `StandardMaterial` in Solari would produce a different material, while tracing skinned source
|
|
vertices would produce bind-pose geometry instead of the rasterized deformation.
|
|
|
|
Blacksite needs one constrained material expression that can produce the same surface values in
|
|
forward/deferred raster rendering and at Solari ray hits, while leaving transforms, skinning,
|
|
lighting, fog, shadows, and render-pipeline bindings under engine ownership.
|
|
|
|
## Decision
|
|
|
|
- `blacksite_surface` owns versioned Surface ABI v1. A custom evaluator implements:
|
|
|
|
```wgsl
|
|
fn evaluate(
|
|
input: SurfaceInput,
|
|
params: SurfaceParams,
|
|
samples: SurfaceSamples,
|
|
) -> Surface
|
|
```
|
|
|
|
`SurfaceInput` provides UV0, world position, and world normal. `Surface` returns base color,
|
|
tangent-space normal, emissive, metallic, perceptual roughness, reflectance, occlusion, alpha,
|
|
and lit/unlit model selection.
|
|
- The ABI has 16 `vec4` parameter lanes, eight sampled 2D texture slots with UV transforms, and a
|
|
400-byte `SurfaceUniform`. Shader schemas map typed Bool/Float/Vec2/Vec3/Color/Enum properties and
|
|
texture properties into that fixed layout. Exceeding either limit is a validation error.
|
|
- Evaluators cannot declare bindings or shader entry points and cannot use compute/storage,
|
|
ray-query, derivative, discard, barrier/subgroup, texture-store, or atomic constructs. The engine
|
|
supplies resources, entry points, vertex transforms/skinning, lighting, fog, and shadows.
|
|
- Raster rendering composes the evaluator between the engine-owned Surface header and footer and
|
|
installs it as an `ExtendedMaterial<StandardMaterial, SurfaceExtension>` for forward, deferred,
|
|
and prepass pipelines. Tangent-space normals are applied when the mesh supplies tangents.
|
|
- The maintained `third_party/bevy_solari` fork packs the same uniform and texture set, namespaces
|
|
validated evaluator functions, and generates a shader-ID dispatch library for ray hits. Eligible
|
|
non-deformed geometry uses the evaluator for hit material fields, tangent-space normal, emissive,
|
|
unlit behavior, and cutout candidate acceptance.
|
|
- Opaque and cutout are the supported alpha modes. Solari treats geometry as potentially
|
|
non-opaque and evaluates the exact Surface alpha and cutoff before accepting a cutout ray
|
|
candidate.
|
|
- Plain materials without a custom evaluator keep Bevy's standard raster and Solari material path.
|
|
Dependency revisions cover Material Instances, their direct base, shader schema, and evaluator.
|
|
Naga syntax/semantic validation and the cross-pipeline restrictions run before installation;
|
|
invalid updates produce diagnostics and retain the last successfully installed evaluator/library.
|
|
- Meshes with `SkinnedMesh`, runtime morph weights, or morph targets are excluded from Solari until
|
|
an instance-keyed deformed-vertex and BLAS update path exists. They continue to render through
|
|
Bevy's raster path; Solari diagnostics report the exclusion. No bind-pose ray-tracing fallback is
|
|
allowed.
|
|
|
|
## Consequences
|
|
|
|
- Custom material code is portable because it describes a surface, not an entire render stage.
|
|
- Raster and Solari evaluate the same source for supported, Solari-eligible static or rigid
|
|
geometry. Normal parity requires tangents; Solari compatibility diagnostics identify missing
|
|
tangents and other unsupported mesh layouts.
|
|
- Dynamic skinned/morph Solari geometry remains deliberate future work. This is a geometry parity
|
|
limit, not permission to substitute source/bind-pose vertices.
|
|
- ABI layout or semantic changes require a new version and migration. The fixed lanes and texture
|
|
count trade arbitrary resource layouts for deterministic cross-renderer packing.
|
|
- Blend, transmission, refraction, custom vertex displacement, arbitrary entry points, and
|
|
stage-specific shader behavior are unsupported by Surface ABI v1.
|
|
- Maintaining evaluator parity requires carrying the focused Solari fork until the necessary hooks
|
|
exist upstream; its dispatch and cutout behavior are covered by local tests.
|