10. Pipelines

The following figure shows a block diagram of the Vulkan pipelines. Some Vulkan commands specify geometric objects to be drawn or computational work to be performed, while others specify state controlling how objects are handled by the various pipeline stages, or control data transfer between memory organized as images and buffers. Commands are effectively sent through a processing pipeline, either a graphics pipeline, a ray tracing pipeline, or a compute pipeline.

The first stage of the graphics pipeline (Input Assembler) assembles vertices to form geometric primitives such as points, lines, and triangles, based on a requested primitive topology. In the next stage (Vertex Shader) vertices can be transformed, computing positions and attributes for each vertex. If tessellation and/or geometry shaders are supported, they can then generate multiple primitives from a single input primitive, possibly changing the primitive topology or generating additional attribute data in the process.

The final resulting primitives are clipped to a clip volume in preparation for the next stage, Rasterization. The rasterizer produces a series of fragments associated with a region of the framebuffer, from a two-dimensional description of a point, line segment, or triangle. These fragments are processed by fragment operations to determine whether generated values will be written to the framebuffer. Fragment shading determines the values to be written to the framebuffer attachments. Framebuffer operations then read and write the color and depth/stencil attachments of the framebuffer for a given subpass of a render pass instance. The attachments can be used as input attachments in the fragment shader in a later subpass of the same render pass.

The compute pipeline is a separate pipeline from the graphics pipeline, which operates on one-, two-, or three-dimensional workgroups which can read from and write to buffer and image memory.

This ordering is meant only as a tool for describing Vulkan, not as a strict rule of how Vulkan is implemented, and we present it only as a means to organize the various operations of the pipelines. Actual ordering guarantees between pipeline stages are explained in detail in the synchronization chapter.

image/svg+xml Vertex Shader Draw Input Assembler Tessellation Control Shader Tessellation Primitive Generator Tessellation Evaluation Shader Rasterization Indirect Buffer Descriptor Sets Legend Geometry Shader Vertex Post-Processing Early Per-Fragment Tests Fragment Shader Late Per-Fragment Tests Blending Index Buffer Vertex Buffers Push Constants Uniform Buffers Uniform Texel Buffers Sampled Images Storage Buffers Storage Texel Buffers Storage Images Compute Shader Dispatch Depth/Stencil Attachments Input Attachments Color Attachments Fixed Function Stage Shader Stage Storage Images
Figure 2. Block diagram of the Vulkan pipeline

Each pipeline is controlled by a monolithic object created from a description of all of the shader stages and any relevant fixed-function stages. Linking the whole pipeline together allows the optimization of shaders based on their input/outputs and eliminates expensive draw time state validation.

A pipeline object is bound to the current state using vkCmdBindPipeline. Any pipeline object state that is specified as dynamic is not applied to the current state when the pipeline object is bound, but is instead set by dynamic state setting commands.

No state, including dynamic state, is inherited from one command buffer to another.

Compute, ray tracing, and graphics pipelines are each represented by VkPipeline handles:

// Provided by VK_VERSION_1_0
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkPipeline)

10.1. Compute Pipelines

Compute pipelines consist of a single static compute shader stage and the pipeline layout.

The compute pipeline represents a compute shader and is created by calling vkCreateComputePipelines with module and pName selecting an entry point from a shader module, where that entry point defines a valid compute shader, in the VkPipelineShaderStageCreateInfo structure contained within the VkComputePipelineCreateInfo structure.

To create compute pipelines, call:

// Provided by VK_VERSION_1_0
VkResult vkCreateComputePipelines(
    VkDevice                                    device,
    VkPipelineCache                             pipelineCache,
    uint32_t                                    createInfoCount,
    const VkComputePipelineCreateInfo*          pCreateInfos,
    const VkAllocationCallbacks*                pAllocator,
    VkPipeline*                                 pPipelines);
  • device is the logical device that creates the compute pipelines.

  • pipelineCache is either VK_NULL_HANDLE, indicating that pipeline caching is disabled; or the handle of a valid pipeline cache object, in which case use of that cache is enabled for the duration of the command.

  • createInfoCount is the length of the pCreateInfos and pPipelines arrays.

  • pCreateInfos is a pointer to an array of VkComputePipelineCreateInfo structures.

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

  • pPipelines is a pointer to an array of VkPipeline handles in which the resulting compute pipeline objects are returned.

Valid Usage
  • VUID-vkCreateComputePipelines-flags-00695
    If the flags member of any element of pCreateInfos contains the VK_PIPELINE_CREATE_DERIVATIVE_BIT flag, and the basePipelineIndex member of that same element is not -1, basePipelineIndex must be less than the index into pCreateInfos that corresponds to that element

  • VUID-vkCreateComputePipelines-flags-00696
    If the flags member of any element of pCreateInfos contains the VK_PIPELINE_CREATE_DERIVATIVE_BIT flag, the base pipeline must have been created with the VK_PIPELINE_CREATE_ALLOW_DERIVATIVES_BIT flag set

Valid Usage (Implicit)
  • VUID-vkCreateComputePipelines-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkCreateComputePipelines-pipelineCache-parameter
    If pipelineCache is not VK_NULL_HANDLE, pipelineCache must be a valid VkPipelineCache handle

  • VUID-vkCreateComputePipelines-pCreateInfos-parameter
    pCreateInfos must be a valid pointer to an array of createInfoCount valid VkComputePipelineCreateInfo structures

  • VUID-vkCreateComputePipelines-pAllocator-parameter
    If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure

  • VUID-vkCreateComputePipelines-pPipelines-parameter
    pPipelines must be a valid pointer to an array of createInfoCount VkPipeline handles

  • VUID-vkCreateComputePipelines-createInfoCount-arraylength
    createInfoCount must be greater than 0

  • VUID-vkCreateComputePipelines-pipelineCache-parent
    If pipelineCache is a valid handle, it must have been created, allocated, or retrieved from device

Return Codes
Success
  • VK_SUCCESS

Failure
  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

The VkComputePipelineCreateInfo structure is defined as:

// Provided by VK_VERSION_1_0
typedef struct VkComputePipelineCreateInfo {
    VkStructureType                    sType;
    const void*                        pNext;
    VkPipelineCreateFlags              flags;
    VkPipelineShaderStageCreateInfo    stage;
    VkPipelineLayout                   layout;
    VkPipeline                         basePipelineHandle;
    int32_t                            basePipelineIndex;
} VkComputePipelineCreateInfo;
  • sType is the type of this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • flags is a bitmask of VkPipelineCreateFlagBits specifying how the pipeline will be generated.

  • stage is a VkPipelineShaderStageCreateInfo structure describing the compute shader.

  • layout is the description of binding locations used by both the pipeline and descriptor sets used with the pipeline.

  • basePipelineHandle is a pipeline to derive from

  • basePipelineIndex is an index into the pCreateInfos parameter to use as a pipeline to derive from

The parameters basePipelineHandle and basePipelineIndex are described in more detail in Pipeline Derivatives.

Valid Usage
  • VUID-VkComputePipelineCreateInfo-flags-00697
    If flags contains the VK_PIPELINE_CREATE_DERIVATIVE_BIT flag, and basePipelineIndex is -1, basePipelineHandle must be a valid handle to a compute VkPipeline

  • VUID-VkComputePipelineCreateInfo-flags-00698
    If flags contains the VK_PIPELINE_CREATE_DERIVATIVE_BIT flag, and basePipelineHandle is VK_NULL_HANDLE, basePipelineIndex must be a valid index into the calling command’s pCreateInfos parameter

  • VUID-VkComputePipelineCreateInfo-flags-00699
    If flags contains the VK_PIPELINE_CREATE_DERIVATIVE_BIT flag, and basePipelineIndex is not -1, basePipelineHandle must be VK_NULL_HANDLE

  • VUID-VkComputePipelineCreateInfo-flags-00700
    If flags contains the VK_PIPELINE_CREATE_DERIVATIVE_BIT flag, and basePipelineHandle is not VK_NULL_HANDLE, basePipelineIndex must be -1

  • VUID-VkComputePipelineCreateInfo-stage-00701
    The stage member of stage must be VK_SHADER_STAGE_COMPUTE_BIT

  • VUID-VkComputePipelineCreateInfo-stage-00702
    The shader code for the entry point identified by stage and the rest of the state identified by this structure must adhere to the pipeline linking rules described in the Shader Interfaces chapter

  • VUID-VkComputePipelineCreateInfo-layout-00703
    layout must be consistent with the layout of the compute shader specified in stage

  • VUID-VkComputePipelineCreateInfo-layout-01687
    The number of resources in layout accessible to the compute shader stage must be less than or equal to VkPhysicalDeviceLimits::maxPerStageResources

  • VUID-VkComputePipelineCreateInfo-flags-03364
    flags must not include VK_PIPELINE_CREATE_LIBRARY_BIT_KHR

  • VUID-VkComputePipelineCreateInfo-flags-03365
    flags must not include VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_ANY_HIT_SHADERS_BIT_KHR

  • VUID-VkComputePipelineCreateInfo-flags-03366
    flags must not include VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_CLOSEST_HIT_SHADERS_BIT_KHR

  • VUID-VkComputePipelineCreateInfo-flags-03367
    flags must not include VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_MISS_SHADERS_BIT_KHR

  • VUID-VkComputePipelineCreateInfo-flags-03368
    flags must not include VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_INTERSECTION_SHADERS_BIT_KHR

  • VUID-VkComputePipelineCreateInfo-flags-03369
    flags must not include VK_PIPELINE_CREATE_RAY_TRACING_SKIP_TRIANGLES_BIT_KHR

  • VUID-VkComputePipelineCreateInfo-flags-03370
    flags must not include VK_PIPELINE_CREATE_RAY_TRACING_SKIP_AABBS_BIT_KHR

  • VUID-VkComputePipelineCreateInfo-flags-03576
    flags must not include VK_PIPELINE_CREATE_RAY_TRACING_SHADER_GROUP_HANDLE_CAPTURE_REPLAY_BIT_KHR

Valid Usage (Implicit)
  • VUID-VkComputePipelineCreateInfo-sType-sType
    sType must be VK_STRUCTURE_TYPE_COMPUTE_PIPELINE_CREATE_INFO

  • VUID-VkComputePipelineCreateInfo-pNext-pNext
    pNext must be NULL

  • VUID-VkComputePipelineCreateInfo-flags-parameter
    flags must be a valid combination of VkPipelineCreateFlagBits values

  • VUID-VkComputePipelineCreateInfo-stage-parameter
    stage must be a valid VkPipelineShaderStageCreateInfo structure

  • VUID-VkComputePipelineCreateInfo-layout-parameter
    layout must be a valid VkPipelineLayout handle

  • VUID-VkComputePipelineCreateInfo-commonparent
    Both of basePipelineHandle, and layout that are valid handles of non-ignored parameters must have been created, allocated, or retrieved from the same VkDevice

The VkPipelineShaderStageCreateInfo structure is defined as:

// Provided by VK_VERSION_1_0
typedef struct VkPipelineShaderStageCreateInfo {
    VkStructureType                     sType;
    const void*                         pNext;
    VkPipelineShaderStageCreateFlags    flags;
    VkShaderStageFlagBits               stage;
    VkShaderModule                      module;
    const char*                         pName;
    const VkSpecializationInfo*         pSpecializationInfo;
} VkPipelineShaderStageCreateInfo;
  • sType is the type of this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • flags is a bitmask of VkPipelineShaderStageCreateFlagBits specifying how the pipeline shader stage will be generated.

  • stage is a VkShaderStageFlagBits value specifying a single pipeline stage.

  • module is a VkShaderModule object containing the shader for this stage.

  • pName is a pointer to a null-terminated UTF-8 string specifying the entry point name of the shader for this stage.

  • pSpecializationInfo is a pointer to a VkSpecializationInfo structure, as described in Specialization Constants, or NULL.

Valid Usage
  • VUID-VkPipelineShaderStageCreateInfo-stage-00704
    If the geometry shaders feature is not enabled, stage must not be VK_SHADER_STAGE_GEOMETRY_BIT

  • VUID-VkPipelineShaderStageCreateInfo-stage-00705
    If the tessellation shaders feature is not enabled, stage must not be VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT or VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT

  • VUID-VkPipelineShaderStageCreateInfo-stage-00706
    stage must not be VK_SHADER_STAGE_ALL_GRAPHICS, or VK_SHADER_STAGE_ALL

  • VUID-VkPipelineShaderStageCreateInfo-pName-00707
    pName must be the name of an OpEntryPoint in module with an execution model that matches stage

  • VUID-VkPipelineShaderStageCreateInfo-maxClipDistances-00708
    If the identified entry point includes any variable in its interface that is declared with the ClipDistance BuiltIn decoration, that variable must not have an array size greater than VkPhysicalDeviceLimits::maxClipDistances

  • VUID-VkPipelineShaderStageCreateInfo-maxCullDistances-00709
    If the identified entry point includes any variable in its interface that is declared with the CullDistance BuiltIn decoration, that variable must not have an array size greater than VkPhysicalDeviceLimits::maxCullDistances

  • VUID-VkPipelineShaderStageCreateInfo-maxCombinedClipAndCullDistances-00710
    If the identified entry point includes any variables in its interface that are declared with the ClipDistance or CullDistance BuiltIn decoration, those variables must not have array sizes which sum to more than VkPhysicalDeviceLimits::maxCombinedClipAndCullDistances

  • VUID-VkPipelineShaderStageCreateInfo-maxSampleMaskWords-00711
    If the identified entry point includes any variable in its interface that is declared with the SampleMask BuiltIn decoration, that variable must not have an array size greater than VkPhysicalDeviceLimits::maxSampleMaskWords

  • VUID-VkPipelineShaderStageCreateInfo-stage-00712
    If stage is VK_SHADER_STAGE_VERTEX_BIT, the identified entry point must not include any input variable in its interface that is decorated with CullDistance

  • VUID-VkPipelineShaderStageCreateInfo-stage-00713
    If stage is VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT or VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT, and the identified entry point has an OpExecutionMode instruction that specifies a patch size with OutputVertices, the patch size must be greater than 0 and less than or equal to VkPhysicalDeviceLimits::maxTessellationPatchSize

  • VUID-VkPipelineShaderStageCreateInfo-stage-00714
    If stage is VK_SHADER_STAGE_GEOMETRY_BIT, the identified entry point must have an OpExecutionMode instruction that specifies a maximum output vertex count that is greater than 0 and less than or equal to VkPhysicalDeviceLimits::maxGeometryOutputVertices

  • VUID-VkPipelineShaderStageCreateInfo-stage-00715
    If stage is VK_SHADER_STAGE_GEOMETRY_BIT, the identified entry point must have an OpExecutionMode instruction that specifies an invocation count that is greater than 0 and less than or equal to VkPhysicalDeviceLimits::maxGeometryShaderInvocations

  • VUID-VkPipelineShaderStageCreateInfo-stage-02596
    If stage is a vertex processing stage, and the identified entry point writes to Layer for any primitive, it must write the same value to Layer for all vertices of a given primitive

  • VUID-VkPipelineShaderStageCreateInfo-stage-02597
    If stage is a vertex processing stage, and the identified entry point writes to ViewportIndex for any primitive, it must write the same value to ViewportIndex for all vertices of a given primitive

  • VUID-VkPipelineShaderStageCreateInfo-stage-00718
    If stage is VK_SHADER_STAGE_FRAGMENT_BIT, the identified entry point must not include any output variables in its interface decorated with CullDistance

  • VUID-VkPipelineShaderStageCreateInfo-stage-00719
    If stage is VK_SHADER_STAGE_FRAGMENT_BIT, and the identified entry point writes to FragDepth in any execution path, it must write to FragDepth in all execution paths

  • VUID-VkPipelineShaderStageCreateInfo-module-04145
    The SPIR-V code that was used to create module must be valid as described by the Khronos SPIR-V Specification after applying the specializations provided in pSpecializationInfo, if any, and then converting all specialization constants into fixed constants.

Valid Usage (Implicit)
  • VUID-VkPipelineShaderStageCreateInfo-sType-sType
    sType must be VK_STRUCTURE_TYPE_PIPELINE_SHADER_STAGE_CREATE_INFO

  • VUID-VkPipelineShaderStageCreateInfo-pNext-pNext
    pNext must be NULL

  • VUID-VkPipelineShaderStageCreateInfo-flags-zerobitmask
    flags must be 0

  • VUID-VkPipelineShaderStageCreateInfo-stage-parameter
    stage must be a valid VkShaderStageFlagBits value

  • VUID-VkPipelineShaderStageCreateInfo-module-parameter
    module must be a valid VkShaderModule handle

  • VUID-VkPipelineShaderStageCreateInfo-pName-parameter
    pName must be a null-terminated UTF-8 string

  • VUID-VkPipelineShaderStageCreateInfo-pSpecializationInfo-parameter
    If pSpecializationInfo is not NULL, pSpecializationInfo must be a valid pointer to a valid VkSpecializationInfo structure

// Provided by VK_VERSION_1_0
typedef VkFlags VkPipelineShaderStageCreateFlags;

VkPipelineShaderStageCreateFlags is a bitmask type for setting a mask of zero or more VkPipelineShaderStageCreateFlagBits.

Possible values of the flags member of VkPipelineShaderStageCreateInfo specifying how a pipeline shader stage is created, are:

// Provided by VK_VERSION_1_0
typedef enum VkPipelineShaderStageCreateFlagBits {
} VkPipelineShaderStageCreateFlagBits;

