GUI: Setting Up Dear ImGui

# Clone ImGui repository
git clone https://github.com/ocornut/imgui.git external/imgui

# Copy necessary files to your project
cp external/imgui/imgui.h include/
cp external/imgui/imgui.cpp src/
cp external/imgui/imgui_draw.cpp src/
cp external/imgui/imgui_widgets.cpp src/
cp external/imgui/imgui_tables.cpp src/
cp external/imgui/imgui_demo.cpp src/

# ImGui files
set(IMGUI_SOURCES
    src/imgui.cpp
    src/imgui_draw.cpp
    src/imgui_widgets.cpp
    src/imgui_tables.cpp
    src/imgui_demo.cpp
)

# Our custom ImGui Vulkan integration
set(IMGUI_VULKAN_SOURCES
    src/imgui_vulkan_util.cpp
)

add_executable(VulkanApp
    src/main.cpp
    ${IMGUI_SOURCES}
    ${IMGUI_VULKAN_SOURCES}
)

target_include_directories(VulkanApp PRIVATE include)

// ImGuiVulkanUtil.h
#pragma once

#include <vulkan/vulkan_raii.hpp>
#include <imgui.h>

class ImGuiVulkanUtil {
private:
    // Core GPU rendering resources for UI display
    // These objects form the foundation of our ImGui-to-Vulkan rendering pipeline
    vk::raii::Sampler sampler{nullptr};                    // Texture sampling configuration for font rendering
    Buffer vertexBuffer;                                    // Dynamic vertex buffer for UI geometry
    Buffer indexBuffer;                                     // Dynamic index buffer for UI triangle connectivity
    uint32_t vertexCount = 0;                              // Current vertex count for draw commands
    uint32_t indexCount = 0;                               // Current index count for draw commands
    Image fontImage;                                        // GPU texture containing ImGui font atlas
    ImageView fontImageView;                                // Shader-accessible view of font texture

    // Vulkan pipeline infrastructure for UI rendering
    // These objects define the complete GPU processing pipeline for ImGui elements
    vk::raii::PipelineCache pipelineCache{nullptr};        // Pipeline compilation cache for faster startup
    vk::raii::PipelineLayout pipelineLayout{nullptr};      // Resource binding layout (textures, uniforms)
    vk::raii::Pipeline pipeline{nullptr};                  // Complete graphics pipeline for UI rendering
    vk::raii::DescriptorPool descriptorPool{nullptr};      // Pool for allocating descriptor sets
    vk::raii::DescriptorSetLayout descriptorSetLayout{nullptr}; // Layout defining shader resource bindings
    vk::raii::DescriptorSet descriptorSet{nullptr};        // Actual resource bindings for font texture

    // Vulkan device context and system integration
    // These references connect our UI system to the broader Vulkan application context
    vk::raii::Device* device = nullptr;                    // Primary Vulkan device for resource creation
    vk::raii::PhysicalDevice* physicalDevice = nullptr;    // GPU hardware info for capability queries
    vk::raii::Queue* graphicsQueue = nullptr;              // Command submission queue for UI rendering
    uint32_t graphicsQueueFamily = 0;                      // Queue family index for validation

    // UI state management and rendering configuration
    // These members control the visual appearance and dynamic behavior of the UI system
    ImGuiStyle vulkanStyle;                                 // Custom visual styling for Vulkan applications

    // Push constants for efficient per-frame parameter updates
    // This structure enables fast updates of transformation and styling data
    struct PushConstBlock {
        glm::vec2 scale;                                    // UI scaling factors for different screen sizes
        glm::vec2 translate;                                // Translation offset for UI positioning
    } pushConstBlock;

    // Dynamic state tracking for performance optimization
    bool needsUpdateBuffers = false;                        // Flag indicating buffer resize requirements

    // Modern Vulkan rendering configuration
    vk::PipelineRenderingCreateInfo renderingInfo{};        // Dynamic rendering setup parameters
    vk::Format colorFormat = vk::Format::eB8G8R8A8Unorm;   // Target framebuffer format

public:
    // Lifecycle management for proper resource initialization and cleanup
    ImGuiVulkanUtil(vk::raii::Device& device, vk::raii::PhysicalDevice& physicalDevice,
                   vk::raii::Queue& graphicsQueue, uint32_t graphicsQueueFamily);
    ~ImGuiVulkanUtil();

    // Core functionality methods for ImGui integration
    void init(float width, float height);                   // Initialize ImGui context and configure display
    void initResources();                                    // Create all Vulkan resources for rendering
    void setStyle(uint32_t index);                          // Apply visual styling themes

