C Specification

To create pipeline cache objects, call:

// Provided by VK_VERSION_1_0
VkResult vkCreatePipelineCache(
    VkDevice                                    device,
    const VkPipelineCacheCreateInfo*            pCreateInfo,
    const VkAllocationCallbacks*                pAllocator,
    VkPipelineCache*                            pPipelineCache);

Parameters

  • device is the logical device that creates the pipeline cache object.

  • pCreateInfo is a pointer to a VkPipelineCacheCreateInfo structure containing initial parameters for the pipeline cache object.

  • pAllocator controls host memory allocation as described in the Memory Allocation chapter.

  • pPipelineCache is a pointer to a VkPipelineCache handle in which the resulting pipeline cache object is returned.

Description

If the pipeline cache data pointed to by VkPipelineCacheCreateInfo::pInitialData is not compatible with the device, pipeline cache creation will fail and VK_ERROR_INVALID_PIPELINE_CACHE_DATA will be returned.

Once created, a pipeline cache can be passed to the vkCreateGraphicsPipelines and vkCreateComputePipelines commands. The pipeline cache passed into these commands will be queried by the implementation for matching pipelines on pipeline creation. After the cache is created, its contents cannot be updated. The use of the pipeline cache object in these commands is internally synchronized, and the same pipeline cache object can be used in multiple threads simultaneously.

If VkPhysicalDeviceVulkanSC10Properties::deviceNoDynamicHostAllocations is VK_TRUE, vkCreatePipelineCache must not return VK_ERROR_OUT_OF_HOST_MEMORY.

Valid Usage

  • VUID-vkCreatePipelineCache-pCreateInfo-05045
    The contents of the structure pointed to by pCreateInfo and the data pointed to by pCreateInfo->pInitialData must be the same as specified in one of the VkDeviceObjectReservationCreateInfo::pPipelineCacheCreateInfos structures when the device was created

  • VUID-vkCreatePipelineCache-device-05068
    The number of pipeline caches currently allocated from device plus 1 must be less than or equal to the total number of pipeline caches requested via VkDeviceObjectReservationCreateInfo::pipelineCacheRequestCount specified when device was created

Valid Usage (Implicit)

  • VUID-vkCreatePipelineCache-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkCreatePipelineCache-pCreateInfo-parameter
    pCreateInfo must be a valid pointer to a valid VkPipelineCacheCreateInfo structure

  • VUID-vkCreatePipelineCache-pAllocator-null
    pAllocator must be NULL

  • VUID-vkCreatePipelineCache-pPipelineCache-parameter
    pPipelineCache must be a valid pointer to a VkPipelineCache handle

Return Codes
On success, this command returns

  • VK_SUCCESS

On failure, this command returns

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

  • VK_ERROR_INVALID_PIPELINE_CACHE_DATA

See Also

VK_VERSION_1_0, VkAllocationCallbacks, VkDevice, VkPipelineCache, VkPipelineCacheCreateInfo

Document Notes

For more information, see the Vulkan Specification

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

Copyright

Copyright 2014-2023 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0