diff --git a/docs/d3d12-migration.md b/docs/d3d12-migration.md index 4166eac..d4cbd7a 100644 --- a/docs/d3d12-migration.md +++ b/docs/d3d12-migration.md @@ -59,6 +59,12 @@ has feature parity. 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`. +- D3D12 now has the same native debug overlay controls as D3D11. DirectWrite + and Direct2D are kept for crisp overlay text through the documented D3D11On12 + bridge: D3D12 renders the frame, then the overlay acquires the swapchain + backbuffer, draws debug UI, releases it to Present, and does not participate + in scene/medium rendering. Diegetic text remains a future renderer-owned + MSDF/SDF path. - 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 @@ -86,3 +92,5 @@ has feature parity. - D3D12 work must be validated by actual headless runs, not just compilation. - D3D11 output remains the comparison target until D3D12 fully renders the scene. - Transparent surfaces are still events/candidates, not canonical depth. +- DirectWrite overlay text belongs behind the narrow D3D11On12 bridge. Do not + use it for diegetic/world text or let it leak into the renderer's scene graph. diff --git a/docs/hlsl-renderer.md b/docs/hlsl-renderer.md index f1542d5..dede874 100644 --- a/docs/hlsl-renderer.md +++ b/docs/hlsl-renderer.md @@ -292,6 +292,14 @@ composite strength. Those presentation controls feed the shader constant buffer global `GraphicsSettings` CultCache document; they are not cosmetic labels painted over hardcoded renderer state. +D3D12 keeps that native overlay text path through the documented D3D11On12 +bridge. D3D12 owns all scene, medium, bloom, resolve, and swapchain rendering; +after the command list finishes, the overlay briefly acquires the current +backbuffer as a wrapped D3D11 resource so Direct2D/DirectWrite can draw crisp +hinted debug text and controls, then releases it back to Present. This is an +overlay-only bridge. Diegetic text should still become renderer-owned MSDF/SDF +billboards. + It deliberately does not pretend to solve general non-rigid field velocity, volumetric history, or history resurrection yet. diff --git a/src/Aquarium.Engine/Render/D3D12Renderer.cs b/src/Aquarium.Engine/Render/D3D12Renderer.cs index 577909f..17c78cc 100644 --- a/src/Aquarium.Engine/Render/D3D12Renderer.cs +++ b/src/Aquarium.Engine/Render/D3D12Renderer.cs @@ -1,13 +1,20 @@ using Aquarium.Engine.Input; using SharpGen.Runtime; +using Aquarium.Engine.Render.Ui; using Vortice; using Vortice.D3DCompiler; using Vortice.Direct3D; +using Vortice.Direct3D11on12; using Vortice.Direct3D12; using Vortice.DXGI; using Vortice.Mathematics; using System.Numerics; using System.Runtime.InteropServices; +using ID3D11Device = Vortice.Direct3D11.ID3D11Device; +using ID3D11DeviceContext = Vortice.Direct3D11.ID3D11DeviceContext; +using ID3D11Resource = Vortice.Direct3D11.ID3D11Resource; +using D3D11DeviceCreationFlags = Vortice.Direct3D11.DeviceCreationFlags; +using D3D11BindFlags = Vortice.Direct3D11.BindFlags; namespace Aquarium.Engine.Render; @@ -40,10 +47,28 @@ public sealed class D3D12Renderer : IAquariumRenderer private const string MediumShaderRelativePath = "Render/Shaders/D3D12Medium.hlsl"; private const string SceneShaderRelativePath = "Render/Shaders/D3D12Scene.hlsl"; private const string PostShaderRelativePath = "Render/Shaders/D3D12Post.hlsl"; + private static readonly DebugUi.DebugUiOption[] RenderDebugOptions = + [ + new(0, "Final"), + new(1, "Raw Scene"), + new(2, "History"), + new(3, "History Age"), + new(4, "History Weight"), + new(5, "Temporal Control"), + new(6, "Field Identity"), + new(7, "Bloom"), + new(8, "Exposed Luminance"), + new(9, "Medium Ray Density"), + new(10, "Medium Ray Transmittance"), + new(11, "Froxel Density"), + ]; private readonly IDXGIFactory4 factory; private readonly ID3D12Device device; private readonly ID3D12CommandQueue commandQueue; + private readonly ID3D11Device overlayDevice; + private readonly ID3D11DeviceContext overlayContext; + private readonly ID3D11On12Device overlayOn12Device; private readonly IDXGISwapChain3 swapChain; private readonly D3D12ResourceRegistry resourceRegistry = new(); private D3D12DescriptorArena renderTargetViewArena; @@ -63,6 +88,9 @@ public sealed class D3D12Renderer : IAquariumRenderer private readonly ID3D12PipelineState resolvePipelineState; private readonly ID3D12Fence fence; private readonly AutoResetEvent fenceEvent = new(false); + private readonly DebugUi debugUi; + private ID3D11Resource[] overlayWrappedBackBuffers = []; + private DirectWriteOverlay[] overlays = []; private D3D12RenderTarget gridHeightRenderTarget; private D3D12RenderTarget mediumVolumeRenderTarget; private D3D12RenderTarget mediumTransportRenderTarget; @@ -100,7 +128,6 @@ public sealed class D3D12Renderer : IAquariumRenderer private float previousTimeSeconds; private GridHeightBrushConstants gridHeightBrushConstants; private GraphicsSettings settings = GraphicsSettings.Default; - private bool debugUiVisible = true; public D3D12Renderer( IntPtr windowHandle, @@ -122,6 +149,7 @@ public sealed class D3D12Renderer : IAquariumRenderer device.Name = "Aquarium D3D12 Device"; commandQueue = device.CreateCommandQueue(new CommandQueueDescription(CommandListType.Direct)); commandQueue.Name = "Aquarium D3D12 Direct Queue"; + CreateOverlayDevice(out overlayDevice, out overlayContext, out overlayOn12Device); var swapChainDescription = new SwapChainDescription1 { @@ -146,6 +174,8 @@ public sealed class D3D12Renderer : IAquariumRenderer } CreateRenderTargetViews(); + CreateBackBufferOverlays(); + debugUi = CreateDebugUi(); gridHeightRenderTarget = CreateGridHeightRenderTarget(); mediumVolumeRenderTarget = CreateMediumVolumeRenderTarget("medium-volume-target", "Aquarium D3D12 Medium Volume Target"); mediumTransportRenderTarget = CreateMediumVolumeRenderTarget("medium-transport-target", "Aquarium D3D12 Medium Transport Target"); @@ -210,13 +240,13 @@ public sealed class D3D12Renderer : IAquariumRenderer public bool DebugUiVisible { - get => debugUiVisible; - set => debugUiVisible = value; + get => debugUi.IsVisible; + set => debugUi.IsVisible = value; } public void UpdateDebugUi(InputState input) { - _ = input; + debugUi.Update(input); } public void CycleRenderDebugMode() @@ -234,6 +264,22 @@ public sealed class D3D12Renderer : IAquariumRenderer settings = graphicsSettings.Normalized(); } + private DebugUi CreateDebugUi() + { + return new DebugUi("Aquarium Debug") + .Panel(panel => panel + .Section("View") + .Options("Render Debug", () => RenderDebugMode, value => RenderDebugMode = Math.Clamp(value, GraphicsSettings.MinRenderDebugMode, GraphicsSettings.MaxRenderDebugMode), RenderDebugOptions, "Selects the active renderer debug view.") + .Button("Reset View", () => RenderDebugMode = 0, "Returns to the final presented frame.") + .Section("HDR") + .Slider("Exposure", () => settings.SceneExposure, value => settings = (settings with { SceneExposure = Math.Clamp(value, GraphicsSettings.MinSceneExposure, GraphicsSettings.MaxSceneExposure) }).Normalized(), GraphicsSettings.MinSceneExposure, GraphicsSettings.MaxSceneExposure, "0.###", "Manual scene exposure before display transform.") + .Slider("Bloom Intensity", () => settings.BloomIntensity, value => settings = (settings with { BloomIntensity = Math.Clamp(value, GraphicsSettings.MinBloomIntensity, GraphicsSettings.MaxBloomIntensity) }).Normalized(), GraphicsSettings.MinBloomIntensity, GraphicsSettings.MaxBloomIntensity, "0.###", "Strength of pre-tonemap bloom energy.") + .Slider("Bloom Veil", () => settings.BloomVeilIntensity, value => settings = (settings with { BloomVeilIntensity = Math.Clamp(value, GraphicsSettings.MinBloomVeilIntensity, GraphicsSettings.MaxBloomVeilIntensity) }).Normalized(), GraphicsSettings.MinBloomVeilIntensity, GraphicsSettings.MaxBloomVeilIntensity, "0.###", "Low-frequency veil from bright HDR energy.") + .Section("Medium") + .Slider("Composite", () => settings.MediumCompositeIntensity, value => settings = (settings with { MediumCompositeIntensity = Math.Clamp(value, GraphicsSettings.MinMediumCompositeIntensity, GraphicsSettings.MaxMediumCompositeIntensity) }).Normalized(), GraphicsSettings.MinMediumCompositeIntensity, GraphicsSettings.MaxMediumCompositeIntensity, "0.###", "Blends registered medium transport into the final scene.") + .Slider("Ray Step", () => settings.MediumDebugStep, value => settings = (settings with { MediumDebugStep = Math.Clamp(value, GraphicsSettings.MinMediumDebugStep, GraphicsSettings.MaxMediumDebugStep) }).Normalized(), GraphicsSettings.MinMediumDebugStep, GraphicsSettings.MaxMediumDebugStep, "Selects the medium raymarch sample shown by ray debug views.", () => RenderDebugMode is 9 or 10)); + } + public void Render(AquariumFrame frame, int width, int height) { ResizeIfNeeded(width, height); @@ -351,6 +397,7 @@ public sealed class D3D12Renderer : IAquariumRenderer commandList.Close(); commandQueue.ExecuteCommandList(commandList); + RenderOverlay(frame, frameResources); swapChain.Present(1, PresentFlags.None); SignalFrame(frameResources); ReportCapacityOncePerSecond(frame.TimeSeconds, frameResources); @@ -368,6 +415,10 @@ public sealed class D3D12Renderer : IAquariumRenderer fenceEvent.Dispose(); fence.Dispose(); commandList.Dispose(); + DisposeBackBufferOverlays(); + overlayOn12Device.Dispose(); + overlayContext.Dispose(); + overlayDevice.Dispose(); resolvePipelineState.Dispose(); bloomBlurVerticalPipelineState.Dispose(); bloomBlurHorizontalPipelineState.Dispose(); @@ -417,6 +468,70 @@ public sealed class D3D12Renderer : IAquariumRenderer } } + private void CreateOverlayDevice(out ID3D11Device createdDevice, out ID3D11DeviceContext createdContext, out ID3D11On12Device createdOn12Device) + { + var featureLevels = new[] { FeatureLevel.Level_11_1, FeatureLevel.Level_11_0 }; + var commandQueues = new IUnknown[] { commandQueue }; + Apis.D3D11On12CreateDevice( + device, + D3D11DeviceCreationFlags.BgraSupport, + featureLevels, + commandQueues, + 0, + out createdDevice, + out createdContext, + out _).CheckError(); + createdOn12Device = createdDevice.QueryInterface(); + } + + private void CreateBackBufferOverlays() + { + overlayWrappedBackBuffers = new ID3D11Resource[frames.Length]; + overlays = new DirectWriteOverlay[frames.Length]; + var flags = new Vortice.Direct3D11on12.ResourceFlags + { + BindFlags = D3D11BindFlags.RenderTarget, + }; + + for (var index = 0; index < frames.Length; index++) + { + var wrapped = overlayOn12Device.CreateWrappedResource( + frames[index].BackBuffer.Resource, + flags, + ResourceStates.RenderTarget, + ResourceStates.Present); + overlayWrappedBackBuffers[index] = wrapped; + using var surface = wrapped.QueryInterface(); + overlays[index] = new DirectWriteOverlay(surface, width, height); + } + } + + private void RenderOverlay(AquariumFrame frame, FrameResources frameResources) + { + var wrappedBackBuffer = overlayWrappedBackBuffers[frameIndex]; + overlayOn12Device.AcquireWrappedResources([wrappedBackBuffer]); + overlays[frameIndex].Render(frame, RenderDebugMode, debugUi); + overlayOn12Device.ReleaseWrappedResources([wrappedBackBuffer]); + overlayContext.Flush(); + frameResources.BackBuffer.MarkState(ResourceStates.Present); + } + + private void DisposeBackBufferOverlays() + { + foreach (var overlay in overlays) + { + overlay?.Dispose(); + } + + foreach (var wrappedBackBuffer in overlayWrappedBackBuffers) + { + wrappedBackBuffer?.Dispose(); + } + + overlays = []; + overlayWrappedBackBuffers = []; + } + private void UpdateMediumDimensions() { mediumFroxelWidth = Math.Max(1, width / MediumFroxelDownscale); @@ -435,6 +550,7 @@ public sealed class D3D12Renderer : IAquariumRenderer } WaitForGpu(); + DisposeBackBufferOverlays(); RemoveBloomRenderTargets(); RemoveHistoryRenderTargets(); resourceRegistry.RemoveRenderTarget("scene-hdr-target"); @@ -470,6 +586,7 @@ public sealed class D3D12Renderer : IAquariumRenderer swapChain.ResizeBuffers(BackBufferCount, (uint)width, (uint)height, Format.B8G8R8A8_UNorm, SwapChainFlags.None).CheckError(); frameIndex = (int)swapChain.CurrentBackBufferIndex; CreateRenderTargetViews(); + CreateBackBufferOverlays(); gridHeightRenderTarget = CreateGridHeightRenderTarget(); mediumVolumeRenderTarget = CreateMediumVolumeRenderTarget("medium-volume-target", "Aquarium D3D12 Medium Volume Target"); mediumTransportRenderTarget = CreateMediumVolumeRenderTarget("medium-transport-target", "Aquarium D3D12 Medium Transport Target"); @@ -761,7 +878,6 @@ public sealed class D3D12Renderer : IAquariumRenderer context.CommandList.OMSetRenderTargets(context.RenderTargetView, null); context.CommandList.IASetPrimitiveTopology(PrimitiveTopology.TriangleList); context.CommandList.DrawInstanced(3, 1, 0, 0); - context.BackBuffer.Transition(context.CommandList, ResourceStates.Present); return; } @@ -804,7 +920,6 @@ public sealed class D3D12Renderer : IAquariumRenderer null); context.CommandList.IASetPrimitiveTopology(PrimitiveTopology.TriangleList); context.CommandList.DrawInstanced(3, 1, 0, 0); - context.BackBuffer.Transition(context.CommandList, ResourceStates.Present); } finally { diff --git a/src/Aquarium.Engine/Render/D3D12TrackedResource.cs b/src/Aquarium.Engine/Render/D3D12TrackedResource.cs index a8851d6..a1496d2 100644 --- a/src/Aquarium.Engine/Render/D3D12TrackedResource.cs +++ b/src/Aquarium.Engine/Render/D3D12TrackedResource.cs @@ -29,6 +29,11 @@ internal sealed class D3D12TrackedResource : IDisposable State = nextState; } + public void MarkState(ResourceStates state) + { + State = state; + } + public void Dispose() { if (OwnsResource) diff --git a/state/evidence.jsonl b/state/evidence.jsonl index dd98f50..8df6438 100644 --- a/state/evidence.jsonl +++ b/state/evidence.jsonl @@ -84,3 +84,4 @@ {"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"} {"area":"renderer/d3d12/transparent-temporal","lesson":"D3D12 transparent stochastic surfaces now have a generic temporal event summary instead of piggybacking only on bulk medium identity. The medium pass writes a third froxel atlas target carrying transparent event support/density/radiance; the scene pass derives support-weighted travel and emits FIELD_ID_TRANSPARENT_EVENT; the resolve treats that identity as distributed medium-like history. Grid remains just the first producer of this path, not a special transparent surface exception.","files":["src/Aquarium.Engine/Render/D3D12Renderer.cs","src/Aquarium.Engine/Render/Shaders/D3D12Medium.hlsl","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 Aquarium.Engine.slnx",".\\scripts\\dev-reload.ps1 -Headless -RetainSlots 4 with AQUARIUM_RENDERER=d3d12 exited 0"],"ts":"2026-05-09"} +{"area":"renderer/d3d12/overlay","lesson":"D3D12 debug overlay parity uses the official D3D11On12 bridge to preserve native DirectWrite/Direct2D hinted text. The D3D12 frame graph owns scene rendering and leaves the backbuffer as a render target; the overlay briefly acquires the current wrapped swapchain image, draws the shared retained DebugUi, releases it to Present, and marks the tracked resource state. Keep this bridge narrow and overlay-only; diegetic text remains MSDF/SDF renderer work.","files":["src/Aquarium.Engine/Render/D3D12Renderer.cs","src/Aquarium.Engine/Render/D3D12TrackedResource.cs","docs/d3d12-migration.md","docs/hlsl-renderer.md","state/scratch.md"],"verification":["dotnet build Aquarium.Engine.slnx",".\\scripts\\dev-reload.ps1 -Headless -RetainSlots 4 -HeadlessTimeoutSeconds 30 with AQUARIUM_RENDERER=d3d12 and AQUARIUM_RENDER_DEBUG_MODE=0 exited 0",".\\scripts\\dev-reload.ps1 -Headless -RetainSlots 4 -HeadlessTimeoutSeconds 30 with AQUARIUM_RENDERER=d3d12 and AQUARIUM_RENDER_DEBUG_MODE=11 exited 0"],"ts":"2026-05-09"} diff --git a/state/scratch.md b/state/scratch.md index 0fe2ced..8bea67d 100644 --- a/state/scratch.md +++ b/state/scratch.md @@ -340,3 +340,10 @@ can start porting real passes while keeping D3D11 as the visual reference. treats medium and transparent-event identities as distributed history, not opaque surfaces, so Grid is not special-cased and future stochastic billboards can join the same path. +- D3D12 overlay parity pass: DirectWrite/Direct2D debug UI remains native hinted + overlay text through the documented D3D11On12 bridge. D3D12 renders the frame + and leaves the backbuffer in render-target state; the bridge acquires the + current swapchain image, draws the shared `DebugUi`, releases it to Present, + and marks the tracked resource state accordingly. Keep this bridge narrow and + overlay-only. Diegetic/world text still belongs to future MSDF/SDF renderer + billboards.