Owns the Vulkan pipeline cache used when creating pipelines and persists it across runs. More...

#include <headers/evan/PipelineCache.hpp>

Inheritance diagram for evan::PipelineCache:

Collaboration diagram for evan::PipelineCache:

Public Member Functions
	PipelineCache (const PipelineCache &)=delete

PipelineCache &	operator= (const PipelineCache &)=delete

void	init (VkDevice device, VkPhysicalDevice physicalDevice, const std::filesystem::path &path)
	Creates the Vulkan pipeline cache.

void	persist ()
	Flushes the pipeline cache to the path given to init().

void	destroy (VkDevice device)
	Destroys the Vulkan pipeline cache.

VkPipelineCache	getHandle () const
	Retrieves the Vulkan handle to pass to `vkCreateGraphicsPipelines`.

bool	isPersistent () const
	Tells whether the cache is written to and read from disk.

Static Public Member Functions
static VkPipelineCacheHeaderVersionOne	buildHeader (const VkPhysicalDeviceProperties &properties)
	Builds the cache key of a physical device.

static bool	isBlobCompatible (const std::vector< std::byte > &blob, const VkPipelineCacheHeaderVersionOne &expected)
	Tells whether a blob can safely be handed to the driver.

static bool	readBlob (const std::filesystem::path &path, std::vector< std::byte > &blob)
	Reads a whole pipeline cache blob from disk.

static bool	writeBlob (const std::filesystem::path &path, const std::vector< std::byte > &blob)
	Writes a pipeline cache blob to disk atomically.

Detailed Description

Owns the Vulkan pipeline cache used when creating pipelines and persists it across runs.

A VkPipelineCache lets the driver reuse the work it already did when compiling earlier pipelines: both for pipelines created later during the current run and for pipelines created by previous runs, when the cache is reloaded from disk. Without one, every launch recompiles every pipeline from scratch (vkCreateGraphicsPipelines(..., VK_NULL_HANDLE, ...)), which directly costs startup time.

The persisted blob is a driver and device specific artifact. On startup the blob is validated against the vendor id, device id and pipelineCacheUUID reported by the physical device, so a blob produced by another device, or by another driver version, is silently discarded instead of being handed to the driver.

Note: The cache is a pure optimization: every failure (unreadable file, unwritable directory, corrupt or stale blob, driver rejection) is non-fatal and simply leaves the renderer compiling its pipelines uncached.; The blob is written atomically (temporary file followed by a rename) so a process killed during shutdown can never leave a truncated file behind.

Definition at line 47 of file PipelineCache.hpp.

Member Function Documentation

◆ buildHeader()

static VkPipelineCacheHeaderVersionOne evan::PipelineCache::buildHeader ( const VkPhysicalDeviceProperties & properties )

static

Builds the cache key of a physical device.

The key is the part of a pipeline cache blob that identifies the device and the driver version that produced it. It is stored at the beginning of every blob by the Vulkan implementation itself, which makes it usable both to write and to validate a persisted blob.

Parameters

properties Properties of the physical device the cache is created for.

Returns: The header identifying that device and driver.

◆ destroy()

void evan::PipelineCache::destroy ( VkDevice device )

Destroys the Vulkan pipeline cache.

Parameters

device The logical device the cache was created from.

Note: Must be called after the pipelines created with the cache have been destroyed. This method does not persist the cache; call persist() first.

◆ getHandle()

VkPipelineCache evan::PipelineCache::getHandle ( ) const

inline

Retrieves the Vulkan handle to pass to vkCreateGraphicsPipelines.

Returns: The pipeline cache handle, or VK_NULL_HANDLE when the cache could not be created.

Definition at line 166 of file PipelineCache.hpp.

◆ init()

void evan::PipelineCache::init	(	VkDevice	device,
		VkPhysicalDevice	physicalDevice,
		const std::filesystem::path &	path
	)

Creates the Vulkan pipeline cache.

When path holds a blob that still matches the physical device, the blob is loaded and handed to vkCreatePipelineCache so the driver can reuse previously compiled pipelines. In every other case an empty cache is created.

Parameters

device	The logical device the cache belongs to.
physicalDevice	The physical device used to validate the persisted blob.
path	Path of the persisted blob, or an empty path to keep the cache in memory only.

Note: This method never reports failure. When the cache cannot be created at all, getHandle() keeps returning VK_NULL_HANDLE, which vkCreateGraphicsPipelines accepts as "no cache".

◆ isBlobCompatible()

static bool evan::PipelineCache::isBlobCompatible	(	const std::vector< std::byte > &	blob,
		const VkPipelineCacheHeaderVersionOne &	expected
	)

static

Tells whether a blob can safely be handed to the driver.

Compares the header stored at the beginning of blob with expected. A blob that is too short, whose header has an unknown version, or that was produced for another vendor, device or driver version is rejected.

Parameters

blob	Raw bytes read from a previously persisted cache.
expected	Cache key of the current device.

Returns: True when the blob matches the current device, false otherwise.

◆ isPersistent()

bool evan::PipelineCache::isPersistent ( ) const

inline

Tells whether the cache is written to and read from disk.

Returns: True when a path was given to init().

Definition at line 173 of file PipelineCache.hpp.

◆ persist()

void evan::PipelineCache::persist ( )

Flushes the pipeline cache to the path given to init().

Does nothing when the cache is empty or when persistence is disabled. Call it before destroy() so the pipelines created during this run are available to the next one.

◆ readBlob()

static bool evan::PipelineCache::readBlob	(	const std::filesystem::path &	path,
		std::vector< std::byte > &	blob
	)

static

Reads a whole pipeline cache blob from disk.

Parameters

path	Path of the blob to read.
blob	Output vector receiving the raw bytes. It is cleared when the read fails.

Returns: True when the file was read completely, false otherwise.

◆ writeBlob()

static bool evan::PipelineCache::writeBlob	(	const std::filesystem::path &	path,
		const std::vector< std::byte > &	blob
	)

static

Writes a pipeline cache blob to disk atomically.

Missing parent directories are created. The blob is first written to a temporary file next to path and then renamed over it, so a concurrent reader never observes a partially written cache.

Parameters

path	Path of the blob to write.
blob	Raw bytes to persist.

Returns: True when the blob was written, false otherwise.

The documentation for this class was generated from the following file:

headers/evan/PipelineCache.hpp

Public Member Functions

Static Public Member Functions

Detailed Description

Member Function Documentation

◆ buildHeader()

◆ destroy()

◆ getHandle()

◆ init()

◆ isBlobCompatible()

◆ isPersistent()

◆ persist()

◆ readBlob()

◆ writeBlob()