Engine.cpp

Go to the documentation of this file.

#include "Engine/Ecs/FrameProcessing.h"
#include "Engine/Ecs/RegistryManager.h"
#include "Engine/Renderer/PipelineStages.h"
#include "Engine/Renderer/RenderingDataManager.h"
#include "glm/gtc/type_ptr.inl"
#include "Engine/World/SceneGraph.h"
 
#include <cstring>
#include <Engine/Core/Engine.h>
#include <GLFW/glfw3.h>
#include <iostream>
#include <stdexcept>
#include <string>
#include <vector>
#include <vulkan/vulkan_core.h>
 
#ifdef RENDERDOC_ENABLED
    #include "renderdoc_app.h"
#endif
 
#include <algorithm>
#include <thread>
 
#include <Engine/XR/XrErrorCodes.h>
#define XR_LOG_STRING
#include "Engine/Core/VulkanHelper.h"
#include "Engine/Ecs/EcsData.h"
#include "Engine/Entity/Scene.h"
#include "Engine/Files/Path.h"
#include "Engine/Renderer/RenderProcess.h"
#include "Engine/Texture/ExrLoader.h"
 
#include <Engine/Component/MeshComponent.h>
#include <Engine/Core/Exceptions.h>
#include <Engine/Core/Settings.h>
#include <Engine/Core/Ticker.h>
#include <Engine/Game/GameModule.h>
#include <Engine/Input/XrInputHandler.h>
#include <Engine/Logging/TracyMacros.hpp>
#include <Engine/Mesh/Mesh.h>
#include <Engine/Renderer/Headset.h>
#include <Engine/Renderer/Renderer.h>
#include <execution>
#include <filesystem>
#include <chrono>
#include <iomanip>
#include <sstream>
#include <plog/Appenders/ColorConsoleAppender.h>
#include <plog/Appenders/RollingFileAppender.h>
#include <plog/Formatters/TxtFormatter.h>
#include <plog/Init.h>
#include <plog/Log.h>
#include <plog/Severity.h>
#ifdef RENDERDOC_ENABLED
#include "Engine/Logging/RenderDoc.h"
#endif
 
namespace EngineCore {
    Engine::~Engine() {
    }
 
    void Engine::initRenderDoc() {
#ifdef RENDERDOC_ENABLED
        auto renderDoc = RenderDoc::get();
        if (renderDoc.init()) {
            renderDoc.printStatus();
            renderDoc.setCapturePath("./vr_captures/debug_frame_{0}.rdc");
            renderDoc.enableOverlay(true);
        }
#endif
    }
 
    void Engine::run(std::unique_ptr<GameModule> module) {
        this->module = std::move(module);
 
        // Create named thread pool for XR frame operations (visible in Tracy as "XR Frame 1")
        xrFrameThreadPool_ = std::make_unique<NamedThreadPool>(1, "XR Frame");
 
        // init glfw
        initWindow();
        initRenderDoc();
        initVulkan();
        createPhysicsWorld();
        this->module->initUI(mirrorView->getGlfwWindow());
        this->module->startup();
        mainLoop();
        PLOGI << "Shutting down module...";
        this->module->shutdown();
        PLOGI << "Module shutdown complete. Destroying physics world...";
        destroyPhysicsWorld();
        PLOGI << "Physics world destroyed. Starting cleanup...";
        cleanup();
        PLOGI << "Cleanup complete.";
    }
 
    std::shared_ptr<InputHandler> Engine::getInputHandler() {
        if (inputHandler == nullptr) {
            throw std::runtime_error("Input handler does not exist yet");
        }
        return inputHandler;
    }
 
    const std::unique_ptr<AssetManager> & Engine::getAssetManager() const {
        return assetManager;
    }
 
    double Engine::getDeltaTimeSeconds()
    {
        return deltaTimeSeconds;
    }
 
    double Engine::getGlobalTimeSeconds()
    {
        return gameTime;
    }
 
    void Engine::createInputManager()
    {
        xrInputHandler = new Input::XrInputHandler(headset, applicationContext);
    }
 
    uint32_t Engine::getRenderableSceneObjectCount() const {
        return Ecs::RegistryManager::get().view<Ecs::StaticMeshData>(  ).size();
    }
 
    Renderer * Engine::getRenderer() const
    {
        return renderer;
    }
 
    void Engine::initWindow() {
#ifdef ENABLE_TRACY
        TRACY_ZONE_SCOPED_FUNCTION;
#endif
        if (!glfwInit()) {
            throw std::runtime_error("Could not initialize glfw!");
        }
        std::cout << "GLFW has been intialized!" << std::endl;
 
        if (!glfwVulkanSupported()) {
            throw std::runtime_error("Glfw does not support vulkan");
        }
        std::cout << "GLFW supports vulkan!" << std::endl;
    }
 
