Runtime

The Runtime 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 RuntimeCreateParameters

Parameters used for creating a Runtime.

Public Members

VkInstance instance

Vulkan instance.

VkDevice device

Vulkan device.

VkPhysicalDevice physical_device

Vulkan physical device.

std::vector<std::unique_ptr<Executor>> executors

Executors available to the runtime for scheduling.

FunctionPointers pointers

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

class Runtime : public vuk::FunctionPointers

Public Functions

Runtime(RuntimeCreateParameters params)

Create a new Runtime.

Parameters:

params – Vulkan parameters initialized beforehand

bool debug_enabled() const

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

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.

bool is_pipeline_available(Name name) const

Checks if a pipeline is available.

Parameters:

name – the Name of the pipeline to check

Returns:

true if the pipeline is available

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.

void set_shader_target_version(uint32_t target_version = VK_API_VERSION_1_3)

Set the target Vulkan version for shader compilers.

Parameters:

target_version – the version to be set. VK_API_VERSION_1_X defines must be used.

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

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.

DescriptorSetLayoutAllocInfo &acquire_descriptor_set_layout(const struct DescriptorSetLayoutCreateInfo &dslci)

Acquire a cached descriptor set layout.

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.

uint32_t shader_compiler_target_version = VK_API_VERSION_1_3

Shader compiler Vulkan version.

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.