Commands and structures which need to specify one or more shader stages do so using a bitmask whose bits correspond to stages. Bits which can be set to specify shader stages are:

// Provided by VK_VERSION_1_0
typedef enum VkShaderStageFlagBits {
    VK_SHADER_STAGE_VERTEX_BIT = 0x00000001,
    VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT = 0x00000002,
    VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT = 0x00000004,
    VK_SHADER_STAGE_GEOMETRY_BIT = 0x00000008,
    VK_SHADER_STAGE_FRAGMENT_BIT = 0x00000010,
    VK_SHADER_STAGE_COMPUTE_BIT = 0x00000020,
    VK_SHADER_STAGE_ALL_GRAPHICS = 0x0000001F,
    VK_SHADER_STAGE_ALL = 0x7FFFFFFF,
  // Provided by VK_KHR_ray_tracing_pipeline
    VK_SHADER_STAGE_RAYGEN_BIT_KHR = 0x00000100,
  // Provided by VK_KHR_ray_tracing_pipeline
    VK_SHADER_STAGE_ANY_HIT_BIT_KHR = 0x00000200,
  // Provided by VK_KHR_ray_tracing_pipeline
    VK_SHADER_STAGE_CLOSEST_HIT_BIT_KHR = 0x00000400,
  // Provided by VK_KHR_ray_tracing_pipeline
    VK_SHADER_STAGE_MISS_BIT_KHR = 0x00000800,
  // Provided by VK_KHR_ray_tracing_pipeline
    VK_SHADER_STAGE_INTERSECTION_BIT_KHR = 0x00001000,
  // Provided by VK_KHR_ray_tracing_pipeline
    VK_SHADER_STAGE_CALLABLE_BIT_KHR = 0x00002000,
} VkShaderStageFlagBits;
  • VK_SHADER_STAGE_VERTEX_BIT specifies the vertex stage.

  • VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT specifies the tessellation control stage.

  • VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT specifies the tessellation evaluation stage.

  • VK_SHADER_STAGE_GEOMETRY_BIT specifies the geometry stage.

  • VK_SHADER_STAGE_FRAGMENT_BIT specifies the fragment stage.

  • VK_SHADER_STAGE_COMPUTE_BIT specifies the compute stage.

  • VK_SHADER_STAGE_ALL_GRAPHICS is a combination of bits used as shorthand to specify all graphics stages defined above (excluding the compute stage).

  • VK_SHADER_STAGE_ALL is a combination of bits used as shorthand to specify all shader stages supported by the device, including all additional stages which are introduced by extensions.

  • VK_SHADER_STAGE_RAYGEN_BIT_KHR specifies the ray generation stage.

  • VK_SHADER_STAGE_ANY_HIT_BIT_KHR specifies the any-hit stage.

  • VK_SHADER_STAGE_CLOSEST_HIT_BIT_KHR specifies the closest hit stage.

  • VK_SHADER_STAGE_MISS_BIT_KHR specifies the miss stage.

  • VK_SHADER_STAGE_INTERSECTION_BIT_KHR specifies the intersection stage.

  • VK_SHADER_STAGE_CALLABLE_BIT_KHR specifies the callable stage.

Note

VK_SHADER_STAGE_ALL_GRAPHICS only includes the original five graphics stages included in Vulkan 1.0, and not any stages added by extensions. Thus, it may not have the desired effect in all cases.

// Provided by VK_VERSION_1_0
typedef VkFlags VkShaderStageFlags;

VkShaderStageFlags is a bitmask type for setting a mask of zero or more VkShaderStageFlagBits.

10.2. Graphics Pipelines

Graphics pipelines consist of multiple shader stages, multiple fixed-function pipeline stages, and a pipeline layout.

To create graphics pipelines, call:

// Provided by VK_VERSION_1_0
VkResult vkCreateGraphicsPipelines(
    VkDevice                                    device,
    VkPipelineCache                             pipelineCache,
    uint32_t                                    createInfoCount,
    const VkGraphicsPipelineCreateInfo*         pCreateInfos,
    const VkAllocationCallbacks*                pAllocator,
    VkPipeline*                                 pPipelines);
  • device is the logical device that creates the graphics pipelines.

  • pipelineCache is either VK_NULL_HANDLE, indicating that pipeline caching is disabled; or the handle of a valid pipeline cache object, in which case use of that cache is enabled for the duration of the command.

  • createInfoCount is the length of the pCreateInfos and pPipelines arrays.

  • pCreateInfos is a pointer to an array of VkGraphicsPipelineCreateInfo structures.

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

  • pPipelines is a pointer to an array of VkPipeline handles in which the resulting graphics pipeline objects are returned.

The VkGraphicsPipelineCreateInfo structure includes an array of shader create info structures containing all the desired active shader stages, as well as creation info to define all relevant fixed-function stages, and a pipeline layout.

Valid Usage
  • VUID-vkCreateGraphicsPipelines-flags-00720
    If the flags member of any element of pCreateInfos contains the VK_PIPELINE_CREATE_DERIVATIVE_BIT flag, and the basePipelineIndex member of that same element is not -1, basePipelineIndex must be less than the index into pCreateInfos that corresponds to that element

  • VUID-vkCreateGraphicsPipelines-flags-00721
    If the flags member of any element of pCreateInfos contains the VK_PIPELINE_CREATE_DERIVATIVE_BIT flag, the base pipeline must have been created with the VK_PIPELINE_CREATE_ALLOW_DERIVATIVES_BIT flag set

Valid Usage (Implicit)
  • VUID-vkCreateGraphicsPipelines-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkCreateGraphicsPipelines-pipelineCache-parameter
    If pipelineCache is not VK_NULL_HANDLE, pipelineCache must be a valid VkPipelineCache handle

  • VUID-vkCreateGraphicsPipelines-pCreateInfos-parameter
    pCreateInfos must be a valid pointer to an array of createInfoCount valid VkGraphicsPipelineCreateInfo structures

  • VUID-vkCreateGraphicsPipelines-pAllocator-parameter
    If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure

  • VUID-vkCreateGraphicsPipelines-pPipelines-parameter
    pPipelines must be a valid pointer to an array of createInfoCount VkPipeline handles

  • VUID-vkCreateGraphicsPipelines-createInfoCount-arraylength
    createInfoCount must be greater than 0

  • VUID-vkCreateGraphicsPipelines-pipelineCache-parent
    If pipelineCache is a valid handle, it must have been created, allocated, or retrieved from device

Return Codes
Success
  • VK_SUCCESS

Failure
  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

The VkGraphicsPipelineCreateInfo structure is defined as:

// Provided by VK_VERSION_1_0
typedef struct VkGraphicsPipelineCreateInfo {
    VkStructureType                                  sType;
    const void*                                      pNext;
    VkPipelineCreateFlags                            flags;
    uint32_t                                         stageCount;
    const VkPipelineShaderStageCreateInfo*           pStages;
    const VkPipelineVertexInputStateCreateInfo*      pVertexInputState;
    const VkPipelineInputAssemblyStateCreateInfo*    pInputAssemblyState;
    const VkPipelineTessellationStateCreateInfo*     pTessellationState;
    const VkPipelineViewportStateCreateInfo*         pViewportState;
    const VkPipelineRasterizationStateCreateInfo*    pRasterizationState;
    const VkPipelineMultisampleStateCreateInfo*      pMultisampleState;
    const VkPipelineDepthStencilStateCreateInfo*     pDepthStencilState;
    const VkPipelineColorBlendStateCreateInfo*       pColorBlendState;
    const VkPipelineDynamicStateCreateInfo*          pDynamicState;
    VkPipelineLayout                                 layout;
    VkRenderPass                                     renderPass;
    uint32_t                                         subpass;
    VkPipeline                                       basePipelineHandle;
    int32_t                                          basePipelineIndex;
} VkGraphicsPipelineCreateInfo;
  • sType is the type of this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • flags is a bitmask of VkPipelineCreateFlagBits specifying how the pipeline will be generated.

  • stageCount is the number of entries in the pStages array.

  • pStages is a pointer to an array of stageCount VkPipelineShaderStageCreateInfo structures describing the set of the shader stages to be included in the graphics pipeline.

  • pVertexInputState is a pointer to a VkPipelineVertexInputStateCreateInfo structure.

  • pInputAssemblyState is a pointer to a VkPipelineInputAssemblyStateCreateInfo structure which determines input assembly behavior, as described in Drawing Commands.

  • pTessellationState is a pointer to a VkPipelineTessellationStateCreateInfo structure, and is ignored if the pipeline does not include a tessellation control shader stage and tessellation evaluation shader stage.

  • pViewportState is a pointer to a VkPipelineViewportStateCreateInfo structure, and is ignored if the pipeline has rasterization disabled.

  • pRasterizationState is a pointer to a VkPipelineRasterizationStateCreateInfo structure.

  • pMultisampleState is a pointer to a VkPipelineMultisampleStateCreateInfo structure, and is ignored if the pipeline has rasterization disabled.

  • pDepthStencilState is a pointer to a VkPipelineDepthStencilStateCreateInfo structure, and is ignored if the pipeline has rasterization disabled or if the subpass of the render pass the pipeline is created against does not use a depth/stencil attachment.

  • pColorBlendState is a pointer to a VkPipelineColorBlendStateCreateInfo structure, and is ignored if the pipeline has rasterization disabled or if the subpass of the render pass the pipeline is created against does not use any color attachments.

  • pDynamicState is a pointer to a VkPipelineDynamicStateCreateInfo structure, and is used to indicate which properties of the pipeline state object are dynamic and can be changed independently of the pipeline state. This can be NULL, which means no state in the pipeline is considered dynamic.

  • layout is the description of binding locations used by both the pipeline and descriptor sets used with the pipeline.

  • renderPass is a handle to a render pass object describing the environment in which the pipeline will be used; the pipeline must only be used with an instance of any render pass compatible with the one provided. See Render Pass Compatibility for more information.

  • subpass is the index of the subpass in the render pass where this pipeline will be used.

  • basePipelineHandle is a pipeline to derive from.

  • basePipelineIndex is an index into the pCreateInfos parameter to use as a pipeline to derive from.

The parameters basePipelineHandle and basePipelineIndex are described in more detail in Pipeline Derivatives.

The state required for a graphics pipeline is divided into vertex input state, pre-rasterization shader state, fragment shader state, and fragment output state.

Vertex input state is defined by:

Pre-rasterization shader state is defined by:

Fragment shader state is defined by:

Fragment output state is defined by:

A complete graphics pipeline always includes pre-rasterization shader state, with other subsets included depending on that state. If the pre-rasterization shader state includes a vertex shader, then vertex input state is included in a complete graphics pipeline. If the value of VkPipelineRasterizationStateCreateInfo::rasterizerDiscardEnable in the pre-rasterization shader state is VK_FALSE fragment shader state and fragment output interface state is included in a complete graphics pipeline.

Pipelines must be created with a complete set of pipeline state.

