VkExternalMemoryHelpers.hpp

Go to the documentation of this file.

#pragma once
 
#include <score/gfx/Vulkan.hpp>
 
#include <score_plugin_gfx_export.h>
 
#if QT_HAS_VULKAN
 
#include <vector>
 
#include <vulkan/vulkan.h>
 
#include <cstdint>
#include <optional>
 
class QVulkanInstance;
 
namespace score::gfx::vkinterop
{
 
struct ExternalHandle
{
#if defined(_WIN32)
  void* handle{nullptr}; // HANDLE
#else
  int fd{-1};
#endif
  VkExternalMemoryHandleTypeFlagBits type{};
 
  bool isValid() const noexcept
  {
#if defined(_WIN32)
    return handle != nullptr;
#else
    return fd >= 0;
#endif
  }
 
  // OS handle encoded as a void* for the CUDA interop layer / DVP, which expect
  // the Win32 HANDLE directly or the fd cast to pointer width (see
  // CudaInterop.cpp's CUDA_EXTERNAL_MEMORY_HANDLE_DESC fill-in).
  void* osHandle() const noexcept
  {
#if defined(_WIN32)
    return handle;
#else
    return reinterpret_cast<void*>(static_cast<intptr_t>(fd));
#endif
  }
};
 
// Platform-preferred opaque external-memory handle type: OPAQUE_WIN32 on
// Windows, OPAQUE_FD on Linux. Use this instead of hardcoding OPAQUE_FD so
// the same export/import code compiles and runs on both platforms.
inline constexpr VkExternalMemoryHandleTypeFlagBits kOpaqueHandleType =
#if defined(_WIN32)
    VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_BIT;
#else
    VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_FD_BIT;
#endif
 
struct ExternalImageDesc
{
  VkFormat format{};
  VkExtent3D extent{1, 1, 1};
  VkImageUsageFlags usage{};
  VkImageTiling tiling{VK_IMAGE_TILING_OPTIMAL};
  VkExternalMemoryHandleTypeFlagBits handleType{};
  // dedicated=true: required for D3D11_TEXTURE_KMT (Spout); harmless for OPAQUE_*.
  bool dedicated{true};
  bool preferDeviceLocal{true};
 
