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

bool debug_enabled() const

If debug utils is available and debug names & markers are supported.

void set_name(const Texture&, Name name)

Set debug name for Texture.

template<class T>
void set_name(const T &t, Name name)

Set debug name for object.

void begin_region(const VkCommandBuffer&, Name name, std::array<float, 4> color = {1, 1, 1, 1})

Add debug region to command buffer.

Parameters:

• name – Name of the region

• color – Display color of the region

void end_region(const VkCommandBuffer&)

End debug region in command buffer.

void create_named_pipeline(Name name, PipelineBaseCreateInfo pbci)

Create a pipeline base that can be recalled by name.

PipelineBaseInfo *get_named_pipeline(Name name)

Recall name pipeline base.

Program get_pipeline_reflection_info(const PipelineBaseCreateInfo &pbci)

Reflect given pipeline base.

ShaderModule compile_shader(ShaderSource source, std::string path)

Explicitly compile give ShaderSource into a ShaderModule.

bool load_pipeline_cache(std::span<std::byte> data)

Load a Vulkan pipeline cache.

std::vector<std::byte> save_pipeline_cache()

Retrieve the current Vulkan pipeline cache.

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.

uint64_t get_frame_count() const

Retrieve the current frame count.

void next_frame()

Advance internal counter used for caching and garbage collect caches.

Result<void> wait_idle()

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

Query create_timestamp_query()

Create a timestamp query to record timing information.

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.

Sampler acquire_sampler(const SamplerCreateInfo &cu, uint64_t absolute_frame)

Acquire a cached sampler.

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

Acquire a cached descriptor pool.

void collect(uint64_t frame)

Force collection of caches.

uint64_t get_unique_handle_id()

Retrieve a unique uint64_t value.

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.

Public Members

VkPipelineCache vk_pipeline_cache = VK_NULL_HANDLE

Internal pipeline cache to use.

DescriptorSetStrategyFlags default_descriptor_set_strategy = {}

Descriptor set strategy to use by default, can be overridden on the CommandBuffer.

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