Valid Usage
  • VUID-VkGraphicsPipelineCreateInfo-flags-00722
    If flags contains the VK_PIPELINE_CREATE_DERIVATIVE_BIT flag, and basePipelineIndex is -1, basePipelineHandle must be a valid handle to a graphics VkPipeline

  • VUID-VkGraphicsPipelineCreateInfo-flags-00723
    If flags contains the VK_PIPELINE_CREATE_DERIVATIVE_BIT flag, and basePipelineHandle is VK_NULL_HANDLE, basePipelineIndex must be a valid index into the calling command’s pCreateInfos parameter

  • VUID-VkGraphicsPipelineCreateInfo-flags-00724
    If flags contains the VK_PIPELINE_CREATE_DERIVATIVE_BIT flag, and basePipelineIndex is not -1, basePipelineHandle must be VK_NULL_HANDLE

  • VUID-VkGraphicsPipelineCreateInfo-flags-00725
    If flags contains the VK_PIPELINE_CREATE_DERIVATIVE_BIT flag, and basePipelineHandle is not VK_NULL_HANDLE, basePipelineIndex must be -1

  • VUID-VkGraphicsPipelineCreateInfo-stage-00726
    The stage member of each element of pStages must be unique

  • VUID-VkGraphicsPipelineCreateInfo-stage-00727
    If the pipeline is being created with pre-rasterization shader state the stage member of one element of pStages must be VK_SHADER_STAGE_VERTEX_BIT

  • VUID-VkGraphicsPipelineCreateInfo-stage-00728
    The stage member of each element of pStages must not be VK_SHADER_STAGE_COMPUTE_BIT

  • VUID-VkGraphicsPipelineCreateInfo-pStages-00729
    If the pipeline is being created with pre-rasterization shader state and pStages includes a tessellation control shader stage, it must include a tessellation evaluation shader stage

  • VUID-VkGraphicsPipelineCreateInfo-pStages-00730
    If the pipeline is being created with pre-rasterization shader state and pStages includes a tessellation evaluation shader stage, it must include a tessellation control shader stage

  • VUID-VkGraphicsPipelineCreateInfo-pStages-00731
    If the pipeline is being created with pre-rasterization shader state and pStages includes a tessellation control shader stage and a tessellation evaluation shader stage, pTessellationState must be a valid pointer to a valid VkPipelineTessellationStateCreateInfo structure

  • VUID-VkGraphicsPipelineCreateInfo-pStages-00732
    If the pipeline is being created with pre-rasterization shader state and pStages includes tessellation shader stages, the shader code of at least one stage must contain an OpExecutionMode instruction that specifies the type of subdivision in the pipeline

  • VUID-VkGraphicsPipelineCreateInfo-pStages-00733
    If the pipeline is being created with pre-rasterization shader state and pStages includes tessellation shader stages, and the shader code of both stages contain an OpExecutionMode instruction that specifies the type of subdivision in the pipeline, they must both specify the same subdivision mode

  • VUID-VkGraphicsPipelineCreateInfo-pStages-00734
    If the pipeline is being created with pre-rasterization shader state and pStages includes tessellation shader stages, the shader code of at least one stage must contain an OpExecutionMode instruction that specifies the output patch size in the pipeline

  • VUID-VkGraphicsPipelineCreateInfo-pStages-00735
    If the pipeline is being created with pre-rasterization shader state and pStages includes tessellation shader stages, and the shader code of both contain an OpExecutionMode instruction that specifies the out patch size in the pipeline, they must both specify the same patch size

  • VUID-VkGraphicsPipelineCreateInfo-pStages-00736
    If the pipeline is being created with pre-rasterization shader state and pStages includes tessellation shader stages, the topology member of pInputAssembly must be VK_PRIMITIVE_TOPOLOGY_PATCH_LIST

  • VUID-VkGraphicsPipelineCreateInfo-topology-00737
    If the pipeline is being created with pre-rasterization shader state and the topology member of pInputAssembly is VK_PRIMITIVE_TOPOLOGY_PATCH_LIST, pStages must include tessellation shader stages

  • VUID-VkGraphicsPipelineCreateInfo-pStages-00738
    If the pipeline is being created with pre-rasterization shader state and pStages includes a geometry shader stage, and does not include any tessellation shader stages, its shader code must contain an OpExecutionMode instruction that specifies an input primitive type that is compatible with the primitive topology specified in pInputAssembly

  • VUID-VkGraphicsPipelineCreateInfo-pStages-00739
    If the pipeline is being created with pre-rasterization shader state and pStages includes a geometry shader stage, and also includes tessellation shader stages, its shader code must contain an OpExecutionMode instruction that specifies an input primitive type that is compatible with the primitive topology that is output by the tessellation stages

  • VUID-VkGraphicsPipelineCreateInfo-pStages-00740
    If the pipeline is being created with pre-rasterization shader state and fragment shader state, it includes both a fragment shader and a geometry shader, and the fragment shader code reads from an input variable that is decorated with PrimitiveID, then the geometry shader code must write to a matching output variable, decorated with PrimitiveID, in all execution paths

  • VUID-VkGraphicsPipelineCreateInfo-pStages-00741
    If the pipeline is being created with fragment shader state the fragment shader must not read from any input attachment that is defined as VK_ATTACHMENT_UNUSED in subpass

  • VUID-VkGraphicsPipelineCreateInfo-pStages-00742
    If the pipeline is being created with pre-rasterization shader state and multiple pre-rasterization shader stages are included in pStages, the shader code for the entry points identified by those pStages and the rest of the state identified by this structure must adhere to the pipeline linking rules described in the Shader Interfaces chapter

  • VUID-VkGraphicsPipelineCreateInfo-None-04889
    If the pipeline is being created with pre-rasterization shader state and fragment shader state, the fragment shader and last vertex processing shader stage and any relevant state must adhere to the pipeline linking rules described in the Shader Interfaces chapter

  • VUID-VkGraphicsPipelineCreateInfo-subpass-04890
    If the pipeline is being created with fragment shader state, and subpass uses a depth/stencil attachment in renderPass with a read-only layout for the depth aspect in the VkAttachmentReference defined by subpass, the depthWriteEnable member of pDepthStencilState must be VK_FALSE

  • VUID-VkGraphicsPipelineCreateInfo-subpass-04891
    If the pipeline is being created with fragment shader state, and subpass uses a depth/stencil attachment in renderPass with a read-only layout for the stencil aspect in the VkAttachmentReference defined by subpass, the failOp, passOp and depthFailOp members of each of the front and back members of pDepthStencilState must be VK_STENCIL_OP_KEEP

  • VUID-VkGraphicsPipelineCreateInfo-blendEnable-04717
    If the pipeline is being created with fragment output interface state, then for each color attachment in the subpass, if the potential format features of the format of the corresponding attachment description do not contain VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BLEND_BIT, then the blendEnable member of the corresponding element of the pAttachments member of pColorBlendState must be VK_FALSE

  • VUID-VkGraphicsPipelineCreateInfo-attachmentCount-00746
    If the pipeline is being created with fragment output interface state, and the subpass uses color attachments, the attachmentCount member of pColorBlendState must be equal to the colorAttachmentCount used to create subpass

  • VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-00747
    If the pipeline is being created with pre-rasterization shader state, and no element of the pDynamicStates member of pDynamicState is VK_DYNAMIC_STATE_VIEWPORT, the pViewports member of pViewportState must be a valid pointer to an array of pViewportState->viewportCount valid VkViewport structures

  • VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-00748
    If the pipeline is being created with pre-rasterization shader state, and no element of the pDynamicStates member of pDynamicState is VK_DYNAMIC_STATE_SCISSOR, the pScissors member of pViewportState must be a valid pointer to an array of pViewportState->scissorCount VkRect2D structures

  • VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-00749
    If the pipeline is being created with pre-rasterization shader state, and the wide lines feature is not enabled, and no element of the pDynamicStates member of pDynamicState is VK_DYNAMIC_STATE_LINE_WIDTH, the lineWidth member of pRasterizationState must be 1.0

  • VUID-VkGraphicsPipelineCreateInfo-rasterizerDiscardEnable-00750
    If the pipeline is being created with pre-rasterization shader state, and the rasterizerDiscardEnable member of pRasterizationState is VK_FALSE, pViewportState must be a valid pointer to a valid VkPipelineViewportStateCreateInfo structure

  • VUID-VkGraphicsPipelineCreateInfo-rasterizerDiscardEnable-00751
    If the pipeline is being created with fragment shader state, pMultisampleState must be a valid pointer to a valid VkPipelineMultisampleStateCreateInfo structure

  • VUID-VkGraphicsPipelineCreateInfo-rasterizerDiscardEnable-00752
    If the pipeline is being created with fragment shader state, and subpass uses a depth/stencil attachment, pDepthStencilState must be a valid pointer to a valid VkPipelineDepthStencilStateCreateInfo structure

  • VUID-VkGraphicsPipelineCreateInfo-rasterizerDiscardEnable-00753
    If the pipeline is being created with fragment output interface state, and subpass uses color attachments, pColorBlendState must be a valid pointer to a valid VkPipelineColorBlendStateCreateInfo structure

  • VUID-VkGraphicsPipelineCreateInfo-rasterizerDiscardEnable-04493
    If the pipeline is being created with fragment output interface state, pColorBlendState->attachmentCount must be greater than the index of all color attachments that are not VK_ATTACHMENT_UNUSED for the subpass index in renderPass

  • VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-00754
    If the pipeline is being created with pre-rasterization shader state, the depth bias clamping feature is not enabled, no element of the pDynamicStates member of pDynamicState is VK_DYNAMIC_STATE_DEPTH_BIAS, and the depthBiasEnable member of pRasterizationState is VK_TRUE, the depthBiasClamp member of pRasterizationState must be 0.0

  • VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-00755
    If the pipeline is being created with fragment shader state, and no element of the pDynamicStates member of pDynamicState is VK_DYNAMIC_STATE_DEPTH_BOUNDS, and the depthBoundsTestEnable member of pDepthStencilState is VK_TRUE, the minDepthBounds and maxDepthBounds members of pDepthStencilState must be between 0.0 and 1.0, inclusive

  • VUID-VkGraphicsPipelineCreateInfo-layout-00756
    layout must be consistent with all shaders specified in pStages

  • VUID-VkGraphicsPipelineCreateInfo-subpass-00757
    If the pipeline is being created with fragment shader state, and neither the [VK_AMD_mixed_attachment_samples] nor the [VK_NV_framebuffer_mixed_samples] extensions are enabled, and if subpass uses color and/or depth/stencil attachments, then the rasterizationSamples member of pMultisampleState must be the same as the sample count for those subpass attachments

  • VUID-VkGraphicsPipelineCreateInfo-subpass-00758
    If the pipeline is being created with fragment shader state and subpass does not use any color and/or depth/stencil attachments, then the rasterizationSamples member of pMultisampleState must follow the rules for a zero-attachment subpass

  • VUID-VkGraphicsPipelineCreateInfo-subpass-00759
    subpass must be a valid subpass within renderPass

  • VUID-VkGraphicsPipelineCreateInfo-renderPass-00760
    If the pipeline is being created with pre-rasterization shader state, and the renderPass has multiview enabled and subpass has more than one bit set in the view mask and multiviewTessellationShader is not enabled, then pStages must not include tessellation shaders

  • VUID-VkGraphicsPipelineCreateInfo-renderPass-00761
    If the pipeline is being created with pre-rasterization shader state, and the renderPass has multiview enabled and subpass has more than one bit set in the view mask and multiviewGeometryShader is not enabled, then pStages must not include a geometry shader

  • VUID-VkGraphicsPipelineCreateInfo-renderPass-00762
    If the pipeline is being created with pre-rasterization shader state, and the renderPass has multiview enabled and subpass has more than one bit set in the view mask, shaders in the pipeline must not write to the Layer built-in output

  • VUID-VkGraphicsPipelineCreateInfo-renderPass-00763
    If the pipeline is being created with pre-rasterization shader state, and the renderPass has multiview enabled, then all shaders must not include variables decorated with the Layer built-in decoration in their interfaces

  • VUID-VkGraphicsPipelineCreateInfo-flags-00764
    flags must not contain the VK_PIPELINE_CREATE_DISPATCH_BASE flag

  • VUID-VkGraphicsPipelineCreateInfo-pStages-01565
    If the pipeline is being created with fragment shader state and an input attachment was referenced by an aspectMask at renderPass creation time, the fragment shader must only read from the aspects that were specified for that input attachment

  • VUID-VkGraphicsPipelineCreateInfo-layout-01688
    The number of resources in layout accessible to each shader stage that is used by the pipeline must be less than or equal to VkPhysicalDeviceLimits::maxPerStageResources

  • VUID-VkGraphicsPipelineCreateInfo-pStages-02097
    If the pipeline is being created with vertex input state, pVertexInputState must be a valid pointer to a valid VkPipelineVertexInputStateCreateInfo structure

  • VUID-VkGraphicsPipelineCreateInfo-pStages-02098
    If the pipeline is being created with vertex input state, pInputAssemblyState must be a valid pointer to a valid VkPipelineInputAssemblyStateCreateInfo structure

  • VUID-VkGraphicsPipelineCreateInfo-flags-03371
    flags must not include VK_PIPELINE_CREATE_LIBRARY_BIT_KHR

  • VUID-VkGraphicsPipelineCreateInfo-flags-03372
    flags must not include VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_ANY_HIT_SHADERS_BIT_KHR

  • VUID-VkGraphicsPipelineCreateInfo-flags-03373
    flags must not include VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_CLOSEST_HIT_SHADERS_BIT_KHR

  • VUID-VkGraphicsPipelineCreateInfo-flags-03374
    flags must not include VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_MISS_SHADERS_BIT_KHR

  • VUID-VkGraphicsPipelineCreateInfo-flags-03375
    flags must not include VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_INTERSECTION_SHADERS_BIT_KHR

  • VUID-VkGraphicsPipelineCreateInfo-flags-03376
    flags must not include VK_PIPELINE_CREATE_RAY_TRACING_SKIP_TRIANGLES_BIT_KHR

  • VUID-VkGraphicsPipelineCreateInfo-flags-03377
    flags must not include VK_PIPELINE_CREATE_RAY_TRACING_SKIP_AABBS_BIT_KHR

  • VUID-VkGraphicsPipelineCreateInfo-flags-03577
    flags must not include VK_PIPELINE_CREATE_RAY_TRACING_SHADER_GROUP_HANDLE_CAPTURE_REPLAY_BIT_KHR

  • VUID-VkGraphicsPipelineCreateInfo-pDynamicState-04494
    If the pipeline is being created with pre-rasterization shader state or fragment shader state and VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR is not included in pDynamicState->pDynamicStates, VkPipelineFragmentShadingRateStateCreateInfoKHR::fragmentSize.width must be greater than or equal to 1

  • VUID-VkGraphicsPipelineCreateInfo-pDynamicState-04495
    If the pipeline is being created with pre-rasterization shader state or fragment shader state and VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR is not included in pDynamicState->pDynamicStates, VkPipelineFragmentShadingRateStateCreateInfoKHR::fragmentSize.height must be greater than or equal to 1

  • VUID-VkGraphicsPipelineCreateInfo-pDynamicState-04496
    If the pipeline is being created with pre-rasterization shader state or fragment shader state and VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR is not included in pDynamicState->pDynamicStates, VkPipelineFragmentShadingRateStateCreateInfoKHR::fragmentSize.width must be a power-of-two value

  • VUID-VkGraphicsPipelineCreateInfo-pDynamicState-04497
    If the pipeline is being created with pre-rasterization shader state or fragment shader state and VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR is not included in pDynamicState->pDynamicStates, VkPipelineFragmentShadingRateStateCreateInfoKHR::fragmentSize.height must be a power-of-two value

  • VUID-VkGraphicsPipelineCreateInfo-pDynamicState-04498
    If the pipeline is being created with pre-rasterization shader state or fragment shader state and VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR is not included in pDynamicState->pDynamicStates, VkPipelineFragmentShadingRateStateCreateInfoKHR::fragmentSize.width must be less than or equal to 4

  • VUID-VkGraphicsPipelineCreateInfo-pDynamicState-04499
    If the pipeline is being created with pre-rasterization shader state or fragment shader state and VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR is not included in pDynamicState->pDynamicStates, VkPipelineFragmentShadingRateStateCreateInfoKHR::fragmentSize.height must be less than or equal to 4

  • VUID-VkGraphicsPipelineCreateInfo-pDynamicState-04500
    If the pipeline is being created with pre-rasterization shader state or fragment shader state and VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR is not included in pDynamicState->pDynamicStates, and the pipelineFragmentShadingRate feature is not enabled, VkPipelineFragmentShadingRateStateCreateInfoKHR::fragmentSize.width and VkPipelineFragmentShadingRateStateCreateInfoKHR::fragmentSize.height must both be equal to 1

  • VUID-VkGraphicsPipelineCreateInfo-pDynamicState-04501
    If the pipeline is being created with pre-rasterization shader state or fragment shader state and VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR is not included in pDynamicState->pDynamicStates, and the primitiveFragmentShadingRate feature is not enabled, VkPipelineFragmentShadingRateStateCreateInfoKHR::combinerOps[0] must be VK_FRAGMENT_SHADING_RATE_COMBINER_OP_KEEP_KHR

  • VUID-VkGraphicsPipelineCreateInfo-pDynamicState-04502
    If the pipeline is being created with pre-rasterization shader state or fragment shader state and VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR is not included in pDynamicState->pDynamicStates, and the attachmentFragmentShadingRate feature is not enabled, VkPipelineFragmentShadingRateStateCreateInfoKHR::combinerOps[1] must be VK_FRAGMENT_SHADING_RATE_COMBINER_OP_KEEP_KHR

  • VUID-VkGraphicsPipelineCreateInfo-primitiveFragmentShadingRateWithMultipleViewports-04504
    If the pipeline is being created with pre-rasterization shader state and the primitiveFragmentShadingRateWithMultipleViewports limit is not supported, and entry points specified in pStages write to the ViewportIndex built-in, they must not also write to the PrimitiveShadingRateKHR built-in

  • VUID-VkGraphicsPipelineCreateInfo-fragmentShadingRateNonTrivialCombinerOps-04506
    If the pipeline is being created with pre-rasterization shader state or fragment shader state, the fragmentShadingRateNonTrivialCombinerOps limit is not supported, and VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR is not included in pDynamicState->pDynamicStates, elements of VkPipelineFragmentShadingRateStateCreateInfoKHR::combinerOps must be VK_FRAGMENT_SHADING_RATE_COMBINER_OP_KEEP_KHR or VK_FRAGMENT_SHADING_RATE_COMBINER_OP_REPLACE_KHR

  • VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-03578
    All elements of the pDynamicStates member of pDynamicState must not be VK_DYNAMIC_STATE_RAY_TRACING_PIPELINE_STACK_SIZE_KHR

  • VUID-VkGraphicsPipelineCreateInfo-None-04893
    The pipeline must be created with a complete set of state

Valid Usage (Implicit)
  • VUID-VkGraphicsPipelineCreateInfo-sType-sType
    sType must be VK_STRUCTURE_TYPE_GRAPHICS_PIPELINE_CREATE_INFO

  • VUID-VkGraphicsPipelineCreateInfo-pNext-pNext
    pNext must be NULL or a pointer to a valid instance of VkPipelineFragmentShadingRateStateCreateInfoKHR

  • VUID-VkGraphicsPipelineCreateInfo-sType-unique
    The sType value of each struct in the pNext chain must be unique

  • VUID-VkGraphicsPipelineCreateInfo-flags-parameter
    flags must be a valid combination of VkPipelineCreateFlagBits values

  • VUID-VkGraphicsPipelineCreateInfo-pStages-parameter
    pStages must be a valid pointer to an array of stageCount valid VkPipelineShaderStageCreateInfo structures

  • VUID-VkGraphicsPipelineCreateInfo-pRasterizationState-parameter
    pRasterizationState must be a valid pointer to a valid VkPipelineRasterizationStateCreateInfo structure

  • VUID-VkGraphicsPipelineCreateInfo-pDynamicState-parameter
    If pDynamicState is not NULL, pDynamicState must be a valid pointer to a valid VkPipelineDynamicStateCreateInfo structure

  • VUID-VkGraphicsPipelineCreateInfo-layout-parameter
    layout must be a valid VkPipelineLayout handle

  • VUID-VkGraphicsPipelineCreateInfo-renderPass-parameter
    renderPass must be a valid VkRenderPass handle

  • VUID-VkGraphicsPipelineCreateInfo-stageCount-arraylength
    stageCount must be greater than 0

  • VUID-VkGraphicsPipelineCreateInfo-commonparent
    Each of basePipelineHandle, layout, and renderPass that are valid handles of non-ignored parameters must have been created, allocated, or retrieved from the same VkDevice

Possible values of the flags member of VkGraphicsPipelineCreateInfo, VkRayTracingPipelineCreateInfoKHR, and VkComputePipelineCreateInfo, specifying how a pipeline is created, are:

// Provided by VK_VERSION_1_0
typedef enum VkPipelineCreateFlagBits {
    VK_PIPELINE_CREATE_DISABLE_OPTIMIZATION_BIT = 0x00000001,
    VK_PIPELINE_CREATE_ALLOW_DERIVATIVES_BIT = 0x00000002,
    VK_PIPELINE_CREATE_DERIVATIVE_BIT = 0x00000004,
  // Provided by VK_VERSION_1_1
    VK_PIPELINE_CREATE_VIEW_INDEX_FROM_DEVICE_INDEX_BIT = 0x00000008,
  // Provided by VK_VERSION_1_1
    VK_PIPELINE_CREATE_DISPATCH_BASE_BIT = 0x00000010,
  // Provided by VK_KHR_ray_tracing_pipeline
    VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_ANY_HIT_SHADERS_BIT_KHR = 0x00004000,
  // Provided by VK_KHR_ray_tracing_pipeline
    VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_CLOSEST_HIT_SHADERS_BIT_KHR = 0x00008000,
  // Provided by VK_KHR_ray_tracing_pipeline
    VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_MISS_SHADERS_BIT_KHR = 0x00010000,
  // Provided by VK_KHR_ray_tracing_pipeline
    VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_INTERSECTION_SHADERS_BIT_KHR = 0x00020000,
  // Provided by VK_KHR_ray_tracing_pipeline
    VK_PIPELINE_CREATE_RAY_TRACING_SKIP_TRIANGLES_BIT_KHR = 0x00001000,
  // Provided by VK_KHR_ray_tracing_pipeline
    VK_PIPELINE_CREATE_RAY_TRACING_SKIP_AABBS_BIT_KHR = 0x00002000,
  // Provided by VK_KHR_ray_tracing_pipeline
    VK_PIPELINE_CREATE_RAY_TRACING_SHADER_GROUP_HANDLE_CAPTURE_REPLAY_BIT_KHR = 0x00080000,
  // Provided by VK_KHR_pipeline_executable_properties
    VK_PIPELINE_CREATE_CAPTURE_STATISTICS_BIT_KHR = 0x00000040,
  // Provided by VK_KHR_pipeline_executable_properties
    VK_PIPELINE_CREATE_CAPTURE_INTERNAL_REPRESENTATIONS_BIT_KHR = 0x00000080,
  // Provided by VK_KHR_pipeline_library
    VK_PIPELINE_CREATE_LIBRARY_BIT_KHR = 0x00000800,
    VK_PIPELINE_CREATE_DISPATCH_BASE = VK_PIPELINE_CREATE_DISPATCH_BASE_BIT,
  // Provided by VK_KHR_device_group
    VK_PIPELINE_CREATE_VIEW_INDEX_FROM_DEVICE_INDEX_BIT_KHR = VK_PIPELINE_CREATE_VIEW_INDEX_FROM_DEVICE_INDEX_BIT,
  // Provided by VK_KHR_device_group
    VK_PIPELINE_CREATE_DISPATCH_BASE_KHR = VK_PIPELINE_CREATE_DISPATCH_BASE,
} VkPipelineCreateFlagBits;
  • VK_PIPELINE_CREATE_DISABLE_OPTIMIZATION_BIT specifies that the created pipeline will not be optimized. Using this flag may reduce the time taken to create the pipeline.

  • VK_PIPELINE_CREATE_ALLOW_DERIVATIVES_BIT specifies that the pipeline to be created is allowed to be the parent of a pipeline that will be created in a subsequent pipeline creation call.

  • VK_PIPELINE_CREATE_DERIVATIVE_BIT specifies that the pipeline to be created will be a child of a previously created parent pipeline.

  • VK_PIPELINE_CREATE_VIEW_INDEX_FROM_DEVICE_INDEX_BIT specifies that any shader input variables decorated as ViewIndex will be assigned values as if they were decorated as DeviceIndex.

  • VK_PIPELINE_CREATE_DISPATCH_BASE specifies that a compute pipeline can be used with vkCmdDispatchBase with a non-zero base workgroup.

  • VK_PIPELINE_CREATE_CAPTURE_STATISTICS_BIT_KHR specifies that the shader compiler should capture statistics for the pipeline executables produced by the compile process which can later be retrieved by calling vkGetPipelineExecutableStatisticsKHR. Enabling this flag must not affect the final compiled pipeline but may disable pipeline caching or otherwise affect pipeline creation time.

  • VK_PIPELINE_CREATE_CAPTURE_INTERNAL_REPRESENTATIONS_BIT_KHR specifies that the shader compiler should capture the internal representations of pipeline executables produced by the compile process which can later be retrieved by calling vkGetPipelineExecutableInternalRepresentationsKHR. Enabling this flag must not affect the final compiled pipeline but may disable pipeline caching or otherwise affect pipeline creation time.

  • VK_PIPELINE_CREATE_LIBRARY_BIT_KHR specifies that the pipeline cannot be used directly, and instead defines a pipeline library that can be combined with other pipelines using the VkPipelineLibraryCreateInfoKHR structure. This is available in ray tracing pipelines.

  • VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_ANY_HIT_SHADERS_BIT_KHR specifies that an any-hit shader will always be present when an any-hit shader would be executed.

  • VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_CLOSEST_HIT_SHADERS_BIT_KHR specifies that a closest hit shader will always be present when a closest hit shader would be executed.

  • VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_MISS_SHADERS_BIT_KHR specifies that a miss shader will always be present when a miss shader would be executed.

  • VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_INTERSECTION_SHADERS_BIT_KHR specifies that an intersection shader will always be present when an intersection shader would be executed.

  • VK_PIPELINE_CREATE_RAY_TRACING_SKIP_TRIANGLES_BIT_KHR specifies that triangle primitives will be skipped during traversal using OpTraceRayKHR.

  • VK_PIPELINE_CREATE_RAY_TRACING_SKIP_AABBS_BIT_KHR specifies that AABB primitives will be skipped during traversal using OpTraceRayKHR.

  • VK_PIPELINE_CREATE_RAY_TRACING_SHADER_GROUP_HANDLE_CAPTURE_REPLAY_BIT_KHR specifies that the shader group handles can be saved and reused on a subsequent run (e.g. for trace capture and replay).

