Vulkan.Extensions.VK_KHR_pipeline_binary

vkCreatePipelineBinariesKHR - Create pipeline binaries from a pipeline or previously retrieved data

Description

The implementation will attempt to create all pipeline binaries. If creation fails for any pipeline binary, then:

• The corresponding entry in the pPipelineBinaries output array will be filled with NULL_HANDLE.

• The Result returned by createPipelineBinariesKHR will contain the error value for the first entry in the output array in pBinaries containing NULL_HANDLE.

Valid Usage (Implicit)

• device must be a valid Device handle

• pCreateInfo must be a valid pointer to a valid PipelineBinaryCreateInfoKHR structure

• If pAllocator is not NULL, pAllocator must be a valid pointer to a valid AllocationCallbacks structure

• pBinaries must be a valid pointer to a PipelineBinaryHandlesInfoKHR structure

Return Codes

Success

• INCOMPLETE

• PIPELINE_BINARY_MISSING_KHR

• SUCCESS

Failure

• ERROR_INITIALIZATION_FAILED

• ERROR_OUT_OF_DEVICE_MEMORY

• ERROR_OUT_OF_HOST_MEMORY

• ERROR_UNKNOWN

• ERROR_VALIDATION_FAILED

See Also

VK_KHR_pipeline_binary, AllocationCallbacks, Device, PipelineBinaryCreateInfoKHR, PipelineBinaryHandlesInfoKHR

vkDestroyPipelineBinaryKHR - Destroy a pipeline binary

Valid Usage

• If AllocationCallbacks were provided when pipelineBinary was created, a compatible set of callbacks must be provided here

• If no AllocationCallbacks were provided when pipelineBinary was created, pAllocator must be NULL

Valid Usage (Implicit)

• device must be a valid Device handle

• If pipelineBinary is not NULL_HANDLE, pipelineBinary must be a valid PipelineBinaryKHR handle

• If pAllocator is not NULL, pAllocator must be a valid pointer to a valid AllocationCallbacks structure

• If pipelineBinary is a valid handle, it must have been created, allocated, or retrieved from device

Host Synchronization

• Host access to pipelineBinary must be externally synchronized

See Also

VK_KHR_pipeline_binary, AllocationCallbacks, Device, PipelineBinaryKHR

vkGetPipelineKeyKHR - Generate the pipeline key from pipeline creation info

Description

If pPipelineCreateInfo is NULL, then the implementation must return the global key that applies to all pipelines. If the key obtained in this way changes between saving and restoring data obtained from getPipelineBinaryDataKHR in a different Device, then the application must assume that the restored data is invalid and cannot be passed to createPipelineBinariesKHR. Otherwise the application can assume the data is still valid.

If pPipelineCreateInfo is not NULL, the key obtained functions as a method to compare two pipeline creation info structures. Implementations may not compare parts of a pipeline creation info which would not contribute to the final binary output. If a shader module identifier is used instead of a shader module, the pPipelineKey generated must be equal to the key generated when using the shader module from which the identifier was queried. If the content of two pPipelineKey are equal, pipelines created with the two pPipelineCreateInfo->pNext create infos must produce the same PipelineBinaryKHR contents.

The pipeline key is distinct from pipeline binary key. Pipeline binary keys can only be obtained after compilation. The pipeline key is intended to optionally allow associating pipeline create info with multiple pipeline binary keys.

Valid Usage

• The pNext chain of pPipelineCreateInfo must not set PipelineBinaryInfoKHR::binaryCount to a value greater than 0

Valid Usage (Implicit)

• device must be a valid Device handle

• If pPipelineCreateInfo is not NULL, pPipelineCreateInfo must be a valid pointer to a valid PipelineCreateInfoKHR structure

• pPipelineKey must be a valid pointer to a PipelineBinaryKeyKHR structure

Return Codes

Success

• SUCCESS

Failure

• ERROR_OUT_OF_DEVICE_MEMORY

• ERROR_OUT_OF_HOST_MEMORY

• ERROR_UNKNOWN

• ERROR_VALIDATION_FAILED

See Also

VK_KHR_pipeline_binary, Device, PipelineBinaryKeyKHR, PipelineCreateInfoKHR

vkGetPipelineBinaryDataKHR - Get the data store from a pipeline binary

Description

