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.
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);-
deviceis the logical device that creates the compute pipelines. -
pipelineCacheis 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. -
createInfoCountis the length of thepCreateInfosandpPipelinesarrays. -
pCreateInfosis a pointer to an array of VkComputePipelineCreateInfo structures. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter. -
pPipelinesis a pointer to an array of VkPipeline handles in which the resulting compute pipeline objects are returned.
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;-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis a bitmask of VkPipelineCreateFlagBits specifying how the pipeline will be generated. -
stageis a VkPipelineShaderStageCreateInfo structure describing the compute shader. -
layoutis the description of binding locations used by both the pipeline and descriptor sets used with the pipeline. -
basePipelineHandleis a pipeline to derive from -
basePipelineIndexis an index into thepCreateInfosparameter to use as a pipeline to derive from
The parameters basePipelineHandle and basePipelineIndex are
described in more detail in Pipeline
Derivatives.
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;-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis a bitmask of VkPipelineShaderStageCreateFlagBits specifying how the pipeline shader stage will be generated. -
stageis a VkShaderStageFlagBits value specifying a single pipeline stage. -
moduleis a VkShaderModule object containing the shader code for this stage. -
pNameis a pointer to a null-terminated UTF-8 string specifying the entry point name of the shader for this stage. -
pSpecializationInfois a pointer to a VkSpecializationInfo structure, as described in Specialization Constants, orNULL.
The shader code used by the pipeline is defined by module.
// 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 {
// Provided by VK_VERSION_1_3
VK_PIPELINE_SHADER_STAGE_CREATE_ALLOW_VARYING_SUBGROUP_SIZE_BIT = 0x00000001,
// Provided by VK_VERSION_1_3
VK_PIPELINE_SHADER_STAGE_CREATE_REQUIRE_FULL_SUBGROUPS_BIT = 0x00000002,
} VkPipelineShaderStageCreateFlagBits;-
VK_PIPELINE_SHADER_STAGE_CREATE_ALLOW_VARYING_SUBGROUP_SIZE_BITspecifies that theSubgroupSizemay vary in the shader stage. -
VK_PIPELINE_SHADER_STAGE_CREATE_REQUIRE_FULL_SUBGROUPS_BITspecifies that the subgroup sizes must be launched with all invocations active in the compute stage.
|
Note
If |
Bits which can be set by commands and structures, specifying one or more 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_BITspecifies the vertex stage. -
VK_SHADER_STAGE_TESSELLATION_CONTROL_BITspecifies the tessellation control stage. -
VK_SHADER_STAGE_TESSELLATION_EVALUATION_BITspecifies the tessellation evaluation stage. -
VK_SHADER_STAGE_GEOMETRY_BITspecifies the geometry stage. -
VK_SHADER_STAGE_FRAGMENT_BITspecifies the fragment stage. -
VK_SHADER_STAGE_COMPUTE_BITspecifies the compute stage. -
VK_SHADER_STAGE_ALL_GRAPHICSis a combination of bits used as shorthand to specify all graphics stages defined above (excluding the compute stage). -
VK_SHADER_STAGE_ALLis 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_KHRspecifies the ray generation stage. -
VK_SHADER_STAGE_ANY_HIT_BIT_KHRspecifies the any-hit stage. -
VK_SHADER_STAGE_CLOSEST_HIT_BIT_KHRspecifies the closest hit stage. -
VK_SHADER_STAGE_MISS_BIT_KHRspecifies the miss stage. -
VK_SHADER_STAGE_INTERSECTION_BIT_KHRspecifies the intersection stage. -
VK_SHADER_STAGE_CALLABLE_BIT_KHRspecifies the callable stage.
|
Note
|
// Provided by VK_VERSION_1_0
typedef VkFlags VkShaderStageFlags;VkShaderStageFlags is a bitmask type for setting a mask of zero or
more VkShaderStageFlagBits.
The VkPipelineShaderStageRequiredSubgroupSizeCreateInfo structure is
defined as:
// Provided by VK_VERSION_1_3
typedef struct VkPipelineShaderStageRequiredSubgroupSizeCreateInfo {
VkStructureType sType;
void* pNext;
uint32_t requiredSubgroupSize;
} VkPipelineShaderStageRequiredSubgroupSizeCreateInfo;If a VkPipelineShaderStageRequiredSubgroupSizeCreateInfo structure is
included in the pNext chain of VkPipelineShaderStageCreateInfo,
it specifies that the pipeline shader stage being compiled has a required
subgroup size.
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);-
deviceis the logical device that creates the graphics pipelines. -
pipelineCacheis 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. -
createInfoCountis the length of thepCreateInfosandpPipelinesarrays. -
pCreateInfosis a pointer to an array of VkGraphicsPipelineCreateInfo structures. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter. -
pPipelinesis a pointer to an array of VkPipeline handles in which the resulting graphics pipeline objects are returned.
The VkGraphicsPipelineCreateInfo structure includes an array of VkPipelineShaderStageCreateInfo structures for each of the desired active shader stages, as well as creation information for all relevant fixed-function stages, and a pipeline layout.
|
Note
An implicit cache may be provided by the implementation or a layer.
For this reason, it is still valid to set
|
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;-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis a bitmask of VkPipelineCreateFlagBits specifying how the pipeline will be generated. -
stageCountis the number of entries in thepStagesarray. -
pStagesis a pointer to an array ofstageCountVkPipelineShaderStageCreateInfo structures describing the set of the shader stages to be included in the graphics pipeline. -
pVertexInputStateis a pointer to a VkPipelineVertexInputStateCreateInfo structure. -
pInputAssemblyStateis a pointer to a VkPipelineInputAssemblyStateCreateInfo structure which determines input assembly behavior for vertex shading, as described in Drawing Commands. -
pTessellationStateis a pointer to a VkPipelineTessellationStateCreateInfo structure defining tessellation state used by tessellation shaders. -
pViewportStateis a pointer to a VkPipelineViewportStateCreateInfo structure defining viewport state used when rasterization is enabled. -
pRasterizationStateis a pointer to a VkPipelineRasterizationStateCreateInfo structure defining rasterization state. -
pMultisampleStateis a pointer to a VkPipelineMultisampleStateCreateInfo structure defining multisample state used when rasterization is enabled. -
pDepthStencilStateis a pointer to a VkPipelineDepthStencilStateCreateInfo structure defining depth/stencil state used when rasterization is enabled for depth or stencil attachments accessed during rendering. -
pColorBlendStateis a pointer to a VkPipelineColorBlendStateCreateInfo structure defining color blend state used when rasterization is enabled for any color attachments accessed during rendering. -
pDynamicStateis a pointer to a VkPipelineDynamicStateCreateInfo structure defining which properties of the pipeline state object are dynamic and can be changed independently of the pipeline state. This can beNULL, which means no state in the pipeline is considered dynamic. -
layoutis the description of binding locations used by both the pipeline and descriptor sets used with the pipeline. -
renderPassis a handle to a render pass object describing the environment in which the pipeline will be used. The pipeline must only be used with a render pass instance compatible with the one provided. See Render Pass Compatibility for more information. -
subpassis the index of the subpass in the render pass where this pipeline will be used. -
basePipelineHandleis a pipeline to derive from. -
basePipelineIndexis an index into thepCreateInfosparameter 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:
This state must be specified to create a complete graphics pipeline.
Pre-rasterization shader state is defined by:
-
VkPipelineShaderStageCreateInfo entries for:
-
Vertex shaders
-
Tessellation control shaders
-
Tessellation evaluation shaders
-
Geometry shaders
-
-
Within the VkPipelineLayout, the full pipeline layout must be specified.
-
VkRenderPass and
subpassparameter -
The
viewMaskparameter of VkPipelineRenderingCreateInfo (formats are ignored)
This state must be specified to create a complete graphics pipeline.
Fragment shader state is defined by:
-
A VkPipelineShaderStageCreateInfo entry for the fragment shader
-
Within the VkPipelineLayout, the full pipeline layout must be specified.
-
VkPipelineMultisampleStateCreateInfo if sample shading is enabled or
renderpassis not VK_NULL_HANDLE -
VkRenderPass and
subpassparameter -
The
viewMaskparameter of VkPipelineRenderingCreateInfo (formats are ignored) -
Inclusion/omission of the
VK_PIPELINE_RASTERIZATION_STATE_CREATE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHRflag
If
rasterizerDiscardEnable is set to VK_FALSE
or VK_DYNAMIC_STATE_RASTERIZER_DISCARD_ENABLE is used,
this state must be specified to create a
complete graphics pipeline.
Fragment output state is defined by:
If
rasterizerDiscardEnable is set to VK_FALSE
or VK_DYNAMIC_STATE_RASTERIZER_DISCARD_ENABLE is used,
this state must be specified to create a
complete graphics pipeline.
Dynamic state values set via pDynamicState must be ignored if the
state they correspond to is not otherwise statically set by one of the state
subsets used to create the pipeline.
For example, if a pipeline only included
pre-rasterization shader
state, then any dynamic state value corresponding to depth or stencil
testing has no effect.
A complete graphics pipeline always includes pre-rasterization shader state, with other subsets included depending on that state as specified in the above sections.
The VkPipelineRenderingCreateInfo structure is defined as:
// Provided by VK_VERSION_1_3
typedef struct VkPipelineRenderingCreateInfo {
VkStructureType sType;
const void* pNext;
uint32_t viewMask;
uint32_t colorAttachmentCount;
const VkFormat* pColorAttachmentFormats;
VkFormat depthAttachmentFormat;
VkFormat stencilAttachmentFormat;
} VkPipelineRenderingCreateInfo;or the equivalent
// Provided by VK_KHR_dynamic_rendering
typedef VkPipelineRenderingCreateInfo VkPipelineRenderingCreateInfoKHR;-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
viewMaskis the viewMask used for rendering. -
colorAttachmentCountis the number of entries inpColorAttachmentFormats -
pColorAttachmentFormatsis a pointer to an array of VkFormat values defining the format of color attachments used in this pipeline. -
depthAttachmentFormatis a VkFormat value defining the format of the depth attachment used in this pipeline. -
stencilAttachmentFormatis a VkFormat value defining the format of the stencil attachment used in this pipeline.
When a pipeline is created without a VkRenderPass, if this structure
is present in the pNext chain of VkGraphicsPipelineCreateInfo,
it specifies the view mask and format of attachments used for rendering.
If this structure is not specified, and the pipeline does not include a
VkRenderPass, viewMask and colorAttachmentCount are 0,
and depthAttachmentFormat and stencilAttachmentFormat are
VK_FORMAT_UNDEFINED.
If a graphics pipeline is created with a valid VkRenderPass,
parameters of this structure are ignored.
If depthAttachmentFormat, stencilAttachmentFormat, or any
element of pColorAttachmentFormats is VK_FORMAT_UNDEFINED, it
indicates that the corresponding attachment is unused within the render
pass.
Valid formats indicate that an attachment can be used - but it is still
valid to set the attachment to NULL when beginning rendering.
Bits which can be set in
-
VkGraphicsPipelineCreateInfo::
flags -
VkComputePipelineCreateInfo::
flags
specify how a pipeline is created, and 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_VERSION_1_3
VK_PIPELINE_CREATE_FAIL_ON_PIPELINE_COMPILE_REQUIRED_BIT = 0x00000100,
// Provided by VK_VERSION_1_3
VK_PIPELINE_CREATE_EARLY_RETURN_ON_FAILURE_BIT = 0x00000200,
// Provided by VK_KHR_dynamic_rendering with VK_KHR_fragment_shading_rate
VK_PIPELINE_CREATE_RENDERING_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR = 0x00200000,
// Provided by VK_KHR_dynamic_rendering with VK_EXT_fragment_density_map
VK_PIPELINE_CREATE_RENDERING_FRAGMENT_DENSITY_MAP_ATTACHMENT_BIT_EXT = 0x00400000,
// 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,
// Provided by VK_VERSION_1_1
VK_PIPELINE_CREATE_DISPATCH_BASE = VK_PIPELINE_CREATE_DISPATCH_BASE_BIT,
// Provided by VK_KHR_dynamic_rendering with VK_KHR_fragment_shading_rate
VK_PIPELINE_RASTERIZATION_STATE_CREATE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR = VK_PIPELINE_CREATE_RENDERING_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR,
// Provided by VK_KHR_dynamic_rendering with VK_EXT_fragment_density_map
VK_PIPELINE_RASTERIZATION_STATE_CREATE_FRAGMENT_DENSITY_MAP_ATTACHMENT_BIT_EXT = VK_PIPELINE_CREATE_RENDERING_FRAGMENT_DENSITY_MAP_ATTACHMENT_BIT_EXT,
// 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_BITspecifies 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_BITspecifies 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_BITspecifies that the pipeline to be created will be a child of a previously created parent pipeline. -
VK_PIPELINE_CREATE_VIEW_INDEX_FROM_DEVICE_INDEX_BITspecifies that any shader input variables decorated asViewIndexwill be assigned values as if they were decorated asDeviceIndex. -
VK_PIPELINE_CREATE_DISPATCH_BASEspecifies that a compute pipeline can be used with vkCmdDispatchBase with a non-zero base workgroup. -
VK_PIPELINE_CREATE_CAPTURE_STATISTICS_BIT_KHRspecifies 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_KHRspecifies 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. When capturing IR from pipelines created with pipeline libraries, there is no guarantee that IR from libraries can be retrieved from the linked pipeline. Applications should retrieve IR from each library, and any linked pipelines, separately. -
VK_PIPELINE_CREATE_LIBRARY_BIT_KHRspecifies 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_KHRspecifies that an any-hit shader will always be present when an any-hit shader would be executed. A NULL any-hit shader is an any-hit shader which is effectivelyVK_SHADER_UNUSED_KHR, such as from a shader group consisting entirely of zeros. -
VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_CLOSEST_HIT_SHADERS_BIT_KHRspecifies that a closest hit shader will always be present when a closest hit shader would be executed. A NULL closest hit shader is a closest hit shader which is effectivelyVK_SHADER_UNUSED_KHR, such as from a shader group consisting entirely of zeros. -
VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_MISS_SHADERS_BIT_KHRspecifies that a miss shader will always be present when a miss shader would be executed. A NULL miss shader is a miss shader which is effectivelyVK_SHADER_UNUSED_KHR, such as from a shader group consisting entirely of zeros. -
VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_INTERSECTION_SHADERS_BIT_KHRspecifies that an intersection shader will always be present when an intersection shader would be executed. A NULL intersection shader is an intersection shader which is effectivelyVK_SHADER_UNUSED_KHR, such as from a shader group consisting entirely of zeros. -
VK_PIPELINE_CREATE_RAY_TRACING_SKIP_TRIANGLES_BIT_KHRspecifies that triangle primitives will be skipped during traversal usingOpTraceRayKHR. -
VK_PIPELINE_CREATE_RAY_TRACING_SKIP_AABBS_BIT_KHRspecifies that AABB primitives will be skipped during traversal usingOpTraceRayKHR. -
VK_PIPELINE_CREATE_RAY_TRACING_SHADER_GROUP_HANDLE_CAPTURE_REPLAY_BIT_KHRspecifies that the shader group handles can be saved and reused on a subsequent run (e.g. for trace capture and replay). -
VK_PIPELINE_CREATE_FAIL_ON_PIPELINE_COMPILE_REQUIRED_BITspecifies that pipeline creation will fail if a compile is required for creation of a valid VkPipeline object;VK_PIPELINE_COMPILE_REQUIREDwill be returned by pipeline creation, and the VkPipeline will be set to VK_NULL_HANDLE. -
When creating multiple pipelines,
VK_PIPELINE_CREATE_EARLY_RETURN_ON_FAILURE_BITspecifies that control will be returned to the application if any individual pipeline returns a result which is notVK_SUCCESSrather than continuing to create additional pipelines. -
VK_PIPELINE_CREATE_RENDERING_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHRspecifies that the pipeline will be used with a fragment shading rate attachment and dynamic rendering.
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;-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis reserved for future use. -
dynamicStateCountis the number of elements in thepDynamicStatesarray. -
pDynamicStatesis 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 information.
// 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_VERSION_1_3
VK_DYNAMIC_STATE_CULL_MODE = 1000267000,
// Provided by VK_VERSION_1_3
VK_DYNAMIC_STATE_FRONT_FACE = 1000267001,
// Provided by VK_VERSION_1_3
VK_DYNAMIC_STATE_PRIMITIVE_TOPOLOGY = 1000267002,
// Provided by VK_VERSION_1_3
VK_DYNAMIC_STATE_VIEWPORT_WITH_COUNT = 1000267003,
// Provided by VK_VERSION_1_3
VK_DYNAMIC_STATE_SCISSOR_WITH_COUNT = 1000267004,
// Provided by VK_VERSION_1_3
VK_DYNAMIC_STATE_VERTEX_INPUT_BINDING_STRIDE = 1000267005,
// Provided by VK_VERSION_1_3
VK_DYNAMIC_STATE_DEPTH_TEST_ENABLE = 1000267006,
// Provided by VK_VERSION_1_3
VK_DYNAMIC_STATE_DEPTH_WRITE_ENABLE = 1000267007,
// Provided by VK_VERSION_1_3
VK_DYNAMIC_STATE_DEPTH_COMPARE_OP = 1000267008,
// Provided by VK_VERSION_1_3
VK_DYNAMIC_STATE_DEPTH_BOUNDS_TEST_ENABLE = 1000267009,
// Provided by VK_VERSION_1_3
VK_DYNAMIC_STATE_STENCIL_TEST_ENABLE = 1000267010,
// Provided by VK_VERSION_1_3
VK_DYNAMIC_STATE_STENCIL_OP = 1000267011,
// Provided by VK_VERSION_1_3
VK_DYNAMIC_STATE_RASTERIZER_DISCARD_ENABLE = 1000377001,
// Provided by VK_VERSION_1_3
VK_DYNAMIC_STATE_DEPTH_BIAS_ENABLE = 1000377002,
// Provided by VK_VERSION_1_3
VK_DYNAMIC_STATE_PRIMITIVE_RESTART_ENABLE = 1000377004,
// 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;-
VK_DYNAMIC_STATE_VIEWPORTspecifies that thepViewportsstate in VkPipelineViewportStateCreateInfo will be ignored and must be set dynamically with vkCmdSetViewport before any drawing commands. The number of viewports used by a pipeline is still specified by theviewportCountmember of VkPipelineViewportStateCreateInfo. -
VK_DYNAMIC_STATE_SCISSORspecifies that thepScissorsstate in VkPipelineViewportStateCreateInfo will be ignored and must be set dynamically with vkCmdSetScissor before any drawing commands. The number of scissor rectangles used by a pipeline is still specified by thescissorCountmember of VkPipelineViewportStateCreateInfo. -
VK_DYNAMIC_STATE_LINE_WIDTHspecifies that thelineWidthstate in VkPipelineRasterizationStateCreateInfo will be ignored and must be set dynamically with vkCmdSetLineWidth before any drawing commands that generate line primitives for the rasterizer. -
VK_DYNAMIC_STATE_DEPTH_BIASspecifies that thedepthBiasConstantFactor,depthBiasClampanddepthBiasSlopeFactorstates in VkPipelineRasterizationStateCreateInfo will be ignored and must be set dynamically with vkCmdSetDepthBias before any draws are performed withdepthBiasEnablein VkPipelineRasterizationStateCreateInfo set toVK_TRUE. -
VK_DYNAMIC_STATE_BLEND_CONSTANTSspecifies that theblendConstantsstate in VkPipelineColorBlendStateCreateInfo will be ignored and must be set dynamically with vkCmdSetBlendConstants before any draws are performed with a pipeline state withVkPipelineColorBlendAttachmentStatememberblendEnableset toVK_TRUEand any of the blend functions using a constant blend color. -
VK_DYNAMIC_STATE_DEPTH_BOUNDSspecifies that theminDepthBoundsandmaxDepthBoundsstates of VkPipelineDepthStencilStateCreateInfo will be ignored and must be set dynamically with vkCmdSetDepthBounds before any draws are performed with a pipeline state with VkPipelineDepthStencilStateCreateInfo memberdepthBoundsTestEnableset toVK_TRUE. -
VK_DYNAMIC_STATE_STENCIL_COMPARE_MASKspecifies that thecompareMaskstate in VkPipelineDepthStencilStateCreateInfo for bothfrontandbackwill be ignored and must be set dynamically with vkCmdSetStencilCompareMask before any draws are performed with a pipeline state with VkPipelineDepthStencilStateCreateInfo memberstencilTestEnableset toVK_TRUE -
VK_DYNAMIC_STATE_STENCIL_WRITE_MASKspecifies that thewriteMaskstate in VkPipelineDepthStencilStateCreateInfo for bothfrontandbackwill be ignored and must be set dynamically with vkCmdSetStencilWriteMask before any draws are performed with a pipeline state with VkPipelineDepthStencilStateCreateInfo memberstencilTestEnableset toVK_TRUE -
VK_DYNAMIC_STATE_STENCIL_REFERENCEspecifies that thereferencestate in VkPipelineDepthStencilStateCreateInfo for bothfrontandbackwill be ignored and must be set dynamically with vkCmdSetStencilReference before any draws are performed with a pipeline state with VkPipelineDepthStencilStateCreateInfo memberstencilTestEnableset toVK_TRUE -
VK_DYNAMIC_STATE_CULL_MODEspecifies that thecullModestate in VkPipelineRasterizationStateCreateInfo will be ignored and must be set dynamically with vkCmdSetCullMode before any drawing commands. -
VK_DYNAMIC_STATE_FRONT_FACEspecifies that thefrontFacestate in VkPipelineRasterizationStateCreateInfo will be ignored and must be set dynamically with vkCmdSetFrontFace before any drawing commands. -
VK_DYNAMIC_STATE_PRIMITIVE_TOPOLOGYspecifies that thetopologystate in VkPipelineInputAssemblyStateCreateInfo only specifies the topology class, and the specific topology order and adjacency must be set dynamically with vkCmdSetPrimitiveTopology before any drawing commands. -
VK_DYNAMIC_STATE_VIEWPORT_WITH_COUNTspecifies that theviewportCountandpViewportsstate in VkPipelineViewportStateCreateInfo will be ignored and must be set dynamically with vkCmdSetViewportWithCount before any draw call. -
VK_DYNAMIC_STATE_SCISSOR_WITH_COUNTspecifies that thescissorCountandpScissorsstate in VkPipelineViewportStateCreateInfo will be ignored and must be set dynamically with vkCmdSetScissorWithCount before any draw call. -
VK_DYNAMIC_STATE_VERTEX_INPUT_BINDING_STRIDEspecifies that thestridestate in VkVertexInputBindingDescription will be ignored and must be set dynamically with vkCmdBindVertexBuffers2 before any draw call. -
VK_DYNAMIC_STATE_DEPTH_TEST_ENABLEspecifies that thedepthTestEnablestate in VkPipelineDepthStencilStateCreateInfo will be ignored and must be set dynamically with vkCmdSetDepthTestEnable before any draw call. -
VK_DYNAMIC_STATE_DEPTH_WRITE_ENABLEspecifies that thedepthWriteEnablestate in VkPipelineDepthStencilStateCreateInfo will be ignored and must be set dynamically with vkCmdSetDepthWriteEnable before any draw call. -
VK_DYNAMIC_STATE_DEPTH_COMPARE_OPspecifies that thedepthCompareOpstate in VkPipelineDepthStencilStateCreateInfo will be ignored and must be set dynamically with vkCmdSetDepthCompareOp before any draw call. -
VK_DYNAMIC_STATE_DEPTH_BOUNDS_TEST_ENABLEspecifies that thedepthBoundsTestEnablestate in VkPipelineDepthStencilStateCreateInfo will be ignored and must be set dynamically with vkCmdSetDepthBoundsTestEnable before any draw call. -
VK_DYNAMIC_STATE_STENCIL_TEST_ENABLEspecifies that thestencilTestEnablestate in VkPipelineDepthStencilStateCreateInfo will be ignored and must be set dynamically with vkCmdSetStencilTestEnable before any draw call. -
VK_DYNAMIC_STATE_STENCIL_OPspecifies that thefailOp,passOp,depthFailOp, andcompareOpstates inVkPipelineDepthStencilStateCreateInfofor bothfrontandbackwill be ignored and must be set dynamically with vkCmdSetStencilOp before any draws are performed with a pipeline state withVkPipelineDepthStencilStateCreateInfomemberstencilTestEnableset toVK_TRUE -
VK_DYNAMIC_STATE_RASTERIZER_DISCARD_ENABLEspecifies that therasterizerDiscardEnablestate in VkPipelineRasterizationStateCreateInfo will be ignored and must be set dynamically with vkCmdSetRasterizerDiscardEnable before any drawing commands. -
VK_DYNAMIC_STATE_DEPTH_BIAS_ENABLEspecifies that thedepthBiasEnablestate in VkPipelineRasterizationStateCreateInfo will be ignored and must be set dynamically with vkCmdSetDepthBiasEnable before any drawing commands. -
VK_DYNAMIC_STATE_PRIMITIVE_RESTART_ENABLEspecifies that theprimitiveRestartEnablestate in VkPipelineInputAssemblyStateCreateInfo will be ignored and must be set dynamically with vkCmdSetPrimitiveRestartEnable before any drawing commands. -
VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHRspecifies that state in VkPipelineFragmentShadingRateStateCreateInfoKHR will be ignored and must be set dynamically with vkCmdSetFragmentShadingRateKHR before any drawing commands. -
VK_DYNAMIC_STATE_RAY_TRACING_PIPELINE_STACK_SIZE_KHRspecifies that the default stack size computation for the pipeline will be ignored and must be set dynamically with vkCmdSetRayTracingPipelineStackSizeKHR before any ray tracing calls are performed.
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 determined by Fragment Operations state. 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.
-
Depth/stencil-only rendering in a subpass with no color attachments
-
Active Pipeline Shader Stages
-
Vertex Shader
-
-
Required: Fixed-Function Pipeline Stages
-
-
Color-only rendering in a subpass with no depth/stencil attachment
-
Active Pipeline Shader Stages
-
Vertex Shader
-
Fragment Shader
-
-
Required: Fixed-Function Pipeline Stages
-
-
Rendering pipeline with tessellation and geometry shaders
-
Active Pipeline Shader Stages
-
Vertex Shader
-
Tessellation Control Shader
-
Tessellation Evaluation Shader
-
Geometry Shader
-
Fragment Shader
-
-
Required: Fixed-Function Pipeline Stages
-
10.3. Ray Tracing Pipelines
Ray tracing pipelines consist of multiple shader stages, fixed-function traversal stages, and a pipeline layout.
VK_SHADER_UNUSED_KHR is a special shader index used to indicate that a
ray generation, miss, or callable shader member is not used.
#define VK_SHADER_UNUSED_KHR (~0U)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);-
deviceis the logical device that creates the ray tracing pipelines. -
deferredOperationis VK_NULL_HANDLE or the handle of a valid VkDeferredOperationKHR request deferral object for this command. -
pipelineCacheis 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. -
createInfoCountis the length of thepCreateInfosandpPipelinesarrays. -
pCreateInfosis a pointer to an array of VkRayTracingPipelineCreateInfoKHR structures. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter. -
pPipelinesis 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.
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;-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis a bitmask of VkPipelineCreateFlagBits specifying how the pipeline will be generated. -
stageCountis the number of entries in thepStagesarray. -
pStagesis a pointer to an array ofstageCountVkPipelineShaderStageCreateInfo structures describing the set of the shader stages to be included in the ray tracing pipeline. -
groupCountis the number of entries in thepGroupsarray. -
pGroupsis a pointer to an array ofgroupCountVkRayTracingShaderGroupCreateInfoKHR structures describing the set of the shader stages to be included in each shader group in the ray tracing pipeline. -
maxPipelineRayRecursionDepthis the maximum recursion depth of shaders executed by this pipeline. -
pLibraryInfois a pointer to a VkPipelineLibraryCreateInfoKHR structure defining pipeline libraries to include. -
pLibraryInterfaceis a pointer to a VkRayTracingPipelineInterfaceCreateInfoKHR structure defining additional information when using pipeline libraries. -
pDynamicStateis 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 beNULL, which means no state in the pipeline is considered dynamic. -
layoutis the description of binding locations used by both the pipeline and descriptor sets used with the pipeline. -
basePipelineHandleis a pipeline to derive from. -
basePipelineIndexis an index into thepCreateInfosparameter 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.
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;-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
typeis the type of hit group specified in this structure. -
generalShaderis the index of the ray generation, miss, or callable shader from VkRayTracingPipelineCreateInfoKHR::pStagesin the group if the shader group hastypeofVK_RAY_TRACING_SHADER_GROUP_TYPE_GENERAL_KHR, andVK_SHADER_UNUSED_KHRotherwise. -
closestHitShaderis the optional index of the closest hit shader from VkRayTracingPipelineCreateInfoKHR::pStagesin the group if the shader group hastypeofVK_RAY_TRACING_SHADER_GROUP_TYPE_TRIANGLES_HIT_GROUP_KHRorVK_RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_KHR, andVK_SHADER_UNUSED_KHRotherwise. -
anyHitShaderis the optional index of the any-hit shader from VkRayTracingPipelineCreateInfoKHR::pStagesin the group if the shader group hastypeofVK_RAY_TRACING_SHADER_GROUP_TYPE_TRIANGLES_HIT_GROUP_KHRorVK_RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_KHR, andVK_SHADER_UNUSED_KHRotherwise. -
intersectionShaderis the index of the intersection shader from VkRayTracingPipelineCreateInfoKHR::pStagesin the group if the shader group hastypeofVK_RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_KHR, andVK_SHADER_UNUSED_KHRotherwise. -
pShaderGroupCaptureReplayHandleisNULLor a pointer to replay information for this shader group queried from vkGetRayTracingCaptureReplayShaderGroupHandlesKHR, as described in Ray Tracing Capture Replay. Ignored if VkPhysicalDeviceRayTracingPipelineFeaturesKHR::rayTracingPipelineShaderGroupHandleCaptureReplayisVK_FALSE.
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_KHRindicates a shader group with a singleVK_SHADER_STAGE_RAYGEN_BIT_KHR,VK_SHADER_STAGE_MISS_BIT_KHR, orVK_SHADER_STAGE_CALLABLE_BIT_KHRshader in it. -
VK_RAY_TRACING_SHADER_GROUP_TYPE_TRIANGLES_HIT_GROUP_KHRspecifies 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_KHRspecifies 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;-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
maxPipelineRayPayloadSizeis the maximum payload size in bytes used by any shader in the pipeline. -
maxPipelineRayHitAttributeSizeis 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 |
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);-
deviceis the logical device containing the ray tracing pipeline. -
pipelineis the ray tracing pipeline object containing the shaders. -
firstGroupis the index of the first group to retrieve a handle for from the VkRayTracingPipelineCreateInfoKHR::pGroupsarray. -
groupCountis the number of shader handles to retrieve. -
dataSizeis the size in bytes of the buffer pointed to bypData. -
pDatais a pointer to a user-allocated buffer where the results will be written.
To query the opaque capture data of shader groups in a 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);-
deviceis the logical device containing the ray tracing pipeline. -
pipelineis the ray tracing pipeline object containing the shaders. -
firstGroupis the index of the first group to retrieve a handle for from the VkRayTracingPipelineCreateInfoKHR::pGroupsarray. -
groupCountis the number of shader handles to retrieve. -
dataSizeis the size in bytes of the buffer pointed to bypData. -
pDatais a pointer to a user-allocated buffer where the results will be written.
Once queried, this opaque data can be provided at pipeline creation time
(in a subsequent execution), using
VkRayTracingShaderGroupCreateInfoKHR::pShaderGroupCaptureReplayHandle,
as described in Ray Tracing Capture Replay.
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);-
deviceis the logical device containing the ray tracing pipeline. -
pipelineis the ray tracing pipeline object containing the shaders groups. -
groupis the index of the shader group to query. -
groupShaderis 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.
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;-
VK_SHADER_GROUP_SHADER_GENERAL_KHRuses the shader specified in the group with VkRayTracingShaderGroupCreateInfoKHR::generalShader -
VK_SHADER_GROUP_SHADER_CLOSEST_HIT_KHRuses the shader specified in the group with VkRayTracingShaderGroupCreateInfoKHR::closestHitShader -
VK_SHADER_GROUP_SHADER_ANY_HIT_KHRuses the shader specified in the group with VkRayTracingShaderGroupCreateInfoKHR::anyHitShader -
VK_SHADER_GROUP_SHADER_INTERSECTION_KHRuses the shader specified in the group with VkRayTracingShaderGroupCreateInfoKHR::intersectionShader
To dynamically set the stack size for a ray tracing pipeline, call:
// Provided by VK_KHR_ray_tracing_pipeline
void vkCmdSetRayTracingPipelineStackSizeKHR(
VkCommandBuffer commandBuffer,
uint32_t pipelineStackSize);-
commandBufferis the command buffer into which the command will be recorded. -
pipelineStackSizeis the stack size to use for subsequent ray tracing trace commands.
This command sets the stack size for subsequent ray tracing commands when
the ray tracing pipeline is created with
VK_DYNAMIC_STATE_RAY_TRACING_PIPELINE_STACK_SIZE_KHR set in
VkPipelineDynamicStateCreateInfo::pDynamicStates.
Otherwise, the stack size is computed as described in
Ray Tracing Pipeline Stack.
10.4. Pipeline Destruction
To destroy a pipeline, call:
// Provided by VK_VERSION_1_0
void vkDestroyPipeline(
VkDevice device,
VkPipeline pipeline,
const VkAllocationCallbacks* pAllocator);-
deviceis the logical device that destroys the pipeline. -
pipelineis the handle of the pipeline to destroy. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter.
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.
If creation fails for a pipeline that had
VK_PIPELINE_CREATE_EARLY_RETURN_ON_FAILURE_BIT set, pipelines at an
index in the pPipelines array greater than or equal to that of the
failing pipeline must be set to VK_NULL_HANDLE.
If multiple pipelines fail to be created, the VkResult must be the
return value of any of the pipelines which did not return VK_SUCCESS.
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)10.7.1. Creating a Pipeline Cache
To create pipeline cache objects, call:
// Provided by VK_VERSION_1_0
VkResult vkCreatePipelineCache(
VkDevice device,
const VkPipelineCacheCreateInfo* pCreateInfo,
const VkAllocationCallbacks* pAllocator,
VkPipelineCache* pPipelineCache);-
deviceis the logical device that creates the pipeline cache object. -
pCreateInfois a pointer to a VkPipelineCacheCreateInfo structure containing initial parameters for the pipeline cache object. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter. -
pPipelineCacheis 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 |
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.
If flags of pCreateInfo includes
VK_PIPELINE_CACHE_CREATE_EXTERNALLY_SYNCHRONIZED_BIT, all commands
that modify the returned pipeline cache object must be
externally synchronized.
|
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 |
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;-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis a bitmask of VkPipelineCacheCreateFlagBits specifying the behavior of the pipeline cache. -
initialDataSizeis the number of bytes inpInitialData. IfinitialDataSizeis zero, the pipeline cache will initially be empty. -
pInitialDatais 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. IfinitialDataSizeis zero,pInitialDatais ignored.
// Provided by VK_VERSION_1_0
typedef VkFlags VkPipelineCacheCreateFlags;VkPipelineCacheCreateFlags is a bitmask type for setting a mask of
zero or more VkPipelineCacheCreateFlagBits.
Bits which can be set in VkPipelineCacheCreateInfo::flags,
specifying behavior of the pipeline cache, are:
typedef enum VkPipelineCacheCreateFlagBits {
// Provided by VK_VERSION_1_3
VK_PIPELINE_CACHE_CREATE_EXTERNALLY_SYNCHRONIZED_BIT = 0x00000001,
} VkPipelineCacheCreateFlagBits;-
VK_PIPELINE_CACHE_CREATE_EXTERNALLY_SYNCHRONIZED_BITspecifies that all commands that modify the created VkPipelineCache will be externally synchronized. When set, the implementation may skip any unnecessary processing needed to support simultaneous modification from multiple threads where allowed.
10.7.2. Merging Pipeline Caches
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);-
deviceis the logical device that owns the pipeline cache objects. -
dstCacheis the handle of the pipeline cache to merge results into. -
srcCacheCountis the length of thepSrcCachesarray. -
pSrcCachesis a pointer to an array of pipeline cache handles, which will be merged intodstCache. The previous contents ofdstCacheare 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. |
10.7.3. Retrieving Pipeline Cache Data
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);-
deviceis the logical device that owns the pipeline cache. -
pipelineCacheis the pipeline cache to retrieve data from. -
pDataSizeis a pointer to asize_tvalue related to the amount of data in the pipeline cache, as described below. -
pDatais eitherNULLor 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.
The initial bytes written to pData must be a header as described in
the Pipeline Cache Header section.
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.
10.7.4. Pipeline Cache Header
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 pipeline cache data must begin with a valid pipeline cache header.
Version one of the pipeline cache header is defined as:
// Provided by VK_VERSION_1_0
typedef struct VkPipelineCacheHeaderVersionOne {
uint32_t headerSize;
VkPipelineCacheHeaderVersion headerVersion;
uint32_t vendorID;
uint32_t deviceID;
uint8_t pipelineCacheUUID[VK_UUID_SIZE];
} VkPipelineCacheHeaderVersionOne;-
headerSizeis the length in bytes of the pipeline cache header. -
headerVersionis a VkPipelineCacheHeaderVersion enum value specifying the version of the header. A consumer of the pipeline cache should use the cache version to interpret the remainder of the cache header. -
vendorIDis theVkPhysicalDeviceProperties::vendorIDof the implementation. -
deviceIDis theVkPhysicalDeviceProperties::deviceIDof the implementation. -
pipelineCacheUUIDis theVkPhysicalDeviceProperties::pipelineCacheUUIDof the implementation.
Unlike most structures declared by the Vulkan API, all fields of this structure are written with the least significant byte first, regardless of host byte-order.
The C language specification does not define the packing of structure members. This layout assumes tight structure member packing, with members laid out in the order listed in the structure, and the intended size of the structure is 32 bytes. If a compiler produces code that diverges from that pattern, applications must employ another method to set values at the correct offsets.
Possible values of the headerVersion value of the pipeline cache
header are:
// Provided by VK_VERSION_1_0
typedef enum VkPipelineCacheHeaderVersion {
VK_PIPELINE_CACHE_HEADER_VERSION_ONE = 1,
} VkPipelineCacheHeaderVersion;-
VK_PIPELINE_CACHE_HEADER_VERSION_ONEspecifies version one of the pipeline cache.
10.7.5. Destroying a Pipeline Cache
To destroy a pipeline cache, call:
// Provided by VK_VERSION_1_0
void vkDestroyPipelineCache(
VkDevice device,
VkPipelineCache pipelineCache,
const VkAllocationCallbacks* pAllocator);-
deviceis the logical device that destroys the pipeline cache object. -
pipelineCacheis the handle of the pipeline cache to destroy. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter.
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;-
mapEntryCountis the number of entries in thepMapEntriesarray. -
pMapEntriesis a pointer to an array ofVkSpecializationMapEntrystructures, which map constant IDs to offsets inpData. -
dataSizeis the byte size of thepDatabuffer. -
pDatacontains the actual constant values to specialize with.
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;-
constantIDis the ID of the specialization constant in SPIR-V. -
offsetis the byte offset of the specialization constant value within the supplied data buffer. -
sizeis 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.
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 WorkgroupSizeFrom 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 constantFrom 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 information 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.
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;-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
libraryCountis the number of pipeline libraries inpLibraries. -
pLibrariesis a pointer to an array of VkPipeline structures specifying pipeline libraries to use when creating a pipeline.
Pipelines created with VK_PIPELINE_CREATE_LIBRARY_BIT_KHR libraries
can depend on other pipeline libraries in
VkPipelineLibraryCreateInfoKHR.
A pipeline library is considered in-use, as long as one of the linking pipelines is in-use. This applies recursively if a pipeline library includes other pipeline libraries.
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);-
commandBufferis the command buffer that the pipeline will be bound to. -
pipelineBindPointis a VkPipelineBindPoint value specifying to which bind point the pipeline is bound. Binding one does not disturb the others. -
pipelineis 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.
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_COMPUTEspecifies binding as a compute pipeline. -
VK_PIPELINE_BIND_POINT_GRAPHICSspecifies binding as a graphics pipeline. -
VK_PIPELINE_BIND_POINT_RAY_TRACING_KHRspecifies 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 made invalid by another pipeline bind with that state specified as static.
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. The state-setting commands must be recorded after command buffer recording was begun, or after the last command binding a pipeline object with that state specified as static, whichever was the latter.
-
If the state is not included (corresponding pointer in VkGraphicsPipelineCreateInfo was
NULLor was ignored) in the new pipeline object, then that command buffer state is not disturbed.
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 Properties and 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);-
deviceis the device that created the pipeline. -
pPipelineInfodescribes the pipeline being queried. -
pExecutableCountis a pointer to an integer related to the number of pipeline executables available or queried, as described below. -
pPropertiesis eitherNULLor 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.
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;-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
stagesis a bitmask of zero or more VkShaderStageFlagBits indicating which shader stages (if any) were principally used as inputs to compile this pipeline executable. -
nameis an array ofVK_MAX_DESCRIPTION_SIZEcharcontaining a null-terminated UTF-8 string which is a short human readable name for this pipeline executable. -
descriptionis an array ofVK_MAX_DESCRIPTION_SIZEcharcontaining a null-terminated UTF-8 string which is a human readable description for this pipeline executable. -
subgroupSizeis 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.
The VkPipelineInfoKHR structure is defined as:
// Provided by VK_KHR_pipeline_executable_properties
typedef struct VkPipelineInfoKHR {
VkStructureType sType;
const void* pNext;
VkPipeline pipeline;
} VkPipelineInfoKHR;-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
pipelineis aVkPipelinehandle.
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);-
deviceis the device that created the pipeline. -
pExecutableInfodescribes the pipeline executable being queried. -
pStatisticCountis a pointer to an integer related to the number of statistics available or queried, as described below. -
pStatisticsis eitherNULLor 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.
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;-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
pipelineis the pipeline to query. -
executableIndexis the index of the pipeline executable to query in the array of executable properties returned by vkGetPipelineExecutablePropertiesKHR.
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;-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
nameis an array ofVK_MAX_DESCRIPTION_SIZEcharcontaining a null-terminated UTF-8 string which is a short human readable name for this statistic. -
descriptionis an array ofVK_MAX_DESCRIPTION_SIZEcharcontaining a null-terminated UTF-8 string which is a human readable description for this statistic. -
formatis a VkPipelineExecutableStatisticFormatKHR value specifying the format of the data found invalue. -
valueis the value of this statistic.
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_KHRspecifies that the statistic is returned as a 32-bit boolean value which must be eitherVK_TRUEorVK_FALSEand should be read from theb32field ofVkPipelineExecutableStatisticValueKHR. -
VK_PIPELINE_EXECUTABLE_STATISTIC_FORMAT_INT64_KHRspecifies that the statistic is returned as a signed 64-bit integer and should be read from thei64field ofVkPipelineExecutableStatisticValueKHR. -
VK_PIPELINE_EXECUTABLE_STATISTIC_FORMAT_UINT64_KHRspecifies that the statistic is returned as an unsigned 64-bit integer and should be read from theu64field ofVkPipelineExecutableStatisticValueKHR. -
VK_PIPELINE_EXECUTABLE_STATISTIC_FORMAT_FLOAT64_KHRspecifies that the statistic is returned as a 64-bit floating-point value and should be read from thef64field ofVkPipelineExecutableStatisticValueKHR.
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;-
b32is the 32-bit boolean value if theVkPipelineExecutableStatisticFormatKHRisVK_PIPELINE_EXECUTABLE_STATISTIC_FORMAT_BOOL32_KHR. -
i64is the signed 64-bit integer value if theVkPipelineExecutableStatisticFormatKHRisVK_PIPELINE_EXECUTABLE_STATISTIC_FORMAT_INT64_KHR. -
u64is the unsigned 64-bit integer value if theVkPipelineExecutableStatisticFormatKHRisVK_PIPELINE_EXECUTABLE_STATISTIC_FORMAT_UINT64_KHR. -
f64is the 64-bit floating-point value if theVkPipelineExecutableStatisticFormatKHRisVK_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);-
deviceis the device that created the pipeline. -
pExecutableInfodescribes the pipeline executable being queried. -
pInternalRepresentationCountis a pointer to an integer related to the number of internal representations available or queried, as described below. -
pInternalRepresentationsis eitherNULLor 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.
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;-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
nameis an array ofVK_MAX_DESCRIPTION_SIZEcharcontaining a null-terminated UTF-8 string which is a short human readable name for this internal representation. -
descriptionis an array ofVK_MAX_DESCRIPTION_SIZEcharcontaining a null-terminated UTF-8 string which is a human readable description for this internal representation. -
isTextspecifies whether the returned data is text or opaque data. IfisTextisVK_TRUEthen the data returned inpDatais text and is guaranteed to be a null-terminated UTF-8 string. -
dataSizeis an integer related to the size, in bytes, of the internal representation’s data, as described below. -
pDatais eitherNULLor 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.
10.13. Pipeline Creation Feedback
Feedback about the creation of a particular pipeline object can be obtained
by adding a VkPipelineCreationFeedbackCreateInfo structure to the
pNext chain of VkGraphicsPipelineCreateInfo,
VkRayTracingPipelineCreateInfoKHR,
or VkComputePipelineCreateInfo.
The VkPipelineCreationFeedbackCreateInfo structure is defined as:
// Provided by VK_VERSION_1_3
typedef struct VkPipelineCreationFeedbackCreateInfo {
VkStructureType sType;
const void* pNext;
VkPipelineCreationFeedback* pPipelineCreationFeedback;
uint32_t pipelineStageCreationFeedbackCount;
VkPipelineCreationFeedback* pPipelineStageCreationFeedbacks;
} VkPipelineCreationFeedbackCreateInfo;-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
pPipelineCreationFeedbackis a pointer to a VkPipelineCreationFeedback structure. -
pipelineStageCreationFeedbackCountis the number of elements inpPipelineStageCreationFeedbacks. -
pPipelineStageCreationFeedbacksis a pointer to an array ofpipelineStageCreationFeedbackCountVkPipelineCreationFeedback structures.
An implementation should write pipeline creation feedback to
pPipelineCreationFeedback and may write pipeline stage creation
feedback to pPipelineStageCreationFeedbacks.
An implementation must set or clear the
VK_PIPELINE_CREATION_FEEDBACK_VALID_BIT in
VkPipelineCreationFeedback::flags for
pPipelineCreationFeedback and every element of
pPipelineStageCreationFeedbacks.
|
Note
One common scenario for an implementation to skip per-stage feedback is when
|
When chained to
VkRayTracingPipelineCreateInfoKHR,
or
VkGraphicsPipelineCreateInfo, the i element of
pPipelineStageCreationFeedbacks corresponds to the i element of
VkRayTracingPipelineCreateInfoKHR::pStages,
or
VkGraphicsPipelineCreateInfo::pStages.
When chained to VkComputePipelineCreateInfo, the first element of
pPipelineStageCreationFeedbacks corresponds to
VkComputePipelineCreateInfo::stage.
The VkPipelineCreationFeedback structure is defined as:
// Provided by VK_VERSION_1_3
typedef struct VkPipelineCreationFeedback {
VkPipelineCreationFeedbackFlags flags;
uint64_t duration;
} VkPipelineCreationFeedback;-
flagsis a bitmask of VkPipelineCreationFeedbackFlagBits providing feedback about the creation of a pipeline or of a pipeline stage. -
durationis the duration spent creating a pipeline or pipeline stage in nanoseconds.
If the VK_PIPELINE_CREATION_FEEDBACK_VALID_BIT is not set in
flags, an implementation must not set any other bits in flags,
and the values of all other VkPipelineCreationFeedback data members
are undefined.
Possible values of the flags member of
VkPipelineCreationFeedback are:
// Provided by VK_VERSION_1_3
typedef enum VkPipelineCreationFeedbackFlagBits {
VK_PIPELINE_CREATION_FEEDBACK_VALID_BIT = 0x00000001,
VK_PIPELINE_CREATION_FEEDBACK_APPLICATION_PIPELINE_CACHE_HIT_BIT = 0x00000002,
VK_PIPELINE_CREATION_FEEDBACK_BASE_PIPELINE_ACCELERATION_BIT = 0x00000004,
VK_PIPELINE_CREATION_FEEDBACK_VALID_BIT_EXT = VK_PIPELINE_CREATION_FEEDBACK_VALID_BIT,
VK_PIPELINE_CREATION_FEEDBACK_APPLICATION_PIPELINE_CACHE_HIT_BIT_EXT = VK_PIPELINE_CREATION_FEEDBACK_APPLICATION_PIPELINE_CACHE_HIT_BIT,
VK_PIPELINE_CREATION_FEEDBACK_BASE_PIPELINE_ACCELERATION_BIT_EXT = VK_PIPELINE_CREATION_FEEDBACK_BASE_PIPELINE_ACCELERATION_BIT,
} VkPipelineCreationFeedbackFlagBits;-
VK_PIPELINE_CREATION_FEEDBACK_VALID_BITindicates that the feedback information is valid. -
VK_PIPELINE_CREATION_FEEDBACK_APPLICATION_PIPELINE_CACHE_HIT_BITindicates that a readily usable pipeline or pipeline stage was found in thepipelineCachespecified by the application in the pipeline creation command.An implementation should set the
VK_PIPELINE_CREATION_FEEDBACK_APPLICATION_PIPELINE_CACHE_HIT_BITbit if it was able to avoid the large majority of pipeline or pipeline stage creation work by using thepipelineCacheparameter of vkCreateGraphicsPipelines, vkCreateRayTracingPipelinesKHR, or vkCreateComputePipelines. When an implementation sets this bit for the entire pipeline, it may leave it unset for any stage.NoteImplementations are encouraged to provide a meaningful signal to applications using this bit. The intention is to communicate to the application that the pipeline or pipeline stage was created “as fast as it gets” using the pipeline cache provided by the application. If an implementation uses an internal cache, it is discouraged from setting this bit as the feedback would be unactionable.
-
VK_PIPELINE_CREATION_FEEDBACK_BASE_PIPELINE_ACCELERATION_BITindicates that the base pipeline specified by thebasePipelineHandleorbasePipelineIndexmember of theVk*PipelineCreateInfostructure was used to accelerate the creation of the pipeline.An implementation should set the
VK_PIPELINE_CREATION_FEEDBACK_BASE_PIPELINE_ACCELERATION_BITbit if it was able to avoid a significant amount of work by using the base pipeline.NoteWhile “significant amount of work” is subjective, implementations are encouraged to provide a meaningful signal to applications using this bit. For example, a 1% reduction in duration may not warrant setting this bit, while a 50% reduction would.
// Provided by VK_VERSION_1_3
typedef VkFlags VkPipelineCreationFeedbackFlags;VkPipelineCreationFeedbackFlags is a bitmask type for providing zero
or more VkPipelineCreationFeedbackFlagBits.