diff --git a/docs/hlsl-renderer.md b/docs/hlsl-renderer.md index e05d2db..291c4b2 100644 --- a/docs/hlsl-renderer.md +++ b/docs/hlsl-renderer.md @@ -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 diff --git a/docs/sdf-field-renderer-plan.md b/docs/sdf-field-renderer-plan.md index 65d02c7..20a7514 100644 --- a/docs/sdf-field-renderer-plan.md +++ b/docs/sdf-field-renderer-plan.md @@ -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. diff --git a/state/evidence.jsonl b/state/evidence.jsonl index 32d9858..8d8ca18 100644 --- a/state/evidence.jsonl +++ b/state/evidence.jsonl @@ -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"} diff --git a/state/memory.json b/state/memory.json index 6269925..6e6ca67 100644 --- a/state/memory.json +++ b/state/memory.json @@ -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." ], diff --git a/state/scratch.md b/state/scratch.md index a936fb5..23fb402 100644 --- a/state/scratch.md +++ b/state/scratch.md @@ -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.