KDGpu::Adapter

Module: Public API

Adapter is a representation of a physical hardware device. More...

#include <KDGpu/adapter.h>

Public Functions

	Name
	Adapter() =default Default constructor creates an invalid adapter.
	~Adapter() Destructor - note that adapter is owned by Instance, not destroyed here.
	Adapter(Adapter && other) Move constructor transfers ownership of the adapter handle.
Adapter &	operator=(Adapter && other) Move assignment transfers ownership of the adapter handle.
	Adapter(const Adapter & ) =delete Copy constructor deleted - adapters cannot be copied.
Adapter &	operator=(const Adapter & ) =delete Copy assignment deleted - adapters cannot be copied.
Handle< Adapter_t >	handle() const Returns the internal handle to the Vulkan physical device.
bool	isValid() const Checks if this adapter is valid.
	operator Handle< Adapter_t >() const Implicit conversion to handle for passing to low-level APIs.
std::vector< Extension >	extensions() const Queries all device extensions available on this adapter.
const AdapterProperties &	properties() const Returns GPU properties (name, type, version, limits, etc.)
const AdapterFeatures &	features() const Returns GPU feature support (shaders, ray tracing, etc.)
std::span< AdapterQueueType >	queueTypes() const Returns available queue families on this GPU.
AdapterSwapchainProperties	swapchainProperties(const Handle< Surface_t > & surface) const Queries swapchain capabilities for a given surface.
bool	supportsPresentation(const Handle< Surface_t > & surface, uint32_t queueTypeIndex) const Checks if a queue family supports presenting to a surface.
FormatProperties	formatProperties(Format format) const Queries format properties for a specific texture/image format.
bool	supportsBlitting(Format srcFormat, TextureTiling srcTiling, Format dstFormat, TextureTiling dstTiling) const Checks if blitting (texture copying with scaling) is supported between two formats.
bool	supportsBlitting(Format format, TextureTiling tiling) const Checks if a format supports blitting (shorthand for same src/dst format)
std::vector< DrmFormatModifierProperties >	drmFormatModifierProperties(Format format) const Queries DRM format modifier properties (Linux-specific multi-plane formats)
Device	createDevice(const DeviceOptions & options =DeviceOptions()) Creates a logical device from this adapter.

Protected Functions

	Name
	Adapter(GraphicsApi * api, const Handle< Adapter_t > & adapter)

Protected Attributes

	Name
GraphicsApi *	m_api
Handle< Adapter_t >	m_adapter
AdapterProperties	m_properties
AdapterFeatures	m_features
std::vector< AdapterQueueType >	m_queueTypes

Friends

	Name
class	Instance
class	VulkanGraphicsApi

Detailed Description

class KDGpu::Adapter;

Adapter is a representation of a physical hardware device.

See:

• KDGpu::Instance::createDefaultDevice
• KDGpu::Instance::adapters
• KDGpu::Instance::selectAdapter
• KDGpu::Device
• Instance, Instance::adapters(), Instance::selectAdapter(), Device
• AdapterProperties, AdapterFeatures, AdapterQueueType
• KDGpu API Overview
• KDGpu to Vulkan API Mapping

Represents a physical GPU device available in the system.

Adapter instances are provided by the Instance. The Adapter is used to query what the underlying physical hardware supports. In turn, a logical Device can be created from the Adapter.

using namespace KDGpu;

Adapter *selectedAdapter = instance.selectAdapter(AdapterDeviceType::Default);
if (!selectedAdapter)
    return;

auto queueTypes = selectedAdapter->queueTypes();
const bool hasGraphicsAndCompute = queueTypes[0].supportsFeature(QueueFlags(QueueFlagBits::GraphicsBit) | QueueFlags(QueueFlagBits::ComputeBit));
const bool supportsPresentation = selectedAdapter->supportsPresentation(surface, 0);

if (!supportsPresentation || !hasGraphicsAndCompute)
    return;
...

Vulkan equivalent:VkPhysicalDevice

An Adapter represents a physical GPU (graphics card) in the system. It provides information about the GPU's capabilities, features, and supported formats, and is used to create a logical Device for rendering.

Key responsibilities:

• Query GPU properties (name, type, version, limits)
• Query supported features (geometry shaders, ray tracing, etc.)
• Query format support (color formats, depth formats, compression)
• Query queue families (graphics, compute, transfer capabilities)
• Create logical devices for rendering

Lifetime: Adapters are owned by the Instance and remain valid for its lifetime. Do not store Adapter pointers beyond the Instance's scope.

