KDGpuExample Helper API¶

Most examples in this collection use the KDGpuExample helper API to reduce boilerplate code and focus on demonstrating specific Vulkan features and rendering techniques. This page explains what the helper API provides and how it simplifies example development.

What is KDGpuExample?¶

The KDGpuExample helper API is an abstraction layer that handles common initialization and management tasks that would otherwise need to be repeated in every example:

Instance and Device Creation: Automatically creates a Vulkan instance with appropriate extensions and selects a suitable physical device
Surface and Swapchain Management: Creates the window surface and manages the swapchain, including recreation on window resize
Command Buffer Management: Provides command buffers for recording rendering commands
Frame Synchronization: Handles frame pacing and synchronization primitives (semaphores, fences) for multi-buffered rendering
Window and Event Loop: Creates and manages the application window and processes input events
ImGui Integration: Provides optional UI overlay support for debugging and visualization

Helper API vs Native API¶

To understand the difference between using the helper API and raw KDGpu, compare these two examples:

Hello Triangle - Uses KDGpuExample helper API (~100 lines of example-specific code)
Hello Triangle Native API - Uses raw KDGpu API (~300+ lines including all initialization)

The hello_triangle_native example shows everything that KDGpuExample handles for you: instance creation with validation layers, physical device selection, logical device creation, surface setup, swapchain management with recreation logic, command pool management, and frame synchronization with multiple in-flight frames.

Using KDGpuExample¶

To use the helper API in your example, inherit from [KDGpuExample::SimpleExampleEngineLayer](classKDGpuExample_1_1SimpleExampleEngineLayer.md) or [KDGpuExample::ExampleEngineLayer](classKDGpuExample_1_1ExampleEngineLayer.md) and implement the required virtual methods:

class MyExample : public KDGpuExample::SimpleExampleEngineLayer
{
public:
    MyExample()
        : KDGpuExample::SimpleExampleEngineLayer()
    {
    }

protected:
    void initializeScene() override
    {
        // Create buffers, pipelines, textures, etc.
        // The device, queue, and swapchain are already initialized
    }

    void cleanupScene() override
    {
        // Clean up resources created in initializeScene()
    }

    void updateScene() override
    {
        // Per-frame logic: update uniforms, physics, etc.
    }

    void render() override
    {
        // Record and submit rendering commands
        auto commandRecorder = m_device.createCommandRecorder();
        auto renderPass = commandRecorder.beginRenderPass(/* ... */);
        // ... rendering commands ...
    }
};

What the Helper Provides¶

When your example runs, the helper API provides these pre-initialized members:

m_device - KDGpu::Device ready for creating resources
m_queue - KDGpu::Queue for submitting commands
m_swapchainViews - Array of image views for the swapchain images
m_depthTextureView - Depth buffer (if depth testing is enabled)
m_commandBuffer - Current frame's command buffer
m_window - Application window

Helper utility methods:

uploadBufferData() - Uploads data to GPU buffers using staging buffers
uploadTextureData() - Uploads texture data to GPU images
renderImGuiOverlay() - Renders the ImGui UI overlay
currentSwapchainIndex() - Returns the current swapchain image index

When to Use the Helper API¶

Use the helper API when:

You want to focus on demonstrating a specific Vulkan feature or technique
Your example doesn't require custom instance extensions or device features beyond the defaults
You're creating a learning example that should be easy to understand
You want to minimize boilerplate code

Use the native API when:

You need full control over instance/device creation (custom extensions, validation layers)
You're demonstrating low-level Vulkan concepts like synchronization or swapchain management
Your example requires platform-specific initialization (see Hello Triangle (Native Apple))
You're building production code or a framework rather than a learning example

Customization¶

While the helper API uses sensible defaults, you can customize behavior by:

Overriding createEngineOptions() to specify custom device features, extensions, or window properties
Accessing the underlying KDGpu objects directly for advanced use cases
Implementing custom frame synchronization if the default triple-buffering doesn't fit your needs