It is valid to set both VK_PIPELINE_CREATE_ALLOW_DERIVATIVES_BIT and VK_PIPELINE_CREATE_DERIVATIVE_BIT. This allows a pipeline to be both a parent and possibly a child in a pipeline hierarchy. See Pipeline Derivatives for more information.

// Provided by VK_VERSION_1_0
typedef VkFlags VkPipelineCreateFlags;

VkPipelineCreateFlags is a bitmask type for setting a mask of zero or more VkPipelineCreateFlagBits.

The VkPipelineDynamicStateCreateInfo structure is defined as:

// Provided by VK_VERSION_1_0
typedef struct VkPipelineDynamicStateCreateInfo {
    VkStructureType                      sType;
    const void*                          pNext;
    VkPipelineDynamicStateCreateFlags    flags;
    uint32_t                             dynamicStateCount;
    const VkDynamicState*                pDynamicStates;
} VkPipelineDynamicStateCreateInfo;
  • sType is the type of this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • flags is reserved for future use.

  • dynamicStateCount is the number of elements in the pDynamicStates array.

  • pDynamicStates is a pointer to an array of VkDynamicState values specifying which pieces of pipeline state will use the values from dynamic state commands rather than from pipeline state creation info.

Valid Usage
  • VUID-VkPipelineDynamicStateCreateInfo-pDynamicStates-01442
    Each element of pDynamicStates must be unique

Valid Usage (Implicit)
  • VUID-VkPipelineDynamicStateCreateInfo-sType-sType
    sType must be VK_STRUCTURE_TYPE_PIPELINE_DYNAMIC_STATE_CREATE_INFO

  • VUID-VkPipelineDynamicStateCreateInfo-pNext-pNext
    pNext must be NULL

  • VUID-VkPipelineDynamicStateCreateInfo-flags-zerobitmask
    flags must be 0

  • VUID-VkPipelineDynamicStateCreateInfo-pDynamicStates-parameter
    If dynamicStateCount is not 0, pDynamicStates must be a valid pointer to an array of dynamicStateCount valid VkDynamicState values

// Provided by VK_VERSION_1_0
typedef VkFlags VkPipelineDynamicStateCreateFlags;

VkPipelineDynamicStateCreateFlags is a bitmask type for setting a mask, but is currently reserved for future use.

The source of different pieces of dynamic state is specified by the VkPipelineDynamicStateCreateInfo::pDynamicStates property of the currently active pipeline, each of whose elements must be one of the values:

// Provided by VK_VERSION_1_0
typedef enum VkDynamicState {
    VK_DYNAMIC_STATE_VIEWPORT = 0,
    VK_DYNAMIC_STATE_SCISSOR = 1,
    VK_DYNAMIC_STATE_LINE_WIDTH = 2,
    VK_DYNAMIC_STATE_DEPTH_BIAS = 3,
    VK_DYNAMIC_STATE_BLEND_CONSTANTS = 4,
    VK_DYNAMIC_STATE_DEPTH_BOUNDS = 5,
    VK_DYNAMIC_STATE_STENCIL_COMPARE_MASK = 6,
    VK_DYNAMIC_STATE_STENCIL_WRITE_MASK = 7,
    VK_DYNAMIC_STATE_STENCIL_REFERENCE = 8,
  // Provided by VK_KHR_ray_tracing_pipeline
    VK_DYNAMIC_STATE_RAY_TRACING_PIPELINE_STACK_SIZE_KHR = 1000347000,
  // Provided by VK_KHR_fragment_shading_rate
    VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR = 1000226000,
} VkDynamicState;

10.2.1. Valid Combinations of Stages for Graphics Pipelines

If tessellation shader stages are omitted, the tessellation shading and fixed-function stages of the pipeline are skipped.

If a geometry shader is omitted, the geometry shading stage is skipped.

If a fragment shader is omitted, fragment color outputs have undefined values, and the fragment depth value is unmodified. This can be useful for depth-only rendering.

Presence of a shader stage in a pipeline is indicated by including a valid VkPipelineShaderStageCreateInfo with module and pName selecting an entry point from a shader module, where that entry point is valid for the stage specified by stage.

Presence of some of the fixed-function stages in the pipeline is implicitly derived from enabled shaders and provided state. For example, the fixed-function tessellator is always present when the pipeline has valid Tessellation Control and Tessellation Evaluation shaders.

For example:

10.3. Ray Tracing Pipelines

Ray tracing pipelines consist of multiple shader stages, fixed-function traversal stages, and a pipeline layout.

To create ray tracing pipelines, call:

// Provided by VK_KHR_ray_tracing_pipeline
VkResult vkCreateRayTracingPipelinesKHR(
    VkDevice                                    device,
    VkDeferredOperationKHR                      deferredOperation,
    VkPipelineCache                             pipelineCache,
    uint32_t                                    createInfoCount,
    const VkRayTracingPipelineCreateInfoKHR*    pCreateInfos,
    const VkAllocationCallbacks*                pAllocator,
    VkPipeline*                                 pPipelines);
  • device is the logical device that creates the ray tracing pipelines.

  • deferredOperation is VK_NULL_HANDLE or the handle of a valid VkDeferredOperationKHR request deferral object for this command.

  • pipelineCache is either VK_NULL_HANDLE, indicating that pipeline caching is disabled, or the handle of a valid pipeline cache object, in which case use of that cache is enabled for the duration of the command.

  • createInfoCount is the length of the pCreateInfos and pPipelines arrays.

  • pCreateInfos is a pointer to an array of VkRayTracingPipelineCreateInfoKHR structures.

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

  • pPipelines is a pointer to an array in which the resulting ray tracing pipeline objects are returned.

The VK_ERROR_INVALID_OPAQUE_CAPTURE_ADDRESS error is returned if the implementation is unable to re-use the shader group handles provided in VkRayTracingShaderGroupCreateInfoKHR::pShaderGroupCaptureReplayHandle when VkPhysicalDeviceRayTracingPipelineFeaturesKHR::rayTracingPipelineShaderGroupHandleCaptureReplay is enabled.

Valid Usage
  • VUID-vkCreateRayTracingPipelinesKHR-flags-03415
    If the flags member of any element of pCreateInfos contains the VK_PIPELINE_CREATE_DERIVATIVE_BIT flag, and the basePipelineIndex member of that same element is not -1, basePipelineIndex must be less than the index into pCreateInfos that corresponds to that element

  • VUID-vkCreateRayTracingPipelinesKHR-flags-03416
    If the flags member of any element of pCreateInfos contains the VK_PIPELINE_CREATE_DERIVATIVE_BIT flag, the base pipeline must have been created with the VK_PIPELINE_CREATE_ALLOW_DERIVATIVES_BIT flag set

  • VUID-vkCreateRayTracingPipelinesKHR-flags-03816
    flags must not contain the VK_PIPELINE_CREATE_DISPATCH_BASE flag

  • VUID-vkCreateRayTracingPipelinesKHR-deferredOperation-03677
    If deferredOperation is not VK_NULL_HANDLE, it must be a valid VkDeferredOperationKHR object

  • VUID-vkCreateRayTracingPipelinesKHR-deferredOperation-03678
    Any previous deferred operation that was associated with deferredOperation must be complete

  • VUID-vkCreateRayTracingPipelinesKHR-rayTracingPipeline-03586
    The rayTracingPipeline feature must be enabled

Valid Usage (Implicit)
  • VUID-vkCreateRayTracingPipelinesKHR-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkCreateRayTracingPipelinesKHR-deferredOperation-parameter
    If deferredOperation is not VK_NULL_HANDLE, deferredOperation must be a valid VkDeferredOperationKHR handle

  • VUID-vkCreateRayTracingPipelinesKHR-pipelineCache-parameter
    If pipelineCache is not VK_NULL_HANDLE, pipelineCache must be a valid VkPipelineCache handle

  • VUID-vkCreateRayTracingPipelinesKHR-pCreateInfos-parameter
    pCreateInfos must be a valid pointer to an array of createInfoCount valid VkRayTracingPipelineCreateInfoKHR structures

  • VUID-vkCreateRayTracingPipelinesKHR-pAllocator-parameter
    If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure

  • VUID-vkCreateRayTracingPipelinesKHR-pPipelines-parameter
    pPipelines must be a valid pointer to an array of createInfoCount VkPipeline handles

  • VUID-vkCreateRayTracingPipelinesKHR-createInfoCount-arraylength
    createInfoCount must be greater than 0

  • VUID-vkCreateRayTracingPipelinesKHR-deferredOperation-parent
    If deferredOperation is a valid handle, it must have been created, allocated, or retrieved from device

  • VUID-vkCreateRayTracingPipelinesKHR-pipelineCache-parent
    If pipelineCache is a valid handle, it must have been created, allocated, or retrieved from device

Return Codes
Success
  • VK_SUCCESS

  • VK_OPERATION_DEFERRED_KHR

  • VK_OPERATION_NOT_DEFERRED_KHR

Failure
  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

  • VK_ERROR_INVALID_OPAQUE_CAPTURE_ADDRESS

The VkRayTracingPipelineCreateInfoKHR structure is defined as:

// Provided by VK_KHR_ray_tracing_pipeline
typedef struct VkRayTracingPipelineCreateInfoKHR {
    VkStructureType                                      sType;
    const void*                                          pNext;
    VkPipelineCreateFlags                                flags;
    uint32_t                                             stageCount;
    const VkPipelineShaderStageCreateInfo*               pStages;
    uint32_t                                             groupCount;
    const VkRayTracingShaderGroupCreateInfoKHR*          pGroups;
    uint32_t                                             maxPipelineRayRecursionDepth;
    const VkPipelineLibraryCreateInfoKHR*                pLibraryInfo;
    const VkRayTracingPipelineInterfaceCreateInfoKHR*    pLibraryInterface;
    const VkPipelineDynamicStateCreateInfo*              pDynamicState;
    VkPipelineLayout                                     layout;
    VkPipeline                                           basePipelineHandle;
    int32_t                                              basePipelineIndex;
} VkRayTracingPipelineCreateInfoKHR;
  • sType is the type of this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • flags is a bitmask of VkPipelineCreateFlagBits specifying how the pipeline will be generated.

  • stageCount is the number of entries in the pStages array.

  • pStages is a pointer to an array of stageCount VkPipelineShaderStageCreateInfo structures describing the set of the shader stages to be included in the ray tracing pipeline.

  • groupCount is the number of entries in the pGroups array.

  • pGroups is a pointer to an array of groupCount VkRayTracingShaderGroupCreateInfoKHR structures describing the set of the shader stages to be included in each shader group in the ray tracing pipeline.

  • maxPipelineRayRecursionDepth is the maximum recursion depth of shaders executed by this pipeline.

  • pLibraryInfo is a pointer to a VkPipelineLibraryCreateInfoKHR structure defining pipeline libraries to include.

  • pLibraryInterface is a pointer to a VkRayTracingPipelineInterfaceCreateInfoKHR structure defining additional information when using pipeline libraries.

  • pDynamicState is a pointer to a VkPipelineDynamicStateCreateInfo structure, and is used to indicate which properties of the pipeline state object are dynamic and can be changed independently of the pipeline state. This can be NULL, which means no state in the pipeline is considered dynamic.

  • layout is the description of binding locations used by both the pipeline and descriptor sets used with the pipeline.

  • basePipelineHandle is a pipeline to derive from.

  • basePipelineIndex is an index into the pCreateInfos parameter to use as a pipeline to derive from.

The parameters basePipelineHandle and basePipelineIndex are described in more detail in Pipeline Derivatives.

When VK_PIPELINE_CREATE_LIBRARY_BIT_KHR is specified, this pipeline defines a pipeline library which cannot be bound as a ray tracing pipeline directly. Instead, pipeline libraries define common shaders and shader groups which can be included in future pipeline creation.

If pipeline libraries are included in pLibraryInfo, shaders defined in those libraries are treated as if they were defined as additional entries in pStages, appended in the order they appear in the pLibraries array and in the pStages array when those libraries were defined.

When referencing shader groups in order to obtain a shader group handle, groups defined in those libraries are treated as if they were defined as additional entries in pGroups, appended in the order they appear in the pLibraries array and in the pGroups array when those libraries were defined. The shaders these groups reference are set when the pipeline library is created, referencing those specified in the pipeline library, not in the pipeline that includes it.

The default stack size for a pipeline if VK_DYNAMIC_STATE_RAY_TRACING_PIPELINE_STACK_SIZE_KHR is not provided is computed as described in Ray Tracing Pipeline Stack.