Enumerating adapters:

    std::vector<KDGpu::Adapter *> adapters = instance.adapters();
    for (KDGpu::Adapter *adapter : adapters) {
        KDGpu::AdapterProperties props = adapter->properties();
        std::cout << "GPU: " << props.deviceName << std::endl;
    }

Filename: kdgpu_doc_snippets.cpp

Querying adapter properties:

    KDGpu::AdapterProperties props = adapter->properties();
    std::cout << "Device: " << props.deviceName << std::endl;
    std::cout << "Vendor ID: 0x" << std::hex << props.vendorID << std::endl;
    std::cout << "Device ID: 0x" << std::hex << props.deviceID << std::endl;
    std::cout << "Driver version: " << props.driverVersion << std::endl;

    switch (props.deviceType) {
    case KDGpu::AdapterDeviceType::DiscreteGpu:
        std::cout << "Type: Discrete GPU" << std::endl;
        break;
    case KDGpu::AdapterDeviceType::IntegratedGpu:
        std::cout << "Type: Integrated GPU" << std::endl;
        break;
    case KDGpu::AdapterDeviceType::Cpu:
        std::cout << "Type: CPU/Software" << std::endl;
        break;
    default:
        break;
    }

Filename: kdgpu_doc_snippets.cpp

Checking features:

    const KDGpu::AdapterFeatures &features = adapter->features();
    if (features.geometryShader)
        std::cout << "Geometry shaders supported" << std::endl;
    if (features.tessellationShader)
        std::cout << "Tessellation supported" << std::endl;
    if (features.multiDrawIndirect)
        std::cout << "Multi-draw indirect supported" << std::endl;

Filename: kdgpu_doc_snippets.cpp

Checking limits:

    const KDGpu::AdapterProperties &adapterProps = adapter->properties();
    std::cout << "Max texture size: " << adapterProps.limits.maxImageDimension2D << std::endl;
    std::cout << "Max uniform buffer range: " << adapterProps.limits.maxUniformBufferRange << std::endl;
    std::cout << "Max compute workgroup size: "
              << adapterProps.limits.maxComputeWorkGroupSize[0] << "x"
              << adapterProps.limits.maxComputeWorkGroupSize[1] << "x"
              << adapterProps.limits.maxComputeWorkGroupSize[2] << std::endl;

Filename: kdgpu_doc_snippets.cpp

Querying queue families:

    auto queueTypes = adapter->queueTypes();
    for (size_t i = 0; i < queueTypes.size(); ++i) {
        std::cout << "Queue family " << i << ":" << std::endl;
        auto flags = queueTypes[i].flags;
        if (flags & KDGpu::QueueFlagBits::GraphicsBit)
            std::cout << "  - Graphics" << std::endl;
        if (flags & KDGpu::QueueFlagBits::ComputeBit)
            std::cout << "  - Compute" << std::endl;
        if (flags & KDGpu::QueueFlagBits::TransferBit)
            std::cout << "  - Transfer" << std::endl;
        std::cout << "  Queues available: " << queueTypes.size() << std::endl;
    }

Filename: kdgpu_doc_snippets.cpp

Selecting a discrete GPU:

    for (KDGpu::Adapter *adapter : instance.adapters()) {
        if (adapter->properties().deviceType == KDGpu::AdapterDeviceType::DiscreteGpu)
            return adapter;
    }
    return instance.adapters().front(); // Fallback

Filename: kdgpu_doc_snippets.cpp

Checking surface compatibility:

    auto swapchainProps = adapter->swapchainProperties(surface.handle());
    std::cout << "Supported present modes:" << std::endl;
    for (auto mode : swapchainProps.presentModes) {
        if (mode == KDGpu::PresentMode::Mailbox)
            std::cout << "  - Mailbox (low-latency triple buffering)" << std::endl;
        else if (mode == KDGpu::PresentMode::Immediate)
            std::cout << "  - Immediate (no vsync, tearing)" << std::endl;
        else if (mode == KDGpu::PresentMode::Fifo)
            std::cout << "  - FIFO (vsync)" << std::endl;
    }

Filename: kdgpu_doc_snippets.cpp

Querying format support:

    KDGpu::Format format = KDGpu::Format::R8G8B8A8_SRGB;
    KDGpu::FormatProperties formatProps = adapter->formatProperties(format);

    if (formatProps.optimalTilingFeatures & KDGpu::FormatFeatureFlagBit::SampledImageBit)
        std::cout << "Can use as sampled texture" << std::endl;
    if (formatProps.optimalTilingFeatures & KDGpu::FormatFeatureFlagBit::ColorAttachmentBit)
        std::cout << "Can use as render target" << std::endl;

