From ca5106def2f2808918b6f0eb01f9f2e5cd5da283 Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Sat, 9 May 2026 17:28:52 +0100 Subject: [PATCH] Add D3D12 medium ray debug views --- docs/d3d12-migration.md | 4 + docs/hlsl-renderer.md | 4 + src/Aquarium.Engine/Render/D3D12Renderer.cs | 1 + .../Render/Shaders/D3D12Post.hlsl | 163 ++++++++++++++++++ state/evidence.jsonl | 1 + state/scratch.md | 4 + 6 files changed, 177 insertions(+) diff --git a/docs/d3d12-migration.md b/docs/d3d12-migration.md index 0ecca30..569595b 100644 --- a/docs/d3d12-migration.md +++ b/docs/d3d12-migration.md @@ -53,6 +53,10 @@ has feature parity. opacity and coverage rather than surface normals. Grid/transparent contributions therefore get history through the medium path without becoming fake alpha surfaces. +- D3D12 debug modes `9` and `10` are direct ray-step medium previews, not + repainted atlas views. The resolve shader samples the field instance buffer + for the requested `MediumDebugStep`, so density/transmittance diagnostics can + be compared against the froxel atlas in mode `11`. - Resize waits for the GPU, releases swapchain-dependent resources, rebuilds static shader/RTV descriptor arenas, then recreates backbuffer views and dependent render targets. Descriptor exhaustion on resize is no longer a diff --git a/docs/hlsl-renderer.md b/docs/hlsl-renderer.md index bb8a58b..fa8ef5e 100644 --- a/docs/hlsl-renderer.md +++ b/docs/hlsl-renderer.md @@ -102,6 +102,10 @@ overlay/debug UI still need to move. Medium-only pixels already use a density-weighted ray centroid and `FIELD_ID_MEDIUM`, so transparent Grid and fog contribution can accumulate through the medium history path without inventing a single alpha-surface hit. +D3D12 debug modes `9` and `10` are direct ray-step density/transmittance +previews from the field instance buffer, matching the D3D11 diagnostic contract +rather than sampling the froxel atlas. Mode `11` remains the froxel density +view. The shader far distance is frame-derived, not a fixed constant. C# sends the distance from the camera to the Grid origin plus the Grid radius, which matches diff --git a/src/Aquarium.Engine/Render/D3D12Renderer.cs b/src/Aquarium.Engine/Render/D3D12Renderer.cs index a2e9056..7d1b36f 100644 --- a/src/Aquarium.Engine/Render/D3D12Renderer.cs +++ b/src/Aquarium.Engine/Render/D3D12Renderer.cs @@ -774,6 +774,7 @@ public sealed class D3D12Renderer : IAquariumRenderer context.CommandList.SetGraphicsRootSignature(fullscreenRootSignature); context.CommandList.SetGraphicsRootDescriptorTable(0, frameResources.FrameConstantsDescriptor.Gpu); context.CommandList.SetGraphicsRootDescriptorTable(1, frameResources.SceneDescriptor.Gpu); + context.CommandList.SetGraphicsRootDescriptorTable(4, frameResources.FieldInstanceDescriptor.Gpu); context.CommandList.SetGraphicsRootDescriptorTable(7, frameResources.BloomPresentationDescriptor.Gpu); context.CommandList.SetGraphicsRootDescriptorTable(8, frameResources.SceneMetadataDescriptor.Gpu); context.CommandList.SetGraphicsRootDescriptorTable(9, frameResources.SceneControlDescriptor.Gpu); diff --git a/src/Aquarium.Engine/Render/Shaders/D3D12Post.hlsl b/src/Aquarium.Engine/Render/Shaders/D3D12Post.hlsl index f1d1834..5947f71 100644 --- a/src/Aquarium.Engine/Render/Shaders/D3D12Post.hlsl +++ b/src/Aquarium.Engine/Render/Shaders/D3D12Post.hlsl @@ -33,6 +33,18 @@ Texture2D bloomTexture1 : register(t10); Texture2D bloomTexture2 : register(t11); SamplerState sourceSampler : register(s0); +struct FieldInstance +{ + float4 centerRadius; + float4 radiusAngle; + float4 fieldFlags; + float4 materialMedium; + float4 colorIntensity; + float4 mediumTerms; +}; + +StructuredBuffer fieldInstances : register(t12); + struct VertexOut { float4 position : SV_Position; @@ -54,6 +66,9 @@ static const float FIELD_ID_SELF = 2.0; static const float FIELD_ID_MEDIUM = 3.0; static const float FIELD_ID_PLANET_BASE = 10.0; static const float MAX_HISTORY_AGE = 32.0; +static const int FIELD_INSTANCE_COUNT = 10; +static const int FIELD_FLAG_CLOUD = 2; +static const int MEDIUM_RAY_PREVIEW_STEPS = 48; VertexOut FullscreenTriangleVS(uint vertexId : SV_VertexID) { @@ -241,6 +256,138 @@ float3 presentColor(float3 scene, float2 uv) return aces(exposedScene + bloom * bloomIntensity + luminance(bloom) * bloomVeilIntensity); } +float hash31(float3 p) +{ + p = frac(p * 0.1031); + p += dot(p, p.yzx + 33.33); + return frac((p.x + p.y) * p.z) * 2.0 - 1.0; +} + +float noised3(float3 x) +{ + float3 p = floor(x); + float3 w = frac(x); + float3 u = w * w * w * (w * (w * 6.0 - 15.0) + 10.0); + + float a = hash31(p + float3(0.0, 0.0, 0.0)); + float b = hash31(p + float3(1.0, 0.0, 0.0)); + float c = hash31(p + float3(0.0, 1.0, 0.0)); + float d = hash31(p + float3(1.0, 1.0, 0.0)); + float e = hash31(p + float3(0.0, 0.0, 1.0)); + float f = hash31(p + float3(1.0, 0.0, 1.0)); + float g = hash31(p + float3(0.0, 1.0, 1.0)); + float h = hash31(p + float3(1.0, 1.0, 1.0)); + + float k0 = a; + float k1 = b - a; + float k2 = c - a; + float k3 = e - a; + float k4 = a - b - c + d; + float k5 = a - c - e + g; + float k6 = a - b - e + f; + float k7 = -a + b + c - d + e - f - g + h; + + return k0 + + k1 * u.x + + k2 * u.y + + k3 * u.z + + k4 * u.x * u.y + + k5 * u.y * u.z + + k6 * u.z * u.x + + k7 * u.x * u.y * u.z; +} + +float fbm3(float3 p) +{ + float value = 0.0; + float amplitude = 0.5; + + [unroll] + for (int i = 0; i < 3; i++) + { + value += noised3(p) * amplitude; + p = p.yzx * 2.03 + float3(3.7, 1.9, 5.1); + amplitude *= 0.52; + } + + return clamp(value, -1.0, 1.0); +} + +float2 rotate2(float2 value, float angle) +{ + float s = sin(angle); + float c = cos(angle); + return float2(value.x * c - value.y * s, value.x * s + value.y * c); +} + +float ellipsoidSdf(float3 p, float3 radius) +{ + float3 safeRadius = max(radius, 0.001); + float normalizedDistance = length(p / safeRadius) - 1.0; + return normalizedDistance * min(safeRadius.x, min(safeRadius.y, safeRadius.z)); +} + +float fieldDistance(float3 p, FieldInstance field) +{ + float3 local = p - field.centerRadius.xyz; + local.xy = rotate2(local.xy, -field.radiusAngle.w); + return ellipsoidSdf(local, max(field.radiusAngle.xyz, 0.001)); +} + +float registeredMediumDensity(float3 p) +{ + float density = 0.0; + + [unroll] + for (int i = 0; i < FIELD_INSTANCE_COUNT; i++) + { + FieldInstance field = fieldInstances[i]; + if (((int)(field.fieldFlags.y + 0.5) & FIELD_FLAG_CLOUD) == 0) + { + continue; + } + + float distanceToField = fieldDistance(p, field); + float shell = smoothstep(0.0, 0.42, -distanceToField); + if (shell <= 0.0) + { + continue; + } + + float3 local = p - field.centerRadius.xyz; + local.xy = rotate2(local.xy, -field.radiusAngle.w); + local /= max(field.radiusAngle.xyz, 0.001); + float erosion = saturate(0.86 + fbm3(local * 3.4) * 0.14); + float core = 1.0 - smoothstep(0.80, 1.05, length(local)); + density += shell * core * erosion * field.mediumTerms.w; + } + + return saturate(density); +} + +void previewRegisteredMediumStep(float3 rayOrigin, float3 rayDirection, float maxTravel, float requestedStep, out float stepDensity, out float transmittance) +{ + stepDensity = 0.0; + transmittance = 1.0; + float stepLength = maxTravel / (float)MEDIUM_RAY_PREVIEW_STEPS; + int selectedStep = clamp((int)round(requestedStep), 0, MEDIUM_RAY_PREVIEW_STEPS - 1); + + [loop] + for (int stepIndex = 0; stepIndex < MEDIUM_RAY_PREVIEW_STEPS; stepIndex++) + { + float travel = ((float)stepIndex + 0.5) * stepLength; + float3 p = rayOrigin + rayDirection * travel; + float density = registeredMediumDensity(p); + if (stepIndex == selectedStep) + { + stepDensity = density; + return; + } + + transmittance *= exp(-density * 0.16 * stepLength); + } +} + float4 D3D12BloomPrefilterPS(VertexOut input) : SV_Target0 { return float4(sourceTexture.SampleLevel(sourceSampler, input.uv, 0.0).rgb * max(exposure, 0.001), 1.0); @@ -410,6 +557,22 @@ ResolveOut D3D12ResolvePS(VertexOut input) float luma = luminance(currentColor * max(exposure, 0.001)); finalColor = luma.xxx; } + else if (renderDebugMode >= 8.5 && renderDebugMode < 9.5) + { + float3 debugRay = rayDirectionForPixel(pixel, jitterPixels, cameraPosition, gridCenter); + float stepDensity; + float stepTransmittance; + previewRegisteredMediumStep(cameraPosition, debugRay, farDistance, mediumDebugStep, stepDensity, stepTransmittance); + finalColor = lerp(float3(0.006, 0.016, 0.026), float3(0.32, 0.86, 1.0), saturate(stepDensity * 3.0)); + } + else if (renderDebugMode >= 9.5 && renderDebugMode < 10.5) + { + float3 debugRay = rayDirectionForPixel(pixel, jitterPixels, cameraPosition, gridCenter); + float stepDensity; + float stepTransmittance; + previewRegisteredMediumStep(cameraPosition, debugRay, farDistance, mediumDebugStep, stepDensity, stepTransmittance); + finalColor = lerp(float3(0.10, 0.02, 0.01), float3(0.72, 1.0, 0.86), saturate(stepTransmittance)); + } ResolveOut output; output.finalColor = float4(finalColor, 1.0); diff --git a/state/evidence.jsonl b/state/evidence.jsonl index 9a6ebed..cc89003 100644 --- a/state/evidence.jsonl +++ b/state/evidence.jsonl @@ -82,3 +82,4 @@ {"area":"renderer/d3d12/temporal","lesson":"D3D12 now has the first temporal diagnostic spine: the scene pass writes color/travel, field-id/normal metadata, and temporal-control MRTs, and the present shader can inspect current control in debug mode 5 and field identity in debug mode 6. This is not TAA parity yet; history ping-pong, reprojection, validation, and age/weight outputs still need to be ported before temporal accumulation is real.","files":["src/Aquarium.Engine/Render/D3D12Renderer.cs","src/Aquarium.Engine/Render/Shaders/D3D12Scene.hlsl","src/Aquarium.Engine/Render/Shaders/D3D12Post.hlsl","docs/d3d12-migration.md","docs/hlsl-renderer.md","state/scratch.md"],"verification":["dotnet build src\\Aquarium.Engine\\Aquarium.Engine.csproj","dotnet build Aquarium.Engine.slnx",".\\scripts\\dev-reload.ps1 -Headless -RetainSlots 4 -HeadlessTimeoutSeconds 20 with AQUARIUM_RENDERER=d3d12 and AQUARIUM_RENDER_DEBUG_MODE=0 exited 0",".\\scripts\\dev-reload.ps1 -Headless -RetainSlots 4 -HeadlessTimeoutSeconds 20 with AQUARIUM_RENDERER=d3d12 and AQUARIUM_RENDER_DEBUG_MODE=5 exited 0",".\\scripts\\dev-reload.ps1 -Headless -RetainSlots 4 -HeadlessTimeoutSeconds 20 with AQUARIUM_RENDERER=d3d12 and AQUARIUM_RENDER_DEBUG_MODE=6 exited 0"],"ts":"2026-05-09"} {"area":"renderer/d3d12/temporal","lesson":"D3D12 resolve now owns presentation and history output: it writes the swapchain plus ping-pong history color, metadata, and control targets. Opaque current scene hits reproject through previous camera/Grid state, remap orbiting planet hits to previous centers, and validate by field id, travel, normal, neighborhood color, coverage, and medium opacity before blending. Debug mode 3 shows history age and mode 4 history weight. Grid/transparent-specific temporal reconstruction remains pending.","files":["src/Aquarium.Engine/Render/D3D12Renderer.cs","src/Aquarium.Engine/Render/Shaders/D3D12Post.hlsl","docs/d3d12-migration.md","docs/hlsl-renderer.md","state/scratch.md"],"verification":["dotnet build src\\Aquarium.Engine\\Aquarium.Engine.csproj","dotnet build Aquarium.Engine.slnx",".\\scripts\\dev-reload.ps1 -Headless -RetainSlots 4 -HeadlessTimeoutSeconds 20 with AQUARIUM_RENDERER=d3d12 and AQUARIUM_RENDER_DEBUG_MODE=0 exited 0",".\\scripts\\dev-reload.ps1 -Headless -RetainSlots 4 -HeadlessTimeoutSeconds 20 with AQUARIUM_RENDERER=d3d12 and AQUARIUM_RENDER_DEBUG_MODE=3 exited 0",".\\scripts\\dev-reload.ps1 -Headless -RetainSlots 4 -HeadlessTimeoutSeconds 20 with AQUARIUM_RENDERER=d3d12 and AQUARIUM_RENDER_DEBUG_MODE=4 exited 0",".\\scripts\\dev-reload.ps1 -Headless -RetainSlots 4 -HeadlessTimeoutSeconds 20 with AQUARIUM_RENDERER=d3d12 and AQUARIUM_RENDER_DEBUG_MODE=11 exited 0"],"ts":"2026-05-09"} {"area":"renderer/d3d12/temporal","lesson":"Medium-only D3D12 pixels now get a volumetric temporal identity instead of being excluded from history: the scene pass stores FIELD_ID_MEDIUM, coverage from medium opacity/density, and travel from a density-weighted ray centroid. Resolve treats medium history as volumetric by skipping normal rejection, relaxing color rejection, and validating continuity through coverage and medium opacity. This stabilizes binned Grid/fog contribution without turning transparent surfaces back into alpha-depth surfaces.","files":["src/Aquarium.Engine/Render/Shaders/D3D12Scene.hlsl","src/Aquarium.Engine/Render/Shaders/D3D12Post.hlsl","docs/d3d12-migration.md","docs/hlsl-renderer.md","state/scratch.md"],"verification":["dotnet build src\\Aquarium.Engine\\Aquarium.Engine.csproj","dotnet build Aquarium.Engine.slnx",".\\scripts\\dev-reload.ps1 -Headless -RetainSlots 4 -HeadlessTimeoutSeconds 20 with AQUARIUM_RENDERER=d3d12 and AQUARIUM_RENDER_DEBUG_MODE=0 exited 0",".\\scripts\\dev-reload.ps1 -Headless -RetainSlots 4 -HeadlessTimeoutSeconds 20 with AQUARIUM_RENDERER=d3d12 and AQUARIUM_RENDER_DEBUG_MODE=6 exited 0",".\\scripts\\dev-reload.ps1 -Headless -RetainSlots 4 -HeadlessTimeoutSeconds 20 with AQUARIUM_RENDERER=d3d12 and AQUARIUM_RENDER_DEBUG_MODE=3 exited 0"],"ts":"2026-05-09"} +{"area":"renderer/d3d12/debug","lesson":"D3D12 render debug modes 9 and 10 now match the D3D11 diagnostic contract: the resolve shader binds the field instance buffer and directly samples registered medium density/transmittance at the requested MediumDebugStep. These views are correctness probes independent of the froxel atlas; mode 11 remains the atlas density view.","files":["src/Aquarium.Engine/Render/D3D12Renderer.cs","src/Aquarium.Engine/Render/Shaders/D3D12Post.hlsl","docs/d3d12-migration.md","docs/hlsl-renderer.md","state/scratch.md"],"verification":["dotnet build src\\Aquarium.Engine\\Aquarium.Engine.csproj","dotnet build Aquarium.Engine.slnx",".\\scripts\\dev-reload.ps1 -Headless -RetainSlots 4 -HeadlessTimeoutSeconds 20 with AQUARIUM_RENDERER=d3d12 and AQUARIUM_RENDER_DEBUG_MODE=9 exited 0",".\\scripts\\dev-reload.ps1 -Headless -RetainSlots 4 -HeadlessTimeoutSeconds 20 with AQUARIUM_RENDERER=d3d12 and AQUARIUM_RENDER_DEBUG_MODE=10 exited 0",".\\scripts\\dev-reload.ps1 -Headless -RetainSlots 4 -HeadlessTimeoutSeconds 20 with AQUARIUM_RENDERER=d3d12 and AQUARIUM_RENDER_DEBUG_MODE=0 exited 0"],"ts":"2026-05-09"} diff --git a/state/scratch.md b/state/scratch.md index 0b6b40c..2933af1 100644 --- a/state/scratch.md +++ b/state/scratch.md @@ -329,3 +329,7 @@ can start porting real passes while keeping D3D11 as the visual reference. normal validation is skipped, color rejection is relaxed, and continuity is driven by coverage plus medium opacity. This lets binned Grid/fog contribution accumulate without reintroducing alpha surfaces. +- D3D12 medium ray debug pass: resolve now binds the field instance buffer and + implements direct ray-step registered-medium previews for modes 9 and 10. + These are correctness probes independent of the froxel atlas; mode 11 remains + the atlas density view.