Valid Usage
  • VUID-VkRayTracingPipelineCreateInfoKHR-flags-03421
    If flags contains the VK_PIPELINE_CREATE_DERIVATIVE_BIT flag, and basePipelineIndex is -1, basePipelineHandle must be a valid handle to a ray tracing VkPipeline

  • VUID-VkRayTracingPipelineCreateInfoKHR-flags-03422
    If flags contains the VK_PIPELINE_CREATE_DERIVATIVE_BIT flag, and basePipelineHandle is VK_NULL_HANDLE, basePipelineIndex must be a valid index into the calling command’s pCreateInfos parameter

  • VUID-VkRayTracingPipelineCreateInfoKHR-flags-03423
    If flags contains the VK_PIPELINE_CREATE_DERIVATIVE_BIT flag, and basePipelineIndex is not -1, basePipelineHandle must be VK_NULL_HANDLE

  • VUID-VkRayTracingPipelineCreateInfoKHR-flags-03424
    If flags contains the VK_PIPELINE_CREATE_DERIVATIVE_BIT flag, and basePipelineHandle is not VK_NULL_HANDLE, basePipelineIndex must be -1

  • VUID-VkRayTracingPipelineCreateInfoKHR-pStages-03426
    The shader code for the entry points identified by pStages, and the rest of the state identified by this structure must adhere to the pipeline linking rules described in the Shader Interfaces chapter

  • VUID-VkRayTracingPipelineCreateInfoKHR-layout-03427
    layout must be consistent with all shaders specified in pStages

  • VUID-VkRayTracingPipelineCreateInfoKHR-layout-03428
    The number of resources in layout accessible to each shader stage that is used by the pipeline must be less than or equal to VkPhysicalDeviceLimits::maxPerStageResources

  • VUID-VkRayTracingPipelineCreateInfoKHR-stage-03425
    If flags does not include VK_PIPELINE_CREATE_LIBRARY_BIT_KHR, the stage member of at least one element of pStages, including those implicitly added by pLibraryInfo, must be VK_SHADER_STAGE_RAYGEN_BIT_KHR

  • VUID-VkRayTracingPipelineCreateInfoKHR-maxPipelineRayRecursionDepth-03589
    maxPipelineRayRecursionDepth must be less than or equal to VkPhysicalDeviceRayTracingPipelinePropertiesKHR::maxRayRecursionDepth

  • VUID-VkRayTracingPipelineCreateInfoKHR-flags-03465
    If flags includes VK_PIPELINE_CREATE_LIBRARY_BIT_KHR, pLibraryInterface must not be NULL

  • VUID-VkRayTracingPipelineCreateInfoKHR-pLibraryInfo-03590
    If pLibraryInfo is not NULL and its libraryCount member is greater than 0, its pLibraryInterface member must not be NULL

  • VUID-VkRayTracingPipelineCreateInfoKHR-pLibraries-03591
    Each element of pLibraryInfo->pLibraries must have been created with the value of maxPipelineRayRecursionDepth equal to that in this pipeline

  • VUID-VkRayTracingPipelineCreateInfoKHR-pLibraryInfo-03592
    If pLibraryInfo is not NULL, each element of its pLibraries member must have been created with a layout that is compatible with the layout in this pipeline

  • VUID-VkRayTracingPipelineCreateInfoKHR-pLibraryInfo-03593
    If pLibraryInfo is not NULL, each element of its pLibraries member must have been created with values of the maxPipelineRayPayloadSize and maxPipelineRayHitAttributeSize members of pLibraryInterface equal to those in this pipeline

  • VUID-VkRayTracingPipelineCreateInfoKHR-flags-03594
    If flags includes VK_PIPELINE_CREATE_RAY_TRACING_SHADER_GROUP_HANDLE_CAPTURE_REPLAY_BIT_KHR, each element of pLibraryInfo->pLibraries must have been created with the VK_PIPELINE_CREATE_RAY_TRACING_SHADER_GROUP_HANDLE_CAPTURE_REPLAY_BIT_KHR bit set

  • VUID-VkRayTracingPipelineCreateInfoKHR-flags-04718
    If flags includes VK_PIPELINE_CREATE_RAY_TRACING_SKIP_AABBS_BIT_KHR, each element of pLibraryInfo->pLibraries must have been created with the VK_PIPELINE_CREATE_RAY_TRACING_SKIP_AABBS_BIT_KHR bit set

  • VUID-VkRayTracingPipelineCreateInfoKHR-flags-04719
    If flags includes VK_PIPELINE_CREATE_RAY_TRACING_SKIP_TRIANGLES_BIT_KHR, each element of pLibraryInfo->pLibraries must have been created with the VK_PIPELINE_CREATE_RAY_TRACING_SKIP_TRIANGLES_BIT_KHR bit set

  • VUID-VkRayTracingPipelineCreateInfoKHR-flags-04720
    If flags includes VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_ANY_HIT_SHADERS_BIT_KHR, each element of pLibraryInfo->pLibraries must have been created with the VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_ANY_HIT_SHADERS_BIT_KHR bit set

  • VUID-VkRayTracingPipelineCreateInfoKHR-flags-04721
    If flags includes VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_CLOSEST_HIT_SHADERS_BIT_KHR, each element of pLibraryInfo->pLibraries must have been created with the VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_CLOSEST_HIT_SHADERS_BIT_KHR bit set

  • VUID-VkRayTracingPipelineCreateInfoKHR-flags-04722
    If flags includes VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_INTERSECTION_SHADERS_BIT_KHR, each element of pLibraryInfo->pLibraries must have been created with the VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_INTERSECTION_SHADERS_BIT_KHR bit set

  • VUID-VkRayTracingPipelineCreateInfoKHR-flags-04723
    If flags includes VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_MISS_SHADERS_BIT_KHR, each element of pLibraryInfo->pLibraries must have been created with the VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_MISS_SHADERS_BIT_KHR bit set

  • VUID-VkRayTracingPipelineCreateInfoKHR-pLibraryInfo-03595
    If the VK_KHR_pipeline_library extension is not enabled, pLibraryInfo and pLibraryInterface must be NULL.

  • VUID-VkRayTracingPipelineCreateInfoKHR-flags-03470
    If flags includes VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_ANY_HIT_SHADERS_BIT_KHR, for any element of pGroups with a type of VK_RAY_TRACING_SHADER_GROUP_TYPE_TRIANGLES_HIT_GROUP_KHR or VK_RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_KHR, the anyHitShader of that element must not be VK_SHADER_UNUSED_KHR

  • VUID-VkRayTracingPipelineCreateInfoKHR-flags-03471
    If flags includes VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_CLOSEST_HIT_SHADERS_BIT_KHR, for any element of pGroups with a type of VK_RAY_TRACING_SHADER_GROUP_TYPE_TRIANGLES_HIT_GROUP_KHR or VK_RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_KHR, the closestHitShader of that element must not be VK_SHADER_UNUSED_KHR

  • VUID-VkRayTracingPipelineCreateInfoKHR-rayTraversalPrimitiveCulling-03596
    If the rayTraversalPrimitiveCulling feature is not enabled, flags must not include VK_PIPELINE_CREATE_RAY_TRACING_SKIP_AABBS_BIT_KHR

  • VUID-VkRayTracingPipelineCreateInfoKHR-rayTraversalPrimitiveCulling-03597
    If the rayTraversalPrimitiveCulling feature is not enabled, flags must not include VK_PIPELINE_CREATE_RAY_TRACING_SKIP_TRIANGLES_BIT_KHR

  • VUID-VkRayTracingPipelineCreateInfoKHR-flags-03598
    If flags includes VK_PIPELINE_CREATE_RAY_TRACING_SHADER_GROUP_HANDLE_CAPTURE_REPLAY_BIT_KHR, rayTracingPipelineShaderGroupHandleCaptureReplay must be enabled

  • VUID-VkRayTracingPipelineCreateInfoKHR-rayTracingPipelineShaderGroupHandleCaptureReplay-03599
    If VkPhysicalDeviceRayTracingPipelineFeaturesKHR::rayTracingPipelineShaderGroupHandleCaptureReplay is VK_TRUE and the pShaderGroupCaptureReplayHandle member of any element of pGroups is not NULL, flags must include VK_PIPELINE_CREATE_RAY_TRACING_SHADER_GROUP_HANDLE_CAPTURE_REPLAY_BIT_KHR

  • VUID-VkRayTracingPipelineCreateInfoKHR-pLibraryInfo-03600
    If pLibraryInfo is not NULL and its libraryCount is 0, stageCount must not be 0

  • VUID-VkRayTracingPipelineCreateInfoKHR-pLibraryInfo-03601
    If pLibraryInfo is not NULL and its libraryCount is 0, groupCount must not be 0

  • VUID-VkRayTracingPipelineCreateInfoKHR-pDynamicStates-03602
    Any element of the pDynamicStates member of pDynamicState must be VK_DYNAMIC_STATE_RAY_TRACING_PIPELINE_STACK_SIZE_KHR

Valid Usage (Implicit)
  • VUID-VkRayTracingPipelineCreateInfoKHR-sType-sType
    sType must be VK_STRUCTURE_TYPE_RAY_TRACING_PIPELINE_CREATE_INFO_KHR

  • VUID-VkRayTracingPipelineCreateInfoKHR-pNext-pNext
    pNext must be NULL

  • VUID-VkRayTracingPipelineCreateInfoKHR-flags-parameter
    flags must be a valid combination of VkPipelineCreateFlagBits values

  • VUID-VkRayTracingPipelineCreateInfoKHR-pStages-parameter
    If stageCount is not 0, pStages must be a valid pointer to an array of stageCount valid VkPipelineShaderStageCreateInfo structures

  • VUID-VkRayTracingPipelineCreateInfoKHR-pGroups-parameter
    If groupCount is not 0, pGroups must be a valid pointer to an array of groupCount valid VkRayTracingShaderGroupCreateInfoKHR structures

  • VUID-VkRayTracingPipelineCreateInfoKHR-pLibraryInfo-parameter
    If pLibraryInfo is not NULL, pLibraryInfo must be a valid pointer to a valid VkPipelineLibraryCreateInfoKHR structure

  • VUID-VkRayTracingPipelineCreateInfoKHR-pLibraryInterface-parameter
    If pLibraryInterface is not NULL, pLibraryInterface must be a valid pointer to a valid VkRayTracingPipelineInterfaceCreateInfoKHR structure

  • VUID-VkRayTracingPipelineCreateInfoKHR-pDynamicState-parameter
    If pDynamicState is not NULL, pDynamicState must be a valid pointer to a valid VkPipelineDynamicStateCreateInfo structure

  • VUID-VkRayTracingPipelineCreateInfoKHR-layout-parameter
    layout must be a valid VkPipelineLayout handle

  • VUID-VkRayTracingPipelineCreateInfoKHR-commonparent
    Both of basePipelineHandle, and layout that are valid handles of non-ignored parameters must have been created, allocated, or retrieved from the same VkDevice

The VkRayTracingShaderGroupCreateInfoKHR structure is defined as:

// Provided by VK_KHR_ray_tracing_pipeline
typedef struct VkRayTracingShaderGroupCreateInfoKHR {
    VkStructureType                   sType;
    const void*                       pNext;
    VkRayTracingShaderGroupTypeKHR    type;
    uint32_t                          generalShader;
    uint32_t                          closestHitShader;
    uint32_t                          anyHitShader;
    uint32_t                          intersectionShader;
    const void*                       pShaderGroupCaptureReplayHandle;
} VkRayTracingShaderGroupCreateInfoKHR;
  • sType is the type of this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • type is the type of hit group specified in this structure.

  • generalShader is the index of the ray generation, miss, or callable shader from VkRayTracingPipelineCreateInfoKHR::pStages in the group if the shader group has type of VK_RAY_TRACING_SHADER_GROUP_TYPE_GENERAL_KHR, and VK_SHADER_UNUSED_KHR otherwise.

  • closestHitShader is the optional index of the closest hit shader from VkRayTracingPipelineCreateInfoKHR::pStages in the group if the shader group has type of VK_RAY_TRACING_SHADER_GROUP_TYPE_TRIANGLES_HIT_GROUP_KHR or VK_RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_KHR, and VK_SHADER_UNUSED_KHR otherwise.

  • anyHitShader is the optional index of the any-hit shader from VkRayTracingPipelineCreateInfoKHR::pStages in the group if the shader group has type of VK_RAY_TRACING_SHADER_GROUP_TYPE_TRIANGLES_HIT_GROUP_KHR or VK_RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_KHR, and VK_SHADER_UNUSED_KHR otherwise.

  • intersectionShader is the index of the intersection shader from VkRayTracingPipelineCreateInfoKHR::pStages in the group if the shader group has type of VK_RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_KHR, and VK_SHADER_UNUSED_KHR otherwise.

  • pShaderGroupCaptureReplayHandle is an optional pointer to replay information for this shader group. Ignored if VkPhysicalDeviceRayTracingPipelineFeaturesKHR::rayTracingPipelineShaderGroupHandleCaptureReplay is VK_FALSE.

Valid Usage
  • VUID-VkRayTracingShaderGroupCreateInfoKHR-type-03474
    If type is VK_RAY_TRACING_SHADER_GROUP_TYPE_GENERAL_KHR then generalShader must be a valid index into VkRayTracingPipelineCreateInfoKHR::pStages referring to a shader of VK_SHADER_STAGE_RAYGEN_BIT_KHR, VK_SHADER_STAGE_MISS_BIT_KHR, or VK_SHADER_STAGE_CALLABLE_BIT_KHR

  • VUID-VkRayTracingShaderGroupCreateInfoKHR-type-03475
    If type is VK_RAY_TRACING_SHADER_GROUP_TYPE_GENERAL_KHR then closestHitShader, anyHitShader, and intersectionShader must be VK_SHADER_UNUSED_KHR

  • VUID-VkRayTracingShaderGroupCreateInfoKHR-type-03476
    If type is VK_RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_KHR then intersectionShader must be a valid index into VkRayTracingPipelineCreateInfoKHR::pStages referring to a shader of VK_SHADER_STAGE_INTERSECTION_BIT_KHR

  • VUID-VkRayTracingShaderGroupCreateInfoKHR-type-03477
    If type is VK_RAY_TRACING_SHADER_GROUP_TYPE_TRIANGLES_HIT_GROUP_KHR then intersectionShader must be VK_SHADER_UNUSED_KHR

  • VUID-VkRayTracingShaderGroupCreateInfoKHR-closestHitShader-03478
    closestHitShader must be either VK_SHADER_UNUSED_KHR or a valid index into VkRayTracingPipelineCreateInfoKHR::pStages referring to a shader of VK_SHADER_STAGE_CLOSEST_HIT_BIT_KHR

  • VUID-VkRayTracingShaderGroupCreateInfoKHR-anyHitShader-03479
    anyHitShader must be either VK_SHADER_UNUSED_KHR or a valid index into VkRayTracingPipelineCreateInfoKHR::pStages referring to a shader of VK_SHADER_STAGE_ANY_HIT_BIT_KHR

  • VUID-VkRayTracingShaderGroupCreateInfoKHR-rayTracingPipelineShaderGroupHandleCaptureReplayMixed-03603
    If VkPhysicalDeviceRayTracingPipelineFeaturesKHR::rayTracingPipelineShaderGroupHandleCaptureReplayMixed is VK_FALSE then pShaderGroupCaptureReplayHandle must not be provided if it has not been provided on a previous call to ray tracing pipeline creation

  • VUID-VkRayTracingShaderGroupCreateInfoKHR-rayTracingPipelineShaderGroupHandleCaptureReplayMixed-03604
    If VkPhysicalDeviceRayTracingPipelineFeaturesKHR::rayTracingPipelineShaderGroupHandleCaptureReplayMixed is VK_FALSE then the caller must guarantee that no ray tracing pipeline creation commands with pShaderGroupCaptureReplayHandle provided execute simultaneously with ray tracing pipeline creation commands without pShaderGroupCaptureReplayHandle provided

Valid Usage (Implicit)
  • VUID-VkRayTracingShaderGroupCreateInfoKHR-sType-sType
    sType must be VK_STRUCTURE_TYPE_RAY_TRACING_SHADER_GROUP_CREATE_INFO_KHR

  • VUID-VkRayTracingShaderGroupCreateInfoKHR-pNext-pNext
    pNext must be NULL

  • VUID-VkRayTracingShaderGroupCreateInfoKHR-type-parameter
    type must be a valid VkRayTracingShaderGroupTypeKHR value

Possible values of type in VkRayTracingShaderGroupCreateInfoKHR are:

// Provided by VK_KHR_ray_tracing_pipeline
typedef enum VkRayTracingShaderGroupTypeKHR {
    VK_RAY_TRACING_SHADER_GROUP_TYPE_GENERAL_KHR = 0,
    VK_RAY_TRACING_SHADER_GROUP_TYPE_TRIANGLES_HIT_GROUP_KHR = 1,
    VK_RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_KHR = 2,
} VkRayTracingShaderGroupTypeKHR;
  • VK_RAY_TRACING_SHADER_GROUP_TYPE_GENERAL_KHR indicates a shader group with a single VK_SHADER_STAGE_RAYGEN_BIT_KHR, VK_SHADER_STAGE_MISS_BIT_KHR, or VK_SHADER_STAGE_CALLABLE_BIT_KHR shader in it.

  • VK_RAY_TRACING_SHADER_GROUP_TYPE_TRIANGLES_HIT_GROUP_KHR specifies a shader group that only hits triangles and must not contain an intersection shader, only closest hit and any-hit shaders.

  • VK_RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_KHR specifies a shader group that only intersects with custom geometry and must contain an intersection shader and may contain closest hit and any-hit shaders.

Note

For current group types, the hit group type could be inferred from the presence or absence of the intersection shader, but we provide the type explicitly for future hit groups that do not have that property.

The VkRayTracingPipelineInterfaceCreateInfoKHR structure is defined as:

// Provided by VK_KHR_ray_tracing_pipeline
typedef struct VkRayTracingPipelineInterfaceCreateInfoKHR {
    VkStructureType    sType;
    const void*        pNext;
    uint32_t           maxPipelineRayPayloadSize;
    uint32_t           maxPipelineRayHitAttributeSize;
} VkRayTracingPipelineInterfaceCreateInfoKHR;
  • sType is the type of this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • maxPipelineRayPayloadSize is the maximum payload size in bytes used by any shader in the pipeline.

  • maxPipelineRayHitAttributeSize is the maximum attribute structure size in bytes used by any shader in the pipeline.

maxPipelineRayPayloadSize is calculated as the maximum number of bytes used by any block declared in the RayPayloadKHR or IncomingRayPayloadKHR storage classes. maxPipelineRayHitAttributeSize is calculated as the maximum number of bytes used by any block declared in the HitAttributeKHR storage class. As variables in these storage classes do not have explicit offsets, the size should be calculated as if each variable has a scalar alignment equal to the largest scalar alignment of any of the block’s members.

Note

There is no explicit upper limit for maxPipelineRayPayloadSize, but in practice it should be kept as small as possible. Similar to invocation local memory, it must be allocated for each shader invocation and for devices which support many simultaneous invocations, this storage can rapidly be exhausted, resulting in failure.

Valid Usage
Valid Usage (Implicit)
  • VUID-VkRayTracingPipelineInterfaceCreateInfoKHR-sType-sType
    sType must be VK_STRUCTURE_TYPE_RAY_TRACING_PIPELINE_INTERFACE_CREATE_INFO_KHR

  • VUID-VkRayTracingPipelineInterfaceCreateInfoKHR-pNext-pNext
    pNext must be NULL