    void Engine::createVulkanDebugMessenger() {
#ifdef IS_IN_DEBUG
        constexpr VkDebugUtilsMessageTypeFlagsEXT typeFlags = VK_DEBUG_UTILS_MESSAGE_TYPE_GENERAL_BIT_EXT |
            VK_DEBUG_UTILS_MESSAGE_TYPE_VALIDATION_BIT_EXT |
            VK_DEBUG_UTILS_MESSAGE_TYPE_PERFORMANCE_BIT_EXT;
        constexpr VkDebugUtilsMessageSeverityFlagsEXT severityFlags =
            VK_DEBUG_UTILS_MESSAGE_SEVERITY_VERBOSE_BIT_EXT | VK_DEBUG_UTILS_MESSAGE_SEVERITY_INFO_BIT_EXT |
            VK_DEBUG_UTILS_MESSAGE_SEVERITY_WARNING_BIT_EXT | VK_DEBUG_UTILS_MESSAGE_SEVERITY_ERROR_BIT_EXT;
 
        const auto callback = [](VkDebugUtilsMessageSeverityFlagBitsEXT messageSeverity,
            VkDebugUtilsMessageTypeFlagsEXT messageTypes,
            const VkDebugUtilsMessengerCallbackDataEXT* callbackData, void* userData) -> VkBool32
            {
                if (callbackData == nullptr || callbackData->pMessage == nullptr) {
                    return VK_FALSE;
                }
                
                // Filter out known Monado OpenXR runtime bugs
                // These MUST be filtered silently to prevent Monado from failing during swapchain creation
                const char* msg = callbackData->pMessage;
                
                // Monado bug: uses wrong access masks for vk_image_collection images during swapchain creation
                if (std::strstr(msg, "vk_image_collection image") != nullptr &&
                    std::strstr(msg, "accessMask is") != nullptr) {
                    // Silently ignore - this is an internal Monado bug
                    return VK_FALSE;
                }
                
                // Monado bug: uses VK_PIPELINE_STAGE_ALL_COMMANDS_BIT in transitions
                if (std::strstr(msg, "vkCmdPipelineBarrier()") != nullptr &&
                    std::strstr(msg, "using VK_PIPELINE_STAGE_ALL_COMMANDS_BIT") != nullptr) {
                    // Silently ignore - this is an internal Monado bug
                    return VK_FALSE;
                }
                
                // Monado uses SIMULTANEOUS_USE_BIT internally
                if (std::strstr(msg, "VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT") != nullptr) {
                    // Silently ignore - this is internal Monado behavior
                    return VK_FALSE;
                }
                
                // Log non-filtered messages
                switch (messageSeverity) {
                case VK_DEBUG_UTILS_MESSAGE_SEVERITY_VERBOSE_BIT_EXT:
                    DPLOGI << "Vulkan Debug Message: " << msg << std::endl;
                    break;
                case VK_DEBUG_UTILS_MESSAGE_SEVERITY_WARNING_BIT_EXT:
                    PLOGW << "[Vulkan] " << msg << std::endl;
                    break;
                case VK_DEBUG_UTILS_MESSAGE_SEVERITY_ERROR_BIT_EXT:
                    PLOGE << "[Vulkan] " << msg << std::endl;
                    break;
                case VK_DEBUG_UTILS_MESSAGE_SEVERITY_INFO_BIT_EXT:
                    PLOGI << "[Vulkan] " << msg;
                    break;
                default:
                    PLOGE << "This should never be called as the default case is enum_MAX";
                    PLOGF << "[Vulkan] " << msg << std::endl;
                }
 
                return VK_FALSE; // Returning VK_TRUE will force the calling function to fail
            };
 
        VkDebugUtilsMessengerCreateInfoEXT debugUtilsMessengerCreateInfo{};
        debugUtilsMessengerCreateInfo.sType = VK_STRUCTURE_TYPE_DEBUG_UTILS_MESSENGER_CREATE_INFO_EXT;
        debugUtilsMessengerCreateInfo.messageType = typeFlags;
        debugUtilsMessengerCreateInfo.messageSeverity = severityFlags;
        debugUtilsMessengerCreateInfo.pfnUserCallback = callback;
 
        PLOG_FN_VK(VulkanHelper::getFunctions().vkCreateDebugUtilsMessengerEXT(applicationContext->getVkInstance(), &debugUtilsMessengerCreateInfo, nullptr, &debugMessenger));
#endif
    }
 
    void Engine::populateDebugMessengerCreateInfo(VkDebugUtilsMessengerCreateInfoEXT& createInfo) {
        createInfo = { .sType           = VK_STRUCTURE_TYPE_DEBUG_UTILS_MESSENGER_CREATE_INFO_EXT,
                       .pNext           = nullptr,
                       .flags           = 0,
                       .messageSeverity = VK_DEBUG_UTILS_MESSAGE_SEVERITY_VERBOSE_BIT_EXT |
                                          VK_DEBUG_UTILS_MESSAGE_SEVERITY_WARNING_BIT_EXT |
                                          VK_DEBUG_UTILS_MESSAGE_SEVERITY_ERROR_BIT_EXT,
                       .messageType = VK_DEBUG_UTILS_MESSAGE_TYPE_GENERAL_BIT_EXT |
                                      VK_DEBUG_UTILS_MESSAGE_TYPE_VALIDATION_BIT_EXT |
                                      VK_DEBUG_UTILS_MESSAGE_TYPE_PERFORMANCE_BIT_EXT,
                       .pfnUserCallback = debugCallback,
                       .pUserData       = nullptr };
    }
 
