Make medium debug views legible

This commit is contained in:
Meta Vens 2026-05-09 02:54:19 +01:00
commit a601f1d575
5 changed files with 34 additions and 20 deletions

View file

@ -231,11 +231,11 @@ half-resolution medium pass writes a 4x4 frustum slice atlas into diagnostic and
transport textures before the scene pass. Each atlas texel reconstructs a world
position and samples registered medium density there; resolve integrates those
stored cells front-to-back for transport diagnostics. Mode `9` is a separate
world-anchored density slice at Grid altitude, while modes `10` and `11` show
transport transmittance and source respectively. Final composition uses `surface
* transmittance + in-scattering`, gated by the persisted Medium Composite
control. The default is `0`, so the pass can be inspected without changing the
presented frame until the medium is tuned.
world-anchored density column over the Grid plane, while modes `10` and `11`
show transport transmittance and debug-boosted source respectively. Final
composition uses `surface * transmittance + in-scattering`, gated by the
persisted Medium Composite control. The default is `0`, so the pass can be
inspected without changing the presented frame until the medium is tuned.
The running window also has a Direct2D debug panel toggled with `F2`. It follows
the CultLib code-first composition style rather than an immediate-mode toolkit:

View file

@ -41,7 +41,7 @@ public sealed class D3D11Renderer : IDisposable
new(6, "Field Identity"),
new(7, "Bloom"),
new(8, "Exposed Luminance"),
new(9, "Density Slice"),
new(9, "Density Column"),
new(10, "Medium Transmittance"),
new(11, "Medium Source"),
];

View file

@ -1473,25 +1473,37 @@ float3 debugFieldIdColor(float fieldId)
return float3(1.0, 0.0, 1.0);
}
float mediumDensitySliceDebug(float3 rayDirection)
float mediumDensityColumnDebug(float3 rayDirection)
{
float sliceZ = 0.0;
float denominator = rayDirection.z;
if (abs(denominator) < 0.0001)
{
return 0.0;
}
float travel = (sliceZ - cameraPosition.z) / denominator;
float travel = (0.0 - cameraPosition.z) / denominator;
if (travel <= 0.0 || travel >= farDistance)
{
return 0.0;
}
float3 p = cameraPosition + rayDirection * travel;
float gridMask = 1.0 - smoothstep(gridRadius * 0.98, gridRadius * 1.04, length(p.xy - gridCenter));
float3 scattering;
return registeredMediumDensity(p, scattering) * gridMask;
float2 xy = (cameraPosition + rayDirection * travel).xy;
float gridMask = 1.0 - smoothstep(gridRadius * 0.98, gridRadius * 1.04, length(xy - gridCenter));
float maxDensity = 0.0;
float meanDensity = 0.0;
[unroll]
for (int sampleIndex = 0; sampleIndex < 16; sampleIndex++)
{
float z = lerp(-2.25, 3.5, ((float)sampleIndex + 0.5) / 16.0);
float3 scattering;
float density = registeredMediumDensity(float3(xy, z), scattering);
maxDensity = max(maxDensity, density);
meanDensity += density;
}
meanDensity /= 16.0;
return saturate((maxDensity * 0.85 + meanDensity * 1.75) * gridMask);
}
struct SceneOut
@ -1838,8 +1850,8 @@ ResolveOut AquariumResolvePS(VertexOut input)
else if (renderDebugMode >= 8.5 && renderDebugMode < 9.5)
{
float3 debugRay = rayDirectionForPixel(pixel, jitterPixels, cameraPosition, gridCenter);
float densitySlice = mediumDensitySliceDebug(debugRay);
finalColor = lerp(float3(0.01, 0.025, 0.04), float3(0.28, 0.78, 1.0), densitySlice);
float densityColumn = mediumDensityColumnDebug(debugRay);
finalColor = lerp(float3(0.006, 0.016, 0.026), float3(0.32, 0.86, 1.0), densityColumn);
}
else if (renderDebugMode >= 9.5 && renderDebugMode < 10.5)
{
@ -1848,7 +1860,7 @@ ResolveOut AquariumResolvePS(VertexOut input)
}
else if (renderDebugMode >= 10.5 && renderDebugMode < 11.5)
{
float source = saturate(dot(atlasMediumInScattering, float3(0.2126, 0.7152, 0.0722)) * 0.65);
float source = saturate(dot(atlasMediumInScattering, float3(0.2126, 0.7152, 0.0722)) * 18.0);
finalColor = lerp(float3(0.015, 0.015, 0.028), float3(0.95, 0.74, 0.36), source);
}

