Context

The Context represents the base object of the runtime, encapsulating the knowledge about the GPU (similar to a VkDevice). Use this class to manage pipelines and other cached objects, add/remove swapchains, manage persistent descriptor sets, submit work to device and retrieve query results.

struct ContextCreateParameters

Parameters used for creating a Context.

Public Members

VkInstance instance

Vulkan instance.

VkDevice device

Vulkan device.

VkPhysicalDevice physical_device

Vulkan physical device.

VkQueue graphics_queue = VK_NULL_HANDLE

Optional graphics queue.

uint32_t graphics_queue_family_index = VK_QUEUE_FAMILY_IGNORED

Optional graphics queue family index.

VkQueue compute_queue = VK_NULL_HANDLE

Optional compute queue.

uint32_t compute_queue_family_index = VK_QUEUE_FAMILY_IGNORED

Optional compute queue family index.

VkQueue transfer_queue = VK_NULL_HANDLE

Optional transfer queue.

uint32_t transfer_queue_family_index = VK_QUEUE_FAMILY_IGNORED

Optional transfer queue family index.

bool allow_dynamic_loading_of_vk_function_pointers = true

Allow vuk to load missing required and optional function pointers dynamically If this is false, then you must fill in all required function pointers.

struct FunctionPointers

User provided function pointers. If you want dynamic loading, you must set vkGetInstanceProcAddr & vkGetDeviceProcAddr.

Subclassed by vuk::Context

class Context : public vuk::ContextCreateParameters::FunctionPointers

Public Functions

Context(ContextCreateParameters params)

Create a new Context.

Parameters:

params – Vulkan parameters initialized beforehand

DeviceVkResource &get_vk_resource()

Return an allocator over the direct resource - resources will be allocated from the Vulkan runtime.

Returns:

The resource

SwapchainRef add_swapchain(Swapchain)

Add a swapchain to be managed by the Context.

Returns:

Reference to the new swapchain that can be used during presentation

void remove_swapchain(SwapchainRef)

Remove a swapchain that is managed by the Context the swapchain is not destroyed.

void next_frame()

Advance internal counter used for caching and garbage collect caches.

void wait_idle()

Wait for the device to become idle. Useful for only a few synchronisation events, like resizing or shutting down.

template<class T>
Handle<T> wrap(T payload)

Create a wrapped handle type (eg. a ImageView) from an externally sourced Vulkan handle.

Template Parameters:

T – Vulkan handle type to wrap

Parameters:

payload – Vulkan handle to wrap

Returns:

The wrapped handle.

bool is_timestamp_available(Query q)

Checks if a timestamp query is available.

Parameters:

q – the Query to check

Returns:

true if the timestamp is available

std::optional<uint64_t> retrieve_timestamp(Query q)

Retrieve a timestamp if available.

Parameters:

q – the Query to check

Returns:

the timestamp value if it was available, null optional otherwise

std::optional<double> retrieve_duration(Query q1, Query q2)

Retrive a duration if available.

Parameters:

• q1 – the start timestamp Query

• q2 – the end timestamp Query

Returns:

the duration in seconds if both timestamps were available, null optional otherwise

Result<void> make_timestamp_results_available(std::span<const TimestampQueryPool> pools)

Retrieve results from TimestampQueryPools and make them available to retrieve_timestamp and retrieve_duration.

RGImage acquire_rendertarget(const struct RGCI &ci, uint64_t absolute_frame)

Acquire a cached rendertarget.

Sampler acquire_sampler(const SamplerCreateInfo &cu, uint64_t absolute_frame)

Acquire a cached sampler.

VkRenderPass acquire_renderpass(const struct RenderPassCreateInfo &ci, uint64_t absolute_frame)

Acquire a cached VkRenderPass.

struct PipelineInfo acquire_pipeline(const struct PipelineInstanceCreateInfo &ci, uint64_t absolute_frame)

Acquire a cached pipeline.

struct ComputePipelineInfo acquire_pipeline(const struct ComputePipelineInstanceCreateInfo &ci, uint64_t absolute_frame)

Acquire a cached compute pipeline.

struct RayTracingPipelineInfo acquire_pipeline(const struct RayTracingPipelineInstanceCreateInfo &ci, uint64_t absolute_frame)

Acquire a cached ray tracing pipeline.

struct DescriptorPool &acquire_descriptor_pool(const struct DescriptorSetLayoutAllocInfo &dslai, uint64_t absolute_frame)

Acquire a cached descriptor pool.

struct Query

Handle to a query result.

Submitting work

While submitting work to the device can be performed by the user, it is usually sufficient to use a utility function that takes care of translating a RenderGraph into device execution. Note that these functions are used internally when using :cpp:class:`vuk::Future`s, and as such Futures can be used to manage submission in a more high-level fashion.

Result<VkResult> vuk::execute_submit_and_present_to_one(Allocator &allocator, ExecutableRenderGraph &&executable_rendergraph, SwapchainRef swapchain)

Execute given ExecutableRenderGraph into API VkCommandBuffers, then submit them to queues, presenting to a single swapchain.

Parameters:

• allocator – Allocator to use for submission resources

• executable_rendergraph – ExecutableRenderGraphs for execution

• swapchain – Swapchain referenced by the rendergraph

Result<void> vuk::execute_submit_and_wait(Allocator &allocator, ExecutableRenderGraph &&executable_rendergraph)

Execute given ExecutableRenderGraph into API VkCommandBuffers, then submit them to queues, then blocking-wait for the submission to complete.

Parameters:

• allocator – Allocator to use for submission resources

• executable_rendergraph – ExecutableRenderGraphs for execution

Result<void> vuk::link_execute_submit(Allocator &allocator, Compiler &compiler, std::span<std::shared_ptr<struct RenderGraph>> rendergraphs)

Compile & link given RenderGraphs, then execute them into API VkCommandBuffers, then submit them to queues.

Parameters:

• allocator – Allocator to use for submission resources

• rendergraphs – RenderGraphs for compilation