    VkBool32 Engine::debugCallback(VkDebugUtilsMessageSeverityFlagBitsEXT messageSeverity,
                                   VkDebugUtilsMessageTypeFlagsEXT messageType,
                                   const VkDebugUtilsMessengerCallbackDataEXT *pCallbackData,
                                   void *pUserData) {
 
        // Suppress known SteamVR OpenXR spec violation (ValveSoftware/openvr#1822)
        // SteamVR's compositor creates internal SAMPLED_IMAGE descriptors for swapchain images
        // with incorrect layout expectations. This is a runtime bug, not an application error.
        // The OpenXR spec requires COLOR_ATTACHMENT_OPTIMAL, but SteamVR expects different
        // layouts for different array layers, which is impossible to satisfy.
        if (pCallbackData->pMessageIdName != nullptr &&
            std::strcmp(pCallbackData->pMessageIdName, "VUID-vkCmdDraw-None-09600") == 0) {
            return VK_FALSE; // Suppress this SteamVR-caused validation error
        }
 
        if (messageSeverity >= VK_DEBUG_UTILS_MESSAGE_SEVERITY_WARNING_BIT_EXT) {
            std::cerr << "validation layer: " << pCallbackData->pMessage << std::endl;
        }
 
        // Also log INFO messages when GPU_PRINTF mode is enabled (for shader debugPrintfEXT)
        if constexpr (USE_GPU_PRINTF == GPU_DEBUGGING_MODE::GPU_PRINTF) {
            if (messageSeverity == VK_DEBUG_UTILS_MESSAGE_SEVERITY_INFO_BIT_EXT) {
                PLOGI << "[SHADER_DEBUG] " << pCallbackData->pMessage;
            }
        }
 
        return VK_FALSE;
    }
 
    bool Engine::checkValidationLayerSupport() {
        uint32_t layerCount;
        vkEnumerateInstanceLayerProperties(&layerCount, nullptr);
 
        std::vector<VkLayerProperties> availableLayers(layerCount);
        vkEnumerateInstanceLayerProperties(&layerCount, availableLayers.data());
 
        for (const char* layerName : validationLayers) {
            bool layerFound = false;
 
            for (const auto& layerProperties : availableLayers) {
                if (strcmp(layerName, layerProperties.layerName) == 0) {
                    layerFound = true;
                    break;
                }
            }
 
            if (!layerFound) {
                return false;
            }
        }
 
        return true;
    }
 
    void Engine::createStartupScene() {
        sceneManager->setActiveScene(module->loadInitialScene());
    }
 
 
    void Engine::initVulkan()
    {
#ifdef ENABLE_TRACY
        TRACY_ZONE_SCOPED_FUNCTION;
#endif
        initializePlogDebugger();
 
        tryCreateApplicationContext();
        createVulkanDebugMessenger();


 
        mirrorView = new MirrorView(applicationContext);
#ifdef RENDERDOC_ENABLED
        //RenderDoc& rd = RenderDoc::get();
        //rd.setWindow(mirrorView->getGlfwWindow());
#endif
 
        applicationContext->createDevice(mirrorView->getSurface());
        VulkanHelper::initializeFunctions(applicationContext->getVkInstance(), applicationContext->getVkDevice());
 
        headset = new Headset(applicationContext);
 
        createInputManager();
 
        createAssetManager();
        sceneManager = std::make_unique<SceneManager>(applicationContext);
        createStartupScene();
        renderer = new Renderer(applicationContext, headset, this);
        assetManager->attachToRenderer(renderer);
        assetManager->setRenderingDataManager(renderer->getRenderingDataManager().get());
        initStartupScene();
 
        renderer->allocateDescriptors();
 
        mirrorView->connect(headset, renderer);
 
#ifdef ENABLE_TRACY
        const auto & graphicsCommandBuffers = renderer->getGraphicsCommandBuffers();
        tracyVulkanContext.reserve( graphicsCommandBuffers.size() );
 
        for ( VkCommandBuffer commandBuffer : graphicsCommandBuffers )
        {
            TracyVkCtx tracyContext = TracyVkContext(
                applicationContext->getVkPhysicalDevice(),
                applicationContext->getVkDevice(),
                applicationContext->getGraphicsQueue(),
                commandBuffer
            );
 
            tracyVulkanContext.push_back( tracyContext );
        }
 
        renderer->setupTracy( tracyVulkanContext );
#endif
 
        PLOGI << "Finished init vulkan";
    }
 
    void Engine::tryCreateApplicationContext()
    {
        try
        {
            applicationContext = new ApplicationContext();
            applicationContext->createResources();
        }
        catch(VrHeadsetConnectionException& exception)
        {
            PLOGV << exception.what();
            PLOGI << "Failed to acquire the headset! Retrying in 5 Seconds.";
            applicationContext->cleanup();
            delete applicationContext;
            applicationContext = nullptr;
 
            std::this_thread::sleep_for(std::chrono::milliseconds(5000));
 
            tryCreateApplicationContext();
        }
    }
 
    void Engine::processMirrorWindowEvents()
    {
        TRACY_ZONE_SCOPED_NAMED( "Process mirror window events" );
        glfwPollEvents();
    }
 
    void Engine::calculateFrameTime( double& lastTime )
    {
        TRACY_ZONE_SCOPED_NAMED( "Frame timing calculation" );
        const double currentTime = glfwGetTime();
        deltaTimeSeconds         = currentTime - lastTime;
        lastTime                 = currentTime;
    }
 
    void Engine::fixLoadingAssets() const
    {
        TRACY_ZONE_SCOPED_NAMED_ASSET( "Fixing loading assets" );
        auto& registry = Ecs::RegistryManager::get();
        for (auto& entity : registry.view<Ecs::StaticMeshData, Ecs::AssetRequested>(  ))
        {
            TRACY_ZONE_SCOPED_NAMED( "Asset" );
            auto& data = registry.get<Ecs::StaticMeshData>( entity );
            auto* meshAsset = assetManager->getMeshAsset( data.asset );
            if (meshAsset == nullptr) continue;
 
            data.assetData = meshAsset;
            registry.remove<Ecs::AssetRequested>( entity );
        }
    }
 
    void Engine::processResourceLoadingPipelines()
    {
        TRACY_ZONE_SCOPED_NAMED("Processing resource pipelines");
 
        assetManager->getTextureAssetPipeline().tick( true );
        assetManager->getMeshAssetPipeline().tick( true );
    }
 
