KDGpu::Queue

Module: Public API

Represents a GPU command queue for submitting work to the device. More...

#include <KDGpu/queue.h>

Public Functions

	Name
	Queue()
	~Queue()
const Handle< Queue_t > &	handle() const Returns the handle used to retrieve the underlying API specific Queue.
bool	isValid() const Convenience function to check whether the Queue is actually referencing a valid API specific resource.
	operator Handle< Queue_t >() const
QueueFlags	flags() const
uint32_t	timestampValidBits() const
Extent3D	minImageTransferGranularity() const
uint32_t	queueTypeIndex() const
void	waitUntilIdle() Forces a CPU side blocking wait until all pending commands on the queue have completed their execution.
void	submit(const SubmitOptions & options) Submit commands for execution based on the SubmitOptionsoptions provided.
PresentResult	present(const PresentOptions & options) Request the Queue present content to the swapchains referenced in the PresentOptionsoptions.
std::vector< PresentResult >	lastPerSwapchainPresentResults() const
void	waitForUploadBufferData(const WaitForBufferUploadOptions & options)
UploadStagingBuffer	uploadBufferData(const BufferUploadOptions & options)
void	waitForUploadTextureData(const WaitForTextureUploadOptions & options)
UploadStagingBuffer	uploadTextureData(const TextureUploadOptions & options)

Friends

	Name
class	Device
class	VulkanGraphicsApi

Detailed Description

class KDGpu::Queue;

Represents a GPU command queue for submitting work to the device.

Note: Unlike most other KDGpu resources, Queue instances can be copied around.

Vulkan equivalent:VkQueue

Queue is the interface for submitting command buffers to the GPU for execution. Every Device has one or more queues that support different types of operations (graphics, compute, transfer).

Key responsibilities:

• Submit command buffers for GPU execution
• Present rendered images to swapchains
• Synchronize CPU and GPU with fences and semaphores
• Upload data to buffers and textures
• Wait for GPU operations to complete

Lifetime:Queue objects are created by Device and remain valid for the lifetime of the device. You typically retrieve queues from the device and copy them.

Usage

Basic queue usage:

    queue.submit(KDGpu::SubmitOptions{
            .commandBuffers = { commandBuffer },
    });

Filename: kdgpu_doc_snippets.cpp

Synchronization with fences:

    queue.submit(KDGpu::SubmitOptions{
            .commandBuffers = { commandBuffer },
            .signalFence = fence,
    });

    // Do other work...
    fence.wait(); // Block until GPU completes

Filename: kdgpu_doc_snippets.cpp

GPU-to-GPU synchronization with semaphores:

    queue.submit(KDGpu::SubmitOptions{
            .commandBuffers = { commandBuffer },
            .waitSemaphores = { semaphoreA },
            .signalSemaphores = { semaphoreB },
    });

Filename: kdgpu_doc_snippets.cpp

Presenting to swapchains:

    queue.present(KDGpu::PresentOptions{
            .waitSemaphores = { semaphoreA },
            .swapchainInfos = {
                    {
                            .swapchain = swapchain,
                            .imageIndex = imageIndex,
                    },
            },
    });

Filename: kdgpu_doc_snippets.cpp

Presenting and signalling a fence:

The swapchainMaintenance1 feature allows to signal a fence when a swapchain is presented. This can make it simpler to wait for presentation completeness than using a Queue::waitUntilIdle() or having per swapchain image semaphores.

    // If the device supports the swapchainMaintenance1 feature, it is possible to signal a fence when presentation is completed.
    // This can help simplifying the synchronization.

    KDGpu::Fence presentFence = device.createFence(KDGpu::FenceOptions{ .createSignalled = false });

    queue.present(KDGpu::PresentOptions{
            .waitSemaphores = { semaphoreA },
            .swapchainInfos = {
                    {
                            .swapchain = swapchain,
                            .imageIndex = imageIndex,
                    },
            },
            .signalFence = { presentFence },
    });

    fence.wait();
    // Presentation has completed at this point

Filename: kdgpu_doc_snippets.cpp

Queue capabilities:

    queue.waitUntilIdle(); // Block until queue is empty

Filename: kdgpu_doc_snippets.cpp

Vulkan mapping:

• Queue::submit()->vkQueueSubmit()
• Queue::present()->vkQueuePresentKHR()
• Queue::waitUntilIdle()->vkQueueWaitIdle()
• Queue::uploadBufferData()->staging buffer + vkCmdCopyBuffer()
• Queue::uploadTextureData()->staging buffer + vkCmdCopyBufferToImage()

See also:

SubmitOptions, PresentOptions, Device, CommandRecorder, CommandBuffer, Fence, GpuSemaphore, TimelineSemaphore, Swapchain

KDGpu API Overview

KDGpu to Vulkan API Mapping

Public Functions Documentation

function Queue

Queue()

function ~Queue

~Queue()

function handle

inline const Handle< Queue_t > & handle() const

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

See: ResourceManager

function isValid

inline bool isValid() const

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

function operator Handle< Queue_t >

inline operator Handle< Queue_t >() const

function flags

inline QueueFlags flags() const

function timestampValidBits

inline uint32_t timestampValidBits() const

function minImageTransferGranularity

inline Extent3D minImageTransferGranularity() const

function queueTypeIndex

inline uint32_t queueTypeIndex() const

function waitUntilIdle

void waitUntilIdle()

Forces a CPU side blocking wait until all pending commands on the queue have completed their execution.

function submit

void submit(
    const SubmitOptions & options
)

Submit commands for execution based on the SubmitOptionsoptions provided.

function present

PresentResult present(
    const PresentOptions & options
)

Request the Queue present content to the swapchains referenced in the PresentOptionsoptions.

function lastPerSwapchainPresentResults

std::vector< PresentResult > lastPerSwapchainPresentResults() const

function waitForUploadBufferData

void waitForUploadBufferData(
    const WaitForBufferUploadOptions & options
)

function uploadBufferData

UploadStagingBuffer uploadBufferData(
    const BufferUploadOptions & options
)

function waitForUploadTextureData

void waitForUploadTextureData(
    const WaitForTextureUploadOptions & options
)

function uploadTextureData

UploadStagingBuffer uploadTextureData(
    const TextureUploadOptions & options
)

Friends

friend Device

friend class Device(
    Device 
);

friend VulkanGraphicsApi

friend class VulkanGraphicsApi(
    VulkanGraphicsApi 
);

---

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