Filename: kdgpu_doc_snippets.cpp

Creating a device:

    KDGpu::Device device2 = adapter->createDevice(KDGpu::DeviceOptions{
            .requestedFeatures = {
                    .geometryShader = true,
                    .multiDrawIndirect = true,
            },
    });

Filename: kdgpu_doc_snippets.cpp

Vulkan mapping:

• Adapter is a wrapper around VkPhysicalDevice
• Adapter::properties() → vkGetPhysicalDeviceProperties()
• Adapter::features() → vkGetPhysicalDeviceFeatures()
• Adapter::queueTypes() → vkGetPhysicalDeviceQueueFamilyProperties()
• Adapter::formatProperties() → vkGetPhysicalDeviceFormatProperties()
• Adapter::createDevice() → vkCreateDevice()

Public Functions Documentation

function Adapter

Adapter() =default

Default constructor creates an invalid adapter.

function ~Adapter

~Adapter()

Destructor - note that adapter is owned by Instance, not destroyed here.

function Adapter

Adapter(
    Adapter && other
)

Move constructor transfers ownership of the adapter handle.

function operator=

Adapter & operator=(
    Adapter && other
)

Move assignment transfers ownership of the adapter handle.

function Adapter

Adapter(
    const Adapter & 
) =delete

Copy constructor deleted - adapters cannot be copied.

function operator=

Adapter & operator=(
    const Adapter & 
) =delete

Copy assignment deleted - adapters cannot be copied.

function handle

inline Handle< Adapter_t > handle() const

Returns the internal handle to the Vulkan physical device.

See: ResourceManager

Returns the handle used to retrieve the underlying API specific Adapter.

function isValid

inline bool isValid() const

Checks if this adapter is valid.

Convenience function to check whether the Adapter is actually referencing a valid API specific resource.

function operator Handle< Adapter_t >

inline operator Handle< Adapter_t >() const

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

function extensions

std::vector< Extension > extensions() const

Queries all device extensions available on this adapter.

Return: Vector of available extensions with name and version

Vulkan equivalent: vkEnumerateDeviceExtensionProperties()

    auto extensions = adapter->extensions();
    for (const auto &ext : extensions) {
        if (ext.name == "VK_KHR_ray_tracing_pipeline") {
            std::cout << "Ray tracing supported!" << std::endl;
        }
    }

Filename: kdgpu_doc_snippets.cpp

function properties

const AdapterProperties & properties() const

Returns GPU properties (name, type, version, limits, etc.)

See: AdapterProperties

Return: Reference to adapter properties (cached at adapter creation)

Returns the AdapterFeatures supported by the Adapter.

Properties include:

• Device name (e.g., "NVIDIA GeForce RTX 3080")
• Device type (Discrete, Integrated, Virtual, CPU)
• Vulkan API version
• Driver version
• Limits (max texture size, max uniform buffer size, etc.)
• Unique IDs and vendor/device IDs

Vulkan equivalent: vkGetPhysicalDeviceProperties()

function features

const AdapterFeatures & features() const

Returns GPU feature support (shaders, ray tracing, etc.)

See: AdapterFeatures

Return: Reference to adapter features (cached at adapter creation)

Returns the AdapterFeatures supported by the Adapter.

Features include support for:

• Shader stages (geometry, tessellation)
• Ray tracing pipelines
• Mesh shaders
• Variable rate shading
• And many more

Vulkan equivalent: vkGetPhysicalDeviceFeatures()

function queueTypes

std::span< AdapterQueueType > queueTypes() const

Returns available queue families on this GPU.

See: AdapterQueueType

Return: Span of queue type descriptors

Returns the AdapterQueueType supported by the Adapter.

Each queue type describes a family of queues with specific capabilities:

• Graphics queues (rendering)
• Compute queues (compute shaders)
• Transfer queues (memory copies)
• Sparse binding queues

Vulkan equivalent: vkGetPhysicalDeviceQueueFamilyProperties()

function swapchainProperties

AdapterSwapchainProperties swapchainProperties(
    const Handle< Surface_t > & surface
) const

Queries swapchain capabilities for a given surface.

Parameters:

• surface Handle to window surface

See: AdapterSwapchainProperties

Return: Swapchain properties including supported formats and present modes

