C Specification

Each pipeline cache index entry consists of a VkPipelineCacheSafetyCriticalIndexEntry structure:

// Provided by VKSC_VERSION_1_0
typedef struct VkPipelineCacheSafetyCriticalIndexEntry {
    uint8_t     pipelineIdentifier[VK_UUID_SIZE];
    uint64_t    pipelineMemorySize;
    uint64_t    jsonSize;
    uint64_t    jsonOffset;
    uint32_t    stageIndexCount;
    uint32_t    stageIndexStride;
    uint64_t    stageIndexOffset;
} VkPipelineCacheSafetyCriticalIndexEntry;

Members

  • pipelineIdentifier is the pipeline identifier indicating which pipeline the information is associated with.

  • pipelineMemorySize is the number of bytes of pipeline memory required for this pipeline. This is the minimum value that can be successfully used for VkPipelineOfflineCreateInfo::poolEntrySize when this pipeline is used.

  • jsonSize is the size in bytes of the pipeline JSON data representing the pipeline state for this pipeline. This value may be zero, indicating the JSON data is not present in the pipeline cache for this pipeline.

  • jsonOffset is the offset in bytes from the beginning of the pipeline cache header to the pipeline JSON data for this pipeline. This value must be zero if the JSON data is not present in the pipeline cache for this pipeline.

  • stageIndexCount is the number of entries in the pipeline cache stage validation index for this pipeline. This value may be zero, indicating that no stage validation information is present in the pipeline cache for this pipeline.

  • stageIndexStride is the number of bytes between consecutive stage validation index entries.

  • stageIndexOffset is the offset in bytes from the beginning of the pipeline cache header to the stage validation index for this pipeline. This value must be zero if no stage validation information is present for this pipeline.

Description

The JSON data and the stage validation index are optionally included in the pipeline cache index entry. They are only intended to be used for validation and debugging. If present they must include both the JSON data and the corresponding SPIR-V modules that were used by the offline compiler to compile the pipeline cache entry.

The data at jsonOffset consists of a byte stream of jsonSize bytes of UTF-8 encoded JSON that was used by the offline pipeline compiler to create this pipeline cache entry.

The stage validation index consists of stageIndexCount VkPipelineCacheStageValidationIndexEntry structures which provide the SPIR-V modules used by this pipeline and these are provided in the same order as provided to the VkPipelineShaderStageCreateInfo structure(s) in the Vk*PipelineCreateInfo structure for this pipeline. The stage validation index is located at stageIndexOffset bytes into the cache and the location of stage i is calculated as: stageIndexOffset + i × stageIndexStride. The VkPipelineCacheStageValidationIndexEntry structures may not be tightly packed, enabling additional implementation-specific data to be stored with each entry, or for future extensibility.

Unlike most structures declared by the Vulkan API, all fields of this structure are written with the least significant byte first, regardless of host byte-order.

The C language specification does not define the packing of structure members. This layout assumes tight structure member packing, with members laid out in the order listed in the structure, and the intended size of the structure is 56 bytes. If a compiler produces code that diverges from that pattern, applications must employ another method to set values at the correct offsets.

Valid Usage

  • VUID-VkPipelineCacheSafetyCriticalIndexEntry-jsonSize-05080
    If jsonSize is 0, jsonOffset must be 0

  • VUID-VkPipelineCacheSafetyCriticalIndexEntry-jsonSize-05081
    If jsonSize is 0, stageIndexCount must be 0

  • VUID-VkPipelineCacheSafetyCriticalIndexEntry-jsonSize-08991
    If jsonSize is not 0, jsonOffset + jsonSize must not exceed the size of the pipeline cache

  • VUID-VkPipelineCacheSafetyCriticalIndexEntry-stageIndexCount-05082
    If stageIndexCount is 0, stageIndexOffset and stageIndexStride must be 0

  • VUID-VkPipelineCacheSafetyCriticalIndexEntry-stageIndexCount-05083
    If stageIndexCount is not 0, stageIndexStride must be greater than or equal to 16 (the size of the VkPipelineCacheStageValidationIndexEntry structure)

  • VUID-VkPipelineCacheSafetyCriticalIndexEntry-stageIndexCount-05084
    If stageIndexCount is not 0, stageIndexOffset + stageIndexCount × stageIndexStride must not exceed the size of the pipeline cache

See Also

VKSC_VERSION_1_0

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