KDGpu::Instance¶

Module: Public API

Instance is used to initialize the Rendering API. More...

#include <KDGpu/instance.h>

Public Functions¶

	Name
	Instance() Default constructor creates an invalid instance.
	~Instance() Destructor destroys the Vulkan instance and all owned adapters.
	Instance(Instance && other) Move constructor transfers ownership of the Vulkan instance.
Instance &	operator=(Instance && other) Move assignment transfers ownership of the Vulkan instance.
	Instance(const Instance & ) =delete Copy constructor deleted - instances cannot be copied.
Instance &	operator=(const Instance & ) =delete Copy assignment deleted - instances cannot be copied.
Handle< Instance_t >	handle() const Returns the internal handle to the Vulkan instance.
bool	isValid() const Checks if this instance is valid and ready for use.
	operator Handle< Instance_t >() const Implicit conversion to handle for passing to low-level APIs.
std::vector< Extension >	extensions() const Queries all instance extensions available in Vulkan.
AdapterAndDevice	createDefaultDevice(const Surface & surface, AdapterDeviceType deviceType =AdapterDeviceType::Default) const Creates a device using the best suitable adapter for the given surface.
std::vector< Adapter * >	adapters() const Returns all available physical devices (GPUs)
const std::vector< AdapterGroup > &	adapterGroups() const Returns logical groups of adapters (for multi-GPU setups)
Adapter *	selectAdapter(AdapterDeviceType deviceType) const Selects an adapter matching the requested device type.
Surface	createSurface(const SurfaceOptions & options) Creates a window surface for presentation.

Friends¶

	Name
class	VulkanGraphicsApi

Detailed Description¶

class KDGpu::Instance;

Instance is used to initialize the Rendering API.

See:

Represents a Vulkan instance - the root object for KDGpu applications.

using namespace KDGpu;

std::unique_ptr<GraphicsApi> api = std::make_unique<VulkanGraphicsApi>();

Instance instance = api->createInstance(InstanceOptions{
        .applicationName = "MyApplication",
        .applicationVersion = 0,
});

Vulkan equivalent:VkInstance

The Instance is the first KDGpu object you create. It initializes the Vulkan library, enumerates available physical devices (adapters), and manages instance-level resources like validation layers and extensions.

Key responsibilities:

Initialize Vulkan runtime
Enumerate physical devices (adapters)
Create window surfaces for rendering
Manage instance-level extensions (e.g., VK_KHR_surface, debug utils)
Provide access to validation layers

Lifetime: The Instance should live for the entire application runtime. All adapters and surfaces are owned by the Instance and become invalid when it's destroyed.

¶

Usage¶

Typical initialization flow:

    // Note: Instance creation requires a GraphicsApi (VulkanGraphicsApi)
    std::unique_ptr<KDGpu::GraphicsApi> api = std::make_unique<KDGpu::VulkanGraphicsApi>();

    KDGpu::Instance instance = api->createInstance(KDGpu::InstanceOptions{
            .applicationName = "MyApplication",
            .applicationVersion = KDGPU_MAKE_API_VERSION(0, 1, 0, 0),
    });

Filename: kdgpu_doc_snippets.cpp

Advanced adapter selection:

    std::vector<KDGpu::Adapter *> adapters = instance.adapters();
    // Iterate over adapters, use properties to gather information about each adapter
    for (auto *adapter : adapters) {
        std::cout << "Found GPU: " << adapter->properties().deviceName
                  << KDGpu::adapterDeviceTypeToString(adapter->properties().deviceType)
                  << std::endl;
    }

Filename: kdgpu_doc_snippets.cpp

Registering layers or instance extensions:

    // Extensions are configured through InstanceOptions
    KDGpu::Instance instanceWithExtensions = api->createInstance(KDGpu::InstanceOptions{
            .layers = { "VK_LAYER_KHRONOS_validation" },
            .extensions = { VK_KHR_SURFACE_EXTENSION_NAME },
    });

    for (const KDGpu::Extension &ext : instanceWithExtensions.extensions()) {
        if (ext.name == VK_KHR_SURFACE_EXTENSION_NAME) {
            /* ... */
            break;
        }
    }

Filename: kdgpu_doc_snippets.cpp

KDGpu will try to request some extensions by default KDGpu::getDefaultRequestedInstanceExtensions

¶

Vulkan mapping:¶

Instance::Instance() → vkCreateInstance()
Instance::adapters() → vkEnumeratePhysicalDevices()
Instance::createSurface() → Platform-specific (e.g., vkCreateXcbSurfaceKHR())
Instance::~Instance() → vkDestroyInstance()

¶

Public Functions Documentation¶

function Instance¶

1	`Instance()`

Default constructor creates an invalid instance.

function ~Instance¶

~Instance()

Destructor destroys the Vulkan instance and all owned adapters.

function Instance¶

Instance(
    Instance && other
)

Move constructor transfers ownership of the Vulkan instance.

function operator=¶

Instance & operator=(
    Instance && other
)

Move assignment transfers ownership of the Vulkan instance.

function Instance¶

Instance(
    const Instance & 
) =delete

Copy constructor deleted - instances cannot be copied.

function operator=¶

Instance & operator=(
    const Instance & 
) =delete

Copy assignment deleted - instances cannot be copied.

function handle¶

inline Handle< Instance_t > handle() const

Returns the internal handle to the Vulkan instance.

See: Handle, isValid()

Return: Handle to the underlying VkInstance

function isValid¶

inline bool isValid() const