To query the opaque handles of shaders in the ray tracing pipeline, call:

// Provided by VK_KHR_ray_tracing_pipeline
VkResult vkGetRayTracingShaderGroupHandlesKHR(
    VkDevice                                    device,
    VkPipeline                                  pipeline,
    uint32_t                                    firstGroup,
    uint32_t                                    groupCount,
    size_t                                      dataSize,
    void*                                       pData);
  • device is the logical device containing the ray tracing pipeline.

  • pipeline is the ray tracing pipeline object containing the shaders.

  • firstGroup is the index of the first group to retrieve a handle for from the VkRayTracingPipelineCreateInfoKHR::pGroups array.

  • groupCount is the number of shader handles to retrieve.

  • dataSize is the size in bytes of the buffer pointed to by pData.

  • pData is a pointer to a user-allocated buffer where the results will be written.

Valid Usage
  • VUID-vkGetRayTracingShaderGroupHandlesKHR-pipeline-04619
    pipeline must be a ray tracing pipeline

  • VUID-vkGetRayTracingShaderGroupHandlesKHR-firstGroup-04050
    firstGroup must be less than the number of shader groups in pipeline

  • VUID-vkGetRayTracingShaderGroupHandlesKHR-firstGroup-02419
    The sum of firstGroup and groupCount must be less than or equal to the number of shader groups in pipeline

  • VUID-vkGetRayTracingShaderGroupHandlesKHR-dataSize-02420
    dataSize must be at least VkPhysicalDeviceRayTracingPipelinePropertiesKHR::shaderGroupHandleSize × groupCount

  • VUID-vkGetRayTracingShaderGroupHandlesKHR-pipeline-03482
    pipeline must have not been created with VK_PIPELINE_CREATE_LIBRARY_BIT_KHR

Valid Usage (Implicit)
  • VUID-vkGetRayTracingShaderGroupHandlesKHR-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkGetRayTracingShaderGroupHandlesKHR-pipeline-parameter
    pipeline must be a valid VkPipeline handle

  • VUID-vkGetRayTracingShaderGroupHandlesKHR-pData-parameter
    pData must be a valid pointer to an array of dataSize bytes

  • VUID-vkGetRayTracingShaderGroupHandlesKHR-dataSize-arraylength
    dataSize must be greater than 0

  • VUID-vkGetRayTracingShaderGroupHandlesKHR-pipeline-parent
    pipeline must have been created, allocated, or retrieved from device

Return Codes
Success
  • VK_SUCCESS

Failure
  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

To query the optional capture handle information of shaders in the ray tracing pipeline, call:

// Provided by VK_KHR_ray_tracing_pipeline
VkResult vkGetRayTracingCaptureReplayShaderGroupHandlesKHR(
    VkDevice                                    device,
    VkPipeline                                  pipeline,
    uint32_t                                    firstGroup,
    uint32_t                                    groupCount,
    size_t                                      dataSize,
    void*                                       pData);
  • device is the logical device containing the ray tracing pipeline.

  • pipeline is the ray tracing pipeline object containing the shaders.

  • firstGroup is the index of the first group to retrieve a handle for from the VkRayTracingPipelineCreateInfoKHR::pGroups array.

  • groupCount is the number of shader handles to retrieve.

  • dataSize is the size in bytes of the buffer pointed to by pData.

  • pData is a pointer to a user-allocated buffer where the results will be written.

Valid Usage
  • VUID-vkGetRayTracingCaptureReplayShaderGroupHandlesKHR-pipeline-04620
    pipeline must be a ray tracing pipeline

  • VUID-vkGetRayTracingCaptureReplayShaderGroupHandlesKHR-firstGroup-04051
    firstGroup must be less than the number of shader groups in pipeline

  • VUID-vkGetRayTracingCaptureReplayShaderGroupHandlesKHR-firstGroup-03483
    The sum of firstGroup and groupCount must be less than or equal to the number of shader groups in pipeline

  • VUID-vkGetRayTracingCaptureReplayShaderGroupHandlesKHR-dataSize-03484
    dataSize must be at least VkPhysicalDeviceRayTracingPipelinePropertiesKHR::shaderGroupHandleCaptureReplaySize × groupCount

  • VUID-vkGetRayTracingCaptureReplayShaderGroupHandlesKHR-rayTracingPipelineShaderGroupHandleCaptureReplay-03606
    VkPhysicalDeviceRayTracingPipelineFeaturesKHR::rayTracingPipelineShaderGroupHandleCaptureReplay must be enabled to call this function

  • VUID-vkGetRayTracingCaptureReplayShaderGroupHandlesKHR-pipeline-03607
    pipeline must have been created with a flags that included VK_PIPELINE_CREATE_RAY_TRACING_SHADER_GROUP_HANDLE_CAPTURE_REPLAY_BIT_KHR

Valid Usage (Implicit)
  • VUID-vkGetRayTracingCaptureReplayShaderGroupHandlesKHR-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkGetRayTracingCaptureReplayShaderGroupHandlesKHR-pipeline-parameter
    pipeline must be a valid VkPipeline handle

  • VUID-vkGetRayTracingCaptureReplayShaderGroupHandlesKHR-pData-parameter
    pData must be a valid pointer to an array of dataSize bytes

  • VUID-vkGetRayTracingCaptureReplayShaderGroupHandlesKHR-dataSize-arraylength
    dataSize must be greater than 0

  • VUID-vkGetRayTracingCaptureReplayShaderGroupHandlesKHR-pipeline-parent
    pipeline must have been created, allocated, or retrieved from device

Return Codes
Success
  • VK_SUCCESS

Failure
  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

To query the pipeline stack size of shaders in a shader group in the ray tracing pipeline, call:

// Provided by VK_KHR_ray_tracing_pipeline
VkDeviceSize vkGetRayTracingShaderGroupStackSizeKHR(
    VkDevice                                    device,
    VkPipeline                                  pipeline,
    uint32_t                                    group,
    VkShaderGroupShaderKHR                      groupShader);
  • device is the logical device containing the ray tracing pipeline.

  • pipeline is the ray tracing pipeline object containing the shaders groups.

  • group is the index of the shader group to query.

  • groupShader is the type of shader from the group to query.

The return value is the ray tracing pipeline stack size in bytes for the specified shader as called from the specified shader group.

Valid Usage
  • VUID-vkGetRayTracingShaderGroupStackSizeKHR-pipeline-04622
    pipeline must be a ray tracing pipeline

  • VUID-vkGetRayTracingShaderGroupStackSizeKHR-group-03608
    The value of group must be less than the number of shader groups in pipeline

  • VUID-vkGetRayTracingShaderGroupStackSizeKHR-groupShader-03609
    The shader identified by groupShader in group must not be VK_SHADER_UNUSED_KHR

Valid Usage (Implicit)
  • VUID-vkGetRayTracingShaderGroupStackSizeKHR-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkGetRayTracingShaderGroupStackSizeKHR-pipeline-parameter
    pipeline must be a valid VkPipeline handle

  • VUID-vkGetRayTracingShaderGroupStackSizeKHR-groupShader-parameter
    groupShader must be a valid VkShaderGroupShaderKHR value

  • VUID-vkGetRayTracingShaderGroupStackSizeKHR-pipeline-parent
    pipeline must have been created, allocated, or retrieved from device

Possible values of groupShader in vkGetRayTracingShaderGroupStackSizeKHR are:

// Provided by VK_KHR_ray_tracing_pipeline
typedef enum VkShaderGroupShaderKHR {
    VK_SHADER_GROUP_SHADER_GENERAL_KHR = 0,
    VK_SHADER_GROUP_SHADER_CLOSEST_HIT_KHR = 1,
    VK_SHADER_GROUP_SHADER_ANY_HIT_KHR = 2,
    VK_SHADER_GROUP_SHADER_INTERSECTION_KHR = 3,
} VkShaderGroupShaderKHR;

To set the dynamic stack size for a ray tracing pipeline call:

// Provided by VK_KHR_ray_tracing_pipeline
void vkCmdSetRayTracingPipelineStackSizeKHR(
    VkCommandBuffer                             commandBuffer,
    uint32_t                                    pipelineStackSize);
  • commandBuffer is the command buffer into which the command will be recorded.

  • pipelineStackSize is the stack size to use for subsequent ray tracing trace commands.

See Ray Tracing Pipeline Stack for more on computing pipelineStackSize.

Valid Usage
  • VUID-vkCmdSetRayTracingPipelineStackSizeKHR-pipelineStackSize-03610
    pipelineStackSize must be large enough for any dynamic execution through the shaders in the ray tracing pipeline used by a subsequent trace call

Valid Usage (Implicit)
  • VUID-vkCmdSetRayTracingPipelineStackSizeKHR-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

  • VUID-vkCmdSetRayTracingPipelineStackSizeKHR-commandBuffer-recording
    commandBuffer must be in the recording state

  • VUID-vkCmdSetRayTracingPipelineStackSizeKHR-commandBuffer-cmdpool
    The VkCommandPool that commandBuffer was allocated from must support compute operations

  • VUID-vkCmdSetRayTracingPipelineStackSizeKHR-renderpass
    This command must only be called outside of a render pass instance

Host Synchronization
  • Host access to commandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Supported Queue Types Pipeline Type

Primary
Secondary

Outside

Compute

10.4. Pipeline Destruction

To destroy a pipeline, call:

// Provided by VK_VERSION_1_0
void vkDestroyPipeline(
    VkDevice                                    device,
    VkPipeline                                  pipeline,
    const VkAllocationCallbacks*                pAllocator);
  • device is the logical device that destroys the pipeline.

  • pipeline is the handle of the pipeline to destroy.

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

Valid Usage
  • VUID-vkDestroyPipeline-pipeline-00765
    All submitted commands that refer to pipeline must have completed execution

  • VUID-vkDestroyPipeline-pipeline-00766
    If VkAllocationCallbacks were provided when pipeline was created, a compatible set of callbacks must be provided here

  • VUID-vkDestroyPipeline-pipeline-00767
    If no VkAllocationCallbacks were provided when pipeline was created, pAllocator must be NULL

Valid Usage (Implicit)
  • VUID-vkDestroyPipeline-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkDestroyPipeline-pipeline-parameter
    If pipeline is not VK_NULL_HANDLE, pipeline must be a valid VkPipeline handle

  • VUID-vkDestroyPipeline-pAllocator-parameter
    If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure

  • VUID-vkDestroyPipeline-pipeline-parent
    If pipeline is a valid handle, it must have been created, allocated, or retrieved from device

Host Synchronization
  • Host access to pipeline must be externally synchronized

10.5. Multiple Pipeline Creation

Multiple pipelines can be created simultaneously by passing an array of VkGraphicsPipelineCreateInfo, VkRayTracingPipelineCreateInfoKHR, or VkComputePipelineCreateInfo structures into the vkCreateGraphicsPipelines, vkCreateRayTracingPipelinesKHR, and vkCreateComputePipelines commands, respectively. Applications can group together similar pipelines to be created in a single call, and implementations are encouraged to look for reuse opportunities within a group-create.

When an application attempts to create many pipelines in a single command, it is possible that some subset may fail creation. In that case, the corresponding entries in the pPipelines output array will be filled with VK_NULL_HANDLE values. If any pipeline fails creation despite valid arguments (for example, due to out of memory errors), the VkResult code returned by vkCreate*Pipelines will indicate why. The implementation will attempt to create all pipelines, and only return VK_NULL_HANDLE values for those that actually failed.

10.6. Pipeline Derivatives

A pipeline derivative is a child pipeline created from a parent pipeline, where the child and parent are expected to have much commonality. The goal of derivative pipelines is that they be cheaper to create using the parent as a starting point, and that it be more efficient (on either host or device) to switch/bind between children of the same parent.

A derivative pipeline is created by setting the VK_PIPELINE_CREATE_DERIVATIVE_BIT flag in the Vk*PipelineCreateInfo structure. If this is set, then exactly one of basePipelineHandle or basePipelineIndex members of the structure must have a valid handle/index, and specifies the parent pipeline. If basePipelineHandle is used, the parent pipeline must have already been created. If basePipelineIndex is used, then the parent is being created in the same command. VK_NULL_HANDLE acts as the invalid handle for basePipelineHandle, and -1 is the invalid index for basePipelineIndex. If basePipelineIndex is used, the base pipeline must appear earlier in the array. The base pipeline must have been created with the VK_PIPELINE_CREATE_ALLOW_DERIVATIVES_BIT flag set.

10.7. Pipeline Cache

Pipeline cache objects allow the result of pipeline construction to be reused between pipelines and between runs of an application. Reuse between pipelines is achieved by passing the same pipeline cache object when creating multiple related pipelines. Reuse across runs of an application is achieved by retrieving pipeline cache contents in one run of an application, saving the contents, and using them to preinitialize a pipeline cache on a subsequent run. The contents of the pipeline cache objects are managed by the implementation. Applications can manage the host memory consumed by a pipeline cache object and control the amount of data retrieved from a pipeline cache object.

Pipeline cache objects are represented by VkPipelineCache handles:

// Provided by VK_VERSION_1_0
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkPipelineCache)

To create pipeline cache objects, call:

// Provided by VK_VERSION_1_0
VkResult vkCreatePipelineCache(
    VkDevice                                    device,
    const VkPipelineCacheCreateInfo*            pCreateInfo,
    const VkAllocationCallbacks*                pAllocator,
    VkPipelineCache*                            pPipelineCache);
  • 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.

Note

Applications can track and manage the total host memory size of a pipeline cache object using the pAllocator. Applications can limit the amount of data retrieved from a pipeline cache object in vkGetPipelineCacheData. Implementations should not internally limit the total number of entries added to a pipeline cache object or the total host memory consumed.

Once created, a pipeline cache can be passed to the vkCreateGraphicsPipelines vkCreateRayTracingPipelinesKHR, and vkCreateComputePipelines commands. If the pipeline cache passed into these commands is not VK_NULL_HANDLE, the implementation will query it for possible reuse opportunities and update it with new content. 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.

Note

Implementations should make every effort to limit any critical sections to the actual accesses to the cache, which is expected to be significantly shorter than the duration of the vkCreate*Pipelines commands.

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-parameter
    If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure

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

Return Codes
Success
  • VK_SUCCESS

Failure
  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

The VkPipelineCacheCreateInfo structure is defined as:

// Provided by VK_VERSION_1_0
typedef struct VkPipelineCacheCreateInfo {
    VkStructureType               sType;
    const void*                   pNext;
    VkPipelineCacheCreateFlags    flags;
    size_t                        initialDataSize;
    const void*                   pInitialData;
} VkPipelineCacheCreateInfo;
  • sType is the type of this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • flags is reserved for future use.

  • initialDataSize is the number of bytes in pInitialData. If initialDataSize is zero, the pipeline cache will initially be empty.

  • pInitialData is a pointer to previously retrieved pipeline cache data. If the pipeline cache data is incompatible (as defined below) with the device, the pipeline cache will be initially empty. If initialDataSize is zero, pInitialData is ignored.

Valid Usage
  • VUID-VkPipelineCacheCreateInfo-initialDataSize-00768
    If initialDataSize is not 0, it must be equal to the size of pInitialData, as returned by vkGetPipelineCacheData when pInitialData was originally retrieved

  • VUID-VkPipelineCacheCreateInfo-initialDataSize-00769
    If initialDataSize is not 0, pInitialData must have been retrieved from a previous call to vkGetPipelineCacheData

Valid Usage (Implicit)
  • VUID-VkPipelineCacheCreateInfo-sType-sType
    sType must be VK_STRUCTURE_TYPE_PIPELINE_CACHE_CREATE_INFO

  • VUID-VkPipelineCacheCreateInfo-pNext-pNext
    pNext must be NULL

  • VUID-VkPipelineCacheCreateInfo-flags-zerobitmask
    flags must be 0

  • VUID-VkPipelineCacheCreateInfo-pInitialData-parameter
    If initialDataSize is not 0, pInitialData must be a valid pointer to an array of initialDataSize bytes

// Provided by VK_VERSION_1_0
typedef VkFlags VkPipelineCacheCreateFlags;

VkPipelineCacheCreateFlags is a bitmask type for setting a mask, but is currently reserved for future use.

Pipeline cache objects can be merged using the command:

// Provided by VK_VERSION_1_0
VkResult vkMergePipelineCaches(
    VkDevice                                    device,
    VkPipelineCache                             dstCache,
    uint32_t                                    srcCacheCount,
    const VkPipelineCache*                      pSrcCaches);
  • device is the logical device that owns the pipeline cache objects.

  • dstCache is the handle of the pipeline cache to merge results into.

  • srcCacheCount is the length of the pSrcCaches array.

  • pSrcCaches is a pointer to an array of pipeline cache handles, which will be merged into dstCache. The previous contents of dstCache are included after the merge.

Note

The details of the merge operation are implementation dependent, but implementations should merge the contents of the specified pipelines and prune duplicate entries.

Valid Usage
  • VUID-vkMergePipelineCaches-dstCache-00770
    dstCache must not appear in the list of source caches

Valid Usage (Implicit)
  • VUID-vkMergePipelineCaches-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkMergePipelineCaches-dstCache-parameter
    dstCache must be a valid VkPipelineCache handle

  • VUID-vkMergePipelineCaches-pSrcCaches-parameter
    pSrcCaches must be a valid pointer to an array of srcCacheCount valid VkPipelineCache handles

  • VUID-vkMergePipelineCaches-srcCacheCount-arraylength
    srcCacheCount must be greater than 0

  • VUID-vkMergePipelineCaches-dstCache-parent
    dstCache must have been created, allocated, or retrieved from device

  • VUID-vkMergePipelineCaches-pSrcCaches-parent
    Each element of pSrcCaches must have been created, allocated, or retrieved from device