    void Engine::update( double & gameTime )
    {
        TRACY_ZONE_SCOPED_NAMED("Frame Update");
 
        gameTime += deltaTimeSeconds;
 
        entt::registry& registry = Ecs::RegistryManager::get();
        {
            TRACY_ZONE_SCOPED_NAMED( "Physics Tick" );
            // physics tick
            getPhysicsEngine()->update( deltaTimeSeconds );
            auto physicsTickView = registry.view<Ecs::SimulatesPhysics, Ecs::LocalTransform>();
            // phsics step 1 -
            for (auto [entity, simulatesPhysics, transform] : physicsTickView.each())
            {
                TRACY_ZONE_SCOPED_NAMED( "Physics Object Tick" );
                if (simulatesPhysics.rigidBody == nullptr) continue;
                if (simulatesPhysics.isStatic) continue;
 
                if (simulatesPhysics.isKinematic)
                {
                    btTransform btTrans;
                    btTrans.setFromOpenGLMatrix(glm::value_ptr(transform.matrix));
                    simulatesPhysics.rigidBody->getMotionState()->setWorldTransform(btTrans);
                    registry.emplace_or_replace<Ecs::TransformDirty>(entity);
                    registry.emplace_or_replace<Ecs::TransformDirtyRenderer>(entity);
                    continue;
                }
 
                // Pull transform FROM Bullet (dynamic bodies)
                btTransform btTrans;
                simulatesPhysics.rigidBody->getMotionState()->getWorldTransform(btTrans);
                btTrans.getOpenGLMatrix(glm::value_ptr(transform.matrix));
                registry.emplace_or_replace<Ecs::TransformDirty>(entity);
                registry.emplace_or_replace<Ecs::TransformDirtyRenderer>(entity);
            }
            // Physics Step 2
            // Propagate dirty flags to children
            {
                TRACY_ZONE_SCOPED_NAMED( "Transform Dirty Propagation" );
                auto dirtyView = registry.view<Ecs::TransformDirty, Ecs::SceneNodeRef>();
                for (auto [entity, nodeRef] : dirtyView.each()) {
                    if (auto node = nodeRef.node.lock()) {
                        for (const auto& weakChild : node->getChildren()) {
                            if (auto child = weakChild.lock()) {
                                child->markDirtyRecursive();
                            }
                        }
                    }
                }
            }
        }
 
        {
            TRACY_ZONE_SCOPED_NAMED( "Logic Tick" );
            // logic tick
            auto logicTickView = registry.view<Ecs::Tick>();
            if (module)
                module->preTick();
            for (auto [entity, tick] : logicTickView.each())
            {
                TRACY_ZONE_SCOPED_NAMED("Pre Tick");
                tick.tickable->preTick();
            }
 
            if (module)
                module->tick( deltaTimeSeconds );
            for (auto [entity, tick] : logicTickView.each())
            {
                TRACY_ZONE_SCOPED_NAMED("Tick");
                tick.tickable->tick(deltaTimeSeconds);
            }
 
            if (module)
                module->postTick();
            for (auto [entity, tick] : logicTickView.each())
            {
                TRACY_ZONE_SCOPED_NAMED("Post Tick");
                tick.tickable->postTick();
            }
        }
 
 
        {
            TRACY_ZONE_SCOPED_NAMED( "Hand tracking update" );
            /*if ( leftHand )
                leftHand->getTransform()->overrideMatrix(
                    xrInputHandler->getHandPoseInfo( Input::Hand::LEFT ).matrix
                );
            if ( rightHand )
                rightHand->getTransform()->overrideMatrix(
                    xrInputHandler->getHandPoseInfo( Input::Hand::RIGHT ).matrix
                );*/
        }
    }
 
    void Engine::captureRenderdocFrame()
    {
#ifdef RENDERDOC_ENABLED
        auto & rd = RenderDoc::get();
        {
            TRACY_ZONE_SCOPED_NAMED( "RenderDoc operations" );
            if ( rd.init() )
            {
                rd.startCapture( applicationContext->getVkDevice() );
                rd.printStatus();
            }
            else
            {
                PLOGW << "Could not init renderdoc, capture failed!";
            }
        }
#endif
    }
 
    int Engine::isMirrorViewMinimized()
    {
        return glfwGetWindowAttrib( mirrorView->getGlfwWindow(), GLFW_ICONIFIED );
    }
 
    void Engine::completeFrameAsync(VkFence graphicsFence, bool presentMirror)
    {
        // Note: This function is called from a background thread.
        // The graphicsFence parameter is captured before advanceFrameIndices() is called,
        // so it refers to the correct fence for the frame that was just submitted.
 
        TRACY_ZONE_SCOPED_NAMED("Async Frame Completion");
 
        // Wait for GPU to finish rendering this frame
        {
            TRACY_ZONE_SCOPED_NAMED("Wait Graphics Fence (Async)");
            vkWaitForFences(applicationContext->getVkDevice(), 1, &graphicsFence, VK_TRUE, UINT64_MAX);
        }
 
        // End XR frame (includes xrReleaseSwapchainImage)
        {
            TRACY_ZONE_SCOPED_NAMED("End XR Frame (Async)");
            PLOGI << "[ASYNC] About to call endXrFrame()";
            headset->endXrFrame();
            PLOGI << "[ASYNC] endXrFrame() completed";
        }
 
        // Present mirror view if requested
        if (presentMirror)
        {
            TRACY_ZONE_SCOPED_NAMED("Mirror View Present (Async)");
            PLOGI << "[ASYNC] About to call mirrorView->present()";
            mirrorView->present();
            PLOGI << "[ASYNC] mirrorView->present() completed";
        }
 
        // Signal completion for next frame
        previousFrameXrComplete_.store(true, std::memory_order_release);
    }
 
