VKGETPIPELINECACHEDA(3)

NAME
vkGetPipelineCacheData - Get the data store from a pipeline cache

C SPECIFICATION

Data can be retrieved from a pipeline cache object using the command:

    VkResult vkGetPipelineCacheData(
        VkDevice                                    device,
        VkPipelineCache                             pipelineCache,
        size_t*                                     pDataSize,
        void*                                       pData);

PARAMETERS

    • device is the logical device that owns the pipeline cache.

    • pipelineCache is the pipeline cache to retrieve data from.

    • pDataSize is a pointer to a value related to the amount of data in the pipeline cache, as described below.

    • pData is either NULL or a pointer to a buffer.

DESCRIPTION

If pData is NULL, then the maximum size of the data that can be retrieved from the pipeline cache, in bytes, is returned in pDataSize. Otherwise, pDataSize must point to a variable set by the user to the size of the buffer, in bytes, pointed to by pData, and on return the variable is overwritten with the amount of data actually written to pData.

If pDataSize is less than the maximum size that can be retrieved by the pipeline cache, at most pDataSize bytes will be written to pData, and vkGetPipelineCacheData will return VK_INCOMPLETE. Any data written to pData is valid and can be provided as the pInitialData member of the VkPipelineCacheCreateInfo structure passed to vkCreatePipelineCache.

Two calls to vkGetPipelineCacheData with the same parameters must retrieve the same data unless a command that modifies the contents of the cache is called between them.

Applications can store the data retrieved from the pipeline cache, and use these data, possibly in a future run of the application, to populate new pipeline cache objects. The results of pipeline compiles, however, may depend on the vendor ID, device ID, driver version, and other details of the device. To enable applications to detect when previously retrieved data is incompatible with the device, the initial bytes written to pData must be a header consisting of the following members:

Table 1. Layout for pipeline cache header version VK_PIPELINE_CACHE_HEADER_VERSION_ONE
Offset | Size | Meaning
0 | 4 | length in bytes of the entire pipeline cache header written as a stream of bytes, with the least significant byte first
4 | 4 | a VkPipelineCacheHeaderVersion value written as a stream of bytes, with the least significant byte first
8 | 4 | a vendor ID equal to VkPhysicalDeviceProperties::vendorID written as a stream of bytes, with the least significant byte first
12 | 4 | a device ID equal to VkPhysicalDeviceProperties::deviceID written as a stream of bytes, with the least significant byte first
16 | VK_UUID_SIZE | a pipeline cache ID equal to VkPhysicalDeviceProperties::pipelineCacheUUID

The first four bytes encode the length of the entire pipeline header, in bytes. This value includes all fields in the header including the pipeline cache version field and the size of the length field.

The next four bytes encode the pipeline cache version. This field is interpreted as a VkPipelineCacheHeaderVersion value, and must have one of the following values:

    typedef enum VkPipelineCacheHeaderVersion {
        VK_PIPELINE_CACHE_HEADER_VERSION_ONE = 1,
    } VkPipelineCacheHeaderVersion;

A consumer of the pipeline cache should use the cache version to interpret the remainder of the cache header.

If pDataSize is less than what is necessary to store this header, nothing will be written to pData and zero will be written to pDataSize. Valid Usage (Implicit)

    • device must be a valid VkDevice handle

    • pipelineCache must be a valid VkPipelineCache handle

    • pDataSize must be a pointer to a size_t value

    • If the value referenced by pDataSize is not 0, and pData is not NULL, pData must be a pointer to an array of pDataSize bytes

    • pipelineCache must have been created, allocated, or retrieved from device
Return Codes

On success, this command returns

        • VK_SUCCESS

        • VK_INCOMPLETE

On failure, this command returns

        • VK_ERROR_OUT_OF_HOST_MEMORY

        • VK_ERROR_OUT_OF_DEVICE_MEMORY

SEE ALSO

VkDevice, VkPipelineCache

DOCUMENT NOTES

For more information, see the Vulkan Specification at URL

https://www.khronos.org/registry/vulkan/specs/1.0/xhtml/vkspec.html#vkGetPipelineCacheData

This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification,not directly.

COPYRIGHT

Copyright (c) 2014-2016 Khronos Group. This work is licensed under a Creative Commons Attribution 4.0 International License.

AUTHOR

Khronos Group
    Author.