Host Synchronization
  • Host access to dstCache must be externally synchronized

Return Codes
Success
  • VK_SUCCESS

Failure
  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

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

// Provided by VK_VERSION_1_0
VkResult vkGetPipelineCacheData(
    VkDevice                                    device,
    VkPipelineCache                             pipelineCache,
    size_t*                                     pDataSize,
    void*                                       pData);
  • 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 size_t value related to the amount of data in the pipeline cache, as described below.

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

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 VK_INCOMPLETE will be returned instead of VK_SUCCESS, to indicate that not all of the pipeline cache was returned.

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 11. 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 cache 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, as described for 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)
  • VUID-vkGetPipelineCacheData-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkGetPipelineCacheData-pipelineCache-parameter
    pipelineCache must be a valid VkPipelineCache handle

  • VUID-vkGetPipelineCacheData-pDataSize-parameter
    pDataSize must be a valid pointer to a size_t value

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

  • VUID-vkGetPipelineCacheData-pipelineCache-parent
    pipelineCache must have been created, allocated, or retrieved from device

Return Codes
Success
  • VK_SUCCESS

  • VK_INCOMPLETE

Failure
  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

Possible values of the second group of four bytes in the header returned by vkGetPipelineCacheData, encoding the pipeline cache version, are:

// Provided by VK_VERSION_1_0
typedef enum VkPipelineCacheHeaderVersion {
    VK_PIPELINE_CACHE_HEADER_VERSION_ONE = 1,
} VkPipelineCacheHeaderVersion;
  • VK_PIPELINE_CACHE_HEADER_VERSION_ONE specifies version one of the pipeline cache.

To destroy a pipeline cache, call:

// Provided by VK_VERSION_1_0
void vkDestroyPipelineCache(
    VkDevice                                    device,
    VkPipelineCache                             pipelineCache,
    const VkAllocationCallbacks*                pAllocator);
  • device is the logical device that destroys the pipeline cache object.

  • pipelineCache is the handle of the pipeline cache to destroy.

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

Valid Usage
  • VUID-vkDestroyPipelineCache-pipelineCache-00771
    If VkAllocationCallbacks were provided when pipelineCache was created, a compatible set of callbacks must be provided here

  • VUID-vkDestroyPipelineCache-pipelineCache-00772
    If no VkAllocationCallbacks were provided when pipelineCache was created, pAllocator must be NULL

Valid Usage (Implicit)
  • VUID-vkDestroyPipelineCache-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkDestroyPipelineCache-pipelineCache-parameter
    If pipelineCache is not VK_NULL_HANDLE, pipelineCache must be a valid VkPipelineCache handle

  • VUID-vkDestroyPipelineCache-pAllocator-parameter
    If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure

  • VUID-vkDestroyPipelineCache-pipelineCache-parent
    If pipelineCache is a valid handle, it must have been created, allocated, or retrieved from device

Host Synchronization
  • Host access to pipelineCache must be externally synchronized

10.8. Specialization Constants

Specialization constants are a mechanism whereby constants in a SPIR-V module can have their constant value specified at the time the VkPipeline is created. This allows a SPIR-V module to have constants that can be modified while executing an application that uses the Vulkan API.

Note

Specialization constants are useful to allow a compute shader to have its local workgroup size changed at runtime by the user, for example.

Each VkPipelineShaderStageCreateInfo structure contains a pSpecializationInfo member, which can be NULL to indicate no specialization constants, or point to a VkSpecializationInfo structure.

The VkSpecializationInfo structure is defined as:

// Provided by VK_VERSION_1_0
typedef struct VkSpecializationInfo {
    uint32_t                           mapEntryCount;
    const VkSpecializationMapEntry*    pMapEntries;
    size_t                             dataSize;
    const void*                        pData;
} VkSpecializationInfo;
  • mapEntryCount is the number of entries in the pMapEntries array.

  • pMapEntries is a pointer to an array of VkSpecializationMapEntry structures which map constant IDs to offsets in pData.

  • dataSize is the byte size of the pData buffer.

  • pData contains the actual constant values to specialize with.

Valid Usage
  • VUID-VkSpecializationInfo-offset-00773
    The offset member of each element of pMapEntries must be less than dataSize

  • VUID-VkSpecializationInfo-pMapEntries-00774
    The size member of each element of pMapEntries must be less than or equal to dataSize minus offset

Valid Usage (Implicit)
  • VUID-VkSpecializationInfo-pMapEntries-parameter
    If mapEntryCount is not 0, pMapEntries must be a valid pointer to an array of mapEntryCount valid VkSpecializationMapEntry structures

  • VUID-VkSpecializationInfo-pData-parameter
    If dataSize is not 0, pData must be a valid pointer to an array of dataSize bytes

The VkSpecializationMapEntry structure is defined as:

// Provided by VK_VERSION_1_0
typedef struct VkSpecializationMapEntry {
    uint32_t    constantID;
    uint32_t    offset;
    size_t      size;
} VkSpecializationMapEntry;
  • constantID is the ID of the specialization constant in SPIR-V.

  • offset is the byte offset of the specialization constant value within the supplied data buffer.

  • size is the byte size of the specialization constant value within the supplied data buffer.

If a constantID value is not a specialization constant ID used in the shader, that map entry does not affect the behavior of the pipeline.

Valid Usage
  • VUID-VkSpecializationMapEntry-constantID-00776
    For a constantID specialization constant declared in a shader, size must match the byte size of the constantID. If the specialization constant is of type boolean, size must be the byte size of VkBool32

In human readable SPIR-V:

OpDecorate %x SpecId 13 ; decorate .x component of WorkgroupSize with ID 13
OpDecorate %y SpecId 42 ; decorate .y component of WorkgroupSize with ID 42
OpDecorate %z SpecId 3  ; decorate .z component of WorkgroupSize with ID 3
OpDecorate %wgsize BuiltIn WorkgroupSize ; decorate WorkgroupSize onto constant
%i32 = OpTypeInt 32 0 ; declare an unsigned 32-bit type
%uvec3 = OpTypeVector %i32 3 ; declare a 3 element vector type of unsigned 32-bit
%x = OpSpecConstant %i32 1 ; declare the .x component of WorkgroupSize
%y = OpSpecConstant %i32 1 ; declare the .y component of WorkgroupSize
%z = OpSpecConstant %i32 1 ; declare the .z component of WorkgroupSize
%wgsize = OpSpecConstantComposite %uvec3 %x %y %z ; declare WorkgroupSize

From the above we have three specialization constants, one for each of the x, y & z elements of the WorkgroupSize vector.

Now to specialize the above via the specialization constants mechanism:

const VkSpecializationMapEntry entries[] =
{
    {
        13,                             // constantID
        0 * sizeof(uint32_t),           // offset
        sizeof(uint32_t)                // size
    },
    {
        42,                             // constantID
        1 * sizeof(uint32_t),           // offset
        sizeof(uint32_t)                // size
    },
    {
        3,                              // constantID
        2 * sizeof(uint32_t),           // offset
        sizeof(uint32_t)                // size
    }
};

const uint32_t data[] = { 16, 8, 4 }; // our workgroup size is 16x8x4

const VkSpecializationInfo info =
{
    3,                                  // mapEntryCount
    entries,                            // pMapEntries
    3 * sizeof(uint32_t),               // dataSize
    data,                               // pData
};

Then when calling vkCreateComputePipelines, and passing the VkSpecializationInfo we defined as the pSpecializationInfo parameter of VkPipelineShaderStageCreateInfo, we will create a compute pipeline with the runtime specified local workgroup size.

Another example would be that an application has a SPIR-V module that has some platform-dependent constants they wish to use.

In human readable SPIR-V:

OpDecorate %1 SpecId 0  ; decorate our signed 32-bit integer constant
OpDecorate %2 SpecId 12 ; decorate our 32-bit floating-point constant
%i32 = OpTypeInt 32 1   ; declare a signed 32-bit type
%float = OpTypeFloat 32 ; declare a 32-bit floating-point type
%1 = OpSpecConstant %i32 -1 ; some signed 32-bit integer constant
%2 = OpSpecConstant %float 0.5 ; some 32-bit floating-point constant

From the above we have two specialization constants, one is a signed 32-bit integer and the second is a 32-bit floating-point value.

Now to specialize the above via the specialization constants mechanism:

struct SpecializationData {
    int32_t data0;
    float data1;
};

const VkSpecializationMapEntry entries[] =
{
    {
        0,                                    // constantID
        offsetof(SpecializationData, data0),  // offset
        sizeof(SpecializationData::data0)     // size
    },
    {
        12,                                   // constantID
        offsetof(SpecializationData, data1),  // offset
        sizeof(SpecializationData::data1)     // size
    }
};

SpecializationData data;
data.data0 = -42;    // set the data for the 32-bit integer
data.data1 = 42.0f;  // set the data for the 32-bit floating-point

const VkSpecializationInfo info =
{
    2,                                  // mapEntryCount
    entries,                            // pMapEntries
    sizeof(data),                       // dataSize
    &data,                              // pData
};

It is legal for a SPIR-V module with specializations to be compiled into a pipeline where no specialization info was provided. SPIR-V specialization constants contain default values such that if a specialization is not provided, the default value will be used. In the examples above, it would be valid for an application to only specialize some of the specialization constants within the SPIR-V module, and let the other constants use their default values encoded within the OpSpecConstant declarations.

10.9. Pipeline Libraries

A pipeline library is a special pipeline that was created using the VK_PIPELINE_CREATE_LIBRARY_BIT_KHR and cannot be bound, instead it defines a set of pipeline state which can be linked into other pipelines. For ray tracing pipelines this includes shaders and shader groups. The application must maintain the lifetime of a pipeline library based on the pipelines that link with it. A pipeline library is considered in-use, as long as one of the linking pipelines is in-use.

This linkage is achieved by using the following structure within the appropriate creation mechanisms:

The VkPipelineLibraryCreateInfoKHR structure is defined as:

// Provided by VK_KHR_pipeline_library
typedef struct VkPipelineLibraryCreateInfoKHR {
    VkStructureType      sType;
    const void*          pNext;
    uint32_t             libraryCount;
    const VkPipeline*    pLibraries;
} VkPipelineLibraryCreateInfoKHR;
  • sType is the type of this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • libraryCount is the number of pipeline libraries in pLibraries.

  • pLibraries is a pointer to an array of VkPipeline structures specifying pipeline libraries to use when creating a pipeline.

Valid Usage
  • VUID-VkPipelineLibraryCreateInfoKHR-pLibraries-03381
    Each element of pLibraries must have been created with VK_PIPELINE_CREATE_LIBRARY_BIT_KHR

Valid Usage (Implicit)
  • VUID-VkPipelineLibraryCreateInfoKHR-sType-sType
    sType must be VK_STRUCTURE_TYPE_PIPELINE_LIBRARY_CREATE_INFO_KHR

  • VUID-VkPipelineLibraryCreateInfoKHR-pNext-pNext
    pNext must be NULL

  • VUID-VkPipelineLibraryCreateInfoKHR-pLibraries-parameter
    If libraryCount is not 0, pLibraries must be a valid pointer to an array of libraryCount valid VkPipeline handles

10.10. Pipeline Binding

Once a pipeline has been created, it can be bound to the command buffer using the command:

// Provided by VK_VERSION_1_0
void vkCmdBindPipeline(
    VkCommandBuffer                             commandBuffer,
    VkPipelineBindPoint                         pipelineBindPoint,
    VkPipeline                                  pipeline);
  • commandBuffer is the command buffer that the pipeline will be bound to.

  • pipelineBindPoint is a VkPipelineBindPoint value specifying to which bind point the pipeline is bound. Binding one does not disturb the others.

  • pipeline is the pipeline to be bound.

Once bound, a pipeline binding affects subsequent commands that interact with the given pipeline type in the command buffer until a different pipeline of the same type is bound to the bind point. Commands that do not interact with the given pipeline type must not be affected by the pipeline state.

Valid Usage
  • VUID-vkCmdBindPipeline-pipelineBindPoint-00777
    If pipelineBindPoint is VK_PIPELINE_BIND_POINT_COMPUTE, the VkCommandPool that commandBuffer was allocated from must support compute operations

  • VUID-vkCmdBindPipeline-pipelineBindPoint-00778
    If pipelineBindPoint is VK_PIPELINE_BIND_POINT_GRAPHICS, the VkCommandPool that commandBuffer was allocated from must support graphics operations

  • VUID-vkCmdBindPipeline-pipelineBindPoint-00779
    If pipelineBindPoint is VK_PIPELINE_BIND_POINT_COMPUTE, pipeline must be a compute pipeline

  • VUID-vkCmdBindPipeline-pipelineBindPoint-00780
    If pipelineBindPoint is VK_PIPELINE_BIND_POINT_GRAPHICS, pipeline must be a graphics pipeline

  • VUID-vkCmdBindPipeline-pipeline-00781
    If the variable multisample rate feature is not supported, pipeline is a graphics pipeline, the current subpass uses no attachments, and this is not the first call to this function with a graphics pipeline after transitioning to the current subpass, then the sample count specified by this pipeline must match that set in the previous pipeline

  • VUID-vkCmdBindPipeline-pipelineBindPoint-02391
    If pipelineBindPoint is VK_PIPELINE_BIND_POINT_RAY_TRACING_KHR, the VkCommandPool that commandBuffer was allocated from must support compute operations

  • VUID-vkCmdBindPipeline-pipelineBindPoint-02392
    If pipelineBindPoint is VK_PIPELINE_BIND_POINT_RAY_TRACING_KHR, pipeline must be a ray tracing pipeline

  • VUID-vkCmdBindPipeline-pipeline-03382
    pipeline must not have been created with VK_PIPELINE_CREATE_LIBRARY_BIT_KHR set

Valid Usage (Implicit)
  • VUID-vkCmdBindPipeline-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

  • VUID-vkCmdBindPipeline-pipelineBindPoint-parameter
    pipelineBindPoint must be a valid VkPipelineBindPoint value

  • VUID-vkCmdBindPipeline-pipeline-parameter
    pipeline must be a valid VkPipeline handle

  • VUID-vkCmdBindPipeline-commandBuffer-recording
    commandBuffer must be in the recording state

  • VUID-vkCmdBindPipeline-commandBuffer-cmdpool
    The VkCommandPool that commandBuffer was allocated from must support graphics, or compute operations

  • VUID-vkCmdBindPipeline-commonparent
    Both of commandBuffer, and pipeline must have been created, allocated, or retrieved from the same VkDevice

Host Synchronization
  • Host access to commandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Supported Queue Types Pipeline Type

Primary
Secondary

Both

Graphics
Compute

Possible values of vkCmdBindPipeline::pipelineBindPoint, specifying the bind point of a pipeline object, are:

// Provided by VK_VERSION_1_0
typedef enum VkPipelineBindPoint {
    VK_PIPELINE_BIND_POINT_GRAPHICS = 0,
    VK_PIPELINE_BIND_POINT_COMPUTE = 1,
  // Provided by VK_KHR_ray_tracing_pipeline
    VK_PIPELINE_BIND_POINT_RAY_TRACING_KHR = 1000165000,
} VkPipelineBindPoint;
  • VK_PIPELINE_BIND_POINT_COMPUTE specifies binding as a compute pipeline.

  • VK_PIPELINE_BIND_POINT_GRAPHICS specifies binding as a graphics pipeline.

  • VK_PIPELINE_BIND_POINT_RAY_TRACING_KHR specifies binding as a ray tracing pipeline.

10.11. Dynamic State

When a pipeline object is bound, any pipeline object state that is not specified as dynamic is applied to the command buffer state. Pipeline object state that is specified as dynamic is not applied to the command buffer state at this time. Instead, dynamic state can be modified at any time and persists for the lifetime of the command buffer, or until modified by another dynamic state setting command or another pipeline bind.

When a pipeline object is bound, the following applies to each state parameter:

  • If the state is not specified as dynamic in the new pipeline object, then that command buffer state is overwritten by the state in the new pipeline object. Before any draw or dispatch call with this pipeline there must not have been any calls to any of the corresponding dynamic state setting commands after this pipeline was bound

  • If the state is specified as dynamic in the new pipeline object, then that command buffer state is not disturbed. Before any draw or dispatch call with this pipeline there must have been at least one call to each of the corresponding dynamic state setting commands since the command buffer recording was begun, or the last bound pipeline object with that state specified as static, whichever was the latter

Dynamic state that does not affect the result of operations can be left undefined.

Note

For example, if blending is disabled by the pipeline object state then the dynamic color blend constants do not need to be specified in the command buffer, even if this state is specified as dynamic in the pipeline object.

10.12. Pipeline Shader Information

When a pipeline is created, its state and shaders are compiled into zero or more device-specific executables, which are used when executing commands against that pipeline. To query the properties of these pipeline executables, call:

// Provided by VK_KHR_pipeline_executable_properties
VkResult vkGetPipelineExecutablePropertiesKHR(
    VkDevice                                    device,
    const VkPipelineInfoKHR*                    pPipelineInfo,
    uint32_t*                                   pExecutableCount,
    VkPipelineExecutablePropertiesKHR*          pProperties);
  • device is the device that created the pipeline.

  • pPipelineInfo describes the pipeline being queried.

  • pExecutableCount is a pointer to an integer related to the number of pipeline executables available or queried, as described below.

  • pProperties is either NULL or a pointer to an array of VkPipelineExecutablePropertiesKHR structures.

