GaussianSplatVulkanContext.h

Go to the documentation of this file.

// ----------------------------------------------------------------------------
// -                        Open3D: www.open3d.org                            -
// ----------------------------------------------------------------------------
// Copyright (c) 2018-2026 www.open3d.org
// SPDX-License-Identifier: MIT
// ----------------------------------------------------------------------------
//
// Headless Vulkan context for Gaussian splatting compute (Linux/Windows).
//
// Owns the VkInstance, VkPhysicalDevice, VkDevice and compute queue used both
// by the GS compute pipeline and by Filament's Vulkan backend. The same
// VkDevice is shared with Filament via VulkanPlatform::VulkanSharedContext
// (passed as Engine::create()'s sharedContext argument). This eliminates the
// old GL-Vulkan interop path entirely: GS output images are plain VkImages
// imported into Filament through VulkanDriver::importTextureR().
//
// Key relationships:
//   - FilamentEngine.cpp calls Initialize() before Engine::create() and
//     Shutdown() after Engine::destroy() so the shared device outlives
//     Filament.
//   - GaussianSplatVulkanBackend uses GetDevice() / GetComputeQueue() for
//     compute dispatch and creates plain VkImages for depth/colour sharing.
//   - GetVulkanSharedContext() returns a VulkanSharedContext struct for
//     Engine::create(). The struct must stay alive for the engine's lifetime.
//
// Uses vulkan-hpp (Vulkan-Headers) for Vulkan loading and RAII handle
// lifetime management, and VMA (vk_mem_alloc.h from the pinned 3rdparty
// download) for suballocated internal-only buffer allocations.
//
// Thread-safety: not thread-safe. All calls must be made from the render
// thread.
 
#pragma once
 
#if !defined(__APPLE__)
 
#include <cstddef>
#include <cstdint>
#include <string>
 
// Suppress C function-prototype declarations in vulkan.h: all Vulkan entry
// points are resolved at runtime through vulkan-hpp's per-object RAII
// dispatchers (ContextDispatcher / InstanceDispatcher / DeviceDispatcher),
// not as statically-linked symbols.
//
// NOTE: BlueVK (used by Filament) also defines VK_NO_PROTOTYPES before
// including vulkan.h, so the two includes are mutually compatible when
// this header is included after Filament headers.
#ifndef VK_NO_PROTOTYPES
#define VK_NO_PROTOTYPES
#endif
#include <vulkan/vulkan_raii.hpp>
 
namespace open3d {
namespace visualization {
namespace rendering {
 
struct FilamentVulkanSharedContext {
    VkInstance instance = VK_NULL_HANDLE;
    VkPhysicalDevice physical_device = VK_NULL_HANDLE;
    VkDevice logical_device = VK_NULL_HANDLE;
    std::uint32_t graphics_queue_family_index = 0xFFFFFFFFu;
    std::uint32_t graphics_queue_index = 0xFFFFFFFFu;
    bool debug_utils_enabled = false;
    bool debug_markers_supported = false;
    bool multiview_supported = false;
};
 
struct VkImageDesc {
    VkImage vk_image = VK_NULL_HANDLE;
    VkDeviceMemory vk_memory = VK_NULL_HANDLE;
 
    bool IsValid() const { return vk_image != VK_NULL_HANDLE; }
};
 
// ---------------------------------------------------------------------------
// GaussianSplatVulkanContext — headless Vulkan context
// ---------------------------------------------------------------------------
 
class GaussianSplatVulkanContext {
public:
    static GaussianSplatVulkanContext& GetInstance();
 
    bool Initialize();
 
    void Shutdown();
 
    bool IsValid() const { return initialized_; }
 
    bool IsSoftwareDevice() const;
 
    const std::string& GetLastError() const { return last_error_; }
 
    // --- Filament integration ---------------------------------------------
 
    void* GetVulkanSharedContext() { return &shared_context_; }
 
    // --- Device accessors (used by VulkanBackend and ComputeGPUVulkan) -----
 
    VkInstance GetVkInstance() const {
        return static_cast<vk::Instance::CType>(*instance_);
    }
    VkDevice GetDevice() const {
        return static_cast<vk::Device::CType>(*device_);
    }
    VkPhysicalDevice GetPhysicalDevice() const {
        return static_cast<vk::PhysicalDevice::CType>(*physical_device_);
    }
    VkQueue GetComputeQueue() const {
        return static_cast<vk::Queue::CType>(*compute_queue_);
    }
    std::uint32_t GetComputeQueueFamily() const {
        return graphics_queue_family_;
    }
    bool GetDebugUtilsEnabled() const { return debug_utils_enabled_; }
 
    // RAII accessor used by ComputeGPUVulkan to create sub-objects.
    const vk::raii::Device& GetRaiiDevice() const { return device_; }
 
    // --- Image lifecycle --------------------------------------------------
 
    VkImageDesc CreateImage(std::uint32_t width,
                            std::uint32_t height,
                            VkFormat vk_format,
                            VkImageUsageFlags usage,
                            const char* label = nullptr);
 
    bool SupportsOptimalStorageImage(VkFormat vk_format) const;
 
    void DestroyImage(VkImageDesc& desc);
 
    // --- Vulkan device memory type helpers --------------------------------
 
    std::uint32_t FindMemoryType(std::uint32_t type_filter,
                                 VkMemoryPropertyFlags props) const;
 
private:
    GaussianSplatVulkanContext() = default;
    ~GaussianSplatVulkanContext();
 
    GaussianSplatVulkanContext(const GaussianSplatVulkanContext&) = delete;
    GaussianSplatVulkanContext& operator=(const GaussianSplatVulkanContext&) =
            delete;
 
    // --- State ------------------------------------------------------------
    bool initialized_ = false;
    bool debug_utils_enabled_ = false;
    std::string last_error_;
 
    // Queue indices within the graphics queue family; index 0 = GS compute.
    std::uint32_t graphics_queue_family_ = UINT32_MAX;
    std::uint32_t filament_queue_index_ = 1;
 
    // Shared-context record held alive for Filament's lifetime.
    FilamentVulkanSharedContext shared_context_{};
 
    // RAII handles. Destruction order is reverse of declaration order:
    // compute_queue_ → device_ → physical_device_ → instance_ → context_.
    vk::raii::Context context_;
    vk::raii::Instance instance_{nullptr};
    vk::raii::PhysicalDevice physical_device_{nullptr};
    vk::raii::Device device_{nullptr};
    vk::raii::Queue compute_queue_{nullptr};
 
    VkPhysicalDeviceMemoryProperties memory_props_{};
};
 
}  // namespace rendering
}  // namespace visualization
}  // namespace open3d
 
#endif  // !defined(__APPLE__)