    // Frame-by-frame rendering operations
    bool newFrame();                                         // Begin new ImGui frame and generate geometry
    void updateBuffers();                                    // Upload updated geometry to GPU buffers
    void drawFrame(vk::raii::CommandBuffer& commandBuffer); // Record rendering commands to command buffer

    // Input event handling for interactive UI elements
    void handleKey(int key, int scancode, int action, int mods); // Process keyboard input events
    bool getWantKeyCapture();                               // Query if ImGui wants keyboard focus
    void charPressed(uint32_t key);                         // Handle character input for text widgets
};

void ImGuiVulkanUtil::initResources() {
    // Extract font atlas data from ImGui's internal font system
    // ImGui generates a texture atlas containing all glyphs needed for text rendering
    ImGuiIO& io = ImGui::GetIO();
    unsigned char* fontData;                    // Raw pixel data from font atlas
    int texWidth, texHeight;                    // Dimensions of the generated font atlas
    io.Fonts->GetTexDataAsRGBA32(&fontData, &texWidth, &texHeight);

    // Calculate total memory requirements for GPU transfer
    // Each pixel contains 4 bytes (RGBA) requiring precise memory allocation
    vk::DeviceSize uploadSize = texWidth * texHeight * 4 * sizeof(char);

    // Define image dimensions and create extent structure
    // Vulkan requires explicit specification of all image dimensions
    vk::Extent3D fontExtent{
        static_cast<uint32_t>(texWidth),        // Image width in pixels
        static_cast<uint32_t>(texHeight),       // Image height in pixels
        1                                       // Single layer (not a 3D texture or array)
    };

    // Create optimized GPU image for font texture storage
    // This image will be sampled by shaders during UI rendering
    fontImage = Image(*device, fontExtent, vk::Format::eR8G8B8A8Unorm,
                    vk::ImageUsageFlagBits::eSampled | vk::ImageUsageFlagBits::eTransferDst,
                    vk::MemoryPropertyFlagBits::eDeviceLocal);

    // Create image view for shader access
    // The image view defines how shaders interpret the raw image data
    fontImageView = ImageView(*device, fontImage.getHandle(), vk::Format::eR8G8B8A8Unorm,
                           vk::ImageAspectFlagBits::eColor);

    // Create staging buffer for efficient CPU-to-GPU data transfer
    // Host-visible memory allows direct CPU access for data upload
    Buffer stagingBuffer(*device, uploadSize, vk::BufferUsageFlagBits::eTransferSrc,
                       vk::MemoryPropertyFlagBits::eHostVisible | vk::MemoryPropertyFlagBits::eHostCoherent);

    // Map staging buffer memory and copy font data
    // Direct memory mapping provides the fastest path for data transfer
    void* data = stagingBuffer.map();                          // Map GPU memory to CPU address space
    memcpy(data, fontData, uploadSize);                        // Copy font atlas data to GPU memory
    stagingBuffer.unmap();                                     // Unmap memory to ensure data consistency

    // Transition image to optimal layout for data reception
    // Vulkan requires explicit layout transitions for optimal performance and correctness
    transitionImageLayout(fontImage.getHandle(), vk::Format::eR8G8B8A8Unorm,
                         vk::ImageLayout::eUndefined, vk::ImageLayout::eTransferDstOptimal);

    // Execute the actual buffer-to-image copy operation
    // This transfers font data from staging buffer to the final GPU image
    copyBufferToImage(stagingBuffer.getHandle(), fontImage.getHandle(),
                     static_cast<uint32_t>(texWidth), static_cast<uint32_t>(texHeight));

    // Transition image to shader-readable layout for rendering
    // Final layout optimization enables efficient sampling during UI rendering
    transitionImageLayout(fontImage.getHandle(), vk::Format::eR8G8B8A8Unorm,
                         vk::ImageLayout::eTransferDstOptimal, vk::ImageLayout::eShaderReadOnlyOptimal);

    // Configure texture sampling parameters for optimal text rendering
    // These settings directly impact text quality and performance
    vk::SamplerCreateInfo samplerInfo{};
    samplerInfo.magFilter = vk::Filter::eLinear;                    // Smooth scaling when magnified
    samplerInfo.minFilter = vk::Filter::eLinear;                    // Smooth scaling when minified
    samplerInfo.mipmapMode = vk::SamplerMipmapMode::eLinear;        // Smooth transitions between mip levels
    samplerInfo.addressModeU = vk::SamplerAddressMode::eClampToEdge;  // Prevent texture wrapping
    samplerInfo.addressModeV = vk::SamplerAddressMode::eClampToEdge;  // Clean edge handling
    samplerInfo.addressModeW = vk::SamplerAddressMode::eClampToEdge;  // 3D consistency
    samplerInfo.borderColor = vk::BorderColor::eFloatOpaqueWhite;   // White border for clamped areas

    sampler = device->createSampler(samplerInfo);                   // Create the GPU sampler object

    // Create descriptor pool for shader resource binding
    // Descriptors provide the interface between shaders and GPU resources
    vk::DescriptorPoolSize poolSize{vk::DescriptorType::eCombinedImageSampler, 1};

    vk::DescriptorPoolCreateInfo poolInfo{};
    poolInfo.flags = vk::DescriptorPoolCreateFlagBits::eFreeDescriptorSet;     // Allow individual descriptor set freeing
    poolInfo.maxSets = 2;                                                      // Maximum number of descriptor sets
    poolInfo.poolSizeCount = 1;                                                // Number of pool size specifications
    poolInfo.pPoolSizes = &poolSize;                                           // Pool size configuration

    descriptorPool = device->createDescriptorPool(poolInfo);                   // Create descriptor pool

    // Create descriptor set layout defining shader resource interface
    // This layout must match the binding declarations in the ImGui shaders
    vk::DescriptorSetLayoutBinding binding{};
    binding.descriptorType = vk::DescriptorType::eCombinedImageSampler;        // Combined texture and sampler
    binding.descriptorCount = 1;                                               // Single texture binding
    binding.stageFlags = vk::ShaderStageFlagBits::eFragment;                   // Used in fragment shader
    binding.binding = 0;                                                       // Shader binding point 0

    vk::DescriptorSetLayoutCreateInfo layoutInfo{};
    layoutInfo.bindingCount = 1;                                               // Number of bindings in layout
    layoutInfo.pBindings = &binding;                                           // Binding configuration array

    descriptorSetLayout = device->createDescriptorSetLayout(layoutInfo);       // Create layout object

    // Allocate descriptor set from pool using the defined layout
    // This creates the actual binding that connects GPU resources to shaders
    vk::DescriptorSetAllocateInfo allocInfo{};
    allocInfo.descriptorPool = *descriptorPool;                                // Source pool for allocation
    allocInfo.descriptorSetCount = 1;                                          // Number of sets to allocate
    vk::DescriptorSetLayout layouts[] = {*descriptorSetLayout};                // Layout template array
    allocInfo.pSetLayouts = layouts;                                           // Layout configuration

    descriptorSet = std::move(device->allocateDescriptorSets(allocInfo).front()); // Allocate and store set

    // Update descriptor set with actual font texture and sampler resources
    // This final step connects the physical GPU resources to the shader binding points
    vk::DescriptorImageInfo imageInfo{};
    imageInfo.imageLayout = vk::ImageLayout::eShaderReadOnlyOptimal;           // Expected image layout
    imageInfo.imageView = fontImageView.getHandle();                           // Font texture view
    imageInfo.sampler = *sampler;                                              // Texture sampler

    vk::WriteDescriptorSet writeSet{};
    writeSet.dstSet = *descriptorSet;                                          // Target descriptor set
    writeSet.descriptorCount = 1;                                              // Number of resources to bind
    writeSet.descriptorType = vk::DescriptorType::eCombinedImageSampler;       // Resource type
    writeSet.pImageInfo = &imageInfo;                                          // Image resource information
    writeSet.dstBinding = 0;                                                   // Binding point in shader

    device->updateDescriptorSets(1, &writeSet, 0, nullptr);                   // Execute the binding update

    // Create pipeline cache
    vk::PipelineCacheCreateInfo pipelineCacheInfo{};
    pipelineCache = device->createPipelineCache(pipelineCacheInfo);

    // Create pipeline layout
    vk::PushConstantRange pushConstantRange{};
    pushConstantRange.stageFlags = vk::ShaderStageFlagBits::eVertex;
    pushConstantRange.offset = 0;
    pushConstantRange.size = sizeof(PushConstBlock);

    vk::PipelineLayoutCreateInfo pipelineLayoutInfo{};
    pipelineLayoutInfo.setLayoutCount = 1;
    vk::DescriptorSetLayout setLayouts[] = {*descriptorSetLayout};
    pipelineLayoutInfo.pSetLayouts = setLayouts;
    pipelineLayoutInfo.pushConstantRangeCount = 1;
    pipelineLayoutInfo.pPushConstantRanges = &pushConstantRange;

    pipelineLayout = device->createPipelineLayout(pipelineLayoutInfo);

    // Create the graphics pipeline with dynamic rendering
    // ... (shader loading, pipeline state setup, etc.)

    // For brevity, we're omitting the full pipeline creation code here
    // In a real implementation, you would:
    // 1. Load the vertex and fragment shaders
    // 2. Set up all the pipeline state (vertex input, input assembly, rasterization, etc.)
    // 3. Include the renderingInfo in the pipeline creation to enable dynamic rendering
}