    void Engine::mainLoop()
    {
        TRACY_ZONE_SCOPED_NAMED("Engine::mainLoop");
        double lastTime = glfwGetTime();
 
 
        renderer->initializeGpuBuffers();
 
        // check if the meshlet draw function is loaded to prevent exit in the renderer
        if ( !VulkanHelper::getFunctions().vkCmdDrawMeshTasksIndirectEXT )
            PLOGF << "Draw call pointer not valid!";
 
        while ( !glfwWindowShouldClose( mirrorView->getGlfwWindow() ) && !headset->getIsExitRequested() )
        {
            TRACY_ZONE_SCOPED_NAMED( "Engine::mainLoop" );
 
            calculateFrameTime( lastTime );
            processMirrorWindowEvents();
 
            // If window close was requested, notify OpenXR to begin shutdown
            // This prevents xrWaitFrame from blocking indefinitely
            if ( glfwWindowShouldClose( mirrorView->getGlfwWindow() ) )
            {
                headset->requestExitSession();
            }
 
            // === STEP 1: Call xrWaitFrame early (can happen before previous xrEndFrame) ===
            uint32_t swapchainImageIndex = 0;
            Headset::BeginFrameResult beginFrameResult;
            Headset::WaitFrameResult waitFrameResult;
            {
                #if defined(HEADLESS)
                {
                    beginFrameResult = Headset::BeginFrameResult::SkipFully;
                    waitFrameResult.result = beginFrameResult;
                    waitFrameResult.shouldCallBeginFrame = false;
                }
                #elif defined(COMPUTE_DEBUG)
                {
                    beginFrameResult = Headset::BeginFrameResult::ComputeOnly;
                    waitFrameResult.result = beginFrameResult;
                    waitFrameResult.shouldCallBeginFrame = false;
                }
                #else
                {
                    TRACY_ZONE_SCOPED_NAMED( "Wait XR Frame (Early)" );
                    waitFrameResult = headset->waitForXrFrame( renderer );
                    beginFrameResult = waitFrameResult.result;
                }
                #endif
            }
 
            // === STEP 2: Do work that doesn't need swapchain/poses ===
            // This overlaps with GPU work from previous frame
            processResourceLoadingPipelines();
            fixLoadingAssets();
 
            if ( sceneManager->isSceneChangePending() )
            {
                TRACY_ZONE_SCOPED_NAMED( "Scene loading operations" );
                sceneManager->executePendingSceneLoading();
            }
 
            // === STEP 3: Wait for previous frame's xrEndFrame to complete ===
            // This is required before calling xrBeginFrame
            if ( frameCompletionFuture_.valid() )
            {
                TRACY_ZONE_SCOPED_NAMED( "Wait for previous frame completion" );
                frameCompletionFuture_.wait();
            }
 
            // Frame mark after previous frame fully completes (including async xrEndFrame)
            TRACY_FRAME_MARK;
 
            // === STEP 4: Now safe to call xrBeginFrame ===
            if ( waitFrameResult.shouldCallBeginFrame )
            {
                TRACY_ZONE_SCOPED_NAMED( "Begin XR Frame (After Wait)" );
                beginFrameResult = headset->beginXrFrameAfterWait( swapchainImageIndex );
            }
 
            // Input sync needs poses from xrBeginFrame
            if ( beginFrameResult == Headset::BeginFrameResult::RenderFully )
            {
                TRACY_ZONE_SCOPED_NAMED( "Input synchronization" );
                XrTime predictedDisplayTime = headset->getXrFrameState().predictedDisplayTime;
 
                xrInputHandler->syncInputs( headset->getReferenceSpace(), predictedDisplayTime );
            }
 
            update( gameTime );
 
            // Track previous frame result to detect transitions from skip to render
            static Headset::BeginFrameResult previousFrameResult = Headset::BeginFrameResult::RenderFully;
 
            switch ( beginFrameResult )
            {
                case Headset::BeginFrameResult::Error:
                    {
                        THROW_ERROR( "Failed to begin xr frame!" );
                        break;
                    }
                case Headset::BeginFrameResult::RenderFully:
                {
                    TRACY_ZONE_SCOPED_NAMED( "Full frame render" );
 
                    // Mark frame start time for stall detection
                    renderer->markFrameStart();
 
                    // Sync timeline semaphore after transitioning from skip to render.
                    // This ensures the frame counter is advanced enough that timeline
                    // semaphore signals will have increasing values (required by Vulkan).
                    if (previousFrameResult == Headset::BeginFrameResult::SkipRender ||
                        previousFrameResult == Headset::BeginFrameResult::SkipFully)
                    {
                        PLOGI << "Resuming rendering after skip - syncing timeline";
                        renderer->syncTimelineAfterPause();
                    }
 
                    captureRenderdocFrame();
 
                    PLOGI << "Waiting for last frame in flight to complete";
 
                    // Wait for transfer fence (frame N-2 for 2 frames in flight)
                    {
                        TRACY_ZONE_SCOPED_NAMED( "Transfer fence synchronization" );
                        RenderProcess * renderProcess = renderer->getCurrentRenderProcess();
                        vkWaitForFences(
                            applicationContext->getVkDevice(),
                            1,
                            &renderProcess->getTransferCompleteFence(),
                            VK_TRUE,
                            UINT64_MAX
                        );
                        vkResetFences(
                            applicationContext->getVkDevice(),
                            1,
                            &renderProcess->getTransferCompleteFence()
                        );
                        renderProcess->setTransferFenceSubmitted( false );
                    }
 
                    // Wait for previous graphics completion (frame N-2 for 2 frames in flight)
                    // Note: We don't wait for frame N-1's graphics fence here anymore.
                    // Frame N-1's graphics fence is waited on by the async completion thread.
                    {
                        TRACY_ZONE_SCOPED_NAMED( "Graphics fence synchronization" );
                        RenderProcess * renderProcess = renderer->getCurrentRenderProcess();
                        if ( renderProcess->getGraphicsFenceSubmitted() )
                        {
                            vkWaitForFences(
                                applicationContext->getVkDevice(),
                                1,
                                &renderProcess->getGraphicsCompleteFence(),
                                VK_TRUE,
                                UINT64_MAX
                            );
                            vkResetFences(
                                applicationContext->getVkDevice(),
                                1,
                                &renderProcess->getGraphicsCompleteFence()
                            );
                            renderProcess->setGraphicsFenceSubmitted( false );
                        }
                    }
 
                    {
                        TRACY_ZONE_SCOPED_NAMED( "Process completed meshlet generations" );
                        // Safe point: write completed meshlet data to registry
                        auto pendingCompletions = assetManager->getMeshAssetPipeline().takePendingMeshletCompletions();
                        renderer->getRenderingDataManager()->processCompletedMeshletGenerations(std::move(pendingCompletions));
                    }
 
                    {
                        TRACY_ZONE_SCOPED_NAMED( "Process pending mesh loads" );
                        // Safe point: process deferred mesh loads before render update
                        renderer->getRenderingDataManager()->processPendingMeshLoads();
                    }
 
                    {
                        TRACY_ZONE_SCOPED_NAMED( "Update primitive GPU data" );
                        renderer->getRenderingDataManager()->updateIfDirty();
                    }
 
                    {
                        TRACY_ZONE_SCOPED_NAMED( "Update transform GPU data" );
                        renderer->getRenderingDataManager()->updateTransforms();
                    }
 
                    // Sync descriptor sets with RenderingDataManager using version tracking
                    {
                        TRACY_ZONE_SCOPED_NAMED( "Sync descriptor sets" );
                        renderer->getCurrentRenderProcess()->syncWithRenderingDataManager(
                            renderer->getRenderingDataManager().get());
                    }
 
                    {
                        TRACY_ZONE_SCOPED_NAMED( "Renderer data upload" );
                        renderer->uploadFrameData( static_cast<float>( gameTime ) );
                    }
 
                    {
                        TRACY_ZONE_SCOPED_NAMED( "Transfer command recording" );
                        renderer->recordTransfer( static_cast<float>( gameTime ) );
                    }
 
                    {
                        TRACY_ZONE_SCOPED_NAMED( "Transfer submission" );
                        renderer->submitTransfer();
                    }
 
                    {
                        TRACY_ZONE_SCOPED_NAMED( "XR rendering" );
                        renderer->renderToXr( swapchainImageIndex, static_cast<float>( gameTime ) );
                    }
 
                    VkSemaphore mirrorSemaphore = VK_NULL_HANDLE;
                    bool shouldPresentMirror = false;
                    {
                        TRACY_ZONE_SCOPED_NAMED( "Mirror view operations" );
                        // Skip mirror view after timeline sync to prevent WRITE_AFTER_PRESENT hazard
                        const bool skipAfterSync = renderer->shouldSkipMirrorView();
                        const bool isMirrorVisible =
                            !isMirrorViewMinimized() && !skipAfterSync;
 
                        #ifndef HEADLESS
                        if ( isMirrorVisible )
                        {
                            auto mirrorResult = mirrorView->render( swapchainImageIndex );
                            if ( mirrorResult.status == MirrorView::RenderResult::Status::Visible )
                            {
                                mirrorSemaphore = mirrorResult.imageAvailableSemaphore;
                                shouldPresentMirror = true;
                            }
                        }
                        #endif
                    }
 
                    {
                        TRACY_ZONE_SCOPED_NAMED( "Graphics submission" );
                        renderer->submitGraphics( swapchainImageIndex, mirrorSemaphore );
                    }
 
                    #ifdef RENDERDOC_ENABLED
                    {
                        TRACY_ZONE_SCOPED_NAMED( "RenderDoc end capture" );
                        rd.endCapture( applicationContext->getVkDevice() );
                    }
                    #endif
 
                    // === STEP 8: Spawn async completion (non-blocking) ===
                    // This runs on a background thread: waits for GPU fence, ends XR frame, presents mirror
                    {
                        TRACY_ZONE_SCOPED_NAMED( "Spawn async frame completion" );
                        #ifndef HEADLESS
                        previousFrameXrComplete_.store(false, std::memory_order_release);
 
                        // Capture the graphics fence BEFORE advanceFrameIndices changes currentRenderProcess
                        // The async thread needs the fence from THIS frame's RenderProcess
                        VkFence graphicsFence = renderer->getCurrentRenderProcess()->getGraphicsCompleteFence();
 
                        frameCompletionFuture_ = xrFrameThreadPool_->submit_task(
                            [this, graphicsFence, shouldPresentMirror]() {
                                completeFrameAsync(graphicsFence, shouldPresentMirror);
                            });
                        #endif
                    }
 
                    {
                        TRACY_ZONE_SCOPED_NAMED( "Frame cleanup and advancement" );
                        // Staging buffer cleanup moved to Renderer::submitTransfer() after fence wait
                        renderer->advanceFrameIndices();
                    }
                    break;
                }
                case Headset::BeginFrameResult::SkipRender:
                {
                    TRACY_ZONE_SCOPED_NAMED("Skip render frame");
                    PLOGI << "Skipping render.";
                    headset->endXrFrameNoRender();
                    // Staging buffer cleanup moved to Renderer::submitTransfer() after fence wait
                    break;
                }
                case Headset::BeginFrameResult::SkipFully: {
                        TRACY_ZONE_SCOPED_NAMED("Skip frame fully");
                        PLOGI << "Skipping frame fully.";
                        // Staging buffer cleanup moved to Renderer::submitTransfer() after fence wait
 
                        std::this_thread::sleep_for(std::chrono::microseconds(8300));
                        break;
                    }
                case Headset::BeginFrameResult::ComputeOnly:
                {
                    TRACY_ZONE_SCOPED_NAMED( "Compute Debug Frame" );
                    PLOGI << "[COMPUTE_DEBUG] Running compute-only frame";
 
                    // Wait for transfer fence
                    {
                        TRACY_ZONE_SCOPED_NAMED( "Transfer fence synchronization" );
                        RenderProcess * renderProcess = renderer->getCurrentRenderProcess();
                        if ( renderProcess->getTransferFenceSubmitted() )
                        {
                            vkWaitForFences(
                                applicationContext->getVkDevice(),
                                1,
                                &renderProcess->getTransferCompleteFence(),
                                VK_TRUE,
                                UINT64_MAX
                            );
                            vkResetFences(
                                applicationContext->getVkDevice(),
                                1,
                                &renderProcess->getTransferCompleteFence()
                            );
                            renderProcess->setTransferFenceSubmitted( false );
                        }
                    }
 
                    // Wait for previous graphics/compute completion
                    {
                        TRACY_ZONE_SCOPED_NAMED( "Graphics fence synchronization" );
                        RenderProcess * renderProcess = renderer->getCurrentRenderProcess();
                        if ( renderProcess->getGraphicsFenceSubmitted() )
                        {
                            vkWaitForFences(
                                applicationContext->getVkDevice(),
                                1,
                                &renderProcess->getGraphicsCompleteFence(),
                                VK_TRUE,
                                UINT64_MAX
                            );
                            vkResetFences(
                                applicationContext->getVkDevice(),
                                1,
                                &renderProcess->getGraphicsCompleteFence()
                            );
                            renderProcess->setGraphicsFenceSubmitted( false );
                        }
                    }
 
                    {
                        TRACY_ZONE_SCOPED_NAMED( "Process completed meshlet generations" );
                        // Safe point: write completed meshlet data to registry
                        auto pendingCompletions = assetManager->getMeshAssetPipeline().takePendingMeshletCompletions();
                        renderer->getRenderingDataManager()->processCompletedMeshletGenerations(std::move(pendingCompletions));
                    }
 
                    {
                        TRACY_ZONE_SCOPED_NAMED( "Process pending mesh loads" );
                        // Safe point: process deferred mesh loads before render update
                        renderer->getRenderingDataManager()->processPendingMeshLoads();
                    }
 
                    // Update primitive data if dirty
                    {
                        TRACY_ZONE_SCOPED_NAMED( "Update primitive GPU data" );
                        renderer->getRenderingDataManager()->updateIfDirty();
                    }
 
                    {
                        TRACY_ZONE_SCOPED_NAMED( "Update transform GPU data" );
                        renderer->getRenderingDataManager()->updateTransforms();
                    }
 
                    // Sync descriptor sets with RenderingDataManager using version tracking
                    {
                        TRACY_ZONE_SCOPED_NAMED( "Sync descriptor sets" );
                        renderer->getCurrentRenderProcess()->syncWithRenderingDataManager(
                            renderer->getRenderingDataManager().get());
                    }
 
                    // Update CPU-side rendering data
                    {
                        TRACY_ZONE_SCOPED_NAMED( "Renderer data upload" );
                        renderer->uploadFrameData( static_cast<float>( gameTime ) );
                    }
 
                    // Record and submit transfer commands
                    {
                        TRACY_ZONE_SCOPED_NAMED( "Transfer command recording" );
                        renderer->recordTransfer( static_cast<float>( gameTime ) );
                    }
 
                    {
                        TRACY_ZONE_SCOPED_NAMED( "Transfer submission" );
                        renderer->submitTransfer();
                    }
 
                    // Run compute pipeline (without graphics/mesh shaders)
                    {
                        TRACY_ZONE_SCOPED_NAMED( "Compute dispatch" );
                        renderer->renderToXr( 0, static_cast<float>( gameTime ) );
                    }
 
                    // Submit compute commands
                    {
                        TRACY_ZONE_SCOPED_NAMED( "Compute submission" );
                        renderer->submitGraphics( 0, VK_NULL_HANDLE );
                    }
 
                    {
                        TRACY_ZONE_SCOPED_NAMED( "Frame cleanup and advancement" );
                        // Staging buffer cleanup moved to Renderer::submitTransfer() after fence wait
                        renderer->advanceFrameIndices();
                    }
 
                    // Small delay to prevent spinning too fast in debug mode
                    std::this_thread::sleep_for( std::chrono::milliseconds( 8 ) );
                    break;
                }
            }
 
            // Update previous frame result for next iteration's skip-to-render detection
            previousFrameResult = beginFrameResult;
 
            frameCounter++;
        }
        PLOGI << "Exiting main loop";
    }
 
