Add directional shadow integration coverage

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;
-        desc.enableGPUValidation = false;
+        const bool enableD3D12DebugLayer =
+            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
 
 在这些最小验证通过后，再决定是否扩展到：