Merge pull request #3287 from LazyWorksZA/fix/sslr-transparent-attachment-mismatch

fix: Local Reflections causes Vulkan device loss (surplus MRT targets bound in transparent stage)

Author: xen2

sources/engine/Stride.Engine.Tests/ForwardRendererTransparentTargetsTest.cs

@@ -0,0 +1,59 @@
+// Copyright (c) .NET Foundation and Contributors (https://dotnetfoundation.org/ & https://stride3d.net)
+// Distributed under the MIT license. See the LICENSE.md file in the project root for more information.
+
+using Xunit;
+
+using Stride.Graphics;
+using Stride.Graphics.Regression;
+using Stride.Rendering;
+using Stride.Rendering.Compositing;
+
+namespace Stride.Engine.Tests;
+
+public class ForwardRendererTransparentTargetsTest : GameTestBase
+{
+    /// <summary>
+    /// Verifies the ForwardRenderer binds only as many render targets as the transparent stage declares it
+    /// outputs, dropping surplus opaque MRT targets (e.g. those Local Reflections adds). See #3251.
+    /// </summary>
+    [Fact]
+    public void BindsOnlyTransparentStageDeclaredTargets()
+    {
+        PerformDrawTest((game, context) =>
+        {
+            var device = game.GraphicsDevice;
+            var commandList = context.CommandList;
+
+            var transparentStage = new RenderStage("Transparent", "Main")
+            {
+                Output = new RenderOutputDescription(PixelFormat.R8G8B8A8_UNorm, PixelFormat.D24_UNorm_S8_UInt),
+            };
+            var forwardRenderer = new ForwardRenderer { TransparentRenderStage = transparentStage };
+
+            // Formats are irrelevant here (only the target count matters); use a widely supported one.
+            var color = Texture.New2D(device, 16, 16, PixelFormat.R8G8B8A8_UNorm, TextureFlags.RenderTarget);
+            var normal = Texture.New2D(device, 16, 16, PixelFormat.R8G8B8A8_UNorm, TextureFlags.RenderTarget);
+            var specular = Texture.New2D(device, 16, 16, PixelFormat.R8G8B8A8_UNorm, TextureFlags.RenderTarget);
+            var depth = Texture.New2D(device, 16, 16, PixelFormat.D24_UNorm_S8_UInt, TextureFlags.DepthStencil);
+
+            // Opaque stage left 3 color targets + depth bound, as SSLR would.
+            commandList.SetRenderTargets(depth, color, normal, specular);
+            Assert.Equal(3, commandList.RenderTargetCount);
+
+            forwardRenderer.SetTransparentStageRenderTargets(context);
+
+            Assert.Equal(1, commandList.RenderTargetCount);
+            Assert.Equal(color, commandList.RenderTargets[0]);
+            Assert.Equal(depth, commandList.DepthStencilBuffer);
+
+            // Already matching the declared count: no change.
+            forwardRenderer.SetTransparentStageRenderTargets(context);
+            Assert.Equal(1, commandList.RenderTargetCount);
+
+            color.Dispose();
+            normal.Dispose();
+            specular.Dispose();
+            depth.Dispose();
+        }, takeSnapshot: false);
+    }
+}

sources/engine/Stride.Engine.Tests/Stride.Engine.Tests.csproj

@@ -22,6 +22,7 @@
     <Compile Include="XunitAttributes.cs" />
     <Compile Include="Build\TestBuilder.cs" />
     <Compile Include="EngineTestBase.cs" />
+    <Compile Include="ForwardRendererTransparentTargetsTest.cs" />
     <Compile Include="ParameterCollectionUpdateEngineTest.cs" />
     <Compile Include="EntityUpdateEngineTest.cs" />
     <Compile Include="AnimatedModelTests.cs" />

sources/engine/Stride.Engine/Rendering/Compositing/ForwardRenderer.cs

@@ -555,6 +555,8 @@ protected virtual void DrawView(RenderContext context, RenderDrawContext drawCon
 
                         var renderTargetSRV = ResolveRenderTargetAsSRV(drawContext);
 
+                        SetTransparentStageRenderTargets(drawContext);
+
                         renderSystem.Draw(drawContext, context.RenderView, TransparentRenderStage);
 
                         Context.Allocator.ReleaseReference(renderTargetSRV);
@@ -807,6 +809,21 @@ private Texture ResolveDepthAsSRV(RenderDrawContext context)
             return depthStencilSRV;
         }
 