    void Engine::cleanup() {
        PLOGI << "Engine::cleanup() started";
 
        // Wait for any pending async frame completion before cleanup
        if (frameCompletionFuture_.valid()) {
            PLOGI << "Waiting for async frame completion to finish...";
            frameCompletionFuture_.wait();
            PLOGI << "Async frame completion finished";
        }
 
        if (applicationContext->getVkDevice()) {
            // Signal the timeline semaphore from CPU to unblock any GPU work
            // that may be waiting on timeline values that will never be signaled
            // by subsequent GPU submissions (since we're shutting down)
            if (renderer) {
                PLOGI << "Signaling timeline semaphore to unblock pending GPU work...";
                const auto& timelineSync = renderer->getTimelineSynchronizer();
                uint64_t currentValue = timelineSync.getCurrentValue();
                // Signal to a value high enough to unblock any pending work
                // Using current + 100 frames worth of stages ensures all pending
                // waits are satisfied
                uint64_t unblockValue = currentValue + (100 * PIPELINE_STAGE_COUNT);
                PLOGI << "Timeline semaphore: current=" << currentValue << ", signaling=" << unblockValue;
                timelineSync.signalValue(unblockValue);
            }
 
            // Wait for all in-flight fences to complete before device wait idle
            // This ensures any submitted work completes before we try to clean up
            PLOGI << "Waiting for in-flight fences...";
            if (renderer) {
                std::vector<VkFence> fences;
                for (RenderProcess* process : renderer->getRenderProcesses()) {
                    if (process->getTransferFenceSubmitted()) {
                        fences.push_back(process->getTransferCompleteFence());
                    }
                    if (process->getGraphicsFenceSubmitted()) {
                        fences.push_back(process->getGraphicsCompleteFence());
                    }
                }
                if (!fences.empty()) {
                    PLOGI << "Waiting for " << fences.size() << " fences...";
                    VkResult result = vkWaitForFences(
                        applicationContext->getVkDevice(),
                        static_cast<uint32_t>(fences.size()),
                        fences.data(),
                        VK_TRUE,
                        5000000000ULL  // 5 second timeout
                    );
                    if (result == VK_TIMEOUT) {
                        PLOGW << "Fence wait timed out - GPU work may be stuck";
                    }
                }
            }
 
            // Wait for the device to be idle before cleaning up resources
            PLOGI << "Waiting for device to be idle...";
            vkDeviceWaitIdle(applicationContext->getVkDevice());
            PLOGI << "Device is idle";
 
            if (sceneManager) {
                PLOGI << "Cleaning up scene manager...";
                sceneManager->cleanup();
            }
            // asset manager
            if (assetManager) {
                PLOGI << "Cleaning up asset manager...";
                assetManager->cleanup();
                assetManager.reset();
            }
 
            PLOGI << "Cleaning up renderer...";
            renderer->cleanup();
            delete renderer;
            renderer = nullptr;
 
            PLOGI << "Cleaning up headset...";
            headset->cleanup();
            delete headset;
            headset = nullptr;
 
            PLOGI << "Cleaning up mirror view...";
            mirrorView->cleanup();
            delete mirrorView;
            mirrorView = nullptr;
 
#ifdef IS_IN_DEBUG
            // Destroy debug messenger
            if (ARE_VALIDATION_LAYERS_ENABLED) {
                VulkanHelper::getFunctions().vkDestroyDebugUtilsMessengerEXT(applicationContext->getVkInstance(), debugMessenger, nullptr);
            }
#endif
 
            applicationContext->cleanup();
            delete applicationContext;
            applicationContext = nullptr;
 
            // call cleanup on the module while all vulkan objects still exist
            if (module) {
                module->shutdown();
                module = nullptr;
            }
        }
    }
 