If pProperties is NULL, then the number of pipeline executables associated with the pipeline is returned in pExecutableCount. Otherwise, pExecutableCount must point to a variable set by the user to the number of elements in the pProperties array, and on return the variable is overwritten with the number of structures actually written to pProperties. If pExecutableCount is less than the number of pipeline executables associated with the pipeline, at most pExecutableCount structures will be written, and VK_INCOMPLETE will be returned instead of VK_SUCCESS, to indicate that not all the available properties were returned.

Valid Usage
  • VUID-vkGetPipelineExecutablePropertiesKHR-pipelineExecutableInfo-03270
    pipelineExecutableInfo must be enabled

  • VUID-vkGetPipelineExecutablePropertiesKHR-pipeline-03271
    pipeline member of pPipelineInfo must have been created with device

Valid Usage (Implicit)
  • VUID-vkGetPipelineExecutablePropertiesKHR-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkGetPipelineExecutablePropertiesKHR-pPipelineInfo-parameter
    pPipelineInfo must be a valid pointer to a valid VkPipelineInfoKHR structure

  • VUID-vkGetPipelineExecutablePropertiesKHR-pExecutableCount-parameter
    pExecutableCount must be a valid pointer to a uint32_t value

  • VUID-vkGetPipelineExecutablePropertiesKHR-pProperties-parameter
    If the value referenced by pExecutableCount is not 0, and pProperties is not NULL, pProperties must be a valid pointer to an array of pExecutableCount VkPipelineExecutablePropertiesKHR structures

Return Codes
Success
  • VK_SUCCESS

  • VK_INCOMPLETE

Failure
  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

The VkPipelineInfoKHR structure is defined as:

// Provided by VK_KHR_pipeline_executable_properties
typedef struct VkPipelineInfoKHR {
    VkStructureType    sType;
    const void*        pNext;
    VkPipeline         pipeline;
} VkPipelineInfoKHR;
  • sType is the type of this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • pipeline is a VkPipeline handle.

Valid Usage (Implicit)
  • VUID-VkPipelineInfoKHR-sType-sType
    sType must be VK_STRUCTURE_TYPE_PIPELINE_INFO_KHR

  • VUID-VkPipelineInfoKHR-pNext-pNext
    pNext must be NULL

  • VUID-VkPipelineInfoKHR-pipeline-parameter
    pipeline must be a valid VkPipeline handle

The VkPipelineExecutablePropertiesKHR structure is defined as:

// Provided by VK_KHR_pipeline_executable_properties
typedef struct VkPipelineExecutablePropertiesKHR {
    VkStructureType       sType;
    void*                 pNext;
    VkShaderStageFlags    stages;
    char                  name[VK_MAX_DESCRIPTION_SIZE];
    char                  description[VK_MAX_DESCRIPTION_SIZE];
    uint32_t              subgroupSize;
} VkPipelineExecutablePropertiesKHR;
  • sType is the type of this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • stages is a bitmask of zero or more VkShaderStageFlagBits indicating which shader stages (if any) were principally used as inputs to compile this pipeline executable.

  • name is an array of VK_MAX_DESCRIPTION_SIZE char containing a null-terminated UTF-8 string which is a short human readable name for this pipeline executable.

  • description is an array of VK_MAX_DESCRIPTION_SIZE char containing a null-terminated UTF-8 string which is a human readable description for this pipeline executable.

  • subgroupSize is the subgroup size with which this pipeline executable is dispatched.

Not all implementations have a 1:1 mapping between shader stages and pipeline executables and some implementations may reduce a given shader stage to fixed function hardware programming such that no pipeline executable is available. No guarantees are provided about the mapping between shader stages and pipeline executables and stages should be considered a best effort hint. Because the application cannot rely on the stages field to provide an exact description, name and description provide a human readable name and description which more accurately describes the given pipeline executable.

Valid Usage (Implicit)
  • VUID-VkPipelineExecutablePropertiesKHR-sType-sType
    sType must be VK_STRUCTURE_TYPE_PIPELINE_EXECUTABLE_PROPERTIES_KHR

  • VUID-VkPipelineExecutablePropertiesKHR-pNext-pNext
    pNext must be NULL

Each pipeline executable may have a set of statistics associated with it that are generated by the pipeline compilation process. These statistics may include things such as instruction counts, amount of spilling (if any), maximum number of simultaneous threads, or anything else which may aid developers in evaluating the expected performance of a shader. To query the compile-time statistics associated with a pipeline executable, call:

// Provided by VK_KHR_pipeline_executable_properties
VkResult vkGetPipelineExecutableStatisticsKHR(
    VkDevice                                    device,
    const VkPipelineExecutableInfoKHR*          pExecutableInfo,
    uint32_t*                                   pStatisticCount,
    VkPipelineExecutableStatisticKHR*           pStatistics);
  • device is the device that created the pipeline.

  • pExecutableInfo describes the pipeline executable being queried.

  • pStatisticCount is a pointer to an integer related to the number of statistics available or queried, as described below.

  • pStatistics is either NULL or a pointer to an array of VkPipelineExecutableStatisticKHR structures.

If pStatistics is NULL, then the number of statistics associated with the pipeline executable is returned in pStatisticCount. Otherwise, pStatisticCount must point to a variable set by the user to the number of elements in the pStatistics array, and on return the variable is overwritten with the number of structures actually written to pStatistics. If pStatisticCount is less than the number of statistics associated with the pipeline executable, at most pStatisticCount structures will be written, and VK_INCOMPLETE will be returned instead of VK_SUCCESS, to indicate that not all the available statistics were returned.

Valid Usage
  • VUID-vkGetPipelineExecutableStatisticsKHR-pipelineExecutableInfo-03272
    pipelineExecutableInfo must be enabled

  • VUID-vkGetPipelineExecutableStatisticsKHR-pipeline-03273
    pipeline member of pExecutableInfo must have been created with device

  • VUID-vkGetPipelineExecutableStatisticsKHR-pipeline-03274
    pipeline member of pExecutableInfo must have been created with VK_PIPELINE_CREATE_CAPTURE_STATISTICS_BIT_KHR

Valid Usage (Implicit)
  • VUID-vkGetPipelineExecutableStatisticsKHR-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkGetPipelineExecutableStatisticsKHR-pExecutableInfo-parameter
    pExecutableInfo must be a valid pointer to a valid VkPipelineExecutableInfoKHR structure

  • VUID-vkGetPipelineExecutableStatisticsKHR-pStatisticCount-parameter
    pStatisticCount must be a valid pointer to a uint32_t value

  • VUID-vkGetPipelineExecutableStatisticsKHR-pStatistics-parameter
    If the value referenced by pStatisticCount is not 0, and pStatistics is not NULL, pStatistics must be a valid pointer to an array of pStatisticCount VkPipelineExecutableStatisticKHR structures

Return Codes
Success
  • VK_SUCCESS

  • VK_INCOMPLETE

Failure
  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

The VkPipelineExecutableInfoKHR structure is defined as:

// Provided by VK_KHR_pipeline_executable_properties
typedef struct VkPipelineExecutableInfoKHR {
    VkStructureType    sType;
    const void*        pNext;
    VkPipeline         pipeline;
    uint32_t           executableIndex;
} VkPipelineExecutableInfoKHR;
  • sType is the type of this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • pipeline is the pipeline to query.

  • executableIndex is the index of the pipeline executable to query in the array of executable properties returned by vkGetPipelineExecutablePropertiesKHR.

Valid Usage
  • VUID-VkPipelineExecutableInfoKHR-executableIndex-03275
    executableIndex must be less than the number of pipeline executables associated with pipeline as returned in the pExecutableCount parameter of vkGetPipelineExecutablePropertiesKHR

Valid Usage (Implicit)
  • VUID-VkPipelineExecutableInfoKHR-sType-sType
    sType must be VK_STRUCTURE_TYPE_PIPELINE_EXECUTABLE_INFO_KHR

  • VUID-VkPipelineExecutableInfoKHR-pNext-pNext
    pNext must be NULL

  • VUID-VkPipelineExecutableInfoKHR-pipeline-parameter
    pipeline must be a valid VkPipeline handle

The VkPipelineExecutableStatisticKHR structure is defined as:

// Provided by VK_KHR_pipeline_executable_properties
typedef struct VkPipelineExecutableStatisticKHR {
    VkStructureType                           sType;
    void*                                     pNext;
    char                                      name[VK_MAX_DESCRIPTION_SIZE];
    char                                      description[VK_MAX_DESCRIPTION_SIZE];
    VkPipelineExecutableStatisticFormatKHR    format;
    VkPipelineExecutableStatisticValueKHR     value;
} VkPipelineExecutableStatisticKHR;
  • sType is the type of this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • name is an array of VK_MAX_DESCRIPTION_SIZE char containing a null-terminated UTF-8 string which is a short human readable name for this statistic.

  • description is an array of VK_MAX_DESCRIPTION_SIZE char containing a null-terminated UTF-8 string which is a human readable description for this statistic.

  • format is a VkPipelineExecutableStatisticFormatKHR value specifying the format of the data found in value.

  • value is the value of this statistic.

Valid Usage (Implicit)
  • VUID-VkPipelineExecutableStatisticKHR-sType-sType
    sType must be VK_STRUCTURE_TYPE_PIPELINE_EXECUTABLE_STATISTIC_KHR

  • VUID-VkPipelineExecutableStatisticKHR-pNext-pNext
    pNext must be NULL

The VkPipelineExecutableStatisticFormatKHR enum is defined as:

// Provided by VK_KHR_pipeline_executable_properties
typedef enum VkPipelineExecutableStatisticFormatKHR {
    VK_PIPELINE_EXECUTABLE_STATISTIC_FORMAT_BOOL32_KHR = 0,
    VK_PIPELINE_EXECUTABLE_STATISTIC_FORMAT_INT64_KHR = 1,
    VK_PIPELINE_EXECUTABLE_STATISTIC_FORMAT_UINT64_KHR = 2,
    VK_PIPELINE_EXECUTABLE_STATISTIC_FORMAT_FLOAT64_KHR = 3,
} VkPipelineExecutableStatisticFormatKHR;
  • VK_PIPELINE_EXECUTABLE_STATISTIC_FORMAT_BOOL32_KHR specifies that the statistic is returned as a 32-bit boolean value which must be either VK_TRUE or VK_FALSE and should be read from the b32 field of VkPipelineExecutableStatisticValueKHR.

  • VK_PIPELINE_EXECUTABLE_STATISTIC_FORMAT_INT64_KHR specifies that the statistic is returned as a signed 64-bit integer and should be read from the i64 field of VkPipelineExecutableStatisticValueKHR.

  • VK_PIPELINE_EXECUTABLE_STATISTIC_FORMAT_UINT64_KHR specifies that the statistic is returned as an unsigned 64-bit integer and should be read from the u64 field of VkPipelineExecutableStatisticValueKHR.

  • VK_PIPELINE_EXECUTABLE_STATISTIC_FORMAT_FLOAT64_KHR specifies that the statistic is returned as a 64-bit floating-point value and should be read from the f64 field of VkPipelineExecutableStatisticValueKHR.

The VkPipelineExecutableStatisticValueKHR union is defined as:

// Provided by VK_KHR_pipeline_executable_properties
typedef union VkPipelineExecutableStatisticValueKHR {
    VkBool32    b32;
    int64_t     i64;
    uint64_t    u64;
    double      f64;
} VkPipelineExecutableStatisticValueKHR;
  • b32 is the 32-bit boolean value if the VkPipelineExecutableStatisticFormatKHR is VK_PIPELINE_EXECUTABLE_STATISTIC_FORMAT_BOOL32_KHR.

  • i64 is the signed 64-bit integer value if the VkPipelineExecutableStatisticFormatKHR is VK_PIPELINE_EXECUTABLE_STATISTIC_FORMAT_INT64_KHR.

  • u64 is the unsigned 64-bit integer value if the VkPipelineExecutableStatisticFormatKHR is VK_PIPELINE_EXECUTABLE_STATISTIC_FORMAT_UINT64_KHR.

  • f64 is the 64-bit floating-point value if the VkPipelineExecutableStatisticFormatKHR is VK_PIPELINE_EXECUTABLE_STATISTIC_FORMAT_FLOAT64_KHR.

Each pipeline executable may have one or more text or binary internal representations associated with it which are generated as part of the compile process. These may include the final shader assembly, a binary form of the compiled shader, or the shader compiler’s internal representation at any number of intermediate compile steps. To query the internal representations associated with a pipeline executable, call:

// Provided by VK_KHR_pipeline_executable_properties
VkResult vkGetPipelineExecutableInternalRepresentationsKHR(
    VkDevice                                    device,
    const VkPipelineExecutableInfoKHR*          pExecutableInfo,
    uint32_t*                                   pInternalRepresentationCount,
    VkPipelineExecutableInternalRepresentationKHR* pInternalRepresentations);
  • device is the device that created the pipeline.

  • pExecutableInfo describes the pipeline executable being queried.

  • pInternalRepresentationCount is a pointer to an integer related to the number of internal representations available or queried, as described below.

  • pInternalRepresentations is either NULL or a pointer to an array of VkPipelineExecutableInternalRepresentationKHR structures.

If pInternalRepresentations is NULL, then the number of internal representations associated with the pipeline executable is returned in pInternalRepresentationCount. Otherwise, pInternalRepresentationCount must point to a variable set by the user to the number of elements in the pInternalRepresentations array, and on return the variable is overwritten with the number of structures actually written to pInternalRepresentations. If pInternalRepresentationCount is less than the number of internal representations associated with the pipeline executable, at most pInternalRepresentationCount structures will be written, and VK_INCOMPLETE will be returned instead of VK_SUCCESS, to indicate that not all the available representations were returned.

While the details of the internal representations remain implementation dependent, the implementation should order the internal representations in the order in which they occur in the compiled pipeline with the final shader assembly (if any) last.

Valid Usage
  • VUID-vkGetPipelineExecutableInternalRepresentationsKHR-pipelineExecutableInfo-03276
    pipelineExecutableInfo must be enabled

  • VUID-vkGetPipelineExecutableInternalRepresentationsKHR-pipeline-03277
    pipeline member of pExecutableInfo must have been created with device

  • VUID-vkGetPipelineExecutableInternalRepresentationsKHR-pipeline-03278
    pipeline member of pExecutableInfo must have been created with VK_PIPELINE_CREATE_CAPTURE_INTERNAL_REPRESENTATIONS_BIT_KHR

Valid Usage (Implicit)
  • VUID-vkGetPipelineExecutableInternalRepresentationsKHR-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkGetPipelineExecutableInternalRepresentationsKHR-pExecutableInfo-parameter
    pExecutableInfo must be a valid pointer to a valid VkPipelineExecutableInfoKHR structure

  • VUID-vkGetPipelineExecutableInternalRepresentationsKHR-pInternalRepresentationCount-parameter
    pInternalRepresentationCount must be a valid pointer to a uint32_t value

  • VUID-vkGetPipelineExecutableInternalRepresentationsKHR-pInternalRepresentations-parameter
    If the value referenced by pInternalRepresentationCount is not 0, and pInternalRepresentations is not NULL, pInternalRepresentations must be a valid pointer to an array of pInternalRepresentationCount VkPipelineExecutableInternalRepresentationKHR structures

Return Codes
Success
  • VK_SUCCESS

  • VK_INCOMPLETE

Failure
  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

The VkPipelineExecutableInternalRepresentationKHR structure is defined as:

// Provided by VK_KHR_pipeline_executable_properties
typedef struct VkPipelineExecutableInternalRepresentationKHR {
    VkStructureType    sType;
    void*              pNext;
    char               name[VK_MAX_DESCRIPTION_SIZE];
    char               description[VK_MAX_DESCRIPTION_SIZE];
    VkBool32           isText;
    size_t             dataSize;
    void*              pData;
} VkPipelineExecutableInternalRepresentationKHR;
  • sType is the type of this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • name is an array of VK_MAX_DESCRIPTION_SIZE char containing a null-terminated UTF-8 string which is a short human readable name for this internal representation.

  • description is an array of VK_MAX_DESCRIPTION_SIZE char containing a null-terminated UTF-8 string which is a human readable description for this internal representation.

  • isText specifies whether the returned data is text or opaque data. If isText is VK_TRUE then the data returned in pData is text and is guaranteed to be a null-terminated UTF-8 string.

  • dataSize is an integer related to the size, in bytes, of the internal representation’s data, as described below.

  • pData is either NULL or a pointer to a block of data into which the implementation will write the internal representation.

If pData is NULL, then the size, in bytes, of the internal representation data is returned in dataSize. Otherwise, dataSize must be the size of the buffer, in bytes, pointed to by pData and on return dataSize is overwritten with the number of bytes of data actually written to pData including any trailing null character. If dataSize is less than the size, in bytes, of the internal representation’s data, at most dataSize bytes of data will be written to pData, and VK_INCOMPLETE will be returned instead of VK_SUCCESS, to indicate that not all the available representation was returned.

If isText is VK_TRUE and pData is not NULL and dataSize is not zero, the last byte written to pData will be a null character.

Valid Usage (Implicit)
  • VUID-VkPipelineExecutableInternalRepresentationKHR-sType-sType
    sType must be VK_STRUCTURE_TYPE_PIPELINE_EXECUTABLE_INTERNAL_REPRESENTATION_KHR

  • VUID-VkPipelineExecutableInternalRepresentationKHR-pNext-pNext
    pNext must be NULL