void ImGuiVulkanUtil::handleKey(int key, int scancode, int action, int mods) {
    ImGuiIO& io = ImGui::GetIO();

    // This example uses GLFW key codes and actions, but you can adapt this
    // to work with any windowing library's input system

    // Map the platform-specific key action to ImGui's key state
    // In GLFW: GLFW_PRESS = 1, GLFW_RELEASE = 0
    const int KEY_PRESSED = 1;  // Generic key pressed value
    const int KEY_RELEASED = 0; // Generic key released value

    if (action == KEY_PRESSED)
        io.KeysDown[key] = true;
    if (action == KEY_RELEASED)
        io.KeysDown[key] = false;

    // Update modifier keys
    // These key codes are GLFW-specific, but you would use your windowing library's
    // equivalent key codes for other libraries
    const int KEY_LEFT_CTRL = 341;   // GLFW_KEY_LEFT_CONTROL
    const int KEY_RIGHT_CTRL = 345;  // GLFW_KEY_RIGHT_CONTROL
    const int KEY_LEFT_SHIFT = 340;  // GLFW_KEY_LEFT_SHIFT
    const int KEY_RIGHT_SHIFT = 344; // GLFW_KEY_RIGHT_SHIFT
    const int KEY_LEFT_ALT = 342;    // GLFW_KEY_LEFT_ALT
    const int KEY_RIGHT_ALT = 346;   // GLFW_KEY_RIGHT_ALT
    const int KEY_LEFT_SUPER = 343;  // GLFW_KEY_LEFT_SUPER
    const int KEY_RIGHT_SUPER = 347; // GLFW_KEY_RIGHT_SUPER

    io.KeyCtrl = io.KeysDown[KEY_LEFT_CTRL] || io.KeysDown[KEY_RIGHT_CTRL];
    io.KeyShift = io.KeysDown[KEY_LEFT_SHIFT] || io.KeysDown[KEY_RIGHT_SHIFT];
    io.KeyAlt = io.KeysDown[KEY_LEFT_ALT] || io.KeysDown[KEY_RIGHT_ALT];
    io.KeySuper = io.KeysDown[KEY_LEFT_SUPER] || io.KeysDown[KEY_RIGHT_SUPER];
}