If pPipelineBinaryData is NULL, then the size of the data, in bytes, that is required to store the binary is returned in pPipelineBinaryDataSize. Otherwise, pPipelineBinaryDataSize must contain the size of the buffer, in bytes, pointed to by pPipelineBinaryData, and on return pPipelineBinaryDataSize is overwritten with the size of the data, in bytes, that is required to store the binary. If pPipelineBinaryDataSize is less than the size that is required to store the binary, nothing is written to pPipelineBinaryData and ERROR_NOT_ENOUGH_SPACE_KHR will be returned, instead of SUCCESS.

If the call returns one of the success return codes, the pipeline binary key is written to pPipelineBinaryKey, regardless of whether pPipelineBinaryData is NULL or not.

If pipelineBinaryCompressedData is FALSE, implementations should not return compressed pipeline binary data to the application.

Valid Usage (Implicit)

• device must be a valid Device handle

• pInfo must be a valid pointer to a valid PipelineBinaryDataInfoKHR structure

• pPipelineBinaryKey must be a valid pointer to a PipelineBinaryKeyKHR structure

• pPipelineBinaryDataSize must be a valid pointer to a size_t value

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

Return Codes

Success

• SUCCESS

Failure

• ERROR_NOT_ENOUGH_SPACE_KHR

• ERROR_OUT_OF_DEVICE_MEMORY

• ERROR_OUT_OF_HOST_MEMORY

• ERROR_UNKNOWN

• ERROR_VALIDATION_FAILED

See Also

VK_KHR_pipeline_binary, Device, PipelineBinaryDataInfoKHR, PipelineBinaryKeyKHR

vkReleaseCapturedPipelineDataKHR - Release captured pipeline binary data

Description

The implementation may free any resources captured as a result of creating the pipeline with PIPELINE_CREATE_2_CAPTURE_DATA_BIT_KHR and put the pipeline into a state as if PIPELINE_CREATE_2_CAPTURE_DATA_BIT_KHR had not been provided at pipeline creation time.

Any resources captured as a result of creating the pipeline with PIPELINE_CREATE_2_CAPTURE_DATA_BIT_KHR are implicitly freed by destroyPipeline.

Valid Usage

• If AllocationCallbacks were provided when pipeline was created, a compatible set of callbacks must be provided in pAllocator

• If no AllocationCallbacks were provided when pipeline was created, pAllocator must be NULL

Valid Usage (Implicit)

• device must be a valid Device handle

• pInfo must be a valid pointer to a valid ReleaseCapturedPipelineDataInfoKHR structure

• If pAllocator is not NULL, pAllocator must be a valid pointer to a valid AllocationCallbacks structure

Return Codes

Success

• SUCCESS

Failure

• ERROR_UNKNOWN

• ERROR_VALIDATION_FAILED

See Also

VK_KHR_pipeline_binary, AllocationCallbacks, Device, ReleaseCapturedPipelineDataInfoKHR

VkPipelineBinaryCreateInfoKHR - Structure specifying where to retrieve data for pipeline binary creation

Description

When pPipelineCreateInfo is not NULL, an implementation will attempt to retrieve pipeline binary data from an internal cache external to the application if pipelineBinaryInternalCache is TRUE. Applications can use this to determine if a pipeline can be created without compilation. If the implementation fails to create a pipeline binary due to missing an internal cache entry, PIPELINE_BINARY_MISSING_KHR is returned. If creation succeeds, the resulting binary can be used to create a pipeline. PIPELINE_BINARY_MISSING_KHR may be returned for any reason in this situation, even if creating a pipeline binary with the same parameters that succeeded earlier.

If pipelineBinaryPrecompiledInternalCache is TRUE, the implementation may be able to create pipeline binaries even when pPipelineCreateInfo has not been used to create binaries before by the application.

On some platforms, internal pipeline caches may be pre-populated before running the application.

Valid Usage

• If pipeline is not NULL_HANDLE, pipeline must have been created with PIPELINE_CREATE_2_CAPTURE_DATA_BIT_KHR

• If pipeline is not NULL_HANDLE, releaseCapturedPipelineDataKHR must not have been called on pipeline prior to this command

• If pipelineBinaryInternalCache is FALSE pPipelineCreateInfo must be NULL

• If device was created with DevicePipelineBinaryInternalCacheControlKHR::disableInternalCache set to TRUE, pPipelineCreateInfo must be NULL

• One and only one of pKeysAndDataInfo, pipeline, or pPipelineCreateInfo must be non-NULL

• If pPipelineCreateInfo is not NULL, the pNext chain of pPipelineCreateInfo must not set PipelineBinaryInfoKHR::binaryCount to a value greater than 0

Valid Usage (Implicit)

• sType must be STRUCTURE_TYPE_PIPELINE_BINARY_CREATE_INFO_KHR

