Gate SDF field renderer behind waterfall plan
This commit is contained in:
parent
ec39230c84
commit
41aa2528cb
5 changed files with 56 additions and 26 deletions
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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"}
|
||||
|
|
|
|||
|
|
@ -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."
|
||||
],
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
Loading…
Reference in a new issue