bool ImGuiVulkanUtil::getWantKeyCapture() {
    return ImGui::GetIO().WantCaptureKeyboard;
}

void ImGuiVulkanUtil::charPressed(uint32_t key) {
    ImGuiIO& io = ImGui::GetIO();
    io.AddInputCharacter(key);
}

// In your application class
ImGuiVulkanUtil imGui;

// During initialization
void initImGui() {
    // Initialize ImGui directly
    imGui = ImGuiVulkanUtil(
        device,
        physicalDevice,
        graphicsQueue,
        graphicsQueueFamily
    );

    imGui.init(swapChainExtent.width, swapChainExtent.height);
    imGui.initResources(); // No renderPass needed with dynamic rendering
}

// In your render loop
void drawFrame() {
    // ... existing frame preparation code ...

    // Update ImGui
    if (imGui.newFrame()) {
        imGui.updateBuffers();
    }

    // Begin command buffer recording
    // Note: With dynamic rendering, we don't need to begin a render pass
    // The ImGui drawFrame method will handle dynamic rendering internally

    // Render scene using dynamic rendering
    // ...

    // Render ImGui (in multi-frame renderers, pass the current frame index to bind per-frame buffers)
    imGui.drawFrame(commandBuffer);

    // ... submit command buffer ...
}

// Input handling
// This example shows how to handle input with GLFW, but you can adapt this
// to work with any windowing library's input system

// Example key callback function for GLFW
void keyCallback(GLFWwindow* window, int key, int scancode, int action, int mods) {
    // First check if ImGui wants to capture this input
    imGui.handleKey(key, scancode, action, mods);

    // If ImGui doesn't want to capture the keyboard, process for your application
    if (!imGui.getWantKeyCapture()) {
        // Process key for your application
    }
}

// Example character input callback for GLFW
void charCallback(GLFWwindow* window, unsigned int codepoint) {
    imGui.charPressed(codepoint);
}

// With other windowing libraries, you would implement similar callback functions
// using their equivalent APIs and event systems

// Cleanup
void cleanup() {
    // ... existing cleanup code ...

    // ImGui will be automatically cleaned up when the application exits
    // No manual cleanup needed
}

// In your ImGuiVulkanUtil::newFrame method
bool ImGuiVulkanUtil::newFrame() {
    ImGui::NewFrame();

    // Show the demo window
    ImGui::ShowDemoWindow();

    ImGui::EndFrame();
    ImGui::Render();

    // Check if buffers need updating
    // ...
}