• pNext must be NULL

• If pKeysAndDataInfo is not NULL, pKeysAndDataInfo must be a valid pointer to a valid PipelineBinaryKeysAndDataKHR structure

• If pipeline is not NULL_HANDLE, pipeline must be a valid Pipeline handle

• If pPipelineCreateInfo is not NULL, pPipelineCreateInfo must be a valid pointer to a valid PipelineCreateInfoKHR structure

See Also

VK_KHR_pipeline_binary, Pipeline, PipelineBinaryKeysAndDataKHR, PipelineCreateInfoKHR, StructureType, createPipelineBinariesKHR

VkPipelineBinaryHandlesInfoKHR - Structure containing newly created pipeline binaries

Description

If pPipelineBinaries is NULL, the number of binaries that would be created is returned in pipelineBinaryCount. Otherwise, pipelineBinaryCount must be the number of entries in the pPipelineBinaries array, and on return from createPipelineBinariesKHR pipelineBinaryCount is overwritten with the number of handles actually written to pPipelineBinaries. If the value of pipelineBinaryCount is less than the number of binaries that would have been created, at most pipelineBinaryCount handles will be written to pPipelineBinaries and INCOMPLETE will be returned instead of SUCCESS, to indicate that pPipelineBinaries was not large enough to create all the binaries.

Valid Usage (Implicit)

• sType must be STRUCTURE_TYPE_PIPELINE_BINARY_HANDLES_INFO_KHR

• pNext must be NULL

• If pipelineBinaryCount is not 0, and pPipelineBinaries is not NULL, pPipelineBinaries must be a valid pointer to an array of pipelineBinaryCount PipelineBinaryKHR handles

See Also

VK_KHR_pipeline_binary, PipelineBinaryKHR, StructureType, createPipelineBinariesKHR

VkPipelineBinaryDataKHR - Structure specifying data and length of a pipeline binary

Valid Usage (Implicit)

See Also

VK_KHR_pipeline_binary, PipelineBinaryKeysAndDataKHR

VkPipelineBinaryKeysAndDataKHR - Structure specifying arrays of key and data pairs

Valid Usage (Implicit)

See Also

VK_KHR_pipeline_binary, PipelineBinaryCreateInfoKHR, PipelineBinaryDataKHR, PipelineBinaryKeyKHR

VkPipelineBinaryKeyKHR - Structure specifying a key to a pipeline binary

Description

Any returned values beyond the first keySize bytes are undefined. Implementations must return a keySize greater than 0, and less-or-equal to MAX_PIPELINE_BINARY_KEY_SIZE_KHR.

Two keys are considered equal if keySize is equal and the first keySize bytes of key compare equal.

Implementations may return a different keySize for different binaries.

Implementations should ensure that keySize is large enough to uniquely identify a pipeline binary.

Valid Usage (Implicit)

See Also

VK_KHR_pipeline_binary, PipelineBinaryKeysAndDataKHR, StructureType, getPipelineBinaryDataKHR, getPipelineKeyKHR

VkPipelineBinaryInfoKHR - Structure specifying pipeline binaries to use during pipeline creation

Description

If a PipelineBinaryInfoKHR structure with a binaryCount greater than 0 is included in the pNext chain of any Vk*PipelineCreateInfo structure when creating a pipeline, implementations must use the data in pPipelineBinaries instead of recalculating it. Any shader module identifiers, shader modules, or chained ShaderModuleCreateInfo structures declared in PipelineShaderStageCreateInfo instances, are ignored. Any ShaderDescriptorSetAndBindingMappingInfoEXT in the pNext chains of PipelineShaderStageCreateInfo instances are ignored.

If this structure is not included in the pNext chain, it is equivalent to specifying this structure with a binaryCount of 0.

Valid Usage

• binaryCount and the order of the elements in pPipelineBinaries must exactly match that returned by createPipelineBinariesKHR for the matching Vk*PipelineCreateInfo structure and its pNext chain, ignoring the presence of the PipelineBinaryInfoKHR structure, the presence of the PIPELINE_CREATE_2_CAPTURE_DATA_BIT_KHR flag, and absence of any shader module identifiers, shader modules, or ShaderModuleCreateInfo structures, for the same global pipeline key, from either:

  • PipelineBinaryCreateInfoKHR::pPipelineCreateInfo, or

  • PipelineBinaryCreateInfoKHR::pipeline

Valid Usage (Implicit)

• sType must be STRUCTURE_TYPE_PIPELINE_BINARY_INFO_KHR

