KDGpu API Overview¶

Introduction¶

KDGpu is a modern, type-safe C++ wrapper around the Vulkan graphics API. It provides a simplified, high-level interface while maintaining complete control over the underlying Vulkan resources. KDGpu's design philosophy focuses on:

Type Safety: Strong typing through handles and enums
Resource Management: Handle-based ownership model with automatic resource cleanup
Simplicity: Reduced boilerplate compared to raw Vulkan
Performance: Zero-cost abstractions over Vulkan
Familiarity: API structure closely mirrors Vulkan concepts

API Architecture¶

The KDGpu API is organized into several logical groups:

Core Instance & Device Management¶

Instance - Application-wide Vulkan instance (VkInstance)
Adapter - Physical GPU device (VkPhysicalDevice)
Device - Logical device for GPU operations (VkDevice)
Queue - Command submission queue (VkQueue)
Surface - Window surface for presenting (VkSurfaceKHR)

GPU Resources¶

Buffer - GPU memory buffer (VkBuffer)
Texture - Image/texture resource (VkImage)
TextureView - View into a texture (VkImageView)
Sampler - Texture sampling configuration (VkSampler)

Pipelines & Shaders¶

GraphicsPipeline - Graphics rendering pipeline (VkPipeline)
ComputePipeline - Compute shader pipeline (VkPipeline)
RayTracingPipeline - Ray tracing pipeline (VkPipeline)
ShaderModule - SPIR-V shader module (VkShaderModule)
PipelineLayout - Pipeline resource layout (VkPipelineLayout)
PipelineCache - Pipeline creation cache (VkPipelineCache)
RenderPass - Render pass configuration (VkRenderPass)

Descriptors & Bindings¶

BindGroup - Resource descriptor set (VkDescriptorSet)
BindGroupLayout - Descriptor set layout (VkDescriptorSetLayout)
BindGroupPool - Descriptor set pool (VkDescriptorPool)

Command Recording¶

CommandBuffer - Recorded GPU commands (VkCommandBuffer)
CommandRecorder - Records GPU commands (VkCommandBuffer)
RenderPassCommandRecorder - Records rendering commands
ComputePassCommandRecorder - Records compute commands
RayTracingPassCommandRecorder - Records ray tracing commands

Synchronization¶

Fence - CPU-GPU synchronization (VkFence)
GpuSemaphore - GPU-GPU synchronization (VkSemaphore)
TimelineSemaphore - GPU-GPU and CPU-GPU synchronization (VkSemaphore)

Presentation¶

Swapchain - Image presentation chain (VkSwapchainKHR)

Ray Tracing (Extensions)¶

AccelerationStructure - Ray tracing acceleration structure (VkAccelerationStructureKHR)
RayTracingShaderBindingTable - Ray tracing shader binding table

Query Operations¶

TimestampQueryRecorder - GPU timestamp queries (VkQueryPool)

Resource Ownership Model¶

KDGpu uses a handle-based resource management system. See KDGpu Handle-Based Ownership Model for details.

Key principles:

Frontend KDGpu resources (e.g. Texture, Buffer) are wrappers around Vulkan resources
Frontend KDGpu resources use handles to safely reference underlying Vulkan wrapped resources
Resources lifetime is RAII-based, automatically cleaned up when owning objects are destroyed
Move semantics: Resources can be moved but not copied
Reference invalidation: Handles become invalid when resources are destroyed

Basic Initialization Flow¶

Here's a minimal example showing how to initialize KDGpu for rendering:

    // Typical initialization flow:
    KDGpu::VulkanGraphicsApi vulkanGraphisApi;
    KDGpu::Instance instance = vulkanGraphisApi.createInstance(KDGpu::InstanceOptions{ /* ... */ });
    KDGpu::Adapter *adapter = instance.selectAdapter(KDGpu::AdapterDeviceType::Default); // Select GPU
    KDGpu::Device device = adapter->createDevice(KDGpu::DeviceOptions{
            .requestedFeatures = adapter->features(),
    });
    // Device ready to create resources and submit work
    KDGpu::Buffer buffer = device.createBuffer(KDGpu::BufferOptions{
            .usage = KDGpu::BufferUsageFlagBits::UniformBufferBit,
            .memoryUsage = KDGpu::MemoryUsage::GpuOnly,
    });

Filename: kdgpu_doc_snippets.cpp

Typical Usage Pattern¶

    // KDGpu API consists of:
    // 1. Instance - entry point, enumerates adapters
    // 2. Adapter - represents physical GPU
    // 3. Device - logical GPU handle, creates resources
    // 4. Resources - buffers, textures, pipelines, etc.
    // 5. Command recording - record GPU work
    // 6. Synchronization - fences, semaphores for CPU-GPU and GPU-GPU sync