Checks if this instance is valid and ready for use.

Return: true if the instance was successfully created, false otherwise

An instance is invalid if:

It was default-constructed
It was moved from
Creation failed

function operator Handle< Instance_t >¶

inline operator Handle< Instance_t >() const

Implicit conversion to handle for passing to low-level APIs.

function extensions¶

std::vector< Extension > extensions() const

Queries all instance extensions available in Vulkan.

Return: Vector of available extensions with name and version

Returns the extensions requested for the instance.

Query this after creating the instance to check which extensions are supported:

    // Extensions are configured through InstanceOptions
    KDGpu::Instance instanceWithExtensions = api->createInstance(KDGpu::InstanceOptions{
            .layers = { "VK_LAYER_KHRONOS_validation" },
            .extensions = { VK_KHR_SURFACE_EXTENSION_NAME },
    });

    for (const KDGpu::Extension &ext : instanceWithExtensions.extensions()) {
        if (ext.name == VK_KHR_SURFACE_EXTENSION_NAME) {
            /* ... */
            break;
        }
    }

Filename: kdgpu_doc_snippets.cpp

Vulkan equivalent: vkEnumerateInstanceExtensionProperties()

function createDefaultDevice¶

AdapterAndDevice createDefaultDevice(
    const Surface & surface,
    AdapterDeviceType deviceType =AdapterDeviceType::Default
) const

Creates a device using the best suitable adapter for the given surface.

Parameters:

surface Window surface for presentation (must be created first)
deviceType Type of device to prefer (Default, Discrete, Integrated, CPU)

See: adapters(), selectAdapter(), Adapter::createDevice()

Return: Structure containing the selected adapter and created device

Convenience function used to create a Device instance that supports presentation against Surfacesurface.

This is a convenience function that:

Selects an appropriate adapter based on deviceType
Creates a device with defaults suitable for rendering to the surface
Returns both for your use

Example:

    // Platform-specific (example for XCB on Linux)
    // xcb_connection_t *connection = /* ... */;
    // xcb_window_t window = /* ... */;
    KDGpu::Surface surface = instance.createSurface(KDGpu::SurfaceOptions{
            /* Set underlying window handle based on platform */
    });

Filename: kdgpu_doc_snippets.cpp

Vulkan mapping:

Calls vkEnumeratePhysicalDevices() to find adapters
Selects best match based on deviceType
Calls vkCreateDevice() with appropriate queue families

function adapters¶

std::vector< Adapter * > adapters() const

Returns all available physical devices (GPUs)

See: Adapter, Adapter::properties(), selectAdapter()

Return: Vector of pointers to adapters (owned by this instance)

Returns a vector of the Adapter instances available for the instance.

Each adapter represents a physical GPU in the system. You can query properties and create devices from adapters:

    // API version is configured through InstanceOptions
    KDGpu::Instance instanceWithApiVersion = api->createInstance(KDGpu::InstanceOptions{
            .apiVersion = KDGPU_MAKE_API_VERSION(0, 1, 2, 0),
    });

Filename: kdgpu_doc_snippets.cpp

Vulkan equivalent: vkEnumeratePhysicalDevices()

function adapterGroups¶

const std::vector< AdapterGroup > & adapterGroups() const

Returns logical groups of adapters (for multi-GPU setups)

See: AdapterGroup

Return: Vector of adapter groups

Returns a vector of the AdapterGroups available for the instance. AdapterGroup allow to spread operations across multiple adapters;.

Adapter groups represent sets of GPUs that can work together (e.g., SLI/CrossFire). Most systems have one group per GPU.

function selectAdapter¶

Adapter * selectAdapter(
    AdapterDeviceType deviceType
) const

Selects an adapter matching the requested device type.

Parameters:

deviceType Type of device to select (Discrete, Integrated, CPU, etc.)

See: AdapterDeviceType, adapters()

Return: Pointer to selected adapter, or nullptr if no match found

Convenience function to easily select an Adapter instance.

Preference order when deviceType is Default:

Discrete GPU
Integrated GPU
Virtual GPU
CPU

function createSurface¶

Surface createSurface(
    const SurfaceOptions & options
)

Creates a window surface for presentation.

Parameters:

options Platform-specific surface creation options

See: Surface, SurfaceOptions

Return: Surface object for rendering and presentation

Create a Surface instance based on the provided options.

The surface represents the window where rendering will be displayed. Surface creation is platform-dependent (Windows, X11, Wayland, Android, etc.).

Vulkan mapping: Platform-specific:

Windows: vkCreateWin32SurfaceKHR()
X11: vkCreateXcbSurfaceKHR() or vkCreateXlibSurfaceKHR()
Wayland: vkCreateWaylandSurfaceKHR()
Android: vkCreateAndroidSurfaceKHR()

Friends¶

friend VulkanGraphicsApi¶

friend class VulkanGraphicsApi(
    VulkanGraphicsApi 
);

Updated on 2026-03-31 at 00:02:07 +0000

KDGpu::Instance¶

Public Functions¶

Friends¶

Detailed Description¶

¶

Usage¶

¶

Vulkan mapping:¶

¶

See also¶

Public Functions Documentation¶

function Instance¶

function ~Instance¶

function Instance¶

function operator=¶

function Instance¶

function operator=¶

function handle¶

function isValid¶

function operator Handle< Instance_t >¶

function extensions¶

function createDefaultDevice¶

function adapters¶

function adapterGroups¶

function selectAdapter¶

function createSurface¶

Friends¶

friend VulkanGraphicsApi¶