• If binaryCount is not 0, pPipelineBinaries must be a valid pointer to an array of binaryCount valid PipelineBinaryKHR handles

Structure Chaining

Extends the structures

• ComputePipelineCreateInfo

• GraphicsPipelineCreateInfo

• RayTracingPipelineCreateInfoKHR

See Also

VK_KHR_pipeline_binary, PipelineBinaryKHR, StructureType

VkReleaseCapturedPipelineDataInfoKHR - Structure specifying a pipeline whose captured data is to be released

Valid Usage

• pipeline must have been created with PIPELINE_CREATE_2_CAPTURE_DATA_BIT_KHR

• pipeline must not have been used in a previous call to releaseCapturedPipelineDataKHR

Valid Usage (Implicit)

• sType must be STRUCTURE_TYPE_RELEASE_CAPTURED_PIPELINE_DATA_INFO_KHR

• pNext must be NULL

• pipeline must be a valid Pipeline handle

Host Synchronization

• Host access to pipeline must be externally synchronized

See Also

VK_KHR_pipeline_binary, Pipeline, StructureType, releaseCapturedPipelineDataKHR

VkPipelineBinaryDataInfoKHR - Structure specifying a pipeline binary to retrieve binary data from

Valid Usage (Implicit)

See Also

VK_KHR_pipeline_binary, PipelineBinaryKHR, StructureType, getPipelineBinaryDataKHR

VkPipelineCreateInfoKHR - Structure specifying a pipeline createinfo chain

Valid Usage (Implicit)

See Also

VK_KHR_pipeline_binary, PipelineBinaryCreateInfoKHR, StructureType, getPipelineKeyKHR

VkPhysicalDevicePipelineBinaryFeaturesKHR - Structure describing support for pipeline binaries

Members

This structure describes the following feature:

Description

If the PhysicalDevicePipelineBinaryFeaturesKHR structure is included in the pNext chain of the PhysicalDeviceFeatures2 structure passed to getPhysicalDeviceFeatures2, it is filled in to indicate whether each corresponding feature is supported. If the application wishes to use a Device with any features described by PhysicalDevicePipelineBinaryFeaturesKHR, it must add an instance of the structure, with the desired feature members set to TRUE, to the pNext chain of DeviceCreateInfo when creating the Device.

Structure Chaining

Extends the structures

• DeviceCreateInfo

• PhysicalDeviceFeatures2

See Also

VK_KHR_pipeline_binary, Bool32, StructureType

VkDevicePipelineBinaryInternalCacheControlKHR - Structure specifying parameter to disable the internal pipeline cache

Description

If the DeviceCreateInfo::pNext chain does not include this structure, then disableInternalCache defaults to FALSE.

Valid Usage

• If PhysicalDevicePipelineBinaryPropertiesKHR::pipelineBinaryInternalCacheControl is FALSE, disableInternalCache must be FALSE

Valid Usage (Implicit)

• sType must be STRUCTURE_TYPE_DEVICE_PIPELINE_BINARY_INTERNAL_CACHE_CONTROL_KHR

Structure Chaining

Extends the structure

• DeviceCreateInfo

See Also

VK_KHR_pipeline_binary, Bool32, StructureType

VkPhysicalDevicePipelineBinaryPropertiesKHR - Structure describing properties about the pipeline binary implementation

Description

These properties tend to be platform specific and may change depending on external configuration which is outside the scope of this specification. These properties are intended to guide applications when implementations have dedicated caching solutions available. In particular, if the pipelineBinaryPrefersInternalCache limit is exposed, relying on the internal cache may provide some advantage compared to an application-specific solution. An application with its own dedicated solution may still use its own caching system even with this limit exposed.

If the PhysicalDevicePipelineBinaryPropertiesKHR structure is included in the pNext chain of the PhysicalDeviceProperties2 structure passed to getPhysicalDeviceProperties2, it is filled in with each corresponding implementation-dependent property.

Structure Chaining

Extends the structure

• PhysicalDeviceProperties2

See Also

VK_KHR_pipeline_binary, Bool32, StructureType

VkPipelineBinaryKHR - Opaque handle to a pipeline binary object

See Also

VK_DEFINE_NON_DISPATCHABLE_HANDLE, VK_KHR_pipeline_binary, PipelineBinaryDataInfoKHR, PipelineBinaryHandlesInfoKHR, PipelineBinaryInfoKHR, destroyPipelineBinaryKHR

VK_MAX_PIPELINE_BINARY_KEY_SIZE_KHR - Maximum length of binary key

See Also

VK_KHR_pipeline_binary