Gate SDF field renderer behind waterfall plan

This commit is contained in:
Meta Vens 2026-05-08 21:37:32 +01:00
commit 41aa2528cb
5 changed files with 56 additions and 26 deletions

View file

@ -109,6 +109,11 @@ coordinate and composition contract for local SDF clouds, but the final renderer
should move toward the explicit field registry and volume pass described in
`docs/sdf-field-renderer-plan.md`.
Do not grow this scaffold sideways. The SDF cloud path is now a waterfall
renderer task: field contract, broad phase, explicit volume pass, then
composition and acceleration. Correctness fixes belong here only when needed to
keep the scene inspectable while the real machine is built.
Current prototype traits:
- ellipsoid SDF cloud containers

View file

@ -78,34 +78,38 @@ A hybrid field has both solid and medium behavior. Examples:
## Render Architecture
### Stage 1: Analytic Field Prototype
This renderer needs a waterfall implementation shape. The wrong abstraction here
is not a harmless intermediate state; it becomes the renderer. Build the machine
we want, then bring it up behind explicit gates.
Start inside the current fullscreen HLSL path:
### Gate 1: Field Contract
1. Keep the existing terrain/body raymarch.
2. Add a small analytic SDF cloud registry in shader code.
3. March local cloud density along the camera ray up to the nearest solid hit or
the Grid far distance.
4. Composite as:
Define the field instance ABI before adding more visual tricks:
```text
final = cloud_scattering + cloud_transmittance * surface_color
```
- CPU-owned field registry.
- Stable field ids and debug names.
- World transform plus inverse transform.
- Conservative bounds.
- Shape parameters.
- Material and medium ids.
- Field flags for solid, cloud, hybrid, emitter, shadow caster, and receiver.
- Debug mode ids and per-field visibility toggles.
This is allowed as a prototype because it proves the field contract and visual
direction. It is not allowed to become the final volume architecture by stealth.
Hard-coded shader field loops are temporary scaffolding only. Do not extend them
except to replace them.
### Stage 2: Field Instance Contract
### Gate 2: Broad Phase
Move analytic field identity out of hard-coded shader loops:
Move field selection out of brute-force pixel loops:
- CPU packs field instances into a structured buffer.
- Each instance has transform, bounds, kind, material id, medium id, and shape
parameters.
- The current body froxel table evolves into a general field broad phase.
- Debug views show candidate fields, bounds, and step counts.
- Candidate lists are available to solid and medium passes.
- Debug views show candidate fields, bounds, rejected fields, and step counts.
### Stage 3: Explicit Volume Pass
### Gate 3: Explicit Volume Pass
Add a renderer-owned low-resolution volume pass:
@ -119,7 +123,19 @@ Add a renderer-owned low-resolution volume pass:
This follows Wronski/Hillaire for the pass shape, but without assuming clouds
are distant sky content.
### Stage 4: SDF Acceleration
### Gate 4: Surface And Medium Composition
Make composition explicit:
- solid ray hits produce surface color, depth, normal, material, and field id
- medium integration respects surface depth
- clouds in front of surfaces affect surfaces through transmittance
- clouds behind surfaces do not leak through opaque solids
- multiple cloud intervals accumulate front-to-back without sample-budget
starvation
- debug views expose each composition term
### Gate 5: SDF Acceleration
Only after profiling proves the need:
@ -165,15 +181,18 @@ Before this grows teeth, add debug surfaces for:
If we cannot see why a pixel looks wrong, the renderer is already lying.
## First Implementation Slice
## Current Temporary Scaffold
The first code slice is intentionally small:
`Aquarium.hlsl` currently contains an analytic local cloud scaffold. It exists to
keep pixels alive while the real field renderer is built, not to define the
architecture.
1. Add analytic local SDF cloud functions to `Aquarium.hlsl`.
2. March them in world space along each camera ray.
3. Allow clouds below, above, and around the Grid.
4. Composite cloud scattering/transmittance with the existing surface raymarch.
5. Keep all coordinates stable in world/object space.
Rules for that scaffold:
This starts the visual grammar without committing to the final storage or pass
layout. A tiny honest machine. How upsettingly rare.
- Fix correctness bugs when they block evaluation.
- Do not add new cloud features there.
- Do not tune around structural failures.
- Replace it with the field registry, broad phase, and explicit volume pass.
- Treat every artifact as evidence for the final machine, not as an invitation
to add another little compromise. The compromise pile is how renderers become
haunted furniture.

View file