+        /// <summary>
+        /// Binds only the render targets the transparent stage outputs, dropping any surplus opaque targets left
+        /// bound by post-effects (e.g. Local Reflections) so the framebuffer matches the transparent render pass.
+        /// </summary>
+        internal void SetTransparentStageRenderTargets(RenderDrawContext drawContext)
+        {
+            if (TransparentRenderStage == null)
+                return;
+
+            var commandList = drawContext.CommandList;
+            var declaredCount = TransparentRenderStage.Output.RenderTargetCount;
+            if (declaredCount >= 1 && commandList.RenderTargetCount > declaredCount)
+                commandList.SetRenderTargets(commandList.DepthStencilBuffer, commandList.RenderTargets.Slice(0, declaredCount));
+        }
+
         private Texture ResolveRenderTargetAsSRV(RenderDrawContext drawContext)
         {
             if (!BindOpaqueAsResourceDuringTransparentRendering)

sources/engine/Stride.Graphics.Tests/TestFramebufferAttachmentGuard.cs

@@ -0,0 +1,75 @@
+// Copyright (c) .NET Foundation and Contributors (https://dotnetfoundation.org/ & https://stride3d.net)
+// Distributed under the MIT license. See the LICENSE.md file in the project root for more information.
+
+using System;
+
+using Xunit;
+
+using Stride.Core.Mathematics;
+using Stride.Rendering;
+
+namespace Stride.Graphics.Tests;
+
+public class TestFramebufferAttachmentGuard : GraphicTestGameBase
+{
+    private struct Vertex
+    {
+        public Vector3 Position;
+        public Vector2 TexCoords;
+    }
+
+    /// <summary>
+    /// The Vulkan backend's debug guard turns a framebuffer/render-pass attachment-count mismatch into a clear
+    /// exception instead of a device loss. Verify it fires when more render targets are bound than the active
+    /// pipeline's render pass declares.
+    /// </summary>
+    [SkippableFact]
+    public void ThrowsWhenBoundTargetsExceedPipelineRenderPass()
+    {
+        PerformTest(game =>
+        {
+            // The guard lives in the Vulkan backend (and needs the debug device, which GraphicTestGameBase sets).
+            Skip.IfNot(GraphicsDevice.Platform == GraphicsPlatform.Vulkan, "Attachment guard is Vulkan-only.");
+
+            var device = game.GraphicsDevice;
+            var commandList = game.GraphicsContext.CommandList;
+
+            var backBuffer = device.Presenter.BackBuffer;
+            var depth = device.Presenter.DepthStencilBuffer;
+            var extraTarget = Texture.New2D(device, backBuffer.Width, backBuffer.Height, backBuffer.Format, TextureFlags.RenderTarget);
+
+            var declaration = new VertexDeclaration(VertexElement.Position<Vector3>(), VertexElement.TextureCoordinate<Vector2>());
+            var vertexBuffer = Buffer.Vertex.New(device, new Vertex[3], GraphicsResourceUsage.Default);
+            var sampledTexture = Texture.New2D(device, 4, 4, PixelFormat.R8G8B8A8_UNorm, TextureFlags.ShaderResource);
+
+            var effect = new EffectInstance(new Effect(device, SpriteEffect.Bytecode));
+            effect.Parameters.Set(TexturingKeys.Texture0, sampledTexture);
+            effect.Parameters.Set(TexturingKeys.Sampler, device.SamplerStates.LinearClamp);
+            effect.UpdateEffect(device);
+
+            var pipelineState = new MutablePipelineState(device);
+            pipelineState.State.SetDefaults();
+            pipelineState.State.RootSignature = effect.RootSignature;
+            pipelineState.State.EffectBytecode = effect.Effect.Bytecode;
+            pipelineState.State.InputElements = declaration.CreateInputElements();
+            pipelineState.State.PrimitiveType = PrimitiveType.TriangleList;
+
+            // Capture the pipeline Output with a single color + depth bound: its render pass declares 2 attachments.
+            commandList.SetRenderTargetAndViewport(depth, backBuffer);
+            pipelineState.State.Output.CaptureState(commandList);
+            pipelineState.Update();
+
+            // Now bind two color targets + depth: the framebuffer would have 3 attachments, mismatching the pass.
+            commandList.SetRenderTargets(depth, backBuffer, extraTarget);
+            commandList.SetPipelineState(pipelineState.CurrentState);
+            commandList.SetVertexBuffer(0, vertexBuffer, 0, declaration.VertexStride);
+            effect.Apply(game.GraphicsContext);
+
+            var exception = Assert.Throws<InvalidOperationException>(() => commandList.Draw(3));
+            Assert.Contains("render pass", exception.Message);
+
+            sampledTexture.Dispose();
+            extraTarget.Dispose();
+        });
+    }
+}

sources/engine/Stride.Graphics/Vulkan/CommandList.Vulkan.cs

@@ -1760,6 +1760,18 @@ private unsafe void EnsureRenderPass()
 
                 if (framebufferDirty)
                 {
+                    // A framebuffer/render-pass attachment mismatch is undefined behavior that loses the device on
+                    // strict drivers; fail loud in debug (only, to not break drivers that tolerate it) instead.
+                    if (GraphicsDevice.IsDebugMode)
+                    {
+                        var output = activePipeline.Description.Output;
+                        var expectedAttachmentCount = output.RenderTargetCount + (output.DepthStencilFormat != PixelFormat.None ? 1 : 0);
+                        if (framebufferAttachmentCount != expectedAttachmentCount)
+                            throw new InvalidOperationException(
+                                $"Bound render targets ({framebufferAttachmentCount}) do not match the active pipeline's render pass " +
+                                $"({expectedAttachmentCount} attachments). The render targets bound on the command list must match the pipeline's Output description.");
+                    }
+
                     // Create new frame buffer
                     fixed (VkImageView* attachmentsPointer = &framebufferAttachments[0])
                     {