Add directional shadow integration coverage

engine/include/XCEngine/RHI/D3D12/D3D12CommandList.h

@@ -145,10 +145,13 @@ private:
     ComPtr<ID3D12DescriptorHeap> m_rtvHeap;
     ComPtr<ID3D12DescriptorHeap> m_shaderVisibleCbvSrvUavHeap;
     ComPtr<ID3D12DescriptorHeap> m_shaderVisibleSamplerHeap;
+    std::vector<ComPtr<ID3D12DescriptorHeap>> m_retiredShaderVisibleHeaps;
     ID3D12Device* m_device = nullptr;
     CommandQueueType m_type;
     uint32_t m_shaderVisibleCbvSrvUavHeapCapacity = 0;
     uint32_t m_shaderVisibleSamplerHeapCapacity = 0;
+    uint32_t m_shaderVisibleCbvSrvUavCursor = 0;
+    uint32_t m_shaderVisibleSamplerCursor = 0;
 
     std::unordered_map<ID3D12Resource*, ResourceStates> m_resourceStateMap;
     std::vector<ID3D12Resource*> m_trackedResources;

engine/include/XCEngine/Rendering/CameraRenderer.h

@@ -16,6 +16,7 @@ namespace Rendering {
 
 class RenderSurface;
 class RenderPipelineAsset;
+struct RenderContext;
 
 class CameraRenderer {
 public:
@@ -43,7 +44,12 @@ public:
     bool Render(const CameraRenderRequest& request);
 
 private:
+    struct DirectionalShadowSurfaceResources;
+
     void ResetPipeline(std::unique_ptr<RenderPipeline> pipeline);
+    DirectionalShadowSurfaceResources* AcquireDirectionalShadowSurface(
+        const RenderContext& context,
+        const DirectionalShadowRenderPlan& plan);
 
     RenderSceneExtractor m_sceneExtractor;
     std::shared_ptr<const RenderPipelineAsset> m_pipelineAsset;
@@ -51,6 +57,7 @@ private:
     std::unique_ptr<ObjectIdPass> m_objectIdPass;
     std::unique_ptr<RenderPass> m_depthOnlyPass;
     std::unique_ptr<RenderPass> m_shadowCasterPass;
+    std::unique_ptr<DirectionalShadowSurfaceResources> m_directionalShadowSurface;
 };
 
 } // namespace Rendering

engine/src/RHI/D3D12/D3D12CommandList.cpp