@ -12,3 +12,4 @@
{"area":"renderer/sdf-fields","lesson":"Documented the SDF field renderer plan and started a local SDF cloud prototype. Aquarium/Aetheria clouds are local world media that may be above, below, around, or enclosing the camera, so the core cloud architecture must not rely on skybox, hemisphere, paraboloid, or far-only assumptions. First implementation integrates four bounded analytic SDF cloud media along the camera ray before surface composition.","files":["docs/sdf-field-renderer-plan.md","docs/hlsl-renderer.md","src/Aquarium.Engine/Render/Shaders/Aquarium.hlsl","state/map.yaml","state/memory.json","state/scratch.md"],"verification":["dotnet build Aquarium.Engine.slnx",".\\scripts\\dev-reload.ps1 -Headless -RetainSlots 4"],"ts":"2026-05-08"}
{"area":"renderer/sdf-fields","lesson":"The first SDF cloud transfer function made nearer ellipsoid edges occlude farther clouds because the SDF boundary produced a positive-distance absorbing veil and too much extinction. Cloud SDFs should provide sculptural containment and empty-space skipping, while density should be eroded interior occupancy with feathered boundaries and low extinction until a real volume pass owns the transfer function.","files":["src/Aquarium.Engine/Render/Shaders/Aquarium.hlsl","docs/hlsl-renderer.md","state/memory.json","state/scratch.md"],"verification":["dotnet build Aquarium.Engine.slnx",".\\scripts\\dev-reload.ps1 -Headless -RetainSlots 4"],"ts":"2026-05-08"}
{"area":"renderer/sdf-fields","lesson":"Fainter extinction did not fix near-cloud silhouettes because the prototype was still structurally wrong: a global SDF shell march could spend the frame's cloud sample budget inside a nearer ellipsoid and fail to reach farther cloud intervals. The analytic prototype now intersects ray/ellipsoid intervals, jumps empty space to true entries, and samples density only inside container volumes.","files":["src/Aquarium.Engine/Render/Shaders/Aquarium.hlsl","docs/hlsl-renderer.md","state/memory.json","state/scratch.md"],"verification":["dotnet build Aquarium.Engine.slnx",".\\scripts\\dev-reload.ps1 -Headless -RetainSlots 4"],"ts":"2026-05-08"}
{"area":"renderer/sdf-fields","lesson":"The SDF field/cloud renderer should use a waterfall implementation shape, not a chain of shy compromised prototypes. Define the target machine first: field ABI, broad phase, explicit local volume pass, composition contract, and acceleration gates. The current fullscreen analytic cloud code is temporary scaffolding for inspection only, not a place to accumulate features.","files":["docs/sdf-field-renderer-plan.md","docs/hlsl-renderer.md","state/memory.json","state/scratch.md"],"ts":"2026-05-08"}

View file

@ -44,6 +44,7 @@
"The SDF field renderer plan is docs/sdf-field-renderer-plan.md: solids and clouds should share one field grammar, with distance, density, material, medium, bounds, and debug views.",
"SDF cloud distance should shape and accelerate the medium, not create a positive-distance absorbing shell. Prototype ellipsoid edges occluded farther clouds until density was changed to eroded interior occupancy with lower extinction.",
"A bounded cloud prototype should march analytic ray/volume intervals, not global SDF shells. The first cloud artifact persisted until rays jumped between true ellipsoid entry/exit intervals; otherwise near fields can consume the sample budget and masquerade as occluders.",
"SDF clouds/solids need waterfall architecture, not agile accretion. Define and build the field contract, broad phase, explicit local volume pass, composition contract, and acceleration gates before adding more cloud features.",
"Bruneton-style atmospheric scattering is the later sky/planet solution, not the first Grid fog pass. Use LUTs, explicit texture mappings, and unit-tested physical terms when Aquarium reaches ground-to-space atmosphere.",
"GigaVoxels-style ray-guided sparse bricks are only for large sparse field/world storage. Do not turn early fog into a monolithic persistent volume cache."
],

View file

@ -27,3 +27,7 @@ prototype integrated along the camera ray before surface composition.
- Follow-up fix made the march structural: intersect each analytic cloud
ellipsoid, jump empty space to the next true entry, and sample only inside
cloud intervals so near containers cannot eat the budget before far clouds.
- Method correction: stop iterating cloud features by agile half-step. Build the
target renderer as a waterfall machine: field contract, broad phase, explicit
local volume pass, composition, then acceleration. Current shader cloud code is
temporary scaffolding only.