View file

@ -51,3 +51,4 @@
{"area":"renderer/volumetrics","lesson":"Medium composition is now explicit and gated: the half-resolution medium pass writes diagnostic and transport textures, and resolve can composite surface * transmittance + in-scattering through a persisted Medium Composite setting. The default remains zero so final presentation does not change until the medium is intentionally enabled and tuned.","files":["src/Aquarium.Engine.Contracts/GraphicsSettings.cs","src/Aquarium.Engine.Live/State/AquariumGraphicsSettingsState.cs","src/Aquarium.Engine.Live/State/AquariumCultStateStore.cs","src/Aquarium.Engine/Render/D3D11Renderer.cs","src/Aquarium.Engine/Render/Shaders/Aquarium.hlsl","docs/cult-runtime-surface.md","docs/hlsl-renderer.md","docs/sdf-field-renderer-plan.md","state/map.yaml","state/memory.json","state/scratch.md"],"verification":["dotnet build Aquarium.Engine.slnx",".\\scripts\\dev-reload.ps1 -Headless -RetainSlots 4","direct headless startup in final mode with default Medium Composite 0"],"ts":"2026-05-09"}
{"area":"renderer/volumetrics","lesson":"The first medium density view was too screen-ray dependent: it stored a completed half-res ray integral, so debug texture detail read as view-space soup. The pass now stores a 4x4 frustum slice atlas where each texel reconstructs a world point and evaluates field-local density; resolve integrates those stored cells front-to-back. Erosion noise is stationary in field-local space.","files":["src/Aquarium.Engine/Render/Shaders/Aquarium.hlsl","docs/hlsl-renderer.md","docs/sdf-field-renderer-plan.md","state/memory.json","state/scratch.md"],"verification":["dotnet build Aquarium.Engine.slnx",".\\scripts\\dev-reload.ps1 -Headless -RetainSlots 4"],"ts":"2026-05-09"}
{"area":"renderer/volumetrics","lesson":"Do not label a view-dependent transport projection as Medium Density. Mode 9 now evaluates the registered medium field on a world-anchored Grid-altitude slice, while modes 10 and 11 remain frustum transport diagnostics. Density debugging and transport debugging are different tools.","files":["src/Aquarium.Engine/Render/D3D11Renderer.cs","src/Aquarium.Engine/Render/Shaders/Aquarium.hlsl","docs/hlsl-renderer.md","state/scratch.md"],"verification":["dotnet build Aquarium.Engine.slnx"],"ts":"2026-05-09"}
{"area":"renderer/volumetrics","lesson":"A single Grid-altitude density slice can be legitimately blank when local media live above or below the Grid. Mode 9 is now a world-anchored density column over the Grid plane, sampling a fixed z range and visualizing max/mean density. Source debug is boosted independently from physical transport so near-black source patches do not masquerade as useful diagnostics.","files":["src/Aquarium.Engine/Render/D3D11Renderer.cs","src/Aquarium.Engine/Render/Shaders/Aquarium.hlsl","docs/hlsl-renderer.md","state/scratch.md"],"verification":["dotnet build Aquarium.Engine.slnx",".\\scripts\\dev-reload.ps1 -Headless -RetainSlots 4"],"ts":"2026-05-09"}

View file

@ -148,10 +148,11 @@ prototype integrated along the camera ray before surface composition.
reconstructs a world point and evaluates field-local density there; resolve
integrates the stored cells front-to-back. Removed the time term from erosion
noise so the texture itself is stationary under inspection.
- Follow-up correction: mode 9 is no longer the frustum atlas mean. It is a
world-anchored density slice at Grid altitude (`z = 0`) so density-field
texture can be inspected without confusing it with view-dependent transport
slices. Modes 10/11 remain transport diagnostics.
- Follow-up correction: mode 9 is no longer the frustum atlas mean or a single
`z = 0` slice. It is a world-anchored density column over the Grid plane, so
current above/below medium ellipsoids are actually visible. Modes 10/11 remain
transport diagnostics; source debug is boosted separately from physical
transport so black-on-black patches do not pass as information.
- Debug UI control grammar now includes named option rows. Render Debug uses an
option/dropdown selector instead of a numeric slider so the expanding debug
mode list remains legible.