@@ -125,8 +125,11 @@ void D3D12CommandList::Shutdown() {
     m_rtvHeap.Reset();
     m_shaderVisibleCbvSrvUavHeap.Reset();
     m_shaderVisibleSamplerHeap.Reset();
+    m_retiredShaderVisibleHeaps.clear();
     m_shaderVisibleCbvSrvUavHeapCapacity = 0;
     m_shaderVisibleSamplerHeapCapacity = 0;
+    m_shaderVisibleCbvSrvUavCursor = 0;
+    m_shaderVisibleSamplerCursor = 0;
     m_resourceStateMap.clear();
     m_trackedResources.clear();
     m_currentShader = nullptr;
@@ -142,6 +145,9 @@ void D3D12CommandList::Reset() {
     m_currentRootSignature = nullptr;
     m_currentPipelineLayout = nullptr;
     m_currentDescriptorHeap = nullptr;
+    m_retiredShaderVisibleHeaps.clear();
+    m_shaderVisibleCbvSrvUavCursor = 0;
+    m_shaderVisibleSamplerCursor = 0;
     m_resourceStateMap.clear();
     m_trackedResources.clear();
     m_boundRenderTargets.clear();
@@ -250,17 +256,22 @@ void D3D12CommandList::SetGraphicsDescriptorSets(
     auto ensureShaderVisibleHeap =
         [this](D3D12_DESCRIPTOR_HEAP_TYPE heapType,
                uint32_t requiredDescriptors,
+               uint32_t currentCursor,
                ComPtr<ID3D12DescriptorHeap>& heap,
                uint32_t& capacity) -> bool {
             if (requiredDescriptors == 0) {
                 return true;
             }
 
-            if (heap != nullptr && capacity >= requiredDescriptors) {
+            const uint32_t requiredCapacity = currentCursor + requiredDescriptors;
+            if (heap != nullptr && capacity >= requiredCapacity) {
                 return true;
             }
 
-            const uint32_t newCapacity = std::max<uint32_t>(requiredDescriptors, capacity > 0 ? capacity * 2u : 32u);
+            const uint32_t baselineCapacity =
+                heapType == D3D12_DESCRIPTOR_HEAP_TYPE_SAMPLER ? 256u : 4096u;
+            const uint32_t grownCapacity = capacity > 0 ? capacity * 2u : baselineCapacity;
+            const uint32_t newCapacity = std::max<uint32_t>(requiredCapacity, std::max<uint32_t>(grownCapacity, baselineCapacity));
             D3D12_DESCRIPTOR_HEAP_DESC heapDesc = {};
             heapDesc.Type = heapType;
             heapDesc.NumDescriptors = newCapacity;
@@ -272,6 +283,9 @@ void D3D12CommandList::SetGraphicsDescriptorSets(
                 return false;
             }
 
+            if (heap != nullptr) {
+                m_retiredShaderVisibleHeaps.push_back(heap);
+            }
             heap = newHeap;
             capacity = newCapacity;
             return true;
@@ -280,11 +294,13 @@ void D3D12CommandList::SetGraphicsDescriptorSets(
     if (!ensureShaderVisibleHeap(
             D3D12_DESCRIPTOR_HEAP_TYPE_CBV_SRV_UAV,
             requiredCbvSrvUavDescriptors,
+            m_shaderVisibleCbvSrvUavCursor,
             m_shaderVisibleCbvSrvUavHeap,
             m_shaderVisibleCbvSrvUavHeapCapacity) ||
         !ensureShaderVisibleHeap(
             D3D12_DESCRIPTOR_HEAP_TYPE_SAMPLER,
             requiredSamplerDescriptors,
+            m_shaderVisibleSamplerCursor,
             m_shaderVisibleSamplerHeap,
             m_shaderVisibleSamplerHeapCapacity)) {
         return;
@@ -302,8 +318,8 @@ void D3D12CommandList::SetGraphicsDescriptorSets(
         SetDescriptorHeaps(static_cast<uint32_t>(descriptorHeaps.size()), descriptorHeaps.data());
     }
 
-    uint32_t nextCbvSrvUavDescriptor = 0;
+    uint32_t nextCbvSrvUavDescriptor = m_shaderVisibleCbvSrvUavCursor;
-    uint32_t nextSamplerDescriptor = 0;
+    uint32_t nextSamplerDescriptor = m_shaderVisibleSamplerCursor;
 
     for (uint32_t i = 0; i < count; ++i) {
         if (descriptorSets[i] == nullptr) {
@@ -434,6 +450,9 @@ void D3D12CommandList::SetGraphicsDescriptorSets(
             }
         }
     }
+
+    m_shaderVisibleCbvSrvUavCursor = nextCbvSrvUavDescriptor;
+    m_shaderVisibleSamplerCursor = nextSamplerDescriptor;
 }
 
 void D3D12CommandList::SetComputeDescriptorSets(
@@ -470,17 +489,22 @@ void D3D12CommandList::SetComputeDescriptorSets(
     auto ensureShaderVisibleHeap =
         [this](D3D12_DESCRIPTOR_HEAP_TYPE heapType,
                uint32_t requiredDescriptors,
+               uint32_t currentCursor,
                ComPtr<ID3D12DescriptorHeap>& heap,
                uint32_t& capacity) -> bool {
             if (requiredDescriptors == 0) {
                 return true;
             }
 
-            if (heap != nullptr && capacity >= requiredDescriptors) {
+            const uint32_t requiredCapacity = currentCursor + requiredDescriptors;
+            if (heap != nullptr && capacity >= requiredCapacity) {
                 return true;
             }
 
-            const uint32_t newCapacity = std::max<uint32_t>(requiredDescriptors, capacity > 0 ? capacity * 2u : 32u);
+            const uint32_t baselineCapacity =
+                heapType == D3D12_DESCRIPTOR_HEAP_TYPE_SAMPLER ? 256u : 4096u;
+            const uint32_t grownCapacity = capacity > 0 ? capacity * 2u : baselineCapacity;
+            const uint32_t newCapacity = std::max<uint32_t>(requiredCapacity, std::max<uint32_t>(grownCapacity, baselineCapacity));
             D3D12_DESCRIPTOR_HEAP_DESC heapDesc = {};
             heapDesc.Type = heapType;
             heapDesc.NumDescriptors = newCapacity;
@@ -492,6 +516,9 @@ void D3D12CommandList::SetComputeDescriptorSets(
                 return false;
             }
 
+            if (heap != nullptr) {
+                m_retiredShaderVisibleHeaps.push_back(heap);
+            }
             heap = newHeap;
             capacity = newCapacity;
             return true;
@@ -500,11 +527,13 @@ void D3D12CommandList::SetComputeDescriptorSets(
     if (!ensureShaderVisibleHeap(
             D3D12_DESCRIPTOR_HEAP_TYPE_CBV_SRV_UAV,
             requiredCbvSrvUavDescriptors,
+            m_shaderVisibleCbvSrvUavCursor,
             m_shaderVisibleCbvSrvUavHeap,
             m_shaderVisibleCbvSrvUavHeapCapacity) ||
         !ensureShaderVisibleHeap(
             D3D12_DESCRIPTOR_HEAP_TYPE_SAMPLER,
             requiredSamplerDescriptors,
+            m_shaderVisibleSamplerCursor,
             m_shaderVisibleSamplerHeap,
             m_shaderVisibleSamplerHeapCapacity)) {
         return;
@@ -522,8 +551,8 @@ void D3D12CommandList::SetComputeDescriptorSets(
         SetDescriptorHeaps(static_cast<uint32_t>(descriptorHeaps.size()), descriptorHeaps.data());
     }
 
-    uint32_t nextCbvSrvUavDescriptor = 0;
+    uint32_t nextCbvSrvUavDescriptor = m_shaderVisibleCbvSrvUavCursor;
-    uint32_t nextSamplerDescriptor = 0;
+    uint32_t nextSamplerDescriptor = m_shaderVisibleSamplerCursor;
 
     for (uint32_t i = 0; i < count; ++i) {
         if (descriptorSets[i] == nullptr) {
@@ -654,6 +683,9 @@ void D3D12CommandList::SetComputeDescriptorSets(
             }
         }
     }
+
+    m_shaderVisibleCbvSrvUavCursor = nextCbvSrvUavDescriptor;
+    m_shaderVisibleSamplerCursor = nextSamplerDescriptor;
 }
 
 void D3D12CommandList::TransitionBarrierInternal(ID3D12Resource* resource, ResourceStates stateBefore, ResourceStates stateAfter, uint32_t subresource) {

engine/src/RHI/D3D12/D3D12Screenshot.cpp

@@ -7,10 +7,48 @@
 #include <d3d12.h>
 #include <dxgi.h>
 #include <stdio.h>
+#include <vector>
 
 namespace XCEngine {
 namespace RHI {
 
+namespace {
+
+void DumpD3D12InfoQueueMessages(ID3D12Device* device) {
+    if (device == nullptr) {
+        return;
+    }
+
+    ID3D12InfoQueue* infoQueue = nullptr;
+    if (FAILED(device->QueryInterface(IID_PPV_ARGS(&infoQueue))) || infoQueue == nullptr) {
+        return;
+    }
+
+    const UINT64 messageCount = infoQueue->GetNumStoredMessagesAllowedByRetrievalFilter();
+    const UINT64 startIndex = messageCount > 12 ? messageCount - 12 : 0;
+    for (UINT64 messageIndex = startIndex; messageIndex < messageCount; ++messageIndex) {
+        SIZE_T messageLength = 0;
+        if (FAILED(infoQueue->GetMessage(messageIndex, nullptr, &messageLength)) || messageLength == 0) {
+            continue;
+        }
+
+        std::vector<uint8_t> messageStorage(messageLength);
+        auto* message = reinterpret_cast<D3D12_MESSAGE*>(messageStorage.data());
+        if (FAILED(infoQueue->GetMessage(messageIndex, message, &messageLength)) ||
+            message->pDescription == nullptr) {
+            continue;
+        }
+
+        XCEngine::Debug::Logger::Get().Error(
+            XCEngine::Debug::LogCategory::Rendering,
+            message->pDescription);
+    }
+
+    infoQueue->Release();
+}
+
+} // namespace
+
 bool D3D12Screenshot::Capture(ID3D12Device* device, 
                              ID3D12CommandQueue* commandQueue,
                              ID3D12Resource* renderTarget,
@@ -156,7 +194,21 @@ bool D3D12Screenshot::CopyToReadbackAndSave(ID3D12Device* device,
     ID3D12Fence* fence = nullptr;
     hr = device->CreateFence(0, D3D12_FENCE_FLAG_NONE, IID_PPV_ARGS(&fence));
     if (FAILED(hr)) {
-        XCEngine::Debug::Logger::Get().Error(XCEngine::Debug::LogCategory::Rendering, "Screenshot: CreateFence failed");
+        char message[256];
+        sprintf_s(message, sizeof(message), "Screenshot: CreateFence failed hr=0x%08X", static_cast<unsigned int>(hr));
+        XCEngine::Debug::Logger::Get().Error(XCEngine::Debug::LogCategory::Rendering, message);
+        DumpD3D12InfoQueueMessages(device);
+        if (hr == DXGI_ERROR_DEVICE_REMOVED ||
+            hr == DXGI_ERROR_DEVICE_HUNG ||
+            hr == DXGI_ERROR_DEVICE_RESET) {
+            const HRESULT removedReason = device->GetDeviceRemovedReason();
+            sprintf_s(
+                message,
+                sizeof(message),
+                "Screenshot: Device removed reason after CreateFence failure: 0x%08X",
+                static_cast<unsigned int>(removedReason));
+            XCEngine::Debug::Logger::Get().Error(XCEngine::Debug::LogCategory::Rendering, message);
+        }
         cmdList->Release();
         cmdAlloc->Release();
         readbackBuffer->Release();

engine/src/Rendering/CameraRenderer.cpp

@@ -14,22 +14,32 @@
 namespace XCEngine {
 namespace Rendering {
 
-namespace {
+struct CameraRenderer::DirectionalShadowSurfaceResources {
-
+    RHI::RHIDevice* device = nullptr;
-struct OwnedShadowSurfaceResources {
+    uint32_t width = 0;
+    uint32_t height = 0;
     RHI::RHITexture* depthTexture = nullptr;
     RHI::RHIResourceView* depthView = nullptr;
     RHI::RHIResourceView* shaderView = nullptr;
     RenderSurface surface = {};
 
-    OwnedShadowSurfaceResources() = default;
+    DirectionalShadowSurfaceResources() = default;
-    OwnedShadowSurfaceResources(const OwnedShadowSurfaceResources&) = delete;
+    DirectionalShadowSurfaceResources(const DirectionalShadowSurfaceResources&) = delete;
-    OwnedShadowSurfaceResources& operator=(const OwnedShadowSurfaceResources&) = delete;
+    DirectionalShadowSurfaceResources& operator=(const DirectionalShadowSurfaceResources&) = delete;
 
-    ~OwnedShadowSurfaceResources() {
+    ~DirectionalShadowSurfaceResources() {
         Reset();
     }
 
+    bool Matches(const RenderContext& context, const DirectionalShadowRenderPlan& plan) const {
+        return device == context.device &&
+               width == plan.mapWidth &&
+               height == plan.mapHeight &&
+               depthTexture != nullptr &&
+               depthView != nullptr &&
+               shaderView != nullptr;
+    }
+
     void Reset() {
         if (shaderView != nullptr) {
             shaderView->Shutdown();
@@ -49,10 +59,15 @@ struct OwnedShadowSurfaceResources {
             depthTexture = nullptr;
         }
 
+        device = nullptr;
+        width = 0;
+        height = 0;
         surface = RenderSurface();
     }
 };
 
+namespace {
+
 bool InitializePassSequence(
     RenderPassSequence* sequence,
     const RenderContext& context,
@@ -150,67 +165,6 @@ bool ExecuteScenePassRequest(
     return pass->Execute(passContext);
 }
 
-bool CreateDirectionalShadowSurface(
-    const RenderContext& context,
-    const DirectionalShadowRenderPlan& plan,
-    OwnedShadowSurfaceResources& outResources) {
-    if (!context.IsValid() || !plan.IsValid()) {
-        return false;
-    }
-
-    RHI::TextureDesc depthDesc = {};
-    depthDesc.width = plan.mapWidth;
-    depthDesc.height = plan.mapHeight;
-    depthDesc.depth = 1;
-    depthDesc.mipLevels = 1;
-    depthDesc.arraySize = 1;
-    depthDesc.format = static_cast<uint32_t>(RHI::Format::D24_UNorm_S8_UInt);
-    depthDesc.textureType = static_cast<uint32_t>(RHI::TextureType::Texture2D);
-    depthDesc.sampleCount = 1;
-    depthDesc.sampleQuality = 0;
-    depthDesc.flags = 0;
-
-    RHI::RHITexture* depthTexture = context.device->CreateTexture(depthDesc);
-    if (depthTexture == nullptr) {
-        return false;
-    }
-
-    RHI::ResourceViewDesc depthViewDesc = {};
-    depthViewDesc.format = static_cast<uint32_t>(RHI::Format::D24_UNorm_S8_UInt);
-    depthViewDesc.dimension = RHI::ResourceViewDimension::Texture2D;
-    depthViewDesc.mipLevel = 0;
-
-    RHI::RHIResourceView* depthView =
-        context.device->CreateDepthStencilView(depthTexture, depthViewDesc);
-    if (depthView == nullptr) {
-        depthTexture->Shutdown();
-        delete depthTexture;
-        return false;
-    }
-
-    RHI::ResourceViewDesc shaderViewDesc = {};
-    shaderViewDesc.format = depthDesc.format;
-    shaderViewDesc.dimension = RHI::ResourceViewDimension::Texture2D;
-    shaderViewDesc.mipLevel = 0;
-    RHI::RHIResourceView* shaderView =
-        context.device->CreateShaderResourceView(depthTexture, shaderViewDesc);
-    if (shaderView == nullptr) {
-        depthView->Shutdown();
-        delete depthView;
-        depthTexture->Shutdown();
-        delete depthTexture;
-        return false;
-    }
-
-    outResources.Reset();
-    outResources.depthTexture = depthTexture;
-    outResources.depthView = depthView;
-    outResources.shaderView = shaderView;
-    outResources.surface = RenderSurface(plan.mapWidth, plan.mapHeight);
-    outResources.surface.SetDepthAttachment(depthView);
-    return true;
-}
-
 RenderDirectionalShadowData BuildDirectionalShadowData(
     const DirectionalShadowRenderPlan& plan,
     RHI::RHIResourceView* shadowMapView) {
@@ -343,6 +297,75 @@ void CameraRenderer::ResetPipeline(std::unique_ptr<RenderPipeline> pipeline) {
     }
 }
 
+CameraRenderer::DirectionalShadowSurfaceResources* CameraRenderer::AcquireDirectionalShadowSurface(
+    const RenderContext& context,
+    const DirectionalShadowRenderPlan& plan) {
+    if (!context.IsValid() || !plan.IsValid()) {
+        return nullptr;
+    }
+
+    if (m_directionalShadowSurface == nullptr) {
+        m_directionalShadowSurface = std::make_unique<DirectionalShadowSurfaceResources>();
+    }
+
+    if (!m_directionalShadowSurface->Matches(context, plan)) {
+        RHI::TextureDesc depthDesc = {};
+        depthDesc.width = plan.mapWidth;
+        depthDesc.height = plan.mapHeight;
+        depthDesc.depth = 1;
+        depthDesc.mipLevels = 1;
+        depthDesc.arraySize = 1;
+        depthDesc.format = static_cast<uint32_t>(RHI::Format::D24_UNorm_S8_UInt);
+        depthDesc.textureType = static_cast<uint32_t>(RHI::TextureType::Texture2D);
+        depthDesc.sampleCount = 1;
+        depthDesc.sampleQuality = 0;
+        depthDesc.flags = 0;
+
+        RHI::RHITexture* depthTexture = context.device->CreateTexture(depthDesc);
+        if (depthTexture == nullptr) {
+            return nullptr;
+        }
+
+        RHI::ResourceViewDesc depthViewDesc = {};
+        depthViewDesc.format = static_cast<uint32_t>(RHI::Format::D24_UNorm_S8_UInt);
+        depthViewDesc.dimension = RHI::ResourceViewDimension::Texture2D;
+        depthViewDesc.mipLevel = 0;
+        RHI::RHIResourceView* depthView =
+            context.device->CreateDepthStencilView(depthTexture, depthViewDesc);
+        if (depthView == nullptr) {
+            depthTexture->Shutdown();
+            delete depthTexture;
+            return nullptr;
+        }
+
+        RHI::ResourceViewDesc shaderViewDesc = {};
+        shaderViewDesc.format = depthDesc.format;
+        shaderViewDesc.dimension = RHI::ResourceViewDimension::Texture2D;
+        shaderViewDesc.mipLevel = 0;
+        RHI::RHIResourceView* shaderView =
+            context.device->CreateShaderResourceView(depthTexture, shaderViewDesc);
+        if (shaderView == nullptr) {
+            depthView->Shutdown();
+            delete depthView;
+            depthTexture->Shutdown();
+            delete depthTexture;
+            return nullptr;
+        }
+
+        m_directionalShadowSurface->Reset();
+        m_directionalShadowSurface->device = context.device;
+        m_directionalShadowSurface->width = plan.mapWidth;
+        m_directionalShadowSurface->height = plan.mapHeight;
+        m_directionalShadowSurface->depthTexture = depthTexture;
+        m_directionalShadowSurface->depthView = depthView;
+        m_directionalShadowSurface->shaderView = shaderView;
+        m_directionalShadowSurface->surface = RenderSurface(plan.mapWidth, plan.mapHeight);
+        m_directionalShadowSurface->surface.SetDepthAttachment(depthView);
+    }
+
+    return m_directionalShadowSurface.get();
+}
+
 bool CameraRenderer::Render(
     const CameraRenderRequest& request) {
     if (!request.IsValid() || m_pipeline == nullptr) {
@@ -363,20 +386,20 @@ bool CameraRenderer::Render(
     }
 
     ShadowCasterRenderRequest resolvedShadowCaster = request.shadowCaster;
-    OwnedShadowSurfaceResources ownedShadowSurface;
+    DirectionalShadowSurfaceResources* directionalShadowSurface = nullptr;
     if (resolvedShadowCaster.IsRequested()) {
         if (!resolvedShadowCaster.IsValid()) {
             return false;
         }
     } else if (request.directionalShadow.IsValid()) {
-        if (!CreateDirectionalShadowSurface(
+        directionalShadowSurface = AcquireDirectionalShadowSurface(
             request.context,
-                request.directionalShadow,
+            request.directionalShadow);
-                ownedShadowSurface)) {
+        if (directionalShadowSurface == nullptr) {
             return false;
         }
 
-        resolvedShadowCaster.surface = ownedShadowSurface.surface;
+        resolvedShadowCaster.surface = directionalShadowSurface->surface;
         if (!resolvedShadowCaster.hasCameraDataOverride) {
             resolvedShadowCaster.hasCameraDataOverride = true;
             resolvedShadowCaster.cameraDataOverride = request.directionalShadow.cameraData;
@@ -393,7 +416,8 @@ bool CameraRenderer::Render(
     }
 
     if (request.directionalShadow.IsValid()) {
-        RHI::RHIResourceView* shadowMapView = ownedShadowSurface.shaderView;
+        RHI::RHIResourceView* shadowMapView =
+            directionalShadowSurface != nullptr ? directionalShadowSurface->shaderView : nullptr;
         sceneData.lighting.mainDirectionalShadow =
             BuildDirectionalShadowData(request.directionalShadow, shadowMapView);
     }

engine/src/Rendering/Passes/BuiltinDepthStylePassBase.cpp

@@ -101,10 +101,12 @@ RHI::GraphicsPipelineDesc CreatePipelineDesc(
             shader.FindVariant(passName, Resources::ShaderType::Vertex, backend)) {
         ::XCEngine::Rendering::Detail::ApplyShaderStageVariant(*vertexVariant, pipelineDesc.vertexShader);
     }
+    if (pipelineDesc.renderTargetCount > 0) {
         if (const Resources::ShaderStageVariant* fragmentVariant =
                 shader.FindVariant(passName, Resources::ShaderType::Fragment, backend)) {
             ::XCEngine::Rendering::Detail::ApplyShaderStageVariant(*fragmentVariant, pipelineDesc.fragmentShader);
         }
+    }
 
     return pipelineDesc;
 }

tests/RHI/integration/fixtures/RHIIntegrationFixture.cpp

@@ -3,6 +3,7 @@
 #include <iostream>
 #include <windows.h>
 #include <filesystem>
+#include <cstring>
 
 #include "XCEngine/RHI/D3D12/D3D12Device.h"
 #include "XCEngine/RHI/D3D12/D3D12SwapChain.h"
@@ -46,6 +47,19 @@ std::filesystem::path ResolveRuntimePath(const char* path) {
     return GetExecutableDirectory() / resolved;
 }
 
+bool IsTruthyEnvVarEnabled(const char* name) {
+    const char* value = std::getenv(name);
+    if (value == nullptr || value[0] == '\0') {
+        return false;
+    }
+
+    return std::strcmp(value, "0") != 0 &&
+           std::strcmp(value, "false") != 0 &&
+           std::strcmp(value, "FALSE") != 0 &&
+           std::strcmp(value, "off") != 0 &&
+           std::strcmp(value, "OFF") != 0;
+}
+
 } // namespace
 
 void Log(const char* format, ...) {
@@ -89,8 +103,13 @@ void RHIIntegrationFixture::SetUp() {
     bool initResult = false;
     if (GetParam() == RHIType::D3D12 || GetParam() == RHIType::Vulkan) {
         RHIDeviceDesc desc = {};
-        desc.enableDebugLayer = false;
+        const bool enableD3D12DebugLayer =
-        desc.enableGPUValidation = false;
+            GetParam() == RHIType::D3D12 &&
+            IsTruthyEnvVarEnabled("XCENGINE_RHI_ENABLE_DEBUG_LAYER");
+        desc.enableDebugLayer = enableD3D12DebugLayer;
+        desc.enableGPUValidation =
+            enableD3D12DebugLayer &&
+            IsTruthyEnvVarEnabled("XCENGINE_RHI_ENABLE_GPU_VALIDATION");
         initResult = mDevice->Initialize(desc);
     } else if (GetParam() == RHIType::OpenGL) {
         auto* oglDevice = static_cast<OpenGLDevice*>(mDevice);

tests/Rendering/CMakeLists.txt

@@ -15,6 +15,7 @@ add_custom_target(rendering_integration_tests
         rendering_integration_textured_quad_scene
         rendering_integration_unlit_scene
         rendering_integration_object_id_scene
+        rendering_integration_directional_shadow_scene
         rendering_integration_backpack_scene
         rendering_integration_backpack_lit_scene
         rendering_integration_camera_stack_scene

tests/Rendering/integration/CMakeLists.txt

@@ -5,6 +5,7 @@ project(XCEngine_RenderingIntegrationTests)
 add_subdirectory(textured_quad_scene)
 add_subdirectory(unlit_scene)
 add_subdirectory(object_id_scene)
+add_subdirectory(directional_shadow_scene)
 add_subdirectory(backpack_scene)
 add_subdirectory(backpack_lit_scene)
 add_subdirectory(camera_stack_scene)

tests/Rendering/integration/directional_shadow_scene/CMakeLists.txt

@@ -0,0 +1,63 @@
+cmake_minimum_required(VERSION 3.15)
+
+set(CMAKE_RUNTIME_OUTPUT_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR})
+
+project(rendering_integration_directional_shadow_scene)
+
+set(ENGINE_ROOT_DIR ${CMAKE_SOURCE_DIR}/engine)
+set(PACKAGE_DIR ${CMAKE_SOURCE_DIR}/mvs/OpenGL/package)
+
+get_filename_component(PROJECT_ROOT_DIR ${CMAKE_CURRENT_SOURCE_DIR}/../../../.. ABSOLUTE)
+
+find_package(Vulkan QUIET)
+
+add_executable(rendering_integration_directional_shadow_scene
+    main.cpp
+    ${CMAKE_SOURCE_DIR}/tests/RHI/integration/fixtures/RHIIntegrationFixture.cpp
+    ${PACKAGE_DIR}/src/glad.c
+)
+
+target_include_directories(rendering_integration_directional_shadow_scene PRIVATE
+    ${CMAKE_CURRENT_SOURCE_DIR}
+    ${CMAKE_SOURCE_DIR}/tests/RHI/integration/fixtures
+    ${ENGINE_ROOT_DIR}/include
+    ${PACKAGE_DIR}/include
+    ${PROJECT_ROOT_DIR}/engine/src
+)
+
+target_link_libraries(rendering_integration_directional_shadow_scene PRIVATE
+    d3d12
+    dxgi
+    d3dcompiler
+    winmm
+    opengl32
+    XCEngine
+    GTest::gtest
+)
+
+if(TARGET Vulkan::Vulkan)
+    target_link_libraries(rendering_integration_directional_shadow_scene PRIVATE Vulkan::Vulkan)
+    target_compile_definitions(rendering_integration_directional_shadow_scene PRIVATE XCENGINE_SUPPORT_VULKAN)
+endif()
+
+target_compile_definitions(rendering_integration_directional_shadow_scene PRIVATE
+    UNICODE
+    _UNICODE
+    XCENGINE_SUPPORT_OPENGL
+    XCENGINE_SUPPORT_D3D12
+)
+
+add_custom_command(TARGET rendering_integration_directional_shadow_scene POST_BUILD
+    COMMAND ${CMAKE_COMMAND} -E copy_if_different
+        ${CMAKE_SOURCE_DIR}/tests/RHI/integration/compare_ppm.py
+        $<TARGET_FILE_DIR:rendering_integration_directional_shadow_scene>/
+    COMMAND ${CMAKE_COMMAND} -E copy_if_different
+        ${CMAKE_CURRENT_SOURCE_DIR}/GT.ppm
+        $<TARGET_FILE_DIR:rendering_integration_directional_shadow_scene>/GT.ppm
+    COMMAND ${CMAKE_COMMAND} -E copy_if_different
+        ${ENGINE_ROOT_DIR}/third_party/renderdoc/renderdoc.dll
+        $<TARGET_FILE_DIR:rendering_integration_directional_shadow_scene>/
+)
+
+include(GoogleTest)
+gtest_discover_tests(rendering_integration_directional_shadow_scene)

tests/Rendering/integration/directional_shadow_scene/main.cpp

@@ -0,0 +1,481 @@
+#define NOMINMAX
+#include <windows.h>
+
+#include <gtest/gtest.h>
+
+#include "../RenderingIntegrationMain.h"
+
+#include <XCEngine/Components/CameraComponent.h>
+#include <XCEngine/Components/GameObject.h>
+#include <XCEngine/Components/LightComponent.h>
+#include <XCEngine/Components/MeshFilterComponent.h>
+#include <XCEngine/Components/MeshRendererComponent.h>
+#include <XCEngine/Core/Asset/IResource.h>
+#include <XCEngine/Core/Math/Color.h>
+#include <XCEngine/Core/Math/Quaternion.h>
+#include <XCEngine/Core/Math/Vector2.h>
+#include <XCEngine/Core/Math/Vector3.h>
+#include <XCEngine/Debug/ConsoleLogSink.h>
+#include <XCEngine/Debug/Logger.h>
+#include <XCEngine/Rendering/RenderContext.h>
+#include <XCEngine/Rendering/RenderSurface.h>
+#include <XCEngine/Rendering/SceneRenderer.h>
+#include <XCEngine/Resources/BuiltinResources.h>
+#include <XCEngine/Resources/Material/Material.h>
+#include <XCEngine/Resources/Mesh/Mesh.h>
+#include <XCEngine/Resources/Shader/Shader.h>
+#include <XCEngine/RHI/RHITexture.h>
+#include <XCEngine/Scene/Scene.h>
+
+#include "../../../RHI/integration/fixtures/RHIIntegrationFixture.h"
+
+#include <memory>
+#include <vector>
+
+using namespace XCEngine::Components;
+using namespace XCEngine::Debug;
+using namespace XCEngine::Math;
+using namespace XCEngine::Rendering;
+using namespace XCEngine::Resources;
+using namespace XCEngine::RHI;
+using namespace XCEngine::RHI::Integration;
+
+namespace {
+
+constexpr const char* kD3D12Screenshot = "directional_shadow_scene_d3d12.ppm";
+constexpr const char* kOpenGLScreenshot = "directional_shadow_scene_opengl.ppm";
+constexpr const char* kVulkanScreenshot = "directional_shadow_scene_vulkan.ppm";
+constexpr uint32_t kFrameWidth = 1280;
+constexpr uint32_t kFrameHeight = 720;
+
+void AppendQuadFace(
+    std::vector<StaticMeshVertex>& vertices,
+    std::vector<uint32_t>& indices,
+    const Vector3& v0,
+    const Vector3& v1,
+    const Vector3& v2,
+    const Vector3& v3,
+    const Vector3& normal) {
+    const uint32_t baseIndex = static_cast<uint32_t>(vertices.size());
+
+    StaticMeshVertex vertex = {};
+    vertex.normal = normal;
+
+    vertex.position = v0;
+    vertex.uv0 = Vector2(0.0f, 1.0f);
+    vertices.push_back(vertex);
+
+    vertex.position = v1;
+    vertex.uv0 = Vector2(1.0f, 1.0f);
+    vertices.push_back(vertex);
+
+    vertex.position = v2;
+    vertex.uv0 = Vector2(0.0f, 0.0f);
+    vertices.push_back(vertex);
+
+    vertex.position = v3;
+    vertex.uv0 = Vector2(1.0f, 0.0f);
+    vertices.push_back(vertex);
+
+    indices.push_back(baseIndex + 0);
+    indices.push_back(baseIndex + 2);
+    indices.push_back(baseIndex + 1);
+    indices.push_back(baseIndex + 1);
+    indices.push_back(baseIndex + 2);
+    indices.push_back(baseIndex + 3);
+}
+
+Mesh* CreateGroundMesh() {
+    auto* mesh = new Mesh();
+    IResource::ConstructParams params = {};
+    params.name = "DirectionalShadowGroundMesh";
+    params.path = "Tests/Rendering/DirectionalShadowGround.mesh";
+    params.guid = ResourceGUID::Generate(params.path);
+    mesh->Initialize(params);
+
+    StaticMeshVertex vertices[4] = {};
+    vertices[0].position = Vector3(-4.5f, 0.0f, 1.5f);
+    vertices[0].normal = Vector3::Up();
+    vertices[0].uv0 = Vector2(0.0f, 1.0f);
+    vertices[1].position = Vector3(-4.5f, 0.0f, 9.5f);
+    vertices[1].normal = Vector3::Up();
+    vertices[1].uv0 = Vector2(0.0f, 0.0f);
+    vertices[2].position = Vector3(4.5f, 0.0f, 1.5f);
+    vertices[2].normal = Vector3::Up();
+    vertices[2].uv0 = Vector2(1.0f, 1.0f);
+    vertices[3].position = Vector3(4.5f, 0.0f, 9.5f);
+    vertices[3].normal = Vector3::Up();
+    vertices[3].uv0 = Vector2(1.0f, 0.0f);
+
+    const uint32_t indices[6] = { 0, 1, 2, 2, 1, 3 };
+    mesh->SetVertexData(
+        vertices,
+        sizeof(vertices),
+        4,
+        sizeof(StaticMeshVertex),
+        VertexAttribute::Position | VertexAttribute::Normal | VertexAttribute::UV0);
+    mesh->SetIndexData(indices, sizeof(indices), 6, true);
+    const Bounds bounds(Vector3(0.0f, 0.0f, 5.5f), Vector3(9.0f, 0.1f, 8.0f));
+    mesh->SetBounds(bounds);
+
+    MeshSection section = {};
+    section.baseVertex = 0;
+    section.vertexCount = 4;
+    section.startIndex = 0;
+    section.indexCount = 6;
+    section.materialID = 0;
+    section.bounds = bounds;
+    mesh->AddSection(section);
+    return mesh;
+}
+
+Mesh* CreateCubeMesh() {
+    auto* mesh = new Mesh();
+    IResource::ConstructParams params = {};
+    params.name = "DirectionalShadowCubeMesh";
+    params.path = "Tests/Rendering/DirectionalShadowCube.mesh";
+    params.guid = ResourceGUID::Generate(params.path);
+    mesh->Initialize(params);
+
+    std::vector<StaticMeshVertex> vertices;
+    std::vector<uint32_t> indices;
+    vertices.reserve(24);
+    indices.reserve(36);
+
+    constexpr float half = 0.5f;
+    AppendQuadFace(
+        vertices, indices,
+        Vector3(-half, -half, half),
+        Vector3(half, -half, half),
+        Vector3(-half, half, half),
+        Vector3(half, half, half),
+        Vector3::Forward());
+    AppendQuadFace(
+        vertices, indices,
+        Vector3(half, -half, -half),
+        Vector3(-half, -half, -half),
+        Vector3(half, half, -half),
+        Vector3(-half, half, -half),
+        Vector3::Back());
+    AppendQuadFace(
+        vertices, indices,
+        Vector3(-half, -half, -half),
+        Vector3(-half, -half, half),
+        Vector3(-half, half, -half),
+        Vector3(-half, half, half),
+        Vector3::Left());
+    AppendQuadFace(
+        vertices, indices,
+        Vector3(half, -half, half),
+        Vector3(half, -half, -half),
+        Vector3(half, half, half),
+        Vector3(half, half, -half),
+        Vector3::Right());
+    AppendQuadFace(
+        vertices, indices,
+        Vector3(-half, half, half),
+        Vector3(half, half, half),
+        Vector3(-half, half, -half),
+        Vector3(half, half, -half),
+        Vector3::Up());
+    AppendQuadFace(
+        vertices, indices,
+        Vector3(-half, -half, -half),
+        Vector3(half, -half, -half),
+        Vector3(-half, -half, half),
+        Vector3(half, -half, half),
+        Vector3::Down());
+
+    mesh->SetVertexData(
+        vertices.data(),
+        vertices.size() * sizeof(StaticMeshVertex),
+        static_cast<uint32_t>(vertices.size()),
+        sizeof(StaticMeshVertex),
+        VertexAttribute::Position | VertexAttribute::Normal | VertexAttribute::UV0);
+    mesh->SetIndexData(
+        indices.data(),
+        indices.size() * sizeof(uint32_t),
+        static_cast<uint32_t>(indices.size()),
+        true);
+    const Bounds bounds(Vector3::Zero(), Vector3::One());
+    mesh->SetBounds(bounds);
+
+    MeshSection section = {};
+    section.baseVertex = 0;
+    section.vertexCount = static_cast<uint32_t>(vertices.size());
+    section.startIndex = 0;
+    section.indexCount = static_cast<uint32_t>(indices.size());
+    section.materialID = 0;
+    section.bounds = bounds;
+    mesh->AddSection(section);
+    return mesh;
+}
+
+Material* CreateForwardLitMaterial(
+    const char* name,
+    const char* path,
+    const Vector4& baseColor) {
+    auto* material = new Material();
+    IResource::ConstructParams params = {};
+    params.name = name;
+    params.path = path;
+    params.guid = ResourceGUID::Generate(params.path);
+    material->Initialize(params);
+    material->SetShader(ResourceManager::Get().Load<Shader>(GetBuiltinForwardLitShaderPath()));
+    material->SetShaderPass("ForwardLit");
+    material->SetFloat4("_BaseColor", baseColor);
+    return material;
+}
+
+const char* GetScreenshotFilename(RHIType backendType) {
+    switch (backendType) {
+        case RHIType::D3D12:
+            return kD3D12Screenshot;
+        case RHIType::Vulkan:
+            return kVulkanScreenshot;
+        case RHIType::OpenGL:
+        default:
+            return kOpenGLScreenshot;
+    }
+}
+
+int GetComparisonThreshold(RHIType backendType) {
+    return backendType == RHIType::D3D12 ? 10 : 10;
+}
+
+class DirectionalShadowSceneTest : public RHIIntegrationFixture {
+protected:
+    void SetUp() override;
+    void TearDown() override;
+    void RenderFrame() override;
+
+private:
+    void BuildScene();
+    RHIResourceView* GetCurrentBackBufferView();
+
+    std::unique_ptr<Scene> mScene;
+    std::unique_ptr<SceneRenderer> mSceneRenderer;
+    std::vector<RHIResourceView*> mBackBufferViews;
+    RHITexture* mDepthTexture = nullptr;
+    RHIResourceView* mDepthView = nullptr;
+    Mesh* mGroundMesh = nullptr;
+    Mesh* mCubeMesh = nullptr;
+    Material* mGroundMaterial = nullptr;
+    Material* mCasterMaterial = nullptr;
+};
+
+void DirectionalShadowSceneTest::SetUp() {
+    RHIIntegrationFixture::SetUp();
+
+    mSceneRenderer = std::make_unique<SceneRenderer>();
+    mScene = std::make_unique<Scene>("DirectionalShadowScene");
+
+    mGroundMesh = CreateGroundMesh();
+    ASSERT_NE(mGroundMesh, nullptr);
+
+    mCubeMesh = CreateCubeMesh();
+    ASSERT_NE(mCubeMesh, nullptr);
+
+    mGroundMaterial = CreateForwardLitMaterial(
+        "DirectionalShadowGround",
+        "Tests/Rendering/DirectionalShadowGround.material",
+        Vector4(0.82f, 0.83f, 0.86f, 1.0f));
+    mCasterMaterial = CreateForwardLitMaterial(
+        "DirectionalShadowCaster",
+        "Tests/Rendering/DirectionalShadowCaster.material",
+        Vector4(0.82f, 0.34f, 0.24f, 1.0f));
+
+    BuildScene();
+
+    TextureDesc depthDesc = {};
+    depthDesc.width = kFrameWidth;
+    depthDesc.height = kFrameHeight;
+    depthDesc.depth = 1;
+    depthDesc.mipLevels = 1;
+    depthDesc.arraySize = 1;
+    depthDesc.format = static_cast<uint32_t>(Format::D24_UNorm_S8_UInt);
+    depthDesc.textureType = static_cast<uint32_t>(XCEngine::RHI::TextureType::Texture2D);
+    depthDesc.sampleCount = 1;
+    depthDesc.sampleQuality = 0;
+    depthDesc.flags = 0;
+    mDepthTexture = GetDevice()->CreateTexture(depthDesc);
+    ASSERT_NE(mDepthTexture, nullptr);
+
+    ResourceViewDesc depthViewDesc = {};
+    depthViewDesc.format = static_cast<uint32_t>(Format::D24_UNorm_S8_UInt);
+    depthViewDesc.dimension = ResourceViewDimension::Texture2D;
+    depthViewDesc.mipLevel = 0;
+    mDepthView = GetDevice()->CreateDepthStencilView(mDepthTexture, depthViewDesc);
+    ASSERT_NE(mDepthView, nullptr);
+
+    mBackBufferViews.resize(2, nullptr);
+}
+
+void DirectionalShadowSceneTest::TearDown() {
+    mSceneRenderer.reset();
+
+    if (mDepthView != nullptr) {
+        mDepthView->Shutdown();
+        delete mDepthView;
+        mDepthView = nullptr;
+    }
+
+    if (mDepthTexture != nullptr) {
+        mDepthTexture->Shutdown();
+        delete mDepthTexture;
+        mDepthTexture = nullptr;
+    }
+
+    for (RHIResourceView*& backBufferView : mBackBufferViews) {
+        if (backBufferView != nullptr) {
+            backBufferView->Shutdown();
+            delete backBufferView;
+            backBufferView = nullptr;
+        }
+    }
+    mBackBufferViews.clear();
+
+    mScene.reset();
+
+    delete mGroundMaterial;
+    mGroundMaterial = nullptr;
+    delete mCasterMaterial;
+    mCasterMaterial = nullptr;
+    delete mGroundMesh;
+    mGroundMesh = nullptr;
+    delete mCubeMesh;
+    mCubeMesh = nullptr;
+
+    RHIIntegrationFixture::TearDown();
+}
+
+void DirectionalShadowSceneTest::BuildScene() {
+    ASSERT_NE(mScene, nullptr);
+    ASSERT_NE(mGroundMesh, nullptr);
+    ASSERT_NE(mCubeMesh, nullptr);
+    ASSERT_NE(mGroundMaterial, nullptr);
+    ASSERT_NE(mCasterMaterial, nullptr);
+
+    GameObject* cameraObject = mScene->CreateGameObject("MainCamera");
+    auto* camera = cameraObject->AddComponent<CameraComponent>();
+    camera->SetPrimary(true);
+    camera->SetFieldOfView(45.0f);
+    camera->SetNearClipPlane(0.1f);
+    camera->SetFarClipPlane(100.0f);
+    camera->SetClearColor(XCEngine::Math::Color(0.03f, 0.03f, 0.05f, 1.0f));
+    cameraObject->GetTransform()->SetLocalPosition(Vector3(0.0f, 2.2f, -1.8f));
+    cameraObject->GetTransform()->SetLocalRotation(
+        Quaternion::LookRotation(Vector3(0.0f, -0.22f, 1.0f).Normalized()));
+
+    GameObject* lightObject = mScene->CreateGameObject("MainDirectionalLight");
+    auto* light = lightObject->AddComponent<LightComponent>();
+    light->SetLightType(LightType::Directional);
+    light->SetColor(XCEngine::Math::Color(1.0f, 1.0f, 0.97f, 1.0f));
+    light->SetIntensity(1.8f);
+    light->SetCastsShadows(true);
+    lightObject->GetTransform()->SetLocalRotation(
+        Quaternion::LookRotation(Vector3(-0.32f, -0.78f, -0.54f).Normalized()));
+
+    GameObject* groundObject = mScene->CreateGameObject("Ground");
+    auto* groundMeshFilter = groundObject->AddComponent<MeshFilterComponent>();
+    auto* groundMeshRenderer = groundObject->AddComponent<MeshRendererComponent>();
+    groundMeshFilter->SetMesh(ResourceHandle<Mesh>(mGroundMesh));
+    groundMeshRenderer->SetMaterial(0, mGroundMaterial);
+    groundMeshRenderer->SetCastShadows(false);
+    groundMeshRenderer->SetReceiveShadows(true);
+
+    GameObject* casterObject = mScene->CreateGameObject("CasterCube");
+    casterObject->GetTransform()->SetLocalPosition(Vector3(0.0f, 0.8f, 4.5f));
+    casterObject->GetTransform()->SetLocalScale(Vector3(1.2f, 1.6f, 1.2f));
+    auto* casterMeshFilter = casterObject->AddComponent<MeshFilterComponent>();
+    auto* casterMeshRenderer = casterObject->AddComponent<MeshRendererComponent>();
+    casterMeshFilter->SetMesh(ResourceHandle<Mesh>(mCubeMesh));
+    casterMeshRenderer->SetMaterial(0, mCasterMaterial);
+    casterMeshRenderer->SetCastShadows(true);
+    casterMeshRenderer->SetReceiveShadows(true);
+}
+
+RHIResourceView* DirectionalShadowSceneTest::GetCurrentBackBufferView() {
+    const int backBufferIndex = GetCurrentBackBufferIndex();
+    if (backBufferIndex < 0) {
+        return nullptr;
+    }
+
+    if (static_cast<size_t>(backBufferIndex) >= mBackBufferViews.size()) {
+        mBackBufferViews.resize(static_cast<size_t>(backBufferIndex) + 1, nullptr);
+    }
+
+    if (mBackBufferViews[backBufferIndex] == nullptr) {
+        ResourceViewDesc viewDesc = {};
+        viewDesc.format = static_cast<uint32_t>(Format::R8G8B8A8_UNorm);
+        viewDesc.dimension = ResourceViewDimension::Texture2D;
+        viewDesc.mipLevel = 0;
+        mBackBufferViews[backBufferIndex] = GetDevice()->CreateRenderTargetView(GetCurrentBackBuffer(), viewDesc);
+    }
+
+    return mBackBufferViews[backBufferIndex];
+}
+
+void DirectionalShadowSceneTest::RenderFrame() {
+    ASSERT_NE(mScene, nullptr);
+    ASSERT_NE(mSceneRenderer, nullptr);
+
+    RHICommandList* commandList = GetCommandList();
+    ASSERT_NE(commandList, nullptr);
+
+    commandList->Reset();
+
+    RenderSurface surface(kFrameWidth, kFrameHeight);
+    surface.SetColorAttachment(GetCurrentBackBufferView());
+    surface.SetDepthAttachment(mDepthView);
+
+    RenderContext renderContext = {};
+    renderContext.device = GetDevice();
+    renderContext.commandList = commandList;
+    renderContext.commandQueue = GetCommandQueue();
+    renderContext.backendType = GetBackendType();
+
+    ASSERT_TRUE(mSceneRenderer->Render(*mScene, nullptr, renderContext, surface));
+
+    commandList->Close();
+    void* commandLists[] = { commandList };
+    GetCommandQueue()->ExecuteCommandLists(1, commandLists);
+}
+
+TEST_P(DirectionalShadowSceneTest, RenderDirectionalShadowScene) {
+    RHICommandQueue* commandQueue = GetCommandQueue();
+    RHISwapChain* swapChain = GetSwapChain();
+    const int targetFrameCount = 30;
+    const char* screenshotFilename = GetScreenshotFilename(GetBackendType());
+    const int comparisonThreshold = GetComparisonThreshold(GetBackendType());
+
+    for (int frameCount = 0; frameCount <= targetFrameCount; ++frameCount) {
+        if (frameCount > 0) {
+            commandQueue->WaitForPreviousFrame();
+        }
+
+        BeginRender();
+        RenderFrame();
+
+        if (frameCount >= targetFrameCount) {
+            commandQueue->WaitForIdle();
+            ASSERT_TRUE(TakeScreenshot(screenshotFilename));
+            ASSERT_TRUE(CompareWithGoldenTemplate(screenshotFilename, "GT.ppm", static_cast<float>(comparisonThreshold)));
+            break;
+        }
+
+        swapChain->Present(0, 0);
+    }
+}
+
+} // namespace
+
+INSTANTIATE_TEST_SUITE_P(D3D12, DirectionalShadowSceneTest, ::testing::Values(RHIType::D3D12));
+INSTANTIATE_TEST_SUITE_P(OpenGL, DirectionalShadowSceneTest, ::testing::Values(RHIType::OpenGL));
+#if defined(XCENGINE_SUPPORT_VULKAN)
+INSTANTIATE_TEST_SUITE_P(Vulkan, DirectionalShadowSceneTest, ::testing::Values(RHIType::Vulkan));
+#endif
+
+GTEST_API_ int main(int argc, char** argv) {
+    return RunRenderingIntegrationTestMain(argc, argv);
+}

tests/TEST_SPEC.md

@@ -1,6 +1,6 @@
 # XCEngine 测试规范
 
-最后更新：`2026-04-02`
+最后更新：`2026-04-04`
 
 ## 1. 目标
 
@@ -132,9 +132,26 @@ ctest --test-dir build -C Debug --output-on-failure
 
 补充说明：
 
-- `editor_tests` 当前覆盖 action routing、play session、viewport camera controller、picker、move/rotate/scale gizmo、overlay renderer、script component editor utils 等。
+- `editor_tests` 当前覆盖 action routing、application asset cache stub、editor console sink、script assembly builder、play session，以及一整套 viewport helper 链。
+- 当前 viewport 相关覆盖至少包括：
+  - `SceneViewportChrome`
+  - `SceneViewportInteractionFrame`
+  - `SceneViewportNavigation`
+  - `SceneViewportInteractionActions`
+  - `SceneViewportInteractionResolver`
+  - `SceneViewportTransformGizmoCoordinator`
+  - `SceneViewportOverlayFrameCache`
+  - `SceneViewportOverlayProviders`
+  - `SceneViewportOverlaySpriteResources`
+  - `SceneViewportShaderPaths`
+  - `ViewportHostRenderFlowUtils`
+  - `ViewportHostRenderTargets`
+  - `ViewportHostSurfaceUtils`
+  - `ViewportObjectIdPicker`
+- `test_scene_viewport_overlay_renderer.cpp` 这个测试文件名仍保留历史命名，但当前主要锚定的是 viewport math、HUD overlay 和 infinite-grid 参数 helper；它不意味着仓库里仍存在 `SceneViewportOverlayRenderer.*` 源文件。
+- `test_play_session_controller_scripting.cpp` 只会在启用 Mono 且 `xcengine_managed_assemblies` 可用时加入 `editor_tests`。
 - `scripting_tests` 在启用 Mono 时会补入 `test_mono_script_runtime.cpp`。
-- 如果存在 `xcengine_project_managed_assemblies` target，`scripting_tests` 还会补入项目脚本程序集相关测试。
+- 如果存在 `xcengine_test_project_managed_assemblies` target，`scripting_tests` 还会补入 `test_project_script_assembly.cpp`，并使用测试专用的项目脚本程序集输出目录，而不是直接复用 `project/Library/ScriptAssemblies/`。
 
 ### 4.4 Rendering
 
@@ -149,6 +166,9 @@ ctest --test-dir build -C Debug --output-on-failure
 当前 rendering integration targets：
 
 - `rendering_integration_textured_quad_scene`
+- `rendering_integration_unlit_scene`
+- `rendering_integration_object_id_scene`
+- `rendering_integration_directional_shadow_scene`
 - `rendering_integration_backpack_scene`
 - `rendering_integration_backpack_lit_scene`
 - `rendering_integration_camera_stack_scene`
@@ -298,7 +318,7 @@ build\tests\RHI\integration\backpack\Debug\rhi_integration_backpack.exe --gtest_
 - 改 `engine/RHI`：先跑 `rhi_abstraction_tests` 或 `rhi_backend_tests`
 - 改 `engine/Rendering`：先跑 `rendering_unit_tests` 和最相关的 `rendering_integration_*`
 - 改 `editor/Viewport`：先跑 `editor_tests`，必要时再跑 `rendering_phase_regression`
-- 改脚本运行时 / managed / 项目脚本程序集：先构建 `xcengine_project_managed_assemblies`，再跑 `scripting_tests`
+- 改脚本运行时 / managed / 项目脚本程序集：先跑 `scripting_tests`；如果还要验证 editor / runtime 实际使用的项目程序集目录，再补构建 `xcengine_project_managed_assemblies`
 - 改资源导入 / `.meta` / artifact：优先跑对应 `Resources/*` tests
 
 在这些最小验证通过后，再决定是否扩展到：