  const uint64_t* drmModifiers{};
  uint32_t drmModifierCount{};
};
 
struct ExternalBufferDesc
{
  VkDeviceSize size{};
  VkBufferUsageFlags usage{};
  VkExternalMemoryHandleTypeFlagBits handleType{};
  bool dedicated{true};
};
 
struct VulkanCtx
{
  VkInstance instance{VK_NULL_HANDLE};
  VkPhysicalDevice physDev{VK_NULL_HANDLE};
  VkDevice dev{VK_NULL_HANDLE};
  QVulkanInstance* qInst{}; // for getInstanceProcAddr (PFN resolution)
};
 
SCORE_PLUGIN_GFX_EXPORT void setDeviceTimelineSemaphoresEnabled(bool enabled);
SCORE_PLUGIN_GFX_EXPORT bool deviceTimelineSemaphoresEnabled();
 
struct ExternalImage
{
  VkImage image{VK_NULL_HANDLE};
  VkDeviceMemory memory{VK_NULL_HANDLE};
  VkDeviceSize size{0};
  uint64_t drmModifier{(1ull << 56) - 1};
};
 
struct ExternalBuffer
{
  VkBuffer buffer{VK_NULL_HANDLE};
  VkDeviceMemory memory{VK_NULL_HANDLE};
  VkDeviceSize size{0};
};
 
// =============================================================================
// RDMA (VK_NV_external_memory_rdma) — GPU VRAM a third-party DMA engine
// (capture card with GPUDirect RDMA) can target via a remote address. Used by
// the RdmaGpuBuffer allocator. All functions return empty/nullopt when
// the extension is unavailable in the headers or at runtime (safe fallback).
// =============================================================================
 
struct RdmaBuffer
{
  VkBuffer buffer{VK_NULL_HANDLE};
  VkDeviceMemory memory{VK_NULL_HANDLE};
  VkDeviceSize size{0};
  std::uint64_t remoteAddress{0}; 
};
 
SCORE_PLUGIN_GFX_EXPORT std::optional<RdmaBuffer>
createRdmaBuffer(const VulkanCtx&, VkDeviceSize size);
 
SCORE_PLUGIN_GFX_EXPORT std::optional<std::uint64_t>
getMemoryRemoteAddress(const VulkanCtx&, VkDeviceMemory);
 
SCORE_PLUGIN_GFX_EXPORT void destroyRdma(const VulkanCtx&, RdmaBuffer&);
 
// =============================================================================
// EXPORT — score allocates the resource, hands the handle to a peer.
// =============================================================================
 
SCORE_PLUGIN_GFX_EXPORT std::optional<ExternalImage>
createExportableImage(const VulkanCtx&, const ExternalImageDesc&);
 
SCORE_PLUGIN_GFX_EXPORT std::optional<ExternalBuffer>
createExportableBuffer(const VulkanCtx&, const ExternalBufferDesc&);
 
SCORE_PLUGIN_GFX_EXPORT std::optional<ExternalHandle> exportMemoryHandle(
    const VulkanCtx&, VkDeviceMemory, VkExternalMemoryHandleTypeFlagBits);
 
// =============================================================================
// IMPORT — score consumes a handle produced by a peer (Spout, CUDA, etc).
// =============================================================================
 
SCORE_PLUGIN_GFX_EXPORT std::optional<ExternalImage> importExternalImage(
    const VulkanCtx&, const ExternalImageDesc&, const ExternalHandle&);
 
SCORE_PLUGIN_GFX_EXPORT std::optional<ExternalBuffer> importExternalBuffer(
    const VulkanCtx&, const ExternalBufferDesc&, const ExternalHandle&);
 
// =============================================================================
// Cleanup — symmetric helpers. Out-of-line because they dispatch through
// QVulkanInstance::deviceFunctions(), which would otherwise drag
// <QVulkanDeviceFunctions> into every consumer of this header.
// =============================================================================
 
SCORE_PLUGIN_GFX_EXPORT void destroyExternal(const VulkanCtx& v, ExternalImage& img);
SCORE_PLUGIN_GFX_EXPORT void destroyExternal(const VulkanCtx& v, ExternalBuffer& buf);
 
// =============================================================================
// Layout transition — one-time image layout change via a transient command
// buffer (create pool + buffer, record a VkImageMemoryBarrier, submit, wait
// idle). Used by the RDMA capture/output paths to move a freshly-created
// exportable VkImage UNDEFINED -> GENERAL once, so the QRhi-adopted texture
// (told GENERAL via createFrom) and CUDA (which reads/writes the memory) agree.
//
// Broad, conservative access/stage masks cover both the capture (shader-read)
// and output (transfer-write) uses; the following vkQueueWaitIdle makes the
// choice of masks immaterial to correctness for a one-time init transition.
// @p queue / @p queueFamily are the graphics queue + family the barrier submits
// on (from QRhiVulkanNativeHandles). Returns false on any Vulkan failure.
// =============================================================================
SCORE_PLUGIN_GFX_EXPORT bool transitionImageLayout(
    const VulkanCtx& v, VkQueue queue, std::uint32_t queueFamily, VkImage image,
    VkImageLayout oldLayout, VkImageLayout newLayout);
 
// =============================================================================
// DMA-BUF modifier capability probes
// =============================================================================
 
bool can_import_dmabuf_modifier(
    const VulkanCtx& v, VkFormat format, std::uint64_t drm_modifier,
    std::uint32_t width, std::uint32_t height) noexcept;
 
std::vector<std::uint64_t> supported_dmabuf_modifiers(
    const VulkanCtx& v, VkFormat format) noexcept;
 
} // namespace score::gfx::vkinterop
 
#endif // QT_HAS_VULKAN