    void Engine::initializePlogDebugger()
    {
        auto now = std::chrono::system_clock::now();
        auto time = std::chrono::system_clock::to_time_t(now);
        std::ostringstream oss;
        oss << "GameLog_" << std::put_time(std::localtime(&time), "%Y-%m-%d_%H-%M-%S") << ".log";
        static std::string logFileName = oss.str();
 
        static plog::RollingFileAppender<plog::TxtFormatter> fileAppender(logFileName.c_str());
        static plog::ColorConsoleAppender<plog::TxtFormatter> consoleAppender;
        plog::init<PLOG_DEFAULT_INSTANCE_ID>(plog::Severity::info, &fileAppender).addAppender(&consoleAppender);
    }
 
    void Engine::initStartupScene()
    {
        if (sceneManager->getActiveScene()) {
            sceneManager->getActiveScene()->loadContent();
        }
    }
 
    PhysicsEngine * Engine::getPhysicsEngine() const
    {
        return physicsEngine;
    }
 
    void Engine::createAssetManager() {
        assetManager = std::make_unique<AssetManager>(applicationContext);
    }
 
    void Engine::initAssets() {
        PLOGI << "Total mesh count after loading is now: " << assetManager->getAllMeshes().size();
    }
 
    void Engine::createPhysicsWorld()
    {
        physicsEngine = new PhysicsEngine();
    }
 
    void Engine::destroyPhysicsWorld()
    {
        delete physicsEngine;
        physicsEngine = nullptr;
    }
 
    EngineManager & EngineManager::getInstance() {
        static EngineManager instance;
        return instance;
    }
 
    EngineCore::Engine* EngineManager::getEngineModule() {
        return engine;
    }
 
    void EngineManager::setEngine(Engine *engineInstance) {
        engine = engineInstance;
    }
} // namespace EngineCore end
 
 
#undef USE_VULKAN
#undef XR_LOG_STRING