Returns the AdapterSwapchainProperties supported for Surfacesurface.

Vulkan equivalent: vkGetPhysicalDeviceSurfaceCapabilitiesKHR() + vkGetPhysicalDeviceSurfaceFormatsKHR() + vkGetPhysicalDeviceSurfacePresentModesKHR()

See also the class-level documentation for complete swapchain querying examples.

function supportsPresentation

bool supportsPresentation(
    const Handle< Surface_t > & surface,
    uint32_t queueTypeIndex
) const

Checks if a queue family supports presenting to a surface.

Parameters:

• surface Handle to window surface
• queueTypeIndex Index of the queue family to check

Return: true if this queue can present to the surface

Returns whether presentation is supported for surface and queueTypeIndex.

Vulkan equivalent: vkGetPhysicalDeviceSurfaceSupportKHR()

    for (uint32_t i = 0; i < adapter->queueTypes().size(); ++i) {
        if (adapter->supportsPresentation(surface.handle(), i)) {
            std::cout << "Queue family " << i << " can present" << std::endl;
        }
    }

Filename: kdgpu_doc_snippets.cpp

function formatProperties

FormatProperties formatProperties(
    Format format
) const

Queries format properties for a specific texture/image format.

Parameters:

• format Format to query (e.g., Format::R8G8B8A8_UNORM)

See: FormatProperties, Format

Return: Format properties describing supported features

Returns the FormatProperties for Format @format supported by the Adapter.

Vulkan equivalent: vkGetPhysicalDeviceFormatProperties()

See the class-level documentation for format support examples.

function supportsBlitting

bool supportsBlitting(
    Format srcFormat,
    TextureTiling srcTiling,
    Format dstFormat,
    TextureTiling dstTiling
) const

Checks if blitting (texture copying with scaling) is supported between two formats.

Parameters:

• srcFormat Source texture format
• srcTiling Source texture tiling mode
• dstFormat Destination texture format
• dstTiling Destination texture tiling mode

Return: true if vkCmdBlitImage can be used between these formats

    if (adapter->supportsBlitting(
                KDGpu::Format::R8G8B8A8_UNORM, KDGpu::TextureTiling::Optimal,
                KDGpu::Format::R8G8B8A8_SRGB, KDGpu::TextureTiling::Optimal)) {
        // Can blit from UNORM to SRGB
    }

Filename: kdgpu_doc_snippets.cpp

function supportsBlitting

bool supportsBlitting(
    Format format,
    TextureTiling tiling
) const

Checks if a format supports blitting (shorthand for same src/dst format)

Parameters:

• format Texture format
• tiling Tiling mode

Return: true if blitting is supported for this format

function drmFormatModifierProperties

std::vector< DrmFormatModifierProperties > drmFormatModifierProperties(
    Format format
) const

Queries DRM format modifier properties (Linux-specific multi-plane formats)

Parameters:

• format Format to query

See: DrmFormatModifierProperties

Return: Vector of DRM format modifier properties

This is primarily used on Linux for direct scanout and multi-plane image formats.

function createDevice

Device createDevice(
    const DeviceOptions & options =DeviceOptions()
)

Creates a logical device from this adapter.

Parameters:

• options Device creation options (queue families, features, extensions)
• options

See: Device, DeviceOptions

Return:

• Created device
• Device

Create a Device object.

Creates a VkDevice which is the primary object for creating GPU resources. You typically create one device per adapter and use it for the application lifetime.

Vulkan mapping: vkCreateDevice()

See the class-level documentation for device creation examples.

    KDGpu::Device device2 = adapter->createDevice(KDGpu::DeviceOptions{
            .requestedFeatures = {
                    .geometryShader = true,
                    .multiDrawIndirect = true,
            },
    });

Filename: kdgpu_doc_snippets.cpp

Protected Functions Documentation

function Adapter

explicit Adapter(
    GraphicsApi * api,
    const Handle< Adapter_t > & adapter
)

Protected Attributes Documentation

variable m_api

GraphicsApi * m_api { nullptr };

variable m_adapter

Handle< Adapter_t > m_adapter;

variable m_properties

AdapterProperties m_properties;

variable m_features

AdapterFeatures m_features;

variable m_queueTypes

std::vector< AdapterQueueType > m_queueTypes;

Friends

friend Instance

friend class Instance(
    Instance 
);

friend VulkanGraphicsApi

friend class VulkanGraphicsApi(
    VulkanGraphicsApi 
);

---

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