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 graphics pipeline can be operated in two modes, as either primitive shading or mesh shading pipeline.
Primitive Shading
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.
Cluster Culling Shading
When using the Cluster Culling Shader, a compute-like shader will perform cluster-based culling, a set of new built-in output variables are used to express visible cluster, in addition, a new built-in function is used to emit these variables from the cluster culling shader to the Input Assembler(IA) stage, then IA can use these variables to fetches vertices of visible cluster and drive vertex shader to work.
Mesh Shading
When using the mesh shading pipeline input primitives are not assembled implicitly, but explicitly through the (Mesh Shader). The work on the mesh pipeline is initiated by the application drawing a set of mesh tasks.
If an optional (Task Shader) is active, each task triggers the execution of a task shader workgroup that will generate a new set of tasks upon completion. Each of these spawned tasks, or each of the original dispatched tasks if no task shader is present, triggers the execution of a mesh shader workgroup that produces an output mesh with a variable-sized number of primitives assembled from vertices stored in the output mesh.
Common
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.
If the commandBufferInheritance
feature is not enabled, then no
state, including dynamic state, is inherited from one command buffer to
another.
If the commandBufferInheritance
feature is enabled, then all graphics and compute state that is valid at the
end of the command buffer executed in a queue is inherited and valid at
beginning of the command buffer next executed in the same queue.
This applies to both primary and secondary command buffers, where a primary
command buffer submitted to a queue will inherit state from the previously
submitted command buffer to that queue, secondary command buffers will
inherit state from the primary or seconard command buffer they are executed
in, and after a seconard command buffer is executed, its state inherited by
the primary or secondary command buffer that executed it.
Command buffers executed in one queue do not inherit state from any command
buffers executed in another queue.
Compute,
ray tracing,
and graphics pipelines are each represented by VkPipeline
handles:
// Provided by VK_VERSION_1_0
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkPipeline)
Multiple Pipeline Creation
Multiple pipelines can be created in a single call by commands such as vkCreateExecutionGraphPipelinesAMDX, vkCreateRayTracingPipelinesKHR, vkCreateRayTracingPipelinesNV, vkCreateComputePipelines, and vkCreateGraphicsPipelines.
The creation commands are passed an array pCreateInfos
of
Vk*PipelineCreateInfo
structures specifying parameters of each
pipeline to be created, and return a corresponding array of handles in
pPipelines
.
Each element index i of pPipelines
is created based on the
corresponding element i of pCreateInfos
.
Applications can group together similar pipelines to be created in a single call, and implementations are encouraged to look for reuse opportunities when creating a group.
When attempting to create many pipelines in a single command, it is possible
that creation may fail for a subset of them.
In this case, the corresponding elements of pPipelines
will be
VK_NULL_HANDLE.
If creation fails for a pipeline despite valid arguments (for example, due
to out of memory errors), the VkResult code returned by the pipeline
creation command 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 has the
VK_PIPELINE_CREATE_EARLY_RETURN_ON_FAILURE_BIT
set in its
Vk*PipelineCreateInfo
, pipelines at an index in the pPipelines
array greater than or equal to that of the failing pipeline will be
VK_NULL_HANDLE.
If creation fails for multiple pipelines, the returned VkResult must
be the return value of any one of the pipelines which did not succeed.
An application can reliably clean up from a failed call by iterating over
the pPipelines
array and destroying every element that is not
VK_NULL_HANDLE.
If the entire command fails and no pipelines are created, all elements of
pPipelines
will be VK_NULL_HANDLE.
Compute Pipelines
Compute pipelines consist of a single static compute shader stage and the pipeline layout.
The compute pipeline represents a compute shader and is created by calling
vkCreateComputePipelines
with module
and pName
selecting an entry point from a shader
module, where that entry point defines a valid compute shader, in the
VkPipelineShaderStageCreateInfo structure contained within the
VkComputePipelineCreateInfo structure.
To create compute pipelines, call:
// Provided by VK_VERSION_1_0
VkResult vkCreateComputePipelines(
VkDevice device,
VkPipelineCache pipelineCache,
uint32_t createInfoCount,
const VkComputePipelineCreateInfo* pCreateInfos,
const VkAllocationCallbacks* pAllocator,
VkPipeline* pPipelines);
-
device
is the logical device that creates the compute pipelines. -
pipelineCache
is either VK_NULL_HANDLE, indicating that pipeline caching is disabled; or the handle of a valid pipeline cache object, in which case use of that cache is enabled for the duration of the command. -
createInfoCount
is the length of thepCreateInfos
andpPipelines
arrays. -
pCreateInfos
is a pointer to an array of VkComputePipelineCreateInfo structures. -
pAllocator
controls host memory allocation as described in the Memory Allocation chapter. -
pPipelines
is a pointer to an array of VkPipeline handles in which the resulting compute pipeline objects are returned.
Pipelines are created and returned as described for Multiple Pipeline Creation.
The VkComputePipelineCreateInfo
structure is defined as:
// Provided by VK_VERSION_1_0
typedef struct VkComputePipelineCreateInfo {
VkStructureType sType;
const void* pNext;
VkPipelineCreateFlags flags;
VkPipelineShaderStageCreateInfo stage;
VkPipelineLayout layout;
VkPipeline basePipelineHandle;
int32_t basePipelineIndex;
} VkComputePipelineCreateInfo;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
flags
is a bitmask of VkPipelineCreateFlagBits specifying how the pipeline will be generated. -
stage
is a VkPipelineShaderStageCreateInfo structure describing the compute shader. -
layout
is the description of binding locations used by both the pipeline and descriptor sets used with the pipeline. -
basePipelineHandle
is a pipeline to derive from. -
basePipelineIndex
is an index into thepCreateInfos
parameter to use as a pipeline to derive from.
The parameters basePipelineHandle
and basePipelineIndex
are
described in more detail in Pipeline Derivatives.
If the pNext
chain includes a
VkPipelineCreateFlags2CreateInfoKHR structure,
VkPipelineCreateFlags2CreateInfoKHR::flags
from that structure
is used instead of flags
from this structure.
The VkPipelineShaderStageCreateInfo
structure is defined as:
// Provided by VK_VERSION_1_0
typedef struct VkPipelineShaderStageCreateInfo {
VkStructureType sType;
const void* pNext;
VkPipelineShaderStageCreateFlags flags;
VkShaderStageFlagBits stage;
VkShaderModule module;
const char* pName;
const VkSpecializationInfo* pSpecializationInfo;
} VkPipelineShaderStageCreateInfo;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
flags
is a bitmask of VkPipelineShaderStageCreateFlagBits specifying how the pipeline shader stage will be generated. -
stage
is a VkShaderStageFlagBits value specifying a single pipeline stage. -
module
is optionally a VkShaderModule object containing the shader code for this stage. -
pName
is a pointer to a null-terminated UTF-8 string specifying the entry point name of the shader for this stage. -
pSpecializationInfo
is a pointer to a VkSpecializationInfo structure, as described in Specialization Constants, orNULL
.
If module
is not VK_NULL_HANDLE, the shader code used by the
pipeline is defined by module
.
If module
is VK_NULL_HANDLE, the shader code is defined by the
chained VkShaderModuleCreateInfo if present.
If the shaderModuleIdentifier
feature is enabled, applications can omit shader code for stage
and
instead provide a module identifier.
This is done by including a
VkPipelineShaderStageModuleIdentifierCreateInfoEXT struct with
identifierSize
not equal to 0 in the pNext
chain.
A shader stage created in this way is equivalent to one created using a
shader module with the same identifier.
The identifier allows an implementation to look up a pipeline without
consuming a valid SPIR-V module.
If a pipeline is not found, pipeline compilation is not possible and the
implementation must fail as specified by
VK_PIPELINE_CREATE_FAIL_ON_PIPELINE_COMPILE_REQUIRED_BIT
.
When an identifier is used in lieu of a shader module, implementations may
fail pipeline compilation with VK_PIPELINE_COMPILE_REQUIRED
for any
reason.
The rationale for the relaxed requirement on implementations to return a pipeline with VkPipelineShaderStageModuleIdentifierCreateInfoEXT is that layers or tools may intercept pipeline creation calls and require the full SPIR-V context to operate correctly. ICDs are not expected to fail pipeline compilation if the pipeline exists in a cache somewhere. |
Applications can use identifiers when creating pipelines with
VK_PIPELINE_CREATE_LIBRARY_BIT_KHR
.
When creating such pipelines, VK_SUCCESS
may be returned, but
subsequently fail when referencing the pipeline in a
VkPipelineLibraryCreateInfoKHR struct.
Applications must allow pipeline compilation to fail during link steps with
VK_PIPELINE_CREATE_FAIL_ON_PIPELINE_COMPILE_REQUIRED_BIT
as it may
not be possible to determine if a pipeline can be created from identifiers
until the link step.
// 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,
// Provided by VK_EXT_subgroup_size_control
VK_PIPELINE_SHADER_STAGE_CREATE_ALLOW_VARYING_SUBGROUP_SIZE_BIT_EXT = VK_PIPELINE_SHADER_STAGE_CREATE_ALLOW_VARYING_SUBGROUP_SIZE_BIT,
// Provided by VK_EXT_subgroup_size_control
VK_PIPELINE_SHADER_STAGE_CREATE_REQUIRE_FULL_SUBGROUPS_BIT_EXT = VK_PIPELINE_SHADER_STAGE_CREATE_REQUIRE_FULL_SUBGROUPS_BIT,
} VkPipelineShaderStageCreateFlagBits;
-
VK_PIPELINE_SHADER_STAGE_CREATE_ALLOW_VARYING_SUBGROUP_SIZE_BIT
specifies that theSubgroupSize
may vary in the shader stage. -
VK_PIPELINE_SHADER_STAGE_CREATE_REQUIRE_FULL_SUBGROUPS_BIT
specifies that the subgroup sizes must be launched with all invocations active in the task, mesh, or compute stage.
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,
// Provided by VK_EXT_mesh_shader
VK_SHADER_STAGE_TASK_BIT_EXT = 0x00000040,
// Provided by VK_EXT_mesh_shader
VK_SHADER_STAGE_MESH_BIT_EXT = 0x00000080,
// Provided by VK_HUAWEI_subpass_shading
VK_SHADER_STAGE_SUBPASS_SHADING_BIT_HUAWEI = 0x00004000,
// Provided by VK_HUAWEI_cluster_culling_shader
VK_SHADER_STAGE_CLUSTER_CULLING_BIT_HUAWEI = 0x00080000,
// Provided by VK_NV_ray_tracing
VK_SHADER_STAGE_RAYGEN_BIT_NV = VK_SHADER_STAGE_RAYGEN_BIT_KHR,
// Provided by VK_NV_ray_tracing
VK_SHADER_STAGE_ANY_HIT_BIT_NV = VK_SHADER_STAGE_ANY_HIT_BIT_KHR,
// Provided by VK_NV_ray_tracing
VK_SHADER_STAGE_CLOSEST_HIT_BIT_NV = VK_SHADER_STAGE_CLOSEST_HIT_BIT_KHR,
// Provided by VK_NV_ray_tracing
VK_SHADER_STAGE_MISS_BIT_NV = VK_SHADER_STAGE_MISS_BIT_KHR,
// Provided by VK_NV_ray_tracing
VK_SHADER_STAGE_INTERSECTION_BIT_NV = VK_SHADER_STAGE_INTERSECTION_BIT_KHR,
// Provided by VK_NV_ray_tracing
VK_SHADER_STAGE_CALLABLE_BIT_NV = VK_SHADER_STAGE_CALLABLE_BIT_KHR,
// Provided by VK_NV_mesh_shader
VK_SHADER_STAGE_TASK_BIT_NV = VK_SHADER_STAGE_TASK_BIT_EXT,
// Provided by VK_NV_mesh_shader
VK_SHADER_STAGE_MESH_BIT_NV = VK_SHADER_STAGE_MESH_BIT_EXT,
} VkShaderStageFlagBits;
-
VK_SHADER_STAGE_VERTEX_BIT
specifies the vertex stage. -
VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT
specifies the tessellation control stage. -
VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT
specifies the tessellation evaluation stage. -
VK_SHADER_STAGE_GEOMETRY_BIT
specifies the geometry stage. -
VK_SHADER_STAGE_FRAGMENT_BIT
specifies the fragment stage. -
VK_SHADER_STAGE_COMPUTE_BIT
specifies the compute stage. -
VK_SHADER_STAGE_ALL_GRAPHICS
is a combination of bits used as shorthand to specify all graphics stages defined above (excluding the compute stage). -
VK_SHADER_STAGE_ALL
is a combination of bits used as shorthand to specify all shader stages supported by the device, including all additional stages which are introduced by extensions. -
VK_SHADER_STAGE_TASK_BIT_EXT
specifies the task stage. -
VK_SHADER_STAGE_MESH_BIT_EXT
specifies the mesh stage. -
VK_SHADER_STAGE_CLUSTER_CULLING_BIT_HUAWEI
specifies the cluster culling stage. -
VK_SHADER_STAGE_RAYGEN_BIT_KHR
specifies the ray generation stage. -
VK_SHADER_STAGE_ANY_HIT_BIT_KHR
specifies the any-hit stage. -
VK_SHADER_STAGE_CLOSEST_HIT_BIT_KHR
specifies the closest hit stage. -
VK_SHADER_STAGE_MISS_BIT_KHR
specifies the miss stage. -
VK_SHADER_STAGE_INTERSECTION_BIT_KHR
specifies the intersection stage. -
VK_SHADER_STAGE_CALLABLE_BIT_KHR
specifies the callable stage.
|
// 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;
or the equivalent
// Provided by VK_EXT_subgroup_size_control
typedef VkPipelineShaderStageRequiredSubgroupSizeCreateInfo VkPipelineShaderStageRequiredSubgroupSizeCreateInfoEXT;
or the equiavlent
// Provided by VK_EXT_shader_object
typedef VkPipelineShaderStageRequiredSubgroupSizeCreateInfo VkShaderRequiredSubgroupSizeCreateInfoEXT;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
requiredSubgroupSize
is an unsigned integer value specifying the required subgroup size for the newly created pipeline shader stage.
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.
If a VkShaderRequiredSubgroupSizeCreateInfoEXT
structure is included
in the pNext
chain of VkShaderCreateInfoEXT, it specifies that
the shader being compiled has a required subgroup size.
A subpass shading pipeline is a compute pipeline which must be called only
in a subpass of a render pass with work dimensions specified by render area
size.
The subpass shading pipeline shader is a compute shader allowed to access
input attachments specified in the calling subpass.
To create a subpass shading pipeline, call vkCreateComputePipelines
with VkSubpassShadingPipelineCreateInfoHUAWEI in the pNext
chain
of VkComputePipelineCreateInfo.
The VkSubpassShadingPipelineCreateInfoHUAWEI
structure is defined as:
// Provided by VK_HUAWEI_subpass_shading
typedef struct VkSubpassShadingPipelineCreateInfoHUAWEI {
VkStructureType sType;
void* pNext;
VkRenderPass renderPass;
uint32_t subpass;
} VkSubpassShadingPipelineCreateInfoHUAWEI;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
renderPass
is a handle to a render pass object describing the environment in which the pipeline will be used. The pipeline must only be used with a render pass instance compatible with the one provided. See Render Pass Compatibility for more information. -
subpass
is the index of the subpass in the render pass where this pipeline will be used.
A subpass shading pipeline’s workgroup size is a 2D vector with number of power-of-two in width and height. The maximum number of width and height is implementation-dependent, and may vary for different formats and sample counts of attachments in a render pass.
To query the maximum workgroup size, call:
// Provided by VK_HUAWEI_subpass_shading
VkResult vkGetDeviceSubpassShadingMaxWorkgroupSizeHUAWEI(
VkDevice device,
VkRenderPass renderpass,
VkExtent2D* pMaxWorkgroupSize);
-
device
is a handle to a local device object that was used to create the given render pass. -
renderPass
is a handle to a render pass object describing the environment in which the pipeline will be used. The pipeline must only be used with a render pass instance compatible with the one provided. See Render Pass Compatibility for more information. -
pMaxWorkgroupSize
is a pointer to a VkExtent2D structure.
The VkPipelineRobustnessCreateInfoEXT
structure is defined as:
// Provided by VK_EXT_pipeline_robustness
typedef struct VkPipelineRobustnessCreateInfoEXT {
VkStructureType sType;
const void* pNext;
VkPipelineRobustnessBufferBehaviorEXT storageBuffers;
VkPipelineRobustnessBufferBehaviorEXT uniformBuffers;
VkPipelineRobustnessBufferBehaviorEXT vertexInputs;
VkPipelineRobustnessImageBehaviorEXT images;
} VkPipelineRobustnessCreateInfoEXT;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
storageBuffers
sets the behavior of out of bounds accesses made to resources bound as:-
VK_DESCRIPTOR_TYPE_STORAGE_BUFFER
-
VK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFER
-
VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC
-
-
uniformBuffers
describes the behavior of out of bounds accesses made to resources bound as:-
VK_DESCRIPTOR_TYPE_UNIFORM_TEXEL_BUFFER
-
VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER
-
VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC
-
VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK
-
-
vertexInputs
describes the behavior of out of bounds accesses made to vertex input attributes -
images
describes the behavior of out of bounds accesses made to resources bound as:-
VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE
-
VK_DESCRIPTOR_TYPE_STORAGE_IMAGE
-
Resources bound as VK_DESCRIPTOR_TYPE_MUTABLE_EXT
will have the
robustness behavior that covers its active descriptor type.
The scope of the effect of VkPipelineRobustnessCreateInfoEXT
depends
on which structure’s pNext
chain it is included in.
-
VkGraphicsPipelineCreateInfo
,VkRayTracingPipelineCreateInfoKHR
,VkComputePipelineCreateInfo
:
The robustness behavior described byVkPipelineRobustnessCreateInfoEXT
applies to all accesses through this pipeline -
VkPipelineShaderStageCreateInfo
:
The robustness behavior described byVkPipelineRobustnessCreateInfoEXT
applies to all accesses emanating from the shader code of this shader stage
If VkPipelineRobustnessCreateInfoEXT
is specified for both a pipeline
and a pipeline stage, the VkPipelineRobustnessCreateInfoEXT
specified
for the pipeline stage will take precedence.
When VkPipelineRobustnessCreateInfoEXT
is specified for a pipeline, it
only affects the subset of the pipeline that is specified by the create
info, as opposed to subsets linked from pipeline libraries.
For VkGraphicsPipelineCreateInfo, that subset is specified by
VkGraphicsPipelineLibraryCreateInfoEXT::flags
.
For VkRayTracingPipelineCreateInfoKHR, that subset is specified by the
specific stages in VkRayTracingPipelineCreateInfoKHR::pStages
.
Possible values of the storageBuffers
, uniformBuffers
, and
vertexInputs
members of VkPipelineRobustnessCreateInfoEXT are:
// Provided by VK_EXT_pipeline_robustness
typedef enum VkPipelineRobustnessBufferBehaviorEXT {
VK_PIPELINE_ROBUSTNESS_BUFFER_BEHAVIOR_DEVICE_DEFAULT_EXT = 0,
VK_PIPELINE_ROBUSTNESS_BUFFER_BEHAVIOR_DISABLED_EXT = 1,
VK_PIPELINE_ROBUSTNESS_BUFFER_BEHAVIOR_ROBUST_BUFFER_ACCESS_EXT = 2,
VK_PIPELINE_ROBUSTNESS_BUFFER_BEHAVIOR_ROBUST_BUFFER_ACCESS_2_EXT = 3,
} VkPipelineRobustnessBufferBehaviorEXT;
-
VK_PIPELINE_ROBUSTNESS_BUFFER_BEHAVIOR_DEVICE_DEFAULT_EXT
specifies that this pipeline stage follows the behavior of robustness features that are enabled on the device that created this pipeline -
VK_PIPELINE_ROBUSTNESS_BUFFER_BEHAVIOR_DISABLED_EXT
specifies that buffer accesses by this pipeline stage to the relevant resource types must not be out of bounds -
VK_PIPELINE_ROBUSTNESS_BUFFER_BEHAVIOR_ROBUST_BUFFER_ACCESS_EXT
specifies that out of bounds accesses by this pipeline stage to the relevant resource types behave as if therobustBufferAccess
feature is enabled -
VK_PIPELINE_ROBUSTNESS_BUFFER_BEHAVIOR_ROBUST_BUFFER_ACCESS_2_EXT
specifies that out of bounds accesses by this pipeline stage to the relevant resource types behave as if therobustBufferAccess2
feature is enabled
Possible values of the images
member of
VkPipelineRobustnessCreateInfoEXT are:
// Provided by VK_EXT_pipeline_robustness
typedef enum VkPipelineRobustnessImageBehaviorEXT {
VK_PIPELINE_ROBUSTNESS_IMAGE_BEHAVIOR_DEVICE_DEFAULT_EXT = 0,
VK_PIPELINE_ROBUSTNESS_IMAGE_BEHAVIOR_DISABLED_EXT = 1,
VK_PIPELINE_ROBUSTNESS_IMAGE_BEHAVIOR_ROBUST_IMAGE_ACCESS_EXT = 2,
VK_PIPELINE_ROBUSTNESS_IMAGE_BEHAVIOR_ROBUST_IMAGE_ACCESS_2_EXT = 3,
} VkPipelineRobustnessImageBehaviorEXT;
-
VK_PIPELINE_ROBUSTNESS_IMAGE_BEHAVIOR_DEVICE_DEFAULT_EXT
specifies that this pipeline stage follows the behavior of robustness features that are enabled on the device that created this pipeline -
VK_PIPELINE_ROBUSTNESS_IMAGE_BEHAVIOR_DISABLED_EXT
specifies that image accesses by this pipeline stage to the relevant resource types must not be out of bounds -
VK_PIPELINE_ROBUSTNESS_IMAGE_BEHAVIOR_ROBUST_IMAGE_ACCESS_EXT
specifies that out of bounds accesses by this pipeline stage to images behave as if therobustImageAccess
feature is enabled -
VK_PIPELINE_ROBUSTNESS_IMAGE_BEHAVIOR_ROBUST_IMAGE_ACCESS_2_EXT
specifies that out of bounds accesses by this pipeline stage to images behave as if therobustImageAccess2
feature is enabled
An identifier can be provided instead of shader code in an attempt to compile pipelines without providing complete SPIR-V to the implementation.
The VkPipelineShaderStageModuleIdentifierCreateInfoEXT
structure is
defined as:
// Provided by VK_EXT_shader_module_identifier
typedef struct VkPipelineShaderStageModuleIdentifierCreateInfoEXT {
VkStructureType sType;
const void* pNext;
uint32_t identifierSize;
const uint8_t* pIdentifier;
} VkPipelineShaderStageModuleIdentifierCreateInfoEXT;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
identifierSize
is the size, in bytes, of the buffer pointed to bypIdentifier
. -
pIdentifier
is a pointer to a buffer of opaque data specifying an identifier.
Any identifier can be used.
If the pipeline being created with identifier requires compilation to
complete the pipeline creation call, pipeline compilation must fail as
defined by VK_PIPELINE_CREATE_FAIL_ON_PIPELINE_COMPILE_REQUIRED_BIT
.
pIdentifier
and identifierSize
can be obtained from an
VkShaderModuleIdentifierEXT queried earlier.
If a compute pipeline is going to be used in Device-Generated Commands by specifying its pipeline token with
VkBindPipelineIndirectCommandNV, then that pipeline’s associated
metadata must be saved at a specified buffer device address for later use
in indirect command generation.
The buffer device address must be specified at the time of compute pipeline
creation with VkComputePipelineIndirectBufferInfoNV structure in the
pNext
chain of VkComputePipelineCreateInfo.
The VkComputePipelineIndirectBufferInfoNV
structure is defined as:
// Provided by VK_NV_device_generated_commands_compute
typedef struct VkComputePipelineIndirectBufferInfoNV {
VkStructureType sType;
const void* pNext;
VkDeviceAddress deviceAddress;
VkDeviceSize size;
VkDeviceAddress pipelineDeviceAddressCaptureReplay;
} VkComputePipelineIndirectBufferInfoNV;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
deviceAddress
is the address where the pipeline’s metadata will be stored. -
size
is the size of pipeline’s metadata that was queried using vkGetPipelineIndirectMemoryRequirementsNV. -
pipelineDeviceAddressCaptureReplay
is the device address where pipeline’s metadata was originally saved and can now be used to re-populatedeviceAddress
for replay.
If pipelineDeviceAddressCaptureReplay
is zero, no specific address is
requested.
If pipelineDeviceAddressCaptureReplay
is not zero, then it must be an
address retrieved from an identically created pipeline on the same
implementation.
The pipeline metadata must also be placed on an identically created buffer
and at the same offset using the vkCmdUpdatePipelineIndirectBufferNV
command.
To save a compute pipeline’s metadata at a device address call:
// Provided by VK_NV_device_generated_commands_compute
void vkCmdUpdatePipelineIndirectBufferNV(
VkCommandBuffer commandBuffer,
VkPipelineBindPoint pipelineBindPoint,
VkPipeline pipeline);
-
commandBuffer
is the command buffer into which the command will be recorded. -
pipelineBindPoint
is a VkPipelineBindPoint value specifying the type of pipeline whose metadata will be saved. -
pipeline
is the pipeline whose metadata will be saved.
vkCmdUpdatePipelineIndirectBufferNV
is only allowed outside of a
render pass.
This command is treated as a “transfer” operation for the purposes of
synchronization barriers.
The writes to the address must be synchronized using stages
VK_PIPELINE_STAGE_2_COPY_BIT
and
VK_PIPELINE_STAGE_COMMAND_PREPROCESS_BIT_NV
and with access masks
VK_ACCESS_MEMORY_WRITE_BIT
and
VK_ACCESS_COMMAND_PREPROCESS_READ_BIT_NV
respectively before using the
results in preprocessing.
Graphics Pipelines
Graphics pipelines consist of multiple shader stages, multiple fixed-function pipeline stages, and a pipeline layout.
To create graphics pipelines, call:
// Provided by VK_VERSION_1_0
VkResult vkCreateGraphicsPipelines(
VkDevice device,
VkPipelineCache pipelineCache,
uint32_t createInfoCount,
const VkGraphicsPipelineCreateInfo* pCreateInfos,
const VkAllocationCallbacks* pAllocator,
VkPipeline* pPipelines);
-
device
is the logical device that creates the graphics pipelines. -
pipelineCache
is either VK_NULL_HANDLE, indicating that pipeline caching is disabled; or the handle of a valid pipeline cache object, in which case use of that cache is enabled for the duration of the command. -
createInfoCount
is the length of thepCreateInfos
andpPipelines
arrays. -
pCreateInfos
is a pointer to an array of VkGraphicsPipelineCreateInfo structures. -
pAllocator
controls host memory allocation as described in the Memory Allocation chapter. -
pPipelines
is a pointer to an array of VkPipeline handles in which the resulting graphics pipeline objects are returned.
The VkGraphicsPipelineCreateInfo structure includes an array of 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.
Pipelines are created and returned as described for Multiple Pipeline Creation.
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;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
flags
is a bitmask of VkPipelineCreateFlagBits specifying how the pipeline will be generated. -
stageCount
is the number of entries in thepStages
array. -
pStages
is a pointer to an array ofstageCount
VkPipelineShaderStageCreateInfo structures describing the set of the shader stages to be included in the graphics pipeline. -
pVertexInputState
is a pointer to a VkPipelineVertexInputStateCreateInfo structure. It is ignored if the pipeline includes a mesh shader stage. It can beNULL
if the pipeline is created with theVK_DYNAMIC_STATE_VERTEX_INPUT_EXT
dynamic state set. -
pInputAssemblyState
is a pointer to a VkPipelineInputAssemblyStateCreateInfo structure which determines input assembly behavior for vertex shading, as described in Drawing Commands. If theVK_EXT_extended_dynamic_state3
extension is enabled, it can beNULL
if the pipeline is created with bothVK_DYNAMIC_STATE_PRIMITIVE_RESTART_ENABLE
, andVK_DYNAMIC_STATE_PRIMITIVE_TOPOLOGY
dynamic states set anddynamicPrimitiveTopologyUnrestricted
isVK_TRUE
. It is ignored if the pipeline includes a mesh shader stage. -
pTessellationState
is a pointer to a VkPipelineTessellationStateCreateInfo structure defining tessellation state used by tessellation shaders. It can beNULL
if the pipeline is created with theVK_DYNAMIC_STATE_PATCH_CONTROL_POINTS_EXT
dynamic state set. -
pViewportState
is a pointer to a VkPipelineViewportStateCreateInfo structure defining viewport state used when rasterization is enabled. If theVK_EXT_extended_dynamic_state3
extension is enabled, it can beNULL
if the pipeline is created with bothVK_DYNAMIC_STATE_VIEWPORT_WITH_COUNT
, andVK_DYNAMIC_STATE_SCISSOR_WITH_COUNT
dynamic states set. -
pRasterizationState
is a pointer to a VkPipelineRasterizationStateCreateInfo structure defining rasterization state. If theVK_EXT_extended_dynamic_state3
extension is enabled, it can beNULL
if the pipeline is created with all ofVK_DYNAMIC_STATE_DEPTH_CLAMP_ENABLE_EXT
,VK_DYNAMIC_STATE_RASTERIZER_DISCARD_ENABLE
,VK_DYNAMIC_STATE_POLYGON_MODE_EXT
,VK_DYNAMIC_STATE_CULL_MODE
,VK_DYNAMIC_STATE_FRONT_FACE
,VK_DYNAMIC_STATE_DEPTH_BIAS_ENABLE
,VK_DYNAMIC_STATE_DEPTH_BIAS
, andVK_DYNAMIC_STATE_LINE_WIDTH
dynamic states set. -
pMultisampleState
is a pointer to a VkPipelineMultisampleStateCreateInfo structure defining multisample state used when rasterization is enabled. If theVK_EXT_extended_dynamic_state3
extension is enabled, it can beNULL
if the pipeline is created with all ofVK_DYNAMIC_STATE_RASTERIZATION_SAMPLES_EXT
,VK_DYNAMIC_STATE_SAMPLE_MASK_EXT
, andVK_DYNAMIC_STATE_ALPHA_TO_COVERAGE_ENABLE_EXT
dynamic states set, and either alphaToOne is disabled on the device orVK_DYNAMIC_STATE_ALPHA_TO_ONE_ENABLE_EXT
is set, in which case VkPipelineMultisampleStateCreateInfo::sampleShadingEnable
is assumed to beVK_FALSE
. -
pDepthStencilState
is a pointer to a VkPipelineDepthStencilStateCreateInfo structure defining depth/stencil state used when rasterization is enabled for depth or stencil attachments accessed during rendering. If theVK_EXT_extended_dynamic_state3
extension is enabled, it can beNULL
if the pipeline is created with all ofVK_DYNAMIC_STATE_DEPTH_TEST_ENABLE
,VK_DYNAMIC_STATE_DEPTH_WRITE_ENABLE
,VK_DYNAMIC_STATE_DEPTH_COMPARE_OP
,VK_DYNAMIC_STATE_DEPTH_BOUNDS_TEST_ENABLE
,VK_DYNAMIC_STATE_STENCIL_TEST_ENABLE
,VK_DYNAMIC_STATE_STENCIL_OP
, andVK_DYNAMIC_STATE_DEPTH_BOUNDS
dynamic states set. -
pColorBlendState
is a pointer to a VkPipelineColorBlendStateCreateInfo structure defining color blend state used when rasterization is enabled for any color attachments accessed during rendering. If theVK_EXT_extended_dynamic_state3
extension is enabled, it can beNULL
if the pipeline is created with all ofVK_DYNAMIC_STATE_LOGIC_OP_ENABLE_EXT
,VK_DYNAMIC_STATE_LOGIC_OP_EXT
,VK_DYNAMIC_STATE_COLOR_BLEND_ENABLE_EXT
,VK_DYNAMIC_STATE_COLOR_BLEND_EQUATION_EXT
,VK_DYNAMIC_STATE_COLOR_WRITE_MASK_EXT
, andVK_DYNAMIC_STATE_BLEND_CONSTANTS
dynamic states set. -
pDynamicState
is 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. -
layout
is the description of binding locations used by both the pipeline and descriptor sets used with the pipeline. -
renderPass
is a handle to a render pass object describing the environment in which the pipeline will be used. The pipeline must only be used with a render pass instance compatible with the one provided. See Render Pass Compatibility for more information. -
subpass
is the index of the subpass in the render pass where this pipeline will be used. -
basePipelineHandle
is a pipeline to derive from. -
basePipelineIndex
is an index into thepCreateInfos
parameter to use as a pipeline to derive from.
The parameters basePipelineHandle
and basePipelineIndex
are
described in more detail in Pipeline Derivatives.
If any shader stage fails to compile,
the compile log will be reported back to the application, and
VK_ERROR_INVALID_SHADER_NV
will be generated.
With |
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:
If
this pipeline specifies
pre-rasterization state
either directly or by including it as a pipeline library and its
pStages
includes a vertex shader, this state must be specified to
create a complete graphics pipeline.
If a pipeline includes
VK_GRAPHICS_PIPELINE_LIBRARY_VERTEX_INPUT_INTERFACE_BIT_EXT
in
VkGraphicsPipelineLibraryCreateInfoEXT::flags
either explicitly
or as a default, and either the conditions requiring this state for a
complete graphics pipeline are met
or this pipeline does not specify
pre-rasterization state in
any way, that pipeline must specify this state directly.
Pre-rasterization shader state is defined by:
-
VkPipelineShaderStageCreateInfo entries for:
-
Vertex shaders
-
Tessellation control shaders
-
Tessellation evaluation shaders
-
Geometry shaders
-
Task shaders
-
Mesh shaders
-
-
Within the VkPipelineLayout, all descriptor sets with pre-rasterization shader bindings if
VK_PIPELINE_LAYOUT_CREATE_INDEPENDENT_SETS_BIT_EXT
was specified.-
If
VK_PIPELINE_LAYOUT_CREATE_INDEPENDENT_SETS_BIT_EXT
was not specified, the full pipeline layout must be specified.
-
-
VkRenderPass and
subpass
parameter -
The
viewMask
parameter of VkPipelineRenderingCreateInfo (formats are ignored)
This state must be specified to create a complete graphics pipeline.
If either the pNext
chain includes a
VkGraphicsPipelineLibraryCreateInfoEXT structure with
VK_GRAPHICS_PIPELINE_LIBRARY_PRE_RASTERIZATION_SHADERS_BIT_EXT
included in flags
, or it is not specified and would default to include
that value, this state must be specified in the pipeline.
Fragment shader state is defined by:
-
A VkPipelineShaderStageCreateInfo entry for the fragment shader
-
Within the VkPipelineLayout, all descriptor sets with fragment shader bindings if
VK_PIPELINE_LAYOUT_CREATE_INDEPENDENT_SETS_BIT_EXT
was specified.-
If
VK_PIPELINE_LAYOUT_CREATE_INDEPENDENT_SETS_BIT_EXT
was not specified, the full pipeline layout must be specified.
-
-
VkPipelineMultisampleStateCreateInfo if sample shading is enabled or
renderpass
is not VK_NULL_HANDLE -
VkRenderPass and
subpass
parameter -
The
viewMask
parameter of VkPipelineRenderingCreateInfo (formats are ignored) -
Inclusion/omission of the
VK_PIPELINE_RASTERIZATION_STATE_CREATE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR
flag -
Inclusion/omission of the
VK_PIPELINE_RASTERIZATION_STATE_CREATE_FRAGMENT_DENSITY_MAP_ATTACHMENT_BIT_EXT
flag
If
a pipeline specifies
pre-rasterization state
either directly or by including it as a pipeline library and
rasterizerDiscardEnable
is VK_FALSE
or VK_DYNAMIC_STATE_RASTERIZER_DISCARD_ENABLE
is used,
this state must be specified to create a
complete graphics pipeline.
If a pipeline includes
VK_GRAPHICS_PIPELINE_LIBRARY_FRAGMENT_SHADER_BIT_EXT
in
VkGraphicsPipelineLibraryCreateInfoEXT::flags
either explicitly
or as a default, and either the conditions requiring this state for a
complete graphics pipeline are met
or this pipeline does not specify
pre-rasterization state in
any way, that pipeline must specify this state directly.
Fragment output state is defined by:
-
VkRenderPass and
subpass
parameter -
Inclusion/omission of the
VK_PIPELINE_CREATE_COLOR_ATTACHMENT_FEEDBACK_LOOP_BIT_EXT
andVK_PIPELINE_CREATE_DEPTH_STENCIL_ATTACHMENT_FEEDBACK_LOOP_BIT_EXT
flags -
Inclusion/omission of the
VK_PIPELINE_CREATE_2_ENABLE_LEGACY_DITHERING_BIT_EXT
flag
If
a pipeline specifies
pre-rasterization state
either directly or by including it as a pipeline library and
rasterizerDiscardEnable
is VK_FALSE
or VK_DYNAMIC_STATE_RASTERIZER_DISCARD_ENABLE
is used,
this state must be specified to create a
complete graphics pipeline.
If a pipeline includes
VK_GRAPHICS_PIPELINE_LIBRARY_FRAGMENT_OUTPUT_INTERFACE_BIT_EXT
in
VkGraphicsPipelineLibraryCreateInfoEXT::flags
either explicitly
or as a default, and either the conditions requiring this state for a
complete graphics pipeline are met
or this pipeline does not specify
pre-rasterization state in
any way, that pipeline must specify this state directly.
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.
Additionally, setting dynamic state values must not modify whether state in
a linked library is static or dynamic; this is set and unchangeable when the
library is created.
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.
Any linked library that has dynamic state enabled that same dynamic state
must also be enabled in all the other linked libraries to which that
dynamic state applies.
A complete graphics pipeline always includes pre-rasterization shader state, with other subsets included depending on that state as specified in the above sections.
If different subsets are linked together with pipeline layouts created with
VK_PIPELINE_LAYOUT_CREATE_INDEPENDENT_SETS_BIT_EXT
, the final
effective pipeline layout is effectively the union of the linked pipeline
layouts.
When binding descriptor sets for this pipeline, the pipeline layout used
must be compatible with this union.
This pipeline layout can be overridden when linking with
VK_PIPELINE_CREATE_LINK_TIME_OPTIMIZATION_BIT_EXT
by providing a
VkPipelineLayout that is compatible
with this union other than
VK_PIPELINE_LAYOUT_CREATE_INDEPENDENT_SETS_BIT_EXT
, or when linking
without VK_PIPELINE_CREATE_LINK_TIME_OPTIMIZATION_BIT_EXT
by providing
a VkPipelineLayout that is fully
compatible with this union.
If the pNext
chain includes a
VkPipelineCreateFlags2CreateInfoKHR structure,
VkPipelineCreateFlags2CreateInfoKHR::flags
from that structure
is used instead of flags
from this structure.
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;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
viewMask
is the viewMask used for rendering. -
colorAttachmentCount
is the number of entries inpColorAttachmentFormats
-
pColorAttachmentFormats
is a pointer to an array of VkFormat values defining the format of color attachments used in this pipeline. -
depthAttachmentFormat
is a VkFormat value defining the format of the depth attachment used in this pipeline. -
stencilAttachmentFormat
is a VkFormat value defining the format of the stencil attachment used in this pipeline.
When a pipeline is created without a VkRenderPass, if the pNext
chain of VkGraphicsPipelineCreateInfo includes this structure, 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.
If the render pass is going to be used with an external format resolve
attachment, a VkExternalFormatANDROID structure must also be included
in the pNext
chain of VkGraphicsPipelineCreateInfo, defining the
external format of the resolve attachment that will be used.
The VkPipelineCreateFlags2CreateInfoKHR
structure is defined as:
// Provided by VK_KHR_maintenance5
typedef struct VkPipelineCreateFlags2CreateInfoKHR {
VkStructureType sType;
const void* pNext;
VkPipelineCreateFlags2KHR flags;
} VkPipelineCreateFlags2CreateInfoKHR;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
flags
is a bitmask of VkPipelineCreateFlagBits2KHR specifying how a pipeline will be generated.
If this structure is included in the pNext
chain of a pipeline
creation structure, flags
is used instead of the corresponding
flags
value passed in that creation structure, allowing additional
creation flags to be specified.
Bits which can be set in
VkPipelineCreateFlags2CreateInfoKHR::flags
, specifying how a
pipeline is created, are:
// Provided by VK_KHR_maintenance5
// Flag bits for VkPipelineCreateFlagBits2KHR
typedef VkFlags64 VkPipelineCreateFlagBits2KHR;
static const VkPipelineCreateFlagBits2KHR VK_PIPELINE_CREATE_2_DISABLE_OPTIMIZATION_BIT_KHR = 0x00000001ULL;
static const VkPipelineCreateFlagBits2KHR VK_PIPELINE_CREATE_2_ALLOW_DERIVATIVES_BIT_KHR = 0x00000002ULL;
static const VkPipelineCreateFlagBits2KHR VK_PIPELINE_CREATE_2_DERIVATIVE_BIT_KHR = 0x00000004ULL;
#ifdef VK_ENABLE_BETA_EXTENSIONS
// Provided by VK_KHR_maintenance5 with VK_AMDX_shader_enqueue
static const VkPipelineCreateFlagBits2KHR VK_PIPELINE_CREATE_2_EXECUTION_GRAPH_BIT_AMDX = 0x100000000ULL;
#endif
// Provided by VK_EXT_legacy_dithering with (VK_KHR_dynamic_rendering or VK_VERSION_1_3) and VK_KHR_maintenance5
static const VkPipelineCreateFlagBits2KHR VK_PIPELINE_CREATE_2_ENABLE_LEGACY_DITHERING_BIT_EXT = 0x400000000ULL;
// Provided by VK_KHR_maintenance5 with VK_VERSION_1_1 or VK_KHR_device_group
static const VkPipelineCreateFlagBits2KHR VK_PIPELINE_CREATE_2_VIEW_INDEX_FROM_DEVICE_INDEX_BIT_KHR = 0x00000008ULL;
// Provided by VK_KHR_maintenance5 with VK_VERSION_1_1 or VK_KHR_device_group
static const VkPipelineCreateFlagBits2KHR VK_PIPELINE_CREATE_2_DISPATCH_BASE_BIT_KHR = 0x00000010ULL;
// Provided by VK_KHR_maintenance5 with VK_NV_ray_tracing
static const VkPipelineCreateFlagBits2KHR VK_PIPELINE_CREATE_2_DEFER_COMPILE_BIT_NV = 0x00000020ULL;
// Provided by VK_KHR_maintenance5 with VK_KHR_pipeline_executable_properties
static const VkPipelineCreateFlagBits2KHR VK_PIPELINE_CREATE_2_CAPTURE_STATISTICS_BIT_KHR = 0x00000040ULL;
// Provided by VK_KHR_maintenance5 with VK_KHR_pipeline_executable_properties
static const VkPipelineCreateFlagBits2KHR VK_PIPELINE_CREATE_2_CAPTURE_INTERNAL_REPRESENTATIONS_BIT_KHR = 0x00000080ULL;
// Provided by VK_KHR_maintenance5 with VK_VERSION_1_3 or VK_EXT_pipeline_creation_cache_control
static const VkPipelineCreateFlagBits2KHR VK_PIPELINE_CREATE_2_FAIL_ON_PIPELINE_COMPILE_REQUIRED_BIT_KHR = 0x00000100ULL;
// Provided by VK_KHR_maintenance5 with VK_VERSION_1_3 or VK_EXT_pipeline_creation_cache_control
static const VkPipelineCreateFlagBits2KHR VK_PIPELINE_CREATE_2_EARLY_RETURN_ON_FAILURE_BIT_KHR = 0x00000200ULL;
// Provided by VK_KHR_maintenance5 with VK_EXT_graphics_pipeline_library
static const VkPipelineCreateFlagBits2KHR VK_PIPELINE_CREATE_2_LINK_TIME_OPTIMIZATION_BIT_EXT = 0x00000400ULL;
// Provided by VK_KHR_maintenance5 with VK_EXT_graphics_pipeline_library
static const VkPipelineCreateFlagBits2KHR VK_PIPELINE_CREATE_2_RETAIN_LINK_TIME_OPTIMIZATION_INFO_BIT_EXT = 0x00800000ULL;
// Provided by VK_KHR_maintenance5 with VK_KHR_pipeline_library
static const VkPipelineCreateFlagBits2KHR VK_PIPELINE_CREATE_2_LIBRARY_BIT_KHR = 0x00000800ULL;
// Provided by VK_KHR_maintenance5 with VK_KHR_ray_tracing_pipeline
static const VkPipelineCreateFlagBits2KHR VK_PIPELINE_CREATE_2_RAY_TRACING_SKIP_TRIANGLES_BIT_KHR = 0x00001000ULL;
// Provided by VK_KHR_maintenance5 with VK_KHR_ray_tracing_pipeline
static const VkPipelineCreateFlagBits2KHR VK_PIPELINE_CREATE_2_RAY_TRACING_SKIP_AABBS_BIT_KHR = 0x00002000ULL;
// Provided by VK_KHR_maintenance5 with VK_KHR_ray_tracing_pipeline
static const VkPipelineCreateFlagBits2KHR VK_PIPELINE_CREATE_2_RAY_TRACING_NO_NULL_ANY_HIT_SHADERS_BIT_KHR = 0x00004000ULL;
// Provided by VK_KHR_maintenance5 with VK_KHR_ray_tracing_pipeline
static const VkPipelineCreateFlagBits2KHR VK_PIPELINE_CREATE_2_RAY_TRACING_NO_NULL_CLOSEST_HIT_SHADERS_BIT_KHR = 0x00008000ULL;
// Provided by VK_KHR_maintenance5 with VK_KHR_ray_tracing_pipeline
static const VkPipelineCreateFlagBits2KHR VK_PIPELINE_CREATE_2_RAY_TRACING_NO_NULL_MISS_SHADERS_BIT_KHR = 0x00010000ULL;
// Provided by VK_KHR_maintenance5 with VK_KHR_ray_tracing_pipeline
static const VkPipelineCreateFlagBits2KHR VK_PIPELINE_CREATE_2_RAY_TRACING_NO_NULL_INTERSECTION_SHADERS_BIT_KHR = 0x00020000ULL;
// Provided by VK_KHR_maintenance5 with VK_KHR_ray_tracing_pipeline
static const VkPipelineCreateFlagBits2KHR VK_PIPELINE_CREATE_2_RAY_TRACING_SHADER_GROUP_HANDLE_CAPTURE_REPLAY_BIT_KHR = 0x00080000ULL;
// Provided by VK_KHR_maintenance5 with VK_NV_device_generated_commands
static const VkPipelineCreateFlagBits2KHR VK_PIPELINE_CREATE_2_INDIRECT_BINDABLE_BIT_NV = 0x00040000ULL;
// Provided by VK_KHR_maintenance5 with VK_NV_ray_tracing_motion_blur
static const VkPipelineCreateFlagBits2KHR VK_PIPELINE_CREATE_2_RAY_TRACING_ALLOW_MOTION_BIT_NV = 0x00100000ULL;
// Provided by VK_KHR_maintenance5 with (VK_KHR_dynamic_rendering or VK_VERSION_1_3) and VK_KHR_fragment_shading_rate
static const VkPipelineCreateFlagBits2KHR VK_PIPELINE_CREATE_2_RENDERING_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR = 0x00200000ULL;
// Provided by VK_KHR_maintenance5 with (VK_KHR_dynamic_rendering or VK_VERSION_1_3) and VK_EXT_fragment_density_map
static const VkPipelineCreateFlagBits2KHR VK_PIPELINE_CREATE_2_RENDERING_FRAGMENT_DENSITY_MAP_ATTACHMENT_BIT_EXT = 0x00400000ULL;
// Provided by VK_KHR_maintenance5 with VK_EXT_opacity_micromap
static const VkPipelineCreateFlagBits2KHR VK_PIPELINE_CREATE_2_RAY_TRACING_OPACITY_MICROMAP_BIT_EXT = 0x01000000ULL;
// Provided by VK_KHR_maintenance5 with VK_EXT_attachment_feedback_loop_layout
static const VkPipelineCreateFlagBits2KHR VK_PIPELINE_CREATE_2_COLOR_ATTACHMENT_FEEDBACK_LOOP_BIT_EXT = 0x02000000ULL;
// Provided by VK_KHR_maintenance5 with VK_EXT_attachment_feedback_loop_layout
static const VkPipelineCreateFlagBits2KHR VK_PIPELINE_CREATE_2_DEPTH_STENCIL_ATTACHMENT_FEEDBACK_LOOP_BIT_EXT = 0x04000000ULL;
// Provided by VK_KHR_maintenance5 with VK_EXT_pipeline_protected_access
static const VkPipelineCreateFlagBits2KHR VK_PIPELINE_CREATE_2_NO_PROTECTED_ACCESS_BIT_EXT = 0x08000000ULL;
// Provided by VK_KHR_maintenance5 with VK_EXT_pipeline_protected_access
static const VkPipelineCreateFlagBits2KHR VK_PIPELINE_CREATE_2_PROTECTED_ACCESS_ONLY_BIT_EXT = 0x40000000ULL;
// Provided by VK_KHR_maintenance5 with VK_NV_displacement_micromap
static const VkPipelineCreateFlagBits2KHR VK_PIPELINE_CREATE_2_RAY_TRACING_DISPLACEMENT_MICROMAP_BIT_NV = 0x10000000ULL;
// Provided by VK_KHR_maintenance5 with VK_EXT_descriptor_buffer
static const VkPipelineCreateFlagBits2KHR VK_PIPELINE_CREATE_2_DESCRIPTOR_BUFFER_BIT_EXT = 0x20000000ULL;
// Provided by VK_KHR_pipeline_binary
static const VkPipelineCreateFlagBits2KHR VK_PIPELINE_CREATE_2_CAPTURE_DATA_BIT_KHR = 0x80000000ULL;
// Provided by VK_EXT_device_generated_commands
static const VkPipelineCreateFlagBits2KHR VK_PIPELINE_CREATE_2_INDIRECT_BINDABLE_BIT_EXT = 0x4000000000ULL;
-
VK_PIPELINE_CREATE_2_DISABLE_OPTIMIZATION_BIT_KHR
specifies that the created pipeline will not be optimized. Using this flag may reduce the time taken to create the pipeline. -
VK_PIPELINE_CREATE_2_ALLOW_DERIVATIVES_BIT_KHR
specifies that the pipeline to be created is allowed to be the parent of a pipeline that will be created in a subsequent pipeline creation call. -
VK_PIPELINE_CREATE_2_DERIVATIVE_BIT_KHR
specifies that the pipeline to be created will be a child of a previously created parent pipeline. -
VK_PIPELINE_CREATE_2_VIEW_INDEX_FROM_DEVICE_INDEX_BIT_KHR
specifies that any shader input variables decorated asViewIndex
will be assigned values as if they were decorated asDeviceIndex
. -
VK_PIPELINE_CREATE_2_DISPATCH_BASE_BIT_KHR
specifies that a compute pipeline can be used with vkCmdDispatchBase with a non-zero base workgroup. -
VK_PIPELINE_CREATE_2_DEFER_COMPILE_BIT_NV
specifies that a pipeline is created with all shaders in the deferred state. Before using the pipeline the application must call vkCompileDeferredNV exactly once on each shader in the pipeline before using the pipeline. -
VK_PIPELINE_CREATE_2_CAPTURE_STATISTICS_BIT_KHR
specifies that the shader compiler should capture statistics for the pipeline executables produced by the compile process which can later be retrieved by calling vkGetPipelineExecutableStatisticsKHR. Enabling this flag must not affect the final compiled pipeline but may disable pipeline caching or otherwise affect pipeline creation time. -
VK_PIPELINE_CREATE_2_CAPTURE_INTERNAL_REPRESENTATIONS_BIT_KHR
specifies that the shader compiler should capture the internal representations of pipeline executables produced by the compile process which can later be retrieved by calling vkGetPipelineExecutableInternalRepresentationsKHR. Enabling this flag must not affect the final compiled pipeline but may disable pipeline caching or otherwise affect pipeline creation time. 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_2_LIBRARY_BIT_KHR
specifies that the pipeline cannot be used directly, and instead defines a pipeline library that can be combined with other pipelines using the VkPipelineLibraryCreateInfoKHR structure. This is available in ray tracing and graphics pipelines. -
VK_PIPELINE_CREATE_2_RAY_TRACING_NO_NULL_ANY_HIT_SHADERS_BIT_KHR
specifies that an any-hit shader will always be present when an any-hit shader would be executed. 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_2_RAY_TRACING_NO_NULL_CLOSEST_HIT_SHADERS_BIT_KHR
specifies that a closest hit shader will always be present when a closest hit shader would be executed. 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_2_RAY_TRACING_NO_NULL_MISS_SHADERS_BIT_KHR
specifies 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_2_RAY_TRACING_NO_NULL_INTERSECTION_SHADERS_BIT_KHR
specifies 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_2_RAY_TRACING_SKIP_TRIANGLES_BIT_KHR
specifies that triangle primitives will be skipped during traversal using pipeline trace ray instructions. -
VK_PIPELINE_CREATE_2_RAY_TRACING_SKIP_AABBS_BIT_KHR
specifies that AABB primitives will be skipped during traversal using pipeline trace ray instructions. -
VK_PIPELINE_CREATE_2_RAY_TRACING_SHADER_GROUP_HANDLE_CAPTURE_REPLAY_BIT_KHR
specifies that the shader group handles can be saved and reused on a subsequent run (e.g. for trace capture and replay). -
VK_PIPELINE_CREATE_2_INDIRECT_BINDABLE_BIT_NV
specifies that the pipeline can be used in combination with Device-Generated Commands. -
VK_PIPELINE_CREATE_2_INDIRECT_BINDABLE_BIT_EXT
specifies that the pipeline can be used in aVkIndirectExecutionSetEXT
. -
VK_PIPELINE_CREATE_2_FAIL_ON_PIPELINE_COMPILE_REQUIRED_BIT_KHR
specifies that pipeline creation will fail if a compile is required for creation of a valid VkPipeline object;VK_PIPELINE_COMPILE_REQUIRED
will be returned by pipeline creation, and the VkPipeline will be VK_NULL_HANDLE. -
When creating multiple pipelines,
VK_PIPELINE_CREATE_2_EARLY_RETURN_ON_FAILURE_BIT_KHR
specifies that control will be returned to the application if any individual pipeline returns a result which is notVK_SUCCESS
rather than continuing to create additional pipelines. -
VK_PIPELINE_CREATE_2_RAY_TRACING_ALLOW_MOTION_BIT_NV
specifies that the pipeline is allowed to useOpTraceRayMotionNV
. -
VK_PIPELINE_CREATE_2_RENDERING_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR
specifies that the pipeline will be used with a fragment shading rate attachment. -
VK_PIPELINE_CREATE_2_RENDERING_FRAGMENT_DENSITY_MAP_ATTACHMENT_BIT_EXT
specifies that the pipeline will be used with a fragment density map attachment. -
VK_PIPELINE_CREATE_2_LINK_TIME_OPTIMIZATION_BIT_EXT
specifies that pipeline libraries being linked into this library should have link time optimizations applied. If this bit is omitted, implementations should instead perform linking as rapidly as possible. -
VK_PIPELINE_CREATE_2_RETAIN_LINK_TIME_OPTIMIZATION_INFO_BIT_EXT
specifies that pipeline libraries should retain any information necessary to later perform an optimal link withVK_PIPELINE_CREATE_2_LINK_TIME_OPTIMIZATION_BIT_EXT
. -
VK_PIPELINE_CREATE_2_DESCRIPTOR_BUFFER_BIT_EXT
specifies that a pipeline will be used with descriptor buffers, rather than descriptor sets. -
VK_PIPELINE_CREATE_2_COLOR_ATTACHMENT_FEEDBACK_LOOP_BIT_EXT
specifies that the pipeline may be used with an attachment feedback loop including color attachments. -
VK_PIPELINE_CREATE_2_DEPTH_STENCIL_ATTACHMENT_FEEDBACK_LOOP_BIT_EXT
specifies that the pipeline may be used with an attachment feedback loop including depth-stencil attachments. -
VK_PIPELINE_CREATE_2_RAY_TRACING_OPACITY_MICROMAP_BIT_EXT
specifies that the ray tracing pipeline can be used with acceleration structures which reference an opacity micromap array. -
VK_PIPELINE_CREATE_2_RAY_TRACING_DISPLACEMENT_MICROMAP_BIT_NV
specifies that the ray tracing pipeline can be used with acceleration structures which reference a displacement micromap array. -
VK_PIPELINE_CREATE_2_NO_PROTECTED_ACCESS_BIT_EXT
specifies that the pipeline must not be bound to a protected command buffer. -
VK_PIPELINE_CREATE_2_PROTECTED_ACCESS_ONLY_BIT_EXT
specifies that the pipeline must not be bound to an unprotected command buffer. -
VK_PIPELINE_CREATE_2_CAPTURE_DATA_BIT_KHR
specifies thatVkPipelineBinaryKHR
objects can be created from the pipeline. IfVK_PIPELINE_CREATE_2_CAPTURE_DATA_BIT_KHR
is used, implementations should not store pipeline data to an internal cache, if such a cache exists as stated bypipelineBinaryInternalCache
. IfpipelineBinaryPrefersInternalCache
isVK_TRUE
, applications should not useVK_PIPELINE_CREATE_2_CAPTURE_DATA_BIT_KHR
. -
VK_PIPELINE_CREATE_2_ENABLE_LEGACY_DITHERING_BIT_EXT
specifies that the pipeline will be used in a render pass that is begun withVK_RENDERING_ENABLE_LEGACY_DITHERING_BIT_EXT
. -
VK_PIPELINE_CREATE_2_EXECUTION_GRAPH_BIT_AMDX
specifies that the pipeline will be used in an execution graph
It is valid to set both VK_PIPELINE_CREATE_2_ALLOW_DERIVATIVES_BIT_KHR
and VK_PIPELINE_CREATE_2_DERIVATIVE_BIT_KHR
.
This allows a pipeline to be both a parent and possibly a child in a
pipeline hierarchy.
See Pipeline Derivatives for more
information.
When an implementation is looking up a pipeline in a
pipeline cache, if that pipeline is being created using
linked libraries, implementations should always return an equivalent
pipeline created with
VK_PIPELINE_CREATE_2_LINK_TIME_OPTIMIZATION_BIT_EXT
if available,
whether or not that bit was specified.
Using |
// Provided by VK_KHR_maintenance5
typedef VkFlags64 VkPipelineCreateFlags2KHR;
VkPipelineCreateFlags2KHR
is a bitmask type for setting a mask of zero
or more VkPipelineCreateFlagBits2KHR.
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_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_NV_ray_tracing
VK_PIPELINE_CREATE_DEFER_COMPILE_BIT_NV = 0x00000020,
// Provided by VK_EXT_fragment_density_map with VK_VERSION_1_3 or VK_KHR_dynamic_rendering
VK_PIPELINE_CREATE_RENDERING_FRAGMENT_DENSITY_MAP_ATTACHMENT_BIT_EXT = 0x00400000,
// Provided by VK_KHR_fragment_shading_rate with VK_VERSION_1_3 or VK_KHR_dynamic_rendering
VK_PIPELINE_CREATE_RENDERING_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR = 0x00200000,
// 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_NV_device_generated_commands
VK_PIPELINE_CREATE_INDIRECT_BINDABLE_BIT_NV = 0x00040000,
// Provided by VK_KHR_pipeline_library
VK_PIPELINE_CREATE_LIBRARY_BIT_KHR = 0x00000800,
// Provided by VK_EXT_descriptor_buffer
VK_PIPELINE_CREATE_DESCRIPTOR_BUFFER_BIT_EXT = 0x20000000,
// Provided by VK_EXT_graphics_pipeline_library
VK_PIPELINE_CREATE_RETAIN_LINK_TIME_OPTIMIZATION_INFO_BIT_EXT = 0x00800000,
// Provided by VK_EXT_graphics_pipeline_library
VK_PIPELINE_CREATE_LINK_TIME_OPTIMIZATION_BIT_EXT = 0x00000400,
// Provided by VK_NV_ray_tracing_motion_blur
VK_PIPELINE_CREATE_RAY_TRACING_ALLOW_MOTION_BIT_NV = 0x00100000,
// Provided by VK_EXT_attachment_feedback_loop_layout
VK_PIPELINE_CREATE_COLOR_ATTACHMENT_FEEDBACK_LOOP_BIT_EXT = 0x02000000,
// Provided by VK_EXT_attachment_feedback_loop_layout
VK_PIPELINE_CREATE_DEPTH_STENCIL_ATTACHMENT_FEEDBACK_LOOP_BIT_EXT = 0x04000000,
// Provided by VK_EXT_opacity_micromap
VK_PIPELINE_CREATE_RAY_TRACING_OPACITY_MICROMAP_BIT_EXT = 0x01000000,
#ifdef VK_ENABLE_BETA_EXTENSIONS
// Provided by VK_NV_displacement_micromap
VK_PIPELINE_CREATE_RAY_TRACING_DISPLACEMENT_MICROMAP_BIT_NV = 0x10000000,
#endif
// Provided by VK_EXT_pipeline_protected_access
VK_PIPELINE_CREATE_NO_PROTECTED_ACCESS_BIT_EXT = 0x08000000,
// Provided by VK_EXT_pipeline_protected_access
VK_PIPELINE_CREATE_PROTECTED_ACCESS_ONLY_BIT_EXT = 0x40000000,
// Provided by VK_VERSION_1_1
VK_PIPELINE_CREATE_DISPATCH_BASE = VK_PIPELINE_CREATE_DISPATCH_BASE_BIT,
// Provided by VK_KHR_device_group
VK_PIPELINE_CREATE_VIEW_INDEX_FROM_DEVICE_INDEX_BIT_KHR = VK_PIPELINE_CREATE_VIEW_INDEX_FROM_DEVICE_INDEX_BIT,
// Provided by VK_KHR_device_group
VK_PIPELINE_CREATE_DISPATCH_BASE_KHR = VK_PIPELINE_CREATE_DISPATCH_BASE,
// Provided by VK_EXT_fragment_density_map with VK_VERSION_1_3 or VK_KHR_dynamic_rendering
// VK_PIPELINE_RASTERIZATION_STATE_CREATE_FRAGMENT_DENSITY_MAP_ATTACHMENT_BIT_EXT is a deprecated alias
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_fragment_shading_rate with VK_VERSION_1_3 or VK_KHR_dynamic_rendering
// VK_PIPELINE_RASTERIZATION_STATE_CREATE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR is a deprecated alias
VK_PIPELINE_RASTERIZATION_STATE_CREATE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR = VK_PIPELINE_CREATE_RENDERING_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR,
// Provided by VK_EXT_pipeline_creation_cache_control
VK_PIPELINE_CREATE_FAIL_ON_PIPELINE_COMPILE_REQUIRED_BIT_EXT = VK_PIPELINE_CREATE_FAIL_ON_PIPELINE_COMPILE_REQUIRED_BIT,
// Provided by VK_EXT_pipeline_creation_cache_control
VK_PIPELINE_CREATE_EARLY_RETURN_ON_FAILURE_BIT_EXT = VK_PIPELINE_CREATE_EARLY_RETURN_ON_FAILURE_BIT,
} VkPipelineCreateFlagBits;
-
VK_PIPELINE_CREATE_DISABLE_OPTIMIZATION_BIT
specifies that the created pipeline will not be optimized. Using this flag may reduce the time taken to create the pipeline. -
VK_PIPELINE_CREATE_ALLOW_DERIVATIVES_BIT
specifies that the pipeline to be created is allowed to be the parent of a pipeline that will be created in a subsequent pipeline creation call. -
VK_PIPELINE_CREATE_DERIVATIVE_BIT
specifies that the pipeline to be created will be a child of a previously created parent pipeline. -
VK_PIPELINE_CREATE_VIEW_INDEX_FROM_DEVICE_INDEX_BIT
specifies that any shader input variables decorated asViewIndex
will be assigned values as if they were decorated asDeviceIndex
. -
VK_PIPELINE_CREATE_DISPATCH_BASE
specifies that a compute pipeline can be used with vkCmdDispatchBase with a non-zero base workgroup. -
VK_PIPELINE_CREATE_DEFER_COMPILE_BIT_NV
specifies that a pipeline is created with all shaders in the deferred state. Before using the pipeline the application must call vkCompileDeferredNV exactly once on each shader in the pipeline before using the pipeline. -
VK_PIPELINE_CREATE_CAPTURE_STATISTICS_BIT_KHR
specifies that the shader compiler should capture statistics for the pipeline executables produced by the compile process which can later be retrieved by calling vkGetPipelineExecutableStatisticsKHR. Enabling this flag must not affect the final compiled pipeline but may disable pipeline caching or otherwise affect pipeline creation time. -
VK_PIPELINE_CREATE_CAPTURE_INTERNAL_REPRESENTATIONS_BIT_KHR
specifies that the shader compiler should capture the internal representations of pipeline executables produced by the compile process which can later be retrieved by calling vkGetPipelineExecutableInternalRepresentationsKHR. Enabling this flag must not affect the final compiled pipeline but may disable pipeline caching or otherwise affect pipeline creation time. 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_KHR
specifies that the pipeline cannot be used directly, and instead defines a pipeline library that can be combined with other pipelines using the VkPipelineLibraryCreateInfoKHR structure. This is available in ray tracing and graphics pipelines. -
VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_ANY_HIT_SHADERS_BIT_KHR
specifies that an any-hit shader will always be present when an any-hit shader would be executed. 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_KHR
specifies 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_KHR
specifies 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_KHR
specifies 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_KHR
specifies that triangle primitives will be skipped during traversal using pipeline trace ray instructions. -
VK_PIPELINE_CREATE_RAY_TRACING_SKIP_AABBS_BIT_KHR
specifies that AABB primitives will be skipped during traversal using pipeline trace ray instructions. -
VK_PIPELINE_CREATE_RAY_TRACING_SHADER_GROUP_HANDLE_CAPTURE_REPLAY_BIT_KHR
specifies that the shader group handles can be saved and reused on a subsequent run (e.g. for trace capture and replay). -
VK_PIPELINE_CREATE_INDIRECT_BINDABLE_BIT_NV
specifies that the pipeline can be used in combination with Device-Generated Commands. -
VK_PIPELINE_CREATE_FAIL_ON_PIPELINE_COMPILE_REQUIRED_BIT
specifies that pipeline creation will fail if a compile is required for creation of a valid VkPipeline object;VK_PIPELINE_COMPILE_REQUIRED
will be returned by pipeline creation, and the VkPipeline will be VK_NULL_HANDLE. -
When creating multiple pipelines,
VK_PIPELINE_CREATE_EARLY_RETURN_ON_FAILURE_BIT
specifies that control will be returned to the application if any individual pipeline returns a result which is notVK_SUCCESS
rather than continuing to create additional pipelines. -
VK_PIPELINE_CREATE_RAY_TRACING_ALLOW_MOTION_BIT_NV
specifies that the pipeline is allowed to useOpTraceRayMotionNV
. -
VK_PIPELINE_CREATE_RENDERING_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR
specifies that the pipeline will be used with a fragment shading rate attachment and dynamic rendering. -
VK_PIPELINE_CREATE_RENDERING_FRAGMENT_DENSITY_MAP_ATTACHMENT_BIT_EXT
specifies that the pipeline will be used with a fragment density map attachment and dynamic rendering. -
VK_PIPELINE_CREATE_LINK_TIME_OPTIMIZATION_BIT_EXT
specifies that pipeline libraries being linked into this library should have link time optimizations applied. If this bit is omitted, implementations should instead perform linking as rapidly as possible. -
VK_PIPELINE_CREATE_RETAIN_LINK_TIME_OPTIMIZATION_INFO_BIT_EXT
specifies that pipeline libraries should retain any information necessary to later perform an optimal link withVK_PIPELINE_CREATE_LINK_TIME_OPTIMIZATION_BIT_EXT
. -
VK_PIPELINE_CREATE_DESCRIPTOR_BUFFER_BIT_EXT
specifies that a pipeline will be used with descriptor buffers, rather than descriptor sets. -
VK_PIPELINE_CREATE_COLOR_ATTACHMENT_FEEDBACK_LOOP_BIT_EXT
specifies that the pipeline may be used with an attachment feedback loop including color attachments. It is ignored ifVK_DYNAMIC_STATE_ATTACHMENT_FEEDBACK_LOOP_ENABLE_EXT
is set inpDynamicStates
. -
VK_PIPELINE_CREATE_DEPTH_STENCIL_ATTACHMENT_FEEDBACK_LOOP_BIT_EXT
specifies that the pipeline may be used with an attachment feedback loop including depth-stencil attachments. It is ignored ifVK_DYNAMIC_STATE_ATTACHMENT_FEEDBACK_LOOP_ENABLE_EXT
is set inpDynamicStates
. -
VK_PIPELINE_CREATE_RAY_TRACING_OPACITY_MICROMAP_BIT_EXT
specifies that the ray tracing pipeline can be used with acceleration structures which reference an opacity micromap array. -
VK_PIPELINE_CREATE_RAY_TRACING_DISPLACEMENT_MICROMAP_BIT_NV
specifies that the ray tracing pipeline can be used with acceleration structures which reference a displacement micromap array. -
VK_PIPELINE_CREATE_NO_PROTECTED_ACCESS_BIT_EXT
specifies that the pipeline must not be bound to a protected command buffer. -
VK_PIPELINE_CREATE_PROTECTED_ACCESS_ONLY_BIT_EXT
specifies that the pipeline must not be bound to an unprotected command buffer.
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.
When an implementation is looking up a pipeline in a
pipeline cache, if that pipeline is being created using
linked libraries, implementations should always return an equivalent
pipeline created with
VK_PIPELINE_CREATE_LINK_TIME_OPTIMIZATION_BIT_EXT
if available,
whether or not that bit was specified.
Using |
// Provided by VK_VERSION_1_0
typedef VkFlags VkPipelineCreateFlags;
VkPipelineCreateFlags
is a bitmask type for setting a mask of zero or
more VkPipelineCreateFlagBits.
The VkPipelineBinaryInfoKHR
structure is defined as:
// Provided by VK_KHR_pipeline_binary
typedef struct VkPipelineBinaryInfoKHR {
VkStructureType sType;
const void* pNext;
uint32_t binaryCount;
const VkPipelineBinaryKHR* pPipelineBinaries;
} VkPipelineBinaryInfoKHR;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
binaryCount
is the number of elements in thepPipelineBinaries
array. -
pPipelineBinaries
is a pointer to an array of VkPipelineBinaryKHR handles.
If a VkPipelineBinaryInfoKHR
structure with a binaryCount
greater than 0 is included in the pNext
chain of any
Vk*PipelineCreateInfo
structure when creating a pipeline,
implementations must use the data in pPipelineBinaries
instead of
recalculating it.
Any shader module identifiers or shader modules declared in
VkPipelineShaderStageCreateInfo instances are ignored.
If this structure is not included in the pNext
chain, it is equivalent
to specifying this structure with a binaryCount
of 0
.
The VkGraphicsPipelineLibraryCreateInfoEXT
structure is defined as:
// Provided by VK_EXT_graphics_pipeline_library
typedef struct VkGraphicsPipelineLibraryCreateInfoEXT {
VkStructureType sType;
const void* pNext;
VkGraphicsPipelineLibraryFlagsEXT flags;
} VkGraphicsPipelineLibraryCreateInfoEXT;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
flags
is a bitmask of VkGraphicsPipelineLibraryFlagBitsEXT specifying the subsets of the graphics pipeline that are being compiled.
If a VkGraphicsPipelineLibraryCreateInfoEXT
structure is included in
the pNext
chain of VkGraphicsPipelineCreateInfo, it specifies
the subsets of the graphics pipeline being
created, excluding any subsets from linked pipeline libraries.
If the pipeline is created with pipeline libraries, state from those
libraries is aggregated with said subset.
If this structure is omitted, and either
VkGraphicsPipelineCreateInfo::flags
includes
VK_PIPELINE_CREATE_LIBRARY_BIT_KHR
or the
VkGraphicsPipelineCreateInfo::pNext
chain includes a
VkPipelineLibraryCreateInfoKHR structure with a libraryCount
greater than 0
, it is as if flags
is 0
.
Otherwise if this structure is omitted, it is as if flags
includes all
possible subsets of the graphics pipeline (i.e. a
complete graphics pipeline).
// Provided by VK_EXT_graphics_pipeline_library
typedef VkFlags VkGraphicsPipelineLibraryFlagsEXT;
VkGraphicsPipelineLibraryFlagsEXT
is a bitmask type for setting a mask
of zero or more VkGraphicsPipelineLibraryFlagBitsEXT.
Possible values of the flags
member of
VkGraphicsPipelineLibraryCreateInfoEXT, specifying the subsets of a
graphics pipeline to compile are:
// Provided by VK_EXT_graphics_pipeline_library
typedef enum VkGraphicsPipelineLibraryFlagBitsEXT {
VK_GRAPHICS_PIPELINE_LIBRARY_VERTEX_INPUT_INTERFACE_BIT_EXT = 0x00000001,
VK_GRAPHICS_PIPELINE_LIBRARY_PRE_RASTERIZATION_SHADERS_BIT_EXT = 0x00000002,
VK_GRAPHICS_PIPELINE_LIBRARY_FRAGMENT_SHADER_BIT_EXT = 0x00000004,
VK_GRAPHICS_PIPELINE_LIBRARY_FRAGMENT_OUTPUT_INTERFACE_BIT_EXT = 0x00000008,
} VkGraphicsPipelineLibraryFlagBitsEXT;
-
VK_GRAPHICS_PIPELINE_LIBRARY_VERTEX_INPUT_INTERFACE_BIT_EXT
specifies that a pipeline will include vertex input interface state. -
VK_GRAPHICS_PIPELINE_LIBRARY_PRE_RASTERIZATION_SHADERS_BIT_EXT
specifies that a pipeline will include pre-rasterization shader state. -
VK_GRAPHICS_PIPELINE_LIBRARY_FRAGMENT_SHADER_BIT_EXT
specifies that a pipeline will include fragment shader state. -
VK_GRAPHICS_PIPELINE_LIBRARY_FRAGMENT_OUTPUT_INTERFACE_BIT_EXT
specifies that a pipeline will include fragment output interface state.
The VkPipelineDynamicStateCreateInfo
structure is defined as:
// Provided by VK_VERSION_1_0
typedef struct VkPipelineDynamicStateCreateInfo {
VkStructureType sType;
const void* pNext;
VkPipelineDynamicStateCreateFlags flags;
uint32_t dynamicStateCount;
const VkDynamicState* pDynamicStates;
} VkPipelineDynamicStateCreateInfo;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
flags
is reserved for future use. -
dynamicStateCount
is the number of elements in thepDynamicStates
array. -
pDynamicStates
is a pointer to an array of VkDynamicState values specifying which pieces of pipeline state will use the values from dynamic state commands rather than from pipeline state creation 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_NV_clip_space_w_scaling
VK_DYNAMIC_STATE_VIEWPORT_W_SCALING_NV = 1000087000,
// Provided by VK_EXT_discard_rectangles
VK_DYNAMIC_STATE_DISCARD_RECTANGLE_EXT = 1000099000,
// Provided by VK_EXT_discard_rectangles
VK_DYNAMIC_STATE_DISCARD_RECTANGLE_ENABLE_EXT = 1000099001,
// Provided by VK_EXT_discard_rectangles
VK_DYNAMIC_STATE_DISCARD_RECTANGLE_MODE_EXT = 1000099002,
// Provided by VK_EXT_sample_locations
VK_DYNAMIC_STATE_SAMPLE_LOCATIONS_EXT = 1000143000,
// Provided by VK_KHR_ray_tracing_pipeline
VK_DYNAMIC_STATE_RAY_TRACING_PIPELINE_STACK_SIZE_KHR = 1000347000,
// Provided by VK_NV_shading_rate_image
VK_DYNAMIC_STATE_VIEWPORT_SHADING_RATE_PALETTE_NV = 1000164004,
// Provided by VK_NV_shading_rate_image
VK_DYNAMIC_STATE_VIEWPORT_COARSE_SAMPLE_ORDER_NV = 1000164006,
// Provided by VK_NV_scissor_exclusive
VK_DYNAMIC_STATE_EXCLUSIVE_SCISSOR_ENABLE_NV = 1000205000,
// Provided by VK_NV_scissor_exclusive
VK_DYNAMIC_STATE_EXCLUSIVE_SCISSOR_NV = 1000205001,
// Provided by VK_KHR_fragment_shading_rate
VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR = 1000226000,
// Provided by VK_EXT_vertex_input_dynamic_state
VK_DYNAMIC_STATE_VERTEX_INPUT_EXT = 1000352000,
// Provided by VK_EXT_extended_dynamic_state2
VK_DYNAMIC_STATE_PATCH_CONTROL_POINTS_EXT = 1000377000,
// Provided by VK_EXT_extended_dynamic_state2
VK_DYNAMIC_STATE_LOGIC_OP_EXT = 1000377003,
// Provided by VK_EXT_color_write_enable
VK_DYNAMIC_STATE_COLOR_WRITE_ENABLE_EXT = 1000381000,
// Provided by VK_EXT_extended_dynamic_state3
VK_DYNAMIC_STATE_DEPTH_CLAMP_ENABLE_EXT = 1000455003,
// Provided by VK_EXT_extended_dynamic_state3
VK_DYNAMIC_STATE_POLYGON_MODE_EXT = 1000455004,
// Provided by VK_EXT_extended_dynamic_state3
VK_DYNAMIC_STATE_RASTERIZATION_SAMPLES_EXT = 1000455005,
// Provided by VK_EXT_extended_dynamic_state3
VK_DYNAMIC_STATE_SAMPLE_MASK_EXT = 1000455006,
// Provided by VK_EXT_extended_dynamic_state3
VK_DYNAMIC_STATE_ALPHA_TO_COVERAGE_ENABLE_EXT = 1000455007,
// Provided by VK_EXT_extended_dynamic_state3
VK_DYNAMIC_STATE_ALPHA_TO_ONE_ENABLE_EXT = 1000455008,
// Provided by VK_EXT_extended_dynamic_state3
VK_DYNAMIC_STATE_LOGIC_OP_ENABLE_EXT = 1000455009,
// Provided by VK_EXT_extended_dynamic_state3
VK_DYNAMIC_STATE_COLOR_BLEND_ENABLE_EXT = 1000455010,
// Provided by VK_EXT_extended_dynamic_state3
VK_DYNAMIC_STATE_COLOR_BLEND_EQUATION_EXT = 1000455011,
// Provided by VK_EXT_extended_dynamic_state3
VK_DYNAMIC_STATE_COLOR_WRITE_MASK_EXT = 1000455012,
// Provided by VK_EXT_extended_dynamic_state3 with VK_KHR_maintenance2 or VK_VERSION_1_1
VK_DYNAMIC_STATE_TESSELLATION_DOMAIN_ORIGIN_EXT = 1000455002,
// Provided by VK_EXT_extended_dynamic_state3 with VK_EXT_transform_feedback
VK_DYNAMIC_STATE_RASTERIZATION_STREAM_EXT = 1000455013,
// Provided by VK_EXT_conservative_rasterization with VK_EXT_extended_dynamic_state3
VK_DYNAMIC_STATE_CONSERVATIVE_RASTERIZATION_MODE_EXT = 1000455014,
// Provided by VK_EXT_conservative_rasterization with VK_EXT_extended_dynamic_state3
VK_DYNAMIC_STATE_EXTRA_PRIMITIVE_OVERESTIMATION_SIZE_EXT = 1000455015,
// Provided by VK_EXT_depth_clip_enable with VK_EXT_extended_dynamic_state3
VK_DYNAMIC_STATE_DEPTH_CLIP_ENABLE_EXT = 1000455016,
// Provided by VK_EXT_extended_dynamic_state3 with VK_EXT_sample_locations
VK_DYNAMIC_STATE_SAMPLE_LOCATIONS_ENABLE_EXT = 1000455017,
// Provided by VK_EXT_blend_operation_advanced with VK_EXT_extended_dynamic_state3
VK_DYNAMIC_STATE_COLOR_BLEND_ADVANCED_EXT = 1000455018,
// Provided by VK_EXT_extended_dynamic_state3 with VK_EXT_provoking_vertex
VK_DYNAMIC_STATE_PROVOKING_VERTEX_MODE_EXT = 1000455019,
// Provided by VK_EXT_extended_dynamic_state3 with VK_EXT_line_rasterization
VK_DYNAMIC_STATE_LINE_RASTERIZATION_MODE_EXT = 1000455020,
// Provided by VK_EXT_extended_dynamic_state3 with VK_EXT_line_rasterization
VK_DYNAMIC_STATE_LINE_STIPPLE_ENABLE_EXT = 1000455021,
// Provided by VK_EXT_depth_clip_control with VK_EXT_extended_dynamic_state3
VK_DYNAMIC_STATE_DEPTH_CLIP_NEGATIVE_ONE_TO_ONE_EXT = 1000455022,
// Provided by VK_EXT_extended_dynamic_state3 with VK_NV_clip_space_w_scaling
VK_DYNAMIC_STATE_VIEWPORT_W_SCALING_ENABLE_NV = 1000455023,
// Provided by VK_EXT_extended_dynamic_state3 with VK_NV_viewport_swizzle
VK_DYNAMIC_STATE_VIEWPORT_SWIZZLE_NV = 1000455024,
// Provided by VK_EXT_extended_dynamic_state3 with VK_NV_fragment_coverage_to_color
VK_DYNAMIC_STATE_COVERAGE_TO_COLOR_ENABLE_NV = 1000455025,
// Provided by VK_EXT_extended_dynamic_state3 with VK_NV_fragment_coverage_to_color
VK_DYNAMIC_STATE_COVERAGE_TO_COLOR_LOCATION_NV = 1000455026,
// Provided by VK_EXT_extended_dynamic_state3 with VK_NV_framebuffer_mixed_samples
VK_DYNAMIC_STATE_COVERAGE_MODULATION_MODE_NV = 1000455027,
// Provided by VK_EXT_extended_dynamic_state3 with VK_NV_framebuffer_mixed_samples
VK_DYNAMIC_STATE_COVERAGE_MODULATION_TABLE_ENABLE_NV = 1000455028,
// Provided by VK_EXT_extended_dynamic_state3 with VK_NV_framebuffer_mixed_samples
VK_DYNAMIC_STATE_COVERAGE_MODULATION_TABLE_NV = 1000455029,
// Provided by VK_EXT_extended_dynamic_state3 with VK_NV_shading_rate_image
VK_DYNAMIC_STATE_SHADING_RATE_IMAGE_ENABLE_NV = 1000455030,
// Provided by VK_EXT_extended_dynamic_state3 with VK_NV_representative_fragment_test
VK_DYNAMIC_STATE_REPRESENTATIVE_FRAGMENT_TEST_ENABLE_NV = 1000455031,
// Provided by VK_EXT_extended_dynamic_state3 with VK_NV_coverage_reduction_mode
VK_DYNAMIC_STATE_COVERAGE_REDUCTION_MODE_NV = 1000455032,
// Provided by VK_EXT_attachment_feedback_loop_dynamic_state
VK_DYNAMIC_STATE_ATTACHMENT_FEEDBACK_LOOP_ENABLE_EXT = 1000524000,
// Provided by VK_KHR_line_rasterization
VK_DYNAMIC_STATE_LINE_STIPPLE_KHR = 1000259000,
// Provided by VK_EXT_depth_clamp_control
VK_DYNAMIC_STATE_DEPTH_CLAMP_RANGE_EXT = 1000582000,
// Provided by VK_EXT_line_rasterization
VK_DYNAMIC_STATE_LINE_STIPPLE_EXT = VK_DYNAMIC_STATE_LINE_STIPPLE_KHR,
// Provided by VK_EXT_extended_dynamic_state
VK_DYNAMIC_STATE_CULL_MODE_EXT = VK_DYNAMIC_STATE_CULL_MODE,
// Provided by VK_EXT_extended_dynamic_state
VK_DYNAMIC_STATE_FRONT_FACE_EXT = VK_DYNAMIC_STATE_FRONT_FACE,
// Provided by VK_EXT_extended_dynamic_state
VK_DYNAMIC_STATE_PRIMITIVE_TOPOLOGY_EXT = VK_DYNAMIC_STATE_PRIMITIVE_TOPOLOGY,
// Provided by VK_EXT_extended_dynamic_state
VK_DYNAMIC_STATE_VIEWPORT_WITH_COUNT_EXT = VK_DYNAMIC_STATE_VIEWPORT_WITH_COUNT,
// Provided by VK_EXT_extended_dynamic_state
VK_DYNAMIC_STATE_SCISSOR_WITH_COUNT_EXT = VK_DYNAMIC_STATE_SCISSOR_WITH_COUNT,
// Provided by VK_EXT_extended_dynamic_state
VK_DYNAMIC_STATE_VERTEX_INPUT_BINDING_STRIDE_EXT = VK_DYNAMIC_STATE_VERTEX_INPUT_BINDING_STRIDE,
// Provided by VK_EXT_extended_dynamic_state
VK_DYNAMIC_STATE_DEPTH_TEST_ENABLE_EXT = VK_DYNAMIC_STATE_DEPTH_TEST_ENABLE,
// Provided by VK_EXT_extended_dynamic_state
VK_DYNAMIC_STATE_DEPTH_WRITE_ENABLE_EXT = VK_DYNAMIC_STATE_DEPTH_WRITE_ENABLE,
// Provided by VK_EXT_extended_dynamic_state
VK_DYNAMIC_STATE_DEPTH_COMPARE_OP_EXT = VK_DYNAMIC_STATE_DEPTH_COMPARE_OP,
// Provided by VK_EXT_extended_dynamic_state
VK_DYNAMIC_STATE_DEPTH_BOUNDS_TEST_ENABLE_EXT = VK_DYNAMIC_STATE_DEPTH_BOUNDS_TEST_ENABLE,
// Provided by VK_EXT_extended_dynamic_state
VK_DYNAMIC_STATE_STENCIL_TEST_ENABLE_EXT = VK_DYNAMIC_STATE_STENCIL_TEST_ENABLE,
// Provided by VK_EXT_extended_dynamic_state
VK_DYNAMIC_STATE_STENCIL_OP_EXT = VK_DYNAMIC_STATE_STENCIL_OP,
// Provided by VK_EXT_extended_dynamic_state2
VK_DYNAMIC_STATE_RASTERIZER_DISCARD_ENABLE_EXT = VK_DYNAMIC_STATE_RASTERIZER_DISCARD_ENABLE,
// Provided by VK_EXT_extended_dynamic_state2
VK_DYNAMIC_STATE_DEPTH_BIAS_ENABLE_EXT = VK_DYNAMIC_STATE_DEPTH_BIAS_ENABLE,
// Provided by VK_EXT_extended_dynamic_state2
VK_DYNAMIC_STATE_PRIMITIVE_RESTART_ENABLE_EXT = VK_DYNAMIC_STATE_PRIMITIVE_RESTART_ENABLE,
} VkDynamicState;
-
VK_DYNAMIC_STATE_VIEWPORT
specifies that thepViewports
state 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 theviewportCount
member of VkPipelineViewportStateCreateInfo. -
VK_DYNAMIC_STATE_SCISSOR
specifies that thepScissors
state 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 thescissorCount
member of VkPipelineViewportStateCreateInfo. -
VK_DYNAMIC_STATE_LINE_WIDTH
specifies that thelineWidth
state 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_BIAS
specifies that any instance of VkDepthBiasRepresentationInfoEXT included in thepNext
chain of VkPipelineRasterizationStateCreateInfo as well as thedepthBiasConstantFactor
,depthBiasClamp
anddepthBiasSlopeFactor
states in VkPipelineRasterizationStateCreateInfo will be ignored and must be set dynamically with vkCmdSetDepthBias or vkCmdSetDepthBias2EXT before any draws are performed with depth bias enabled. -
VK_DYNAMIC_STATE_BLEND_CONSTANTS
specifies that theblendConstants
state in VkPipelineColorBlendStateCreateInfo will be ignored and must be set dynamically with vkCmdSetBlendConstants before any draws are performed with a pipeline state withVkPipelineColorBlendAttachmentState
memberblendEnable
set toVK_TRUE
and any of the blend functions using a constant blend color. -
VK_DYNAMIC_STATE_DEPTH_BOUNDS
specifies that theminDepthBounds
andmaxDepthBounds
states of VkPipelineDepthStencilStateCreateInfo will be ignored and must be set dynamically with vkCmdSetDepthBounds before any draws are performed with a pipeline state with VkPipelineDepthStencilStateCreateInfo memberdepthBoundsTestEnable
set toVK_TRUE
. -
VK_DYNAMIC_STATE_STENCIL_COMPARE_MASK
specifies that thecompareMask
state in VkPipelineDepthStencilStateCreateInfo for bothfront
andback
will be ignored and must be set dynamically with vkCmdSetStencilCompareMask before any draws are performed with a pipeline state with VkPipelineDepthStencilStateCreateInfo memberstencilTestEnable
set toVK_TRUE
-
VK_DYNAMIC_STATE_STENCIL_WRITE_MASK
specifies that thewriteMask
state in VkPipelineDepthStencilStateCreateInfo for bothfront
andback
will be ignored and must be set dynamically with vkCmdSetStencilWriteMask before any draws are performed with a pipeline state with VkPipelineDepthStencilStateCreateInfo memberstencilTestEnable
set toVK_TRUE
-
VK_DYNAMIC_STATE_STENCIL_REFERENCE
specifies that thereference
state in VkPipelineDepthStencilStateCreateInfo for bothfront
andback
will be ignored and must be set dynamically with vkCmdSetStencilReference before any draws are performed with a pipeline state with VkPipelineDepthStencilStateCreateInfo memberstencilTestEnable
set toVK_TRUE
-
VK_DYNAMIC_STATE_VIEWPORT_W_SCALING_NV
specifies that thepViewportWScalings
state in VkPipelineViewportWScalingStateCreateInfoNV will be ignored and must be set dynamically with vkCmdSetViewportWScalingNV before any draws are performed with a pipeline state with VkPipelineViewportWScalingStateCreateInfoNV memberviewportScalingEnable
set toVK_TRUE
-
VK_DYNAMIC_STATE_DISCARD_RECTANGLE_EXT
specifies that thepDiscardRectangles
state in VkPipelineDiscardRectangleStateCreateInfoEXT will be ignored and must be set dynamically with vkCmdSetDiscardRectangleEXT before any draw or clear commands. -
VK_DYNAMIC_STATE_DISCARD_RECTANGLE_ENABLE_EXT
specifies that the presence of the VkPipelineDiscardRectangleStateCreateInfoEXT structure in the VkGraphicsPipelineCreateInfo chain with adiscardRectangleCount
greater than zero does not implicitly enable discard rectangles and they must be enabled dynamically with vkCmdSetDiscardRectangleEnableEXT before any draw commands. This is available on implementations that support at leastspecVersion
2
of theVK_EXT_discard_rectangles
extension. -
VK_DYNAMIC_STATE_DISCARD_RECTANGLE_MODE_EXT
specifies that thediscardRectangleMode
state in VkPipelineDiscardRectangleStateCreateInfoEXT will be ignored and must be set dynamically with vkCmdSetDiscardRectangleModeEXT before any draw commands. This is available on implementations that support at leastspecVersion
2
of theVK_EXT_discard_rectangles
extension. -
VK_DYNAMIC_STATE_SAMPLE_LOCATIONS_EXT
specifies that thesampleLocationsInfo
state in VkPipelineSampleLocationsStateCreateInfoEXT will be ignored and must be set dynamically with vkCmdSetSampleLocationsEXT before any draw or clear commands. Enabling custom sample locations is still indicated by thesampleLocationsEnable
member of VkPipelineSampleLocationsStateCreateInfoEXT. -
VK_DYNAMIC_STATE_EXCLUSIVE_SCISSOR_NV
specifies that thepExclusiveScissors
state in VkPipelineViewportExclusiveScissorStateCreateInfoNV will be ignored and must be set dynamically with vkCmdSetExclusiveScissorNV before any drawing commands. -
VK_DYNAMIC_STATE_EXCLUSIVE_SCISSOR_ENABLE_NV
specifies that the exclusive scissors must be explicitly enabled with vkCmdSetExclusiveScissorEnableNV and theexclusiveScissorCount
value in VkPipelineViewportExclusiveScissorStateCreateInfoNV will not implicitly enable them. This is available on implementations that support at leastspecVersion
2
of theVK_NV_scissor_exclusive
extension. -
VK_DYNAMIC_STATE_VIEWPORT_SHADING_RATE_PALETTE_NV
specifies that thepShadingRatePalettes
state in VkPipelineViewportShadingRateImageStateCreateInfoNV will be ignored and must be set dynamically with vkCmdSetViewportShadingRatePaletteNV before any drawing commands. -
VK_DYNAMIC_STATE_VIEWPORT_COARSE_SAMPLE_ORDER_NV
specifies that the coarse sample order state in VkPipelineViewportCoarseSampleOrderStateCreateInfoNV will be ignored and must be set dynamically with vkCmdSetCoarseSampleOrderNV before any drawing commands. -
VK_DYNAMIC_STATE_LINE_STIPPLE_EXT
specifies that thelineStippleFactor
andlineStipplePattern
state in VkPipelineRasterizationLineStateCreateInfoKHR will be ignored and must be set dynamically with vkCmdSetLineStippleKHR before any draws are performed with a pipeline state with VkPipelineRasterizationLineStateCreateInfoKHR memberstippledLineEnable
set toVK_TRUE
. -
VK_DYNAMIC_STATE_CULL_MODE
specifies that thecullMode
state in VkPipelineRasterizationStateCreateInfo will be ignored and must be set dynamically with vkCmdSetCullMode before any drawing commands. -
VK_DYNAMIC_STATE_FRONT_FACE
specifies that thefrontFace
state in VkPipelineRasterizationStateCreateInfo will be ignored and must be set dynamically with vkCmdSetFrontFace before any drawing commands. -
VK_DYNAMIC_STATE_PRIMITIVE_TOPOLOGY
specifies that thetopology
state 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_COUNT
specifies that theviewportCount
andpViewports
state in VkPipelineViewportStateCreateInfo will be ignored and must be set dynamically with vkCmdSetViewportWithCount before any draw call. -
VK_DYNAMIC_STATE_SCISSOR_WITH_COUNT
specifies that thescissorCount
andpScissors
state in VkPipelineViewportStateCreateInfo will be ignored and must be set dynamically with vkCmdSetScissorWithCount before any draw call. -
VK_DYNAMIC_STATE_VERTEX_INPUT_BINDING_STRIDE
specifies that thestride
state in VkVertexInputBindingDescription will be ignored and must be set dynamically with vkCmdBindVertexBuffers2 before any draw call. -
VK_DYNAMIC_STATE_DEPTH_TEST_ENABLE
specifies that thedepthTestEnable
state in VkPipelineDepthStencilStateCreateInfo will be ignored and must be set dynamically with vkCmdSetDepthTestEnable before any draw call. -
VK_DYNAMIC_STATE_DEPTH_WRITE_ENABLE
specifies that thedepthWriteEnable
state in VkPipelineDepthStencilStateCreateInfo will be ignored and must be set dynamically with vkCmdSetDepthWriteEnable before any draw call. -
VK_DYNAMIC_STATE_DEPTH_COMPARE_OP
specifies that thedepthCompareOp
state in VkPipelineDepthStencilStateCreateInfo will be ignored and must be set dynamically with vkCmdSetDepthCompareOp before any draw call. -
VK_DYNAMIC_STATE_DEPTH_BOUNDS_TEST_ENABLE
specifies that thedepthBoundsTestEnable
state in VkPipelineDepthStencilStateCreateInfo will be ignored and must be set dynamically with vkCmdSetDepthBoundsTestEnable before any draw call. -
VK_DYNAMIC_STATE_STENCIL_TEST_ENABLE
specifies that thestencilTestEnable
state in VkPipelineDepthStencilStateCreateInfo will be ignored and must be set dynamically with vkCmdSetStencilTestEnable before any draw call. -
VK_DYNAMIC_STATE_STENCIL_OP
specifies that thefailOp
,passOp
,depthFailOp
, andcompareOp
states inVkPipelineDepthStencilStateCreateInfo
for bothfront
andback
will be ignored and must be set dynamically with vkCmdSetStencilOp before any draws are performed with a pipeline state withVkPipelineDepthStencilStateCreateInfo
memberstencilTestEnable
set toVK_TRUE
-
VK_DYNAMIC_STATE_PATCH_CONTROL_POINTS_EXT
specifies that thepatchControlPoints
state in VkPipelineTessellationStateCreateInfo will be ignored and must be set dynamically with vkCmdSetPatchControlPointsEXT before any drawing commands. -
VK_DYNAMIC_STATE_RASTERIZER_DISCARD_ENABLE
specifies that therasterizerDiscardEnable
state in VkPipelineRasterizationStateCreateInfo will be ignored and must be set dynamically with vkCmdSetRasterizerDiscardEnable before any drawing commands. -
VK_DYNAMIC_STATE_DEPTH_BIAS_ENABLE
specifies that thedepthBiasEnable
state in VkPipelineRasterizationStateCreateInfo will be ignored and must be set dynamically with vkCmdSetDepthBiasEnable before any drawing commands. -
VK_DYNAMIC_STATE_LOGIC_OP_EXT
specifies that thelogicOp
state in VkPipelineColorBlendStateCreateInfo will be ignored and must be set dynamically with vkCmdSetLogicOpEXT before any drawing commands. -
VK_DYNAMIC_STATE_PRIMITIVE_RESTART_ENABLE
specifies that theprimitiveRestartEnable
state in VkPipelineInputAssemblyStateCreateInfo will be ignored and must be set dynamically with vkCmdSetPrimitiveRestartEnable before any drawing commands. -
VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR
specifies that state in VkPipelineFragmentShadingRateStateCreateInfoKHR and VkPipelineFragmentShadingRateEnumStateCreateInfoNV will be ignored and must be set dynamically with vkCmdSetFragmentShadingRateKHR or vkCmdSetFragmentShadingRateEnumNV before any drawing commands. -
VK_DYNAMIC_STATE_RAY_TRACING_PIPELINE_STACK_SIZE_KHR
specifies 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. -
VK_DYNAMIC_STATE_VERTEX_INPUT_EXT
specifies that thepVertexInputState
state will be ignored and must be set dynamically with vkCmdSetVertexInputEXT before any drawing commands -
VK_DYNAMIC_STATE_COLOR_WRITE_ENABLE_EXT
specifies that thepColorWriteEnables
state in VkPipelineColorWriteCreateInfoEXT will be ignored and must be set dynamically with vkCmdSetColorWriteEnableEXT before any draw call. -
VK_DYNAMIC_STATE_TESSELLATION_DOMAIN_ORIGIN_EXT
specifies that thedomainOrigin
state in VkPipelineTessellationDomainOriginStateCreateInfo will be ignored and must be set dynamically with vkCmdSetTessellationDomainOriginEXT before any draw call. -
VK_DYNAMIC_STATE_DEPTH_CLAMP_ENABLE_EXT
specifies that thedepthClampEnable
state in VkPipelineRasterizationStateCreateInfo will be ignored and must be set dynamically with vkCmdSetDepthClampEnableEXT before any draw call. -
VK_DYNAMIC_STATE_POLYGON_MODE_EXT
specifies that thepolygonMode
state in VkPipelineRasterizationStateCreateInfo will be ignored and must be set dynamically with vkCmdSetPolygonModeEXT before any draw call. -
VK_DYNAMIC_STATE_RASTERIZATION_SAMPLES_EXT
specifies that therasterizationSamples
state in VkPipelineMultisampleStateCreateInfo will be ignored and must be set dynamically with vkCmdSetRasterizationSamplesEXT before any draw call. -
VK_DYNAMIC_STATE_SAMPLE_MASK_EXT
specifies that thepSampleMask
state in VkPipelineMultisampleStateCreateInfo will be ignored and must be set dynamically with vkCmdSetSampleMaskEXT before any draw call. -
VK_DYNAMIC_STATE_ALPHA_TO_COVERAGE_ENABLE_EXT
specifies that thealphaToCoverageEnable
state in VkPipelineMultisampleStateCreateInfo will be ignored and must be set dynamically with vkCmdSetAlphaToCoverageEnableEXT before any draw call. -
VK_DYNAMIC_STATE_ALPHA_TO_ONE_ENABLE_EXT
specifies that thealphaToOneEnable
state in VkPipelineMultisampleStateCreateInfo will be ignored and must be set dynamically with vkCmdSetAlphaToOneEnableEXT before any draw call. -
VK_DYNAMIC_STATE_LOGIC_OP_ENABLE_EXT
specifies that thelogicOpEnable
state in VkPipelineColorBlendStateCreateInfo will be ignored and must be set dynamically with vkCmdSetLogicOpEnableEXT before any draw call. -
VK_DYNAMIC_STATE_COLOR_BLEND_ENABLE_EXT
specifies that theblendEnable
state in VkPipelineColorBlendAttachmentState will be ignored and must be set dynamically with vkCmdSetColorBlendEnableEXT before any draw call. -
VK_DYNAMIC_STATE_COLOR_BLEND_EQUATION_EXT
specifies that thesrcColorBlendFactor
,dstColorBlendFactor
,colorBlendOp
,srcAlphaBlendFactor
,dstAlphaBlendFactor
, andalphaBlendOp
states in VkPipelineColorBlendAttachmentState will be ignored and must be set dynamically with vkCmdSetColorBlendEquationEXT before any draw call. -
VK_DYNAMIC_STATE_COLOR_WRITE_MASK_EXT
specifies that thecolorWriteMask
state in VkPipelineColorBlendAttachmentState will be ignored and must be set dynamically with vkCmdSetColorWriteMaskEXT before any draw call. -
VK_DYNAMIC_STATE_RASTERIZATION_STREAM_EXT
specifies that therasterizationStream
state in VkPipelineRasterizationStateStreamCreateInfoEXT will be ignored and must be set dynamically with vkCmdSetRasterizationStreamEXT before any draw call. -
VK_DYNAMIC_STATE_CONSERVATIVE_RASTERIZATION_MODE_EXT
specifies that theconservativeRasterizationMode
state in VkPipelineRasterizationConservativeStateCreateInfoEXT will be ignored and must be set dynamically with vkCmdSetConservativeRasterizationModeEXT before any draw call. -
VK_DYNAMIC_STATE_EXTRA_PRIMITIVE_OVERESTIMATION_SIZE_EXT
specifies that theextraPrimitiveOverestimationSize
state in VkPipelineRasterizationConservativeStateCreateInfoEXT will be ignored and must be set dynamically with vkCmdSetExtraPrimitiveOverestimationSizeEXT before any draw call. -
VK_DYNAMIC_STATE_DEPTH_CLIP_ENABLE_EXT
specifies that thedepthClipEnable
state in VkPipelineRasterizationDepthClipStateCreateInfoEXT will be ignored and must be set dynamically with vkCmdSetDepthClipEnableEXT before any draw call. -
VK_DYNAMIC_STATE_SAMPLE_LOCATIONS_ENABLE_EXT
specifies that thesampleLocationsEnable
state in VkPipelineSampleLocationsStateCreateInfoEXT will be ignored and must be set dynamically with vkCmdSetSampleLocationsEnableEXT before any draw call. -
VK_DYNAMIC_STATE_COLOR_BLEND_ADVANCED_EXT
specifies that thecolorBlendOp
state in VkPipelineColorBlendAttachmentState, andsrcPremultiplied
,dstPremultiplied
, andblendOverlap
states in VkPipelineColorBlendAdvancedStateCreateInfoEXT will be ignored and must be set dynamically with vkCmdSetColorBlendAdvancedEXT before any draw call. -
VK_DYNAMIC_STATE_PROVOKING_VERTEX_MODE_EXT
specifies that theprovokingVertexMode
state in VkPipelineRasterizationProvokingVertexStateCreateInfoEXT will be ignored and must be set dynamically with vkCmdSetProvokingVertexModeEXT before any draw call. -
VK_DYNAMIC_STATE_LINE_RASTERIZATION_MODE_EXT
specifies that thelineRasterizationMode
state in VkPipelineRasterizationLineStateCreateInfoKHR will be ignored and must be set dynamically with vkCmdSetLineRasterizationModeEXT before any draw call. -
VK_DYNAMIC_STATE_LINE_STIPPLE_ENABLE_EXT
specifies that thestippledLineEnable
state in VkPipelineRasterizationLineStateCreateInfoKHR will be ignored and must be set dynamically with vkCmdSetLineStippleEnableEXT before any draw call. -
VK_DYNAMIC_STATE_DEPTH_CLIP_NEGATIVE_ONE_TO_ONE_EXT
specifies that thenegativeOneToOne
state in VkPipelineViewportDepthClipControlCreateInfoEXT will be ignored and must be set dynamically with vkCmdSetDepthClipNegativeOneToOneEXT before any draw call. -
VK_DYNAMIC_STATE_DEPTH_CLAMP_RANGE_EXT
specifies that thedepthClampMode
andpDepthClampRange
state in VkPipelineViewportDepthClampControlCreateInfoEXT will be ignored and must be set dynamically with vkCmdSetDepthClampRangeEXT before any draw call. -
VK_DYNAMIC_STATE_VIEWPORT_W_SCALING_ENABLE_NV
specifies that theviewportWScalingEnable
state in VkPipelineViewportWScalingStateCreateInfoNV will be ignored and must be set dynamically with vkCmdSetViewportWScalingEnableNV before any draw call. -
VK_DYNAMIC_STATE_VIEWPORT_SWIZZLE_NV
specifies that theviewportCount
, andpViewportSwizzles
states in VkPipelineViewportSwizzleStateCreateInfoNV will be ignored and must be set dynamically with vkCmdSetViewportSwizzleNV before any draw call. -
VK_DYNAMIC_STATE_COVERAGE_TO_COLOR_ENABLE_NV
specifies that thecoverageToColorEnable
state in VkPipelineCoverageToColorStateCreateInfoNV will be ignored and must be set dynamically with vkCmdSetCoverageToColorEnableNV before any draw call. -
VK_DYNAMIC_STATE_COVERAGE_TO_COLOR_LOCATION_NV
specifies that thecoverageToColorLocation
state in VkPipelineCoverageToColorStateCreateInfoNV will be ignored and must be set dynamically with vkCmdSetCoverageToColorLocationNV before any draw call. -
VK_DYNAMIC_STATE_COVERAGE_MODULATION_MODE_NV
specifies that thecoverageModulationMode
state in VkPipelineCoverageModulationStateCreateInfoNV will be ignored and must be set dynamically with vkCmdSetCoverageModulationModeNV before any draw call. -
VK_DYNAMIC_STATE_COVERAGE_MODULATION_TABLE_ENABLE_NV
specifies that thecoverageModulationTableEnable
state in VkPipelineCoverageModulationStateCreateInfoNV will be ignored and must be set dynamically with vkCmdSetCoverageModulationTableEnableNV before any draw call. -
VK_DYNAMIC_STATE_COVERAGE_MODULATION_TABLE_NV
specifies that thecoverageModulationTableCount
, andpCoverageModulationTable
states in VkPipelineCoverageModulationStateCreateInfoNV will be ignored and must be set dynamically with vkCmdSetCoverageModulationTableNV before any draw call. -
VK_DYNAMIC_STATE_SHADING_RATE_IMAGE_ENABLE_NV
specifies that theshadingRateImageEnable
state in VkPipelineViewportShadingRateImageStateCreateInfoNV will be ignored and must be set dynamically with vkCmdSetShadingRateImageEnableNV before any draw call. -
VK_DYNAMIC_STATE_REPRESENTATIVE_FRAGMENT_TEST_ENABLE_NV
specifies that therepresentativeFragmentTestEnable
state in VkPipelineRepresentativeFragmentTestStateCreateInfoNV will be ignored and must be set dynamically with vkCmdSetRepresentativeFragmentTestEnableNV before any draw call. -
VK_DYNAMIC_STATE_COVERAGE_REDUCTION_MODE_NV
specifies that thecoverageReductionMode
state in VkPipelineCoverageReductionStateCreateInfoNV will be ignored and must be set dynamically with vkCmdSetCoverageReductionModeNV before any draw call. -
VK_DYNAMIC_STATE_ATTACHMENT_FEEDBACK_LOOP_ENABLE_EXT
specifies that theVK_PIPELINE_CREATE_COLOR_ATTACHMENT_FEEDBACK_LOOP_BIT_EXT
andVK_PIPELINE_CREATE_DEPTH_STENCIL_ATTACHMENT_FEEDBACK_LOOP_BIT_EXT
flags will be ignored and must be set dynamically with vkCmdSetAttachmentFeedbackLoopEnableEXT before any draw call.
Valid Combinations of Stages for Graphics Pipelines
Primitive processing can be handled either on a per primitive basis by the vertex, tessellation, and geometry shader stages, or on a per mesh basis using task and mesh shader stages. If the pipeline includes a mesh shader stage, it uses the mesh pipeline, otherwise it uses the primitive pipeline.
If a task shader is omitted, the task shading stage is skipped.
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
-
-
Rendering pipeline with task and mesh shaders
-
Active Pipeline Shader Stages
-
Task Shader
-
Mesh Shader
-
Fragment Shader
-
-
Required: Fixed-Function Pipeline Stages
-
Graphics Pipeline Shader Groups
Graphics pipelines can contain multiple shader groups that can be bound
individually.
Each shader group behaves as if it was a pipeline using the shader group’s
state.
When the pipeline is bound by regular means, it behaves as if the state of
group 0
is active, use vkCmdBindPipelineShaderGroupNV to bind an
individual shader group.
The primary purpose of shader groups is allowing the device to bind different pipeline state using Device-Generated Commands.
The VkGraphicsPipelineShaderGroupsCreateInfoNV
structure is defined
as:
// Provided by VK_NV_device_generated_commands
typedef struct VkGraphicsPipelineShaderGroupsCreateInfoNV {
VkStructureType sType;
const void* pNext;
uint32_t groupCount;
const VkGraphicsShaderGroupCreateInfoNV* pGroups;
uint32_t pipelineCount;
const VkPipeline* pPipelines;
} VkGraphicsPipelineShaderGroupsCreateInfoNV;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
groupCount
is the number of elements in thepGroups
array. -
pGroups
is a pointer to an array of VkGraphicsShaderGroupCreateInfoNV structures specifying which state of the original VkGraphicsPipelineCreateInfo each shader group overrides. -
pipelineCount
is the number of elements in thepPipelines
array. -
pPipelines
is a pointer to an array of graphicsVkPipeline
structures which are referenced within the created pipeline, including all their shader groups.
When referencing shader groups by index, groups defined in the referenced
pipelines are treated as if they were defined as additional entries in
pGroups
.
They are appended in the order they appear in the pPipelines
array and
in the pGroups
array when those pipelines were defined.
The application must maintain the lifetime of all such referenced pipelines based on the pipelines that make use of them.
The VkGraphicsShaderGroupCreateInfoNV
structure provides the state
overrides for each shader group.
Each shader group behaves like a pipeline that was created from its state as
well as the remaining parent’s state.
It is defined as:
// Provided by VK_NV_device_generated_commands
typedef struct VkGraphicsShaderGroupCreateInfoNV {
VkStructureType sType;
const void* pNext;
uint32_t stageCount;
const VkPipelineShaderStageCreateInfo* pStages;
const VkPipelineVertexInputStateCreateInfo* pVertexInputState;
const VkPipelineTessellationStateCreateInfo* pTessellationState;
} VkGraphicsShaderGroupCreateInfoNV;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
stageCount
is the number of entries in thepStages
array. -
pStages
is a pointer to an array VkPipelineShaderStageCreateInfo structures specifying the set of the shader stages to be included in this shader group. -
pVertexInputState
is a pointer to a VkPipelineVertexInputStateCreateInfo structure. -
pTessellationState
is a pointer to a VkPipelineTessellationStateCreateInfo structure, and is ignored if the shader group does not include a tessellation control shader stage and tessellation evaluation shader stage.
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)
or the equivalent
#define VK_SHADER_UNUSED_NV VK_SHADER_UNUSED_KHR
To create ray tracing pipelines, call:
// Provided by VK_NV_ray_tracing
VkResult vkCreateRayTracingPipelinesNV(
VkDevice device,
VkPipelineCache pipelineCache,
uint32_t createInfoCount,
const VkRayTracingPipelineCreateInfoNV* pCreateInfos,
const VkAllocationCallbacks* pAllocator,
VkPipeline* pPipelines);
-
device
is the logical device that creates the ray tracing pipelines. -
pipelineCache
is either VK_NULL_HANDLE, indicating that pipeline caching is disabled, or the handle of a valid pipeline cache object, in which case use of that cache is enabled for the duration of the command. -
createInfoCount
is the length of thepCreateInfos
andpPipelines
arrays. -
pCreateInfos
is a pointer to an array of VkRayTracingPipelineCreateInfoNV structures. -
pAllocator
controls host memory allocation as described in the Memory Allocation chapter. -
pPipelines
is a pointer to an array in which the resulting ray tracing pipeline objects are returned.
Pipelines are created and returned as described for Multiple Pipeline Creation.
To create ray tracing pipelines, call:
// Provided by VK_KHR_ray_tracing_pipeline
VkResult vkCreateRayTracingPipelinesKHR(
VkDevice device,
VkDeferredOperationKHR deferredOperation,
VkPipelineCache pipelineCache,
uint32_t createInfoCount,
const VkRayTracingPipelineCreateInfoKHR* pCreateInfos,
const VkAllocationCallbacks* pAllocator,
VkPipeline* pPipelines);
-
device
is the logical device that creates the ray tracing pipelines. -
deferredOperation
is VK_NULL_HANDLE or the handle of a valid VkDeferredOperationKHR request deferral object for this command. -
pipelineCache
is either VK_NULL_HANDLE, indicating that pipeline caching is disabled, or the handle of a valid pipeline cache object, in which case use of that cache is enabled for the duration of the command. -
createInfoCount
is the length of thepCreateInfos
andpPipelines
arrays. -
pCreateInfos
is a pointer to an array of VkRayTracingPipelineCreateInfoKHR structures. -
pAllocator
controls host memory allocation as described in the Memory Allocation chapter. -
pPipelines
is a pointer to an array in which the resulting ray tracing pipeline objects are returned.
The VK_ERROR_INVALID_OPAQUE_CAPTURE_ADDRESS
error is returned if the
implementation is unable to reuse the shader group handles provided in
VkRayTracingShaderGroupCreateInfoKHR::pShaderGroupCaptureReplayHandle
when
VkPhysicalDeviceRayTracingPipelineFeaturesKHR::rayTracingPipelineShaderGroupHandleCaptureReplay
is enabled.
Pipelines are created and returned as described for Multiple Pipeline Creation.
The VkRayTracingPipelineCreateInfoNV
structure is defined as:
// Provided by VK_NV_ray_tracing
typedef struct VkRayTracingPipelineCreateInfoNV {
VkStructureType sType;
const void* pNext;
VkPipelineCreateFlags flags;
uint32_t stageCount;
const VkPipelineShaderStageCreateInfo* pStages;
uint32_t groupCount;
const VkRayTracingShaderGroupCreateInfoNV* pGroups;
uint32_t maxRecursionDepth;
VkPipelineLayout layout;
VkPipeline basePipelineHandle;
int32_t basePipelineIndex;
} VkRayTracingPipelineCreateInfoNV;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
flags
is a bitmask of VkPipelineCreateFlagBits specifying how the pipeline will be generated. -
stageCount
is the number of entries in thepStages
array. -
pStages
is a pointer to an array of VkPipelineShaderStageCreateInfo structures specifying the set of the shader stages to be included in the ray tracing pipeline. -
groupCount
is the number of entries in thepGroups
array. -
pGroups
is a pointer to an array of VkRayTracingShaderGroupCreateInfoNV structures describing the set of the shader stages to be included in each shader group in the ray tracing pipeline. -
maxRecursionDepth
is the maximum recursion depth of shaders executed by this pipeline. -
layout
is the description of binding locations used by both the pipeline and descriptor sets used with the pipeline. -
basePipelineHandle
is a pipeline to derive from. -
basePipelineIndex
is an index into thepCreateInfos
parameter to use as a pipeline to derive from.
The parameters basePipelineHandle
and basePipelineIndex
are
described in more detail in Pipeline Derivatives.
If the pNext
chain includes a
VkPipelineCreateFlags2CreateInfoKHR structure,
VkPipelineCreateFlags2CreateInfoKHR::flags
from that structure
is used instead of flags
from this structure.
The VkRayTracingPipelineCreateInfoKHR
structure is defined as:
// Provided by VK_KHR_ray_tracing_pipeline
typedef struct VkRayTracingPipelineCreateInfoKHR {
VkStructureType sType;
const void* pNext;
VkPipelineCreateFlags flags;
uint32_t stageCount;
const VkPipelineShaderStageCreateInfo* pStages;
uint32_t groupCount;
const VkRayTracingShaderGroupCreateInfoKHR* pGroups;
uint32_t maxPipelineRayRecursionDepth;
const VkPipelineLibraryCreateInfoKHR* pLibraryInfo;
const VkRayTracingPipelineInterfaceCreateInfoKHR* pLibraryInterface;
const VkPipelineDynamicStateCreateInfo* pDynamicState;
VkPipelineLayout layout;
VkPipeline basePipelineHandle;
int32_t basePipelineIndex;
} VkRayTracingPipelineCreateInfoKHR;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
flags
is a bitmask of VkPipelineCreateFlagBits specifying how the pipeline will be generated. -
stageCount
is the number of entries in thepStages
array. -
pStages
is a pointer to an array ofstageCount
VkPipelineShaderStageCreateInfo structures describing the set of the shader stages to be included in the ray tracing pipeline. -
groupCount
is the number of entries in thepGroups
array. -
pGroups
is a pointer to an array ofgroupCount
VkRayTracingShaderGroupCreateInfoKHR structures describing the set of the shader stages to be included in each shader group in the ray tracing pipeline. -
maxPipelineRayRecursionDepth
is the maximum recursion depth of shaders executed by this pipeline. -
pLibraryInfo
is a pointer to a VkPipelineLibraryCreateInfoKHR structure defining pipeline libraries to include. -
pLibraryInterface
is a pointer to a VkRayTracingPipelineInterfaceCreateInfoKHR structure defining additional information when using pipeline libraries. -
pDynamicState
is a pointer to a VkPipelineDynamicStateCreateInfo structure, and is used to indicate which properties of the pipeline state object are dynamic and can be changed independently of the pipeline state. This can beNULL
, which means no state in the pipeline is considered dynamic. -
layout
is the description of binding locations used by both the pipeline and descriptor sets used with the pipeline. -
basePipelineHandle
is a pipeline to derive from. -
basePipelineIndex
is an index into thepCreateInfos
parameter to use as a pipeline to derive from.
The parameters basePipelineHandle
and basePipelineIndex
are
described in more detail in Pipeline Derivatives.
When VK_PIPELINE_CREATE_LIBRARY_BIT_KHR
is specified, this pipeline
defines a pipeline library which cannot be bound as a ray tracing
pipeline directly.
Instead, pipeline libraries define common shaders and shader groups which
can be included in future pipeline creation.
If pipeline libraries are included in pLibraryInfo
, shaders defined in
those libraries are treated as if they were defined as additional entries in
pStages
, appended in the order they appear in the pLibraries
array and in the pStages
array when those libraries were defined.
When referencing shader groups in order to obtain a shader group handle,
groups defined in those libraries are treated as if they were defined as
additional entries in pGroups
, appended in the order they appear in
the pLibraries
array and in the pGroups
array when those
libraries were defined.
The shaders these groups reference are set when the pipeline library is
created, referencing those specified in the pipeline library, not in the
pipeline that includes it.
The default stack size for a pipeline if
VK_DYNAMIC_STATE_RAY_TRACING_PIPELINE_STACK_SIZE_KHR
is not provided
is computed as described in Ray Tracing Pipeline Stack.
If the pNext
chain includes a
VkPipelineCreateFlags2CreateInfoKHR structure,
VkPipelineCreateFlags2CreateInfoKHR::flags
from that structure
is used instead of flags
from this structure.
The VkRayTracingShaderGroupCreateInfoNV
structure is defined as:
// Provided by VK_NV_ray_tracing
typedef struct VkRayTracingShaderGroupCreateInfoNV {
VkStructureType sType;
const void* pNext;
VkRayTracingShaderGroupTypeKHR type;
uint32_t generalShader;
uint32_t closestHitShader;
uint32_t anyHitShader;
uint32_t intersectionShader;
} VkRayTracingShaderGroupCreateInfoNV;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
type
is the type of hit group specified in this structure. -
generalShader
is the index of the ray generation, miss, or callable shader from VkRayTracingPipelineCreateInfoNV::pStages
in the group if the shader group hastype
ofVK_RAY_TRACING_SHADER_GROUP_TYPE_GENERAL_NV
, andVK_SHADER_UNUSED_NV
otherwise. -
closestHitShader
is the optional index of the closest hit shader from VkRayTracingPipelineCreateInfoNV::pStages
in the group if the shader group hastype
ofVK_RAY_TRACING_SHADER_GROUP_TYPE_TRIANGLES_HIT_GROUP_NV
orVK_RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_NV
, andVK_SHADER_UNUSED_NV
otherwise. -
anyHitShader
is the optional index of the any-hit shader from VkRayTracingPipelineCreateInfoNV::pStages
in the group if the shader group hastype
ofVK_RAY_TRACING_SHADER_GROUP_TYPE_TRIANGLES_HIT_GROUP_NV
orVK_RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_NV
, andVK_SHADER_UNUSED_NV
otherwise. -
intersectionShader
is the index of the intersection shader from VkRayTracingPipelineCreateInfoNV::pStages
in the group if the shader group hastype
ofVK_RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_NV
, andVK_SHADER_UNUSED_NV
otherwise.
The VkRayTracingShaderGroupCreateInfoKHR
structure is defined as:
// Provided by VK_KHR_ray_tracing_pipeline
typedef struct VkRayTracingShaderGroupCreateInfoKHR {
VkStructureType sType;
const void* pNext;
VkRayTracingShaderGroupTypeKHR type;
uint32_t generalShader;
uint32_t closestHitShader;
uint32_t anyHitShader;
uint32_t intersectionShader;
const void* pShaderGroupCaptureReplayHandle;
} VkRayTracingShaderGroupCreateInfoKHR;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
type
is the type of hit group specified in this structure. -
generalShader
is the index of the ray generation, miss, or callable shader from VkRayTracingPipelineCreateInfoKHR::pStages
in the group if the shader group hastype
ofVK_RAY_TRACING_SHADER_GROUP_TYPE_GENERAL_KHR
, andVK_SHADER_UNUSED_KHR
otherwise. -
closestHitShader
is the optional index of the closest hit shader from VkRayTracingPipelineCreateInfoKHR::pStages
in the group if the shader group hastype
ofVK_RAY_TRACING_SHADER_GROUP_TYPE_TRIANGLES_HIT_GROUP_KHR
orVK_RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_KHR
, andVK_SHADER_UNUSED_KHR
otherwise. -
anyHitShader
is the optional index of the any-hit shader from VkRayTracingPipelineCreateInfoKHR::pStages
in the group if the shader group hastype
ofVK_RAY_TRACING_SHADER_GROUP_TYPE_TRIANGLES_HIT_GROUP_KHR
orVK_RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_KHR
, andVK_SHADER_UNUSED_KHR
otherwise. -
intersectionShader
is the index of the intersection shader from VkRayTracingPipelineCreateInfoKHR::pStages
in the group if the shader group hastype
ofVK_RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_KHR
, andVK_SHADER_UNUSED_KHR
otherwise. -
pShaderGroupCaptureReplayHandle
isNULL
or a pointer to replay information for this shader group queried from vkGetRayTracingCaptureReplayShaderGroupHandlesKHR, as described in Ray Tracing Capture Replay. Ignored if VkPhysicalDeviceRayTracingPipelineFeaturesKHR::rayTracingPipelineShaderGroupHandleCaptureReplay
isVK_FALSE
.
If the pipeline is created with VK_PIPELINE_CREATE_LIBRARY_BIT_KHR
and
the pipelineLibraryGroupHandles
feature is enabled, pShaderGroupCaptureReplayHandle
is inherited by
all pipelines which link against this pipeline and remains bitwise identical
for any pipeline which references this pipeline library.
The VkRayTracingShaderGroupTypeKHR
enumeration is defined as:
// 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,
// Provided by VK_NV_ray_tracing
VK_RAY_TRACING_SHADER_GROUP_TYPE_GENERAL_NV = VK_RAY_TRACING_SHADER_GROUP_TYPE_GENERAL_KHR,
// Provided by VK_NV_ray_tracing
VK_RAY_TRACING_SHADER_GROUP_TYPE_TRIANGLES_HIT_GROUP_NV = VK_RAY_TRACING_SHADER_GROUP_TYPE_TRIANGLES_HIT_GROUP_KHR,
// Provided by VK_NV_ray_tracing
VK_RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_NV = VK_RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_KHR,
} VkRayTracingShaderGroupTypeKHR;
or the equivalent
// Provided by VK_NV_ray_tracing
typedef VkRayTracingShaderGroupTypeKHR VkRayTracingShaderGroupTypeNV;
-
VK_RAY_TRACING_SHADER_GROUP_TYPE_GENERAL_KHR
indicates a shader group with a singleVK_SHADER_STAGE_RAYGEN_BIT_KHR
,VK_SHADER_STAGE_MISS_BIT_KHR
, orVK_SHADER_STAGE_CALLABLE_BIT_KHR
shader in it. -
VK_RAY_TRACING_SHADER_GROUP_TYPE_TRIANGLES_HIT_GROUP_KHR
specifies a shader group that only hits triangles and must not contain an intersection shader, only closest hit and any-hit shaders. -
VK_RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_KHR
specifies a shader group that only intersects with custom geometry and must contain an intersection shader and may contain closest hit and any-hit shaders.
For current group types, the hit group type could be inferred from the presence or absence of the intersection shader, but we provide the type explicitly for future hit groups that do not have that property. |
The VkRayTracingPipelineInterfaceCreateInfoKHR
structure is defined
as:
// Provided by VK_KHR_ray_tracing_pipeline
typedef struct VkRayTracingPipelineInterfaceCreateInfoKHR {
VkStructureType sType;
const void* pNext;
uint32_t maxPipelineRayPayloadSize;
uint32_t maxPipelineRayHitAttributeSize;
} VkRayTracingPipelineInterfaceCreateInfoKHR;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
maxPipelineRayPayloadSize
is the maximum payload size in bytes used by any shader in the pipeline. -
maxPipelineRayHitAttributeSize
is the maximum attribute structure size in bytes used by any shader in the pipeline.
maxPipelineRayPayloadSize
is calculated as the maximum number of bytes
used by any block declared in the RayPayloadKHR
or
IncomingRayPayloadKHR
storage classes.
maxPipelineRayHitAttributeSize
is calculated as the maximum number of
bytes used by any block declared in the HitAttributeKHR
storage class.
As variables in these storage classes do not have explicit offsets, the size
should be calculated as if each variable has a
scalar alignment equal to the largest
scalar alignment of any of the block’s members.
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);
or the equivalent command
// Provided by VK_NV_ray_tracing
VkResult vkGetRayTracingShaderGroupHandlesNV(
VkDevice device,
VkPipeline pipeline,
uint32_t firstGroup,
uint32_t groupCount,
size_t dataSize,
void* pData);
-
device
is the logical device containing the ray tracing pipeline. -
pipeline
is the ray tracing pipeline object containing the shaders. -
firstGroup
is the index of the first group to retrieve a handle for from the VkRayTracingPipelineCreateInfoKHR::pGroups
or VkRayTracingPipelineCreateInfoNV::pGroups
array. -
groupCount
is the number of shader handles to retrieve. -
dataSize
is the size in bytes of the buffer pointed to bypData
. -
pData
is a pointer to an application-allocated buffer where the results will be written.
On success, an array of groupCount
shader handles will be written to
pData
, with each element being of size
VkPhysicalDeviceRayTracingPipelinePropertiesKHR::shaderGroupHandleSize
.
If pipeline
was created with VK_PIPELINE_CREATE_LIBRARY_BIT_KHR
and the pipelineLibraryGroupHandles
feature is enabled applications can query group handles from that pipeline,
even if the pipeline is a library and is never bound to a command buffer.
These group handles remain bitwise identical for any pipeline
which
references the pipeline library.
Group indices are assigned as-if the pipeline was created without
VK_PIPELINE_CREATE_LIBRARY_BIT_KHR
.
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);
-
device
is the logical device containing the ray tracing pipeline. -
pipeline
is the ray tracing pipeline object containing the shaders. -
firstGroup
is the index of the first group to retrieve a handle for from the VkRayTracingPipelineCreateInfoKHR::pGroups
array. -
groupCount
is the number of shader handles to retrieve. -
dataSize
is the size in bytes of the buffer pointed to bypData
. -
pData
is a pointer to an application-allocated buffer where the results will be written.
On success, an array of groupCount
shader handles will be written to
pData
, with each element being of size
VkPhysicalDeviceRayTracingPipelinePropertiesKHR::shaderGroupHandleCaptureReplaySize
.
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.
If pipeline
was created with VK_PIPELINE_CREATE_LIBRARY_BIT_KHR
and the pipelineLibraryGroupHandles
feature is enabled applications can query capture replay group handles from
that pipeline.
The capture replay handle remains bitwise identical for any pipeline
which references the pipeline library.
Group indices are assigned as-if the pipeline was created without
VK_PIPELINE_CREATE_LIBRARY_BIT_KHR
.
Ray tracing pipelines can contain more shaders than a graphics or compute pipeline, so to allow parallel compilation of shaders within a pipeline, an application can choose to defer compilation until a later point in time.
To compile a deferred shader in a pipeline call:
// Provided by VK_NV_ray_tracing
VkResult vkCompileDeferredNV(
VkDevice device,
VkPipeline pipeline,
uint32_t shader);
-
device
is the logical device containing the ray tracing pipeline. -
pipeline
is the ray tracing pipeline object containing the shaders. -
shader
is the index of the shader to compile.
To query the pipeline stack size of shaders in a shader group in the ray tracing pipeline, call:
// Provided by VK_KHR_ray_tracing_pipeline
VkDeviceSize vkGetRayTracingShaderGroupStackSizeKHR(
VkDevice device,
VkPipeline pipeline,
uint32_t group,
VkShaderGroupShaderKHR groupShader);
-
device
is the logical device containing the ray tracing pipeline. -
pipeline
is the ray tracing pipeline object containing the shaders groups. -
group
is the index of the shader group to query. -
groupShader
is the type of shader from the group to query.
The return value is the ray tracing pipeline stack size in bytes for the specified shader as called from the specified shader group.
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_KHR
uses the shader specified in the group with VkRayTracingShaderGroupCreateInfoKHR::generalShader
-
VK_SHADER_GROUP_SHADER_CLOSEST_HIT_KHR
uses the shader specified in the group with VkRayTracingShaderGroupCreateInfoKHR::closestHitShader
-
VK_SHADER_GROUP_SHADER_ANY_HIT_KHR
uses the shader specified in the group with VkRayTracingShaderGroupCreateInfoKHR::anyHitShader
-
VK_SHADER_GROUP_SHADER_INTERSECTION_KHR
uses 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);
-
commandBuffer
is the command buffer into which the command will be recorded. -
pipelineStackSize
is the stack size to use for subsequent ray tracing trace commands.
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.
Pipeline Destruction
To destroy a pipeline, call:
// Provided by VK_VERSION_1_0
void vkDestroyPipeline(
VkDevice device,
VkPipeline pipeline,
const VkAllocationCallbacks* pAllocator);
-
device
is the logical device that destroys the pipeline. -
pipeline
is the handle of the pipeline to destroy. -
pAllocator
controls host memory allocation as described in the Memory Allocation chapter.
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.
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)
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);
-
device
is the logical device that creates the pipeline cache object. -
pCreateInfo
is a pointer to a VkPipelineCacheCreateInfo structure containing initial parameters for the pipeline cache object. -
pAllocator
controls host memory allocation as described in the Memory Allocation chapter. -
pPipelineCache
is a pointer to a VkPipelineCache handle in which the resulting pipeline cache object is returned.
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, vkCreateRayTracingPipelinesNV, 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.
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;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
flags
is a bitmask of VkPipelineCacheCreateFlagBits specifying the behavior of the pipeline cache. -
initialDataSize
is the number of bytes inpInitialData
. IfinitialDataSize
is zero, the pipeline cache will initially be empty. -
pInitialData
is a pointer to previously retrieved pipeline cache data. If the pipeline cache data is incompatible (as defined below) with the device, the pipeline cache will be initially empty. IfinitialDataSize
is zero,pInitialData
is 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:
// Provided by VK_EXT_pipeline_creation_cache_control
typedef enum VkPipelineCacheCreateFlagBits {
// Provided by VK_VERSION_1_3
VK_PIPELINE_CACHE_CREATE_EXTERNALLY_SYNCHRONIZED_BIT = 0x00000001,
// Provided by VK_EXT_pipeline_creation_cache_control
VK_PIPELINE_CACHE_CREATE_EXTERNALLY_SYNCHRONIZED_BIT_EXT = VK_PIPELINE_CACHE_CREATE_EXTERNALLY_SYNCHRONIZED_BIT,
} VkPipelineCacheCreateFlagBits;
-
VK_PIPELINE_CACHE_CREATE_EXTERNALLY_SYNCHRONIZED_BIT
specifies 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.
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);
-
device
is the logical device that owns the pipeline cache objects. -
dstCache
is the handle of the pipeline cache to merge results into. -
srcCacheCount
is the length of thepSrcCaches
array. -
pSrcCaches
is a pointer to an array of pipeline cache handles, which will be merged intodstCache
. The previous contents ofdstCache
are included after the merge.
The details of the merge operation are implementation-dependent, but implementations should merge the contents of the specified pipelines and prune duplicate entries. |
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);
-
device
is the logical device that owns the pipeline cache. -
pipelineCache
is the pipeline cache to retrieve data from. -
pDataSize
is a pointer to asize_t
value related to the amount of data in the pipeline cache, as described below. -
pData
is eitherNULL
or a pointer to a buffer.
If pData
is NULL
, then the maximum size of the data that can be
retrieved from the pipeline cache, in bytes, is returned in pDataSize
.
Otherwise, pDataSize
must point to a variable set by the application
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
.
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.
Structures described in this section are not part of the Vulkan API and are only used to describe the representation of data elements in pipeline cache data. Accordingly, the valid usage clauses defined for structures defined in this section do not define valid usage conditions for APIs accepting pipeline cache data as input, as providing invalid pipeline cache data as input to any Vulkan API commands will result in the provided pipeline cache data being ignored. |
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;
-
headerSize
is the length in bytes of the pipeline cache header. -
headerVersion
is a VkPipelineCacheHeaderVersion 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. -
vendorID
is theVkPhysicalDeviceProperties
::vendorID
of the implementation. -
deviceID
is theVkPhysicalDeviceProperties
::deviceID
of the implementation. -
pipelineCacheUUID
is theVkPhysicalDeviceProperties
::pipelineCacheUUID
of 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_ONE
specifies version one of the pipeline cache, described by VkPipelineCacheHeaderVersionOne.
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);
-
device
is the logical device that destroys the pipeline cache object. -
pipelineCache
is the handle of the pipeline cache to destroy. -
pAllocator
controls host memory allocation as described in the Memory Allocation chapter.
Pipeline Binaries
Pipeline binary objects allow the result of pipeline construction to be
reused between pipelines and between runs of an application.
Reuse is achieved by extracting pipeline binaries from a VkPipeline
object, associating them with a corresponding VkPipelineBinaryKeyKHR
and then adding a VkPipelineBinaryInfoKHR to the pNext
chain of
any Vk*PipelineCreateInfo
when creating a pipeline.
Pipeline binaries can be reused between runs by extracting
VkPipelineBinaryDataKHR
from VkPipelineBinaryKHR
objects, saving
the contents, and then using them to create a VkPipelineBinaryKHR
object on subsequent runs.
When creating a pipeline that includes VkPipelineBinaryInfoKHR in the
pNext
chain, or has the
VK_PIPELINE_CREATE_2_CAPTURE_DATA_BIT_KHR
flag set, the use of
VkPipelineCache objects is not allowed.
Pipeline binary objects are represented by VkPipelineBinaryKHR
handles:
// Provided by VK_KHR_pipeline_binary
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkPipelineBinaryKHR)
Generating the Pipeline Key
To generate the key for a particular pipeline creation info, call:
// Provided by VK_KHR_pipeline_binary
VkResult vkGetPipelineKeyKHR(
VkDevice device,
const VkPipelineCreateInfoKHR* pPipelineCreateInfo,
VkPipelineBinaryKeyKHR* pPipelineKey);
-
device
is the logical device that creates the pipeline object. -
pPipelineCreateInfo
isNULL
or a pointer to a VkPipelineCreateInfoKHR structure. -
pPipelineKey
is a pointer to a VkPipelineBinaryKeyKHR structure in which the resulting key is returned.
If pPipelineCreateInfo
is NULL
, then the implementation must return
the global key that applies to all pipelines.
If the key obtained in this way changes between saving and restoring data
obtained from vkGetPipelineBinaryDataKHR in a different
VkDevice, then the application must assume that the restored data is
invalid and cannot be passed to vkCreatePipelineBinariesKHR.
Otherwise the application can assume the data is still valid.
If pPipelineCreateInfo
is not NULL
, the key obtained functions as a
method to compare two pipeline creation info structures.
Implementations may not compare parts of a pipeline creation info which
would not contribute to the final binary output.
If a shader module identifier is used instead of a shader module, the
pPipelineKey
generated must be equal to the key generated when using
the shader module from which the identifier was queried.
If the content of two pPipelineKey
are equal, pipelines created with
the two pPipelineCreateInfo->pname
:pNext create infos must produce
the same VkPipelineBinaryKHR contents.
The pipeline key is distinct from pipeline binary key. Pipeline binary keys can only be obtained after compilation. The pipeline key is intended to optionally allow associating pipeline create info with multiple pipeline binary keys.
The VkPipelineCreateInfoKHR
structure is defined as:
// Provided by VK_KHR_pipeline_binary
typedef struct VkPipelineCreateInfoKHR {
VkStructureType sType;
void* pNext;
} VkPipelineCreateInfoKHR;
-
sType
is a VkStructureType value identifying this structure. -
pNext
is a pointer to a structure extending this structure.
The VkPipelineBinaryKeyKHR
structure is defined as:
// Provided by VK_KHR_pipeline_binary
typedef struct VkPipelineBinaryKeyKHR {
VkStructureType sType;
void* pNext;
uint32_t keySize;
uint8_t key[VK_MAX_PIPELINE_BINARY_KEY_SIZE_KHR];
} VkPipelineBinaryKeyKHR;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
keySize
is the size, in bytes, of valid data returned inkey
. -
key
is a buffer of opaque data specifying a pipeline binary key.
Any returned values beyond the first keySize
bytes are undefined.
Implementations must return a keySize
greater than 0, and
less-or-equal to VK_MAX_PIPELINE_BINARY_KEY_SIZE_KHR
.
Two keys are considered equal if keySize
is equal and the first
keySize
bytes of key
compare equal.
Implementations may return a different keySize
for different
binaries.
Implementations should ensure that keySize
is large enough to
uniquely identify a pipeline binary.
VK_MAX_PIPELINE_BINARY_KEY_SIZE_KHR
is the length in bytes of a binary
key, as returned in VkPipelineBinaryKeyKHR::keySize
.
#define VK_MAX_PIPELINE_BINARY_KEY_SIZE_KHR 32U
Creating Pipeline Binaries
To create pipeline binary objects, call:
// Provided by VK_KHR_pipeline_binary
VkResult vkCreatePipelineBinariesKHR(
VkDevice device,
const VkPipelineBinaryCreateInfoKHR* pCreateInfo,
const VkAllocationCallbacks* pAllocator,
VkPipelineBinaryHandlesInfoKHR* pBinaries);
-
device
is the logical device that creates the pipeline binary objects. -
pCreateInfo
is a pointer to a VkPipelineBinaryCreateInfoKHR structure that contains the data to create the pipeline binaries from. -
pAllocator
controls host memory allocation as described in the Memory Allocation chapter. -
pBinaries
is a pointer to a VkPipelineBinaryHandlesInfoKHR structure in which the resulting pipeline binaries are returned.
The implementation will attempt to create all pipeline binaries. If creation fails for any pipeline binary, then:
-
The corresponding entry in the
pPipelineBinaries
output array will be filled with VK_NULL_HANDLE. -
The
VkResult
returned by vkCreatePipelineBinariesKHR will contain the error value for the first entry in the output array inpBinaries
containing VK_NULL_HANDLE.
The VkPipelineBinaryHandlesInfoKHR
structure is defined as:
// Provided by VK_KHR_pipeline_binary
typedef struct VkPipelineBinaryHandlesInfoKHR {
VkStructureType sType;
const void* pNext;
uint32_t pipelineBinaryCount;
VkPipelineBinaryKHR* pPipelineBinaries;
} VkPipelineBinaryHandlesInfoKHR;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
pipelineBinaryCount
is the number of binaries associated with this pipeline or the number of entries in thepPipelineBinaries
array. -
pPipelineBinaries
isNULL
or a pointer to an array of VkPipelineBinaryKHR handles in which the resulting pipeline binaries are returned.
If pPipelineBinaries
is NULL
, the number of binaries that would be
created is returned in pipelineBinaryCount
.
Otherwise, pipelineBinaryCount
must be the number of entries in the
pPipelineBinaries
array, and on return from
vkCreatePipelineBinariesKHR pipelineBinaryCount
is overwritten
with the number of handles actually written to pPipelineBinaries
.
If the value of pipelineBinaryCount
is less than the number of
binaries that would have been created, at most pipelineBinaryCount
handles will be written to pPipelineBinaries
and VK_INCOMPLETE
will be returned instead of VK_SUCCESS
, to indicate that
pPipelineBinaries
was not large enough to create all the binaries.
The VkPipelineBinaryCreateInfoKHR
structure is defined as:
// Provided by VK_KHR_pipeline_binary
typedef struct VkPipelineBinaryCreateInfoKHR {
VkStructureType sType;
const void* pNext;
const VkPipelineBinaryKeysAndDataKHR* pKeysAndDataInfo;
VkPipeline pipeline;
const VkPipelineCreateInfoKHR* pPipelineCreateInfo;
} VkPipelineBinaryCreateInfoKHR;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
pKeysAndDataInfo
isNULL
or a pointer to a VkPipelineBinaryKeysAndDataKHR structure that contains keys and data to create the pipeline binaries from. -
pipeline
is VK_NULL_HANDLE or aVkPipeline
that contains data to create the pipeline binaries from. -
pPipelineCreateInfo
isNULL
or a pointer to a VkPipelineCreateInfoKHR structure with the pipeline creation info. This is used to probe the implementation’s internal cache for pipeline binaries.
When pPipelineCreateInfo
is not NULL
, an implementation will attempt
to retrieve pipeline binary data from an internal cache external to the
application if
pipelineBinaryInternalCache
is
VK_TRUE
.
Applications can use this to determine if a pipeline can be created
without compilation.
If the implementation fails to create a pipeline binary due to missing an
internal cache entry, VK_PIPELINE_BINARY_MISSING_KHR
is returned.
If creation succeeds, the resulting binary can be used to create a
pipeline.
VK_PIPELINE_BINARY_MISSING_KHR
may be returned for any reason in this
situation, even if creating a pipeline binary with the same parameters that
succeeded earlier.
If
pipelineBinaryPrecompiledInternalCache
is VK_TRUE
, the implementation may be able to create pipeline
binaries even when pPipelineCreateInfo
has not been used to create
binaries before by the application.
On some platforms, internal pipeline caches may be pre-populated before running the application. |
The VkPipelineBinaryKeysAndDataKHR
structure is defined as:
// Provided by VK_KHR_pipeline_binary
typedef struct VkPipelineBinaryKeysAndDataKHR {
uint32_t binaryCount;
const VkPipelineBinaryKeyKHR* pPipelineBinaryKeys;
const VkPipelineBinaryDataKHR* pPipelineBinaryData;
} VkPipelineBinaryKeysAndDataKHR;
-
binaryCount
is the size of thepPipelineBinaryKeys
andpPipelineBinaryData
arrays -
pPipelineBinaryKeys
is a pointer to an array of VkPipelineBinaryKeyKHR structures containing the pipeline binary keys -
pPipelineBinaryData
is a pointer to an array of VkPipelineBinaryDataKHR structures containing the pipeline binary data
The VkPipelineBinaryDataKHR
structure is defined as:
// Provided by VK_KHR_pipeline_binary
typedef struct VkPipelineBinaryDataKHR {
size_t dataSize;
void* pData;
} VkPipelineBinaryDataKHR;
-
dataSize
is the size of thepData
buffer in bytes. -
pData
is a pointer to a buffer ofsize
bytes that contains pipeline binary data obtained fromvkGetPipelineBinaryDataKHR
.
Retrieving Pipeline Binary Data
Data can be retrieved from a pipeline binary object using the command:
// Provided by VK_KHR_pipeline_binary
VkResult vkGetPipelineBinaryDataKHR(
VkDevice device,
const VkPipelineBinaryDataInfoKHR* pInfo,
VkPipelineBinaryKeyKHR* pPipelineBinaryKey,
size_t* pPipelineBinaryDataSize,
void* pPipelineBinaryData);
-
device
is the logical device that created the pipeline binary. -
pInfo
is a pointer to a VkPipelineBinaryDataInfoKHR structure which describes the pipeline binary to get data from. -
pPipelineBinaryKey
is a pointer to a VkPipelineBinaryKeyKHR structure where the key for this binary will be written. -
pPipelineBinaryDataSize
is a pointer to asize_t
value related to the amount of data in the pipeline binary, as described below. -
pPipelineBinaryData
is eitherNULL
or a pointer to a buffer.
If pPipelineBinaryData
is NULL
, then the size of the data, in bytes,
that is required to store the binary is returned in
pPipelineBinaryDataSize
.
Otherwise, pPipelineBinaryDataSize
must contain the size of the
buffer, in bytes, pointed to by pPipelineBinaryData
, and on return
pPipelineBinaryDataSize
is overwritten with the size of the data, in
bytes, that is required to store the binary.
If pPipelineBinaryDataSize
is less than the size that is required to
store the binary, nothing is written to pPipelineBinaryData
and
VK_ERROR_NOT_ENOUGH_SPACE_KHR
will be returned, instead of
VK_SUCCESS
.
If pipelineBinaryCompressedData is
VK_FALSE
, implementations should not return compressed pipeline
binary data to the application.
The VkPipelineBinaryDataInfoKHR
structure is defined as:
// Provided by VK_KHR_pipeline_binary
typedef struct VkPipelineBinaryDataInfoKHR {
VkStructureType sType;
void* pNext;
VkPipelineBinaryKHR pipelineBinary;
} VkPipelineBinaryDataInfoKHR;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
pipelineBinary
is the pipeline binary to get data from.
Releasing Captured Pipeline Binary Data
To release pipeline resources captured with
VK_PIPELINE_CREATE_2_CAPTURE_DATA_BIT_KHR
, call:
// Provided by VK_KHR_pipeline_binary
VkResult vkReleaseCapturedPipelineDataKHR(
VkDevice device,
const VkReleaseCapturedPipelineDataInfoKHR* pInfo,
const VkAllocationCallbacks* pAllocator);
-
device
is the logical device that created the pipeline object. -
pInfo
is a pointer to a VkReleaseCapturedPipelineDataInfoKHR structure which describes the pipeline to release the data from. -
pAllocator
controls host memory allocation as described in the Memory Allocation chapter.
The implementation may free any resources captured as a result of creating
the pipeline with VK_PIPELINE_CREATE_2_CAPTURE_DATA_BIT_KHR
and put
the pipeline into a state as if
VK_PIPELINE_CREATE_2_CAPTURE_DATA_BIT_KHR
had not been provided at
pipeline creation time.
Any resources captured as a result of creating the pipeline with
|
The VkReleaseCapturedPipelineDataInfoKHR
structure is defined as:
// Provided by VK_KHR_pipeline_binary
typedef struct VkReleaseCapturedPipelineDataInfoKHR {
VkStructureType sType;
void* pNext;
VkPipeline pipeline;
} VkReleaseCapturedPipelineDataInfoKHR;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
pipeline
the handle of the pipeline object to release the data from.
Destroying Pipeline Binaries
To destroy a VkPipelineBinaryKHR, call:
// Provided by VK_KHR_pipeline_binary
void vkDestroyPipelineBinaryKHR(
VkDevice device,
VkPipelineBinaryKHR pipelineBinary,
const VkAllocationCallbacks* pAllocator);
-
device
is the logical device that created the pipeline binary object. -
pipelineBinary
is the handle of the pipeline binary object to destroy. -
pAllocator
controls host memory allocation as described in the Memory Allocation chapter.
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.
Specialization constants are useful to allow a compute shader to have its local workgroup size changed at runtime by the user, for example. |
Each VkPipelineShaderStageCreateInfo structure contains a
pSpecializationInfo
member, which can be NULL
to indicate no
specialization constants, or point to a VkSpecializationInfo
structure.
The VkSpecializationInfo
structure is defined as:
// Provided by VK_VERSION_1_0
typedef struct VkSpecializationInfo {
uint32_t mapEntryCount;
const VkSpecializationMapEntry* pMapEntries;
size_t dataSize;
const void* pData;
} VkSpecializationInfo;
-
mapEntryCount
is the number of entries in thepMapEntries
array. -
pMapEntries
is a pointer to an array ofVkSpecializationMapEntry
structures, which map constant IDs to offsets inpData
. -
dataSize
is the byte size of thepData
buffer. -
pData
contains 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;
-
constantID
is the ID of the specialization constant in SPIR-V. -
offset
is the byte offset of the specialization constant value within the supplied data buffer. -
size
is the byte size of the specialization constant value within the supplied data buffer.
If a constantID
value is not a specialization constant ID used in the
shader, that map entry does not affect the behavior of the pipeline.
In human readable SPIR-V:
OpDecorate %x SpecId 13 ; decorate .x component of WorkgroupSize with ID 13
OpDecorate %y SpecId 42 ; decorate .y component of WorkgroupSize with ID 42
OpDecorate %z SpecId 3 ; decorate .z component of WorkgroupSize with ID 3
OpDecorate %wgsize BuiltIn WorkgroupSize ; decorate WorkgroupSize onto constant
%i32 = OpTypeInt 32 0 ; declare an unsigned 32-bit type
%uvec3 = OpTypeVector %i32 3 ; declare a 3 element vector type of unsigned 32-bit
%x = OpSpecConstant %i32 1 ; declare the .x component of WorkgroupSize
%y = OpSpecConstant %i32 1 ; declare the .y component of WorkgroupSize
%z = OpSpecConstant %i32 1 ; declare the .z component of WorkgroupSize
%wgsize = OpSpecConstantComposite %uvec3 %x %y %z ; declare WorkgroupSize
From the above we have three specialization constants, one for each of the x, y & z elements of the WorkgroupSize vector.
Now to specialize the above via the specialization constants mechanism:
const VkSpecializationMapEntry entries[] =
{
{
.constantID = 13,
.offset = 0 * sizeof(uint32_t),
.size = sizeof(uint32_t)
},
{
.constantID = 42,
.offset = 1 * sizeof(uint32_t),
.size = sizeof(uint32_t)
},
{
.constantID = 3,
.offset = 2 * sizeof(uint32_t),
.size = sizeof(uint32_t)
}
};
const uint32_t data[] = { 16, 8, 4 }; // our workgroup size is 16x8x4
const VkSpecializationInfo info =
{
.mapEntryCount = 3,
.pMapEntries = entries,
.dataSize = 3 * sizeof(uint32_t),
.pData = data,
};
Then when calling vkCreateComputePipelines, and passing the
VkSpecializationInfo
we defined as the pSpecializationInfo
parameter of VkPipelineShaderStageCreateInfo, we will create a compute
pipeline with the runtime specified local workgroup size.
Another example would be that an application has a SPIR-V module that has some platform-dependent constants they wish to use.
In human readable SPIR-V:
OpDecorate %1 SpecId 0 ; decorate our signed 32-bit integer constant
OpDecorate %2 SpecId 12 ; decorate our 32-bit floating-point constant
%i32 = OpTypeInt 32 1 ; declare a signed 32-bit type
%float = OpTypeFloat 32 ; declare a 32-bit floating-point type
%1 = OpSpecConstant %i32 -1 ; some signed 32-bit integer constant
%2 = OpSpecConstant %float 0.5 ; some 32-bit floating-point constant
From the above we have two specialization constants, one is a signed 32-bit integer and the second is a 32-bit floating-point value.
Now to specialize the above via the specialization constants mechanism:
struct SpecializationData {
int32_t data0;
float data1;
};
const VkSpecializationMapEntry entries[] =
{
{
.constantID = 0,
.offset = offsetof(SpecializationData, data0),
.size = sizeof(SpecializationData::data0)
},
{
.constantID = 12,
.offset = offsetof(SpecializationData, data1),
.size = sizeof(SpecializationData::data1)
}
};
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 =
{
.mapEntryCount = 2,
.pMapEntries = entries,
.dataSize = sizeof(data),
.pdata = &data,
};
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.
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.
For graphics pipelines this includes distinct library types defined by
VkGraphicsPipelineLibraryFlagBitsEXT.
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;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
libraryCount
is the number of pipeline libraries inpLibraries
. -
pLibraries
is 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.
Pipeline Binding
Once a pipeline has been created, it can be bound to the command buffer using the command:
// Provided by VK_VERSION_1_0
void vkCmdBindPipeline(
VkCommandBuffer commandBuffer,
VkPipelineBindPoint pipelineBindPoint,
VkPipeline pipeline);
-
commandBuffer
is the command buffer that the pipeline will be bound to. -
pipelineBindPoint
is a VkPipelineBindPoint value specifying to which bind point the pipeline is bound. Binding one does not disturb the others. -
pipeline
is the pipeline to be bound.
Once bound, a pipeline binding affects subsequent commands that interact with the given pipeline type in the command buffer until a different pipeline of the same type is bound to the bind point, or until the pipeline bind point is disturbed by binding a shader object as described in Interaction with Pipelines. 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,
#ifdef VK_ENABLE_BETA_EXTENSIONS
// Provided by VK_AMDX_shader_enqueue
VK_PIPELINE_BIND_POINT_EXECUTION_GRAPH_AMDX = 1000134000,
#endif
// Provided by VK_KHR_ray_tracing_pipeline
VK_PIPELINE_BIND_POINT_RAY_TRACING_KHR = 1000165000,
// Provided by VK_HUAWEI_subpass_shading
VK_PIPELINE_BIND_POINT_SUBPASS_SHADING_HUAWEI = 1000369003,
// Provided by VK_NV_ray_tracing
VK_PIPELINE_BIND_POINT_RAY_TRACING_NV = VK_PIPELINE_BIND_POINT_RAY_TRACING_KHR,
} VkPipelineBindPoint;
-
VK_PIPELINE_BIND_POINT_COMPUTE
specifies binding as a compute pipeline. -
VK_PIPELINE_BIND_POINT_GRAPHICS
specifies binding as a graphics pipeline. -
VK_PIPELINE_BIND_POINT_RAY_TRACING_KHR
specifies binding as a ray tracing pipeline. -
VK_PIPELINE_BIND_POINT_SUBPASS_SHADING_HUAWEI
specifies binding as a subpass shading pipeline. -
VK_PIPELINE_BIND_POINT_EXECUTION_GRAPH_AMDX
specifies binding as an execution graph pipeline.
For pipelines that were created with the support of multiple shader groups
(see Graphics Pipeline Shader Groups), the regular
vkCmdBindPipeline
command will bind Shader Group 0
.
To explicitly bind a shader group use:
// Provided by VK_NV_device_generated_commands
void vkCmdBindPipelineShaderGroupNV(
VkCommandBuffer commandBuffer,
VkPipelineBindPoint pipelineBindPoint,
VkPipeline pipeline,
uint32_t groupIndex);
-
commandBuffer
is the command buffer that the pipeline will be bound to. -
pipelineBindPoint
is a VkPipelineBindPoint value specifying the bind point to which the pipeline will be bound. -
pipeline
is the pipeline to be bound. -
groupIndex
is the shader group to be bound.
Interaction With Shader Objects
If the shaderObject
feature is enabled,
applications can use both pipelines and shader objects
at the same time.
The interaction between pipelines and shader objects is described in
Interaction with Pipelines.
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 binding a pipeline in which that state is statically specified.
If the commandBufferInheritance
feature is enabled, all valid state from the previously executed command
buffer in the queue is inherited into the next command buffer executed in
the same queue.
This inherited state does not need to be set again before draw or dispatch
commands.
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
NULL
or was ignored) in the new pipeline object, then that command buffer state is not disturbed. For example, mesh shading pipelines do not include vertex input state and therefore do not disturb any such command buffer state.
Dynamic state that does not affect the result of operations can be left undefined.
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. |
Applications running on Vulkan implementations advertising an
VkPhysicalDeviceDriverProperties:: |
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);
-
device
is the device that created the pipeline. -
pPipelineInfo
describes the pipeline being queried. -
pExecutableCount
is a pointer to an integer related to the number of pipeline executables available or queried, as described below. -
pProperties
is eitherNULL
or a pointer to an array of VkPipelineExecutablePropertiesKHR structures.
If pProperties
is NULL
, then the number of pipeline executables
associated with the pipeline is returned in pExecutableCount
.
Otherwise, pExecutableCount
must point to a variable set by the
application 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;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
stages
is a bitmask of zero or more VkShaderStageFlagBits indicating which shader stages (if any) were principally used as inputs to compile this pipeline executable. -
name
is an array ofVK_MAX_DESCRIPTION_SIZE
char
containing a null-terminated UTF-8 string which is a short human readable name for this pipeline executable. -
description
is an array ofVK_MAX_DESCRIPTION_SIZE
char
containing a null-terminated UTF-8 string which is a human readable description for this pipeline executable. -
subgroupSize
is the subgroup size with which this pipeline executable is dispatched.
Not all implementations have a 1:1 mapping between shader stages and
pipeline executables and some implementations may reduce a given shader
stage to fixed function hardware programming such that no pipeline
executable is available.
No guarantees are provided about the mapping between shader stages and
pipeline executables and stages
should be considered a best effort
hint.
Because the application cannot rely on the stages
field to provide an
exact description, name
and description
provide a human readable
name and description which more accurately describes the given pipeline
executable.
To query the pipeline properties call:
// Provided by VK_EXT_pipeline_properties
VkResult vkGetPipelinePropertiesEXT(
VkDevice device,
const VkPipelineInfoEXT* pPipelineInfo,
VkBaseOutStructure* pPipelineProperties);
-
device
is the logical device that created the pipeline. -
pPipelineInfo
is a pointer to a VkPipelineInfoEXT structure which describes the pipeline being queried. -
pPipelineProperties
is a pointer to a VkBaseOutStructure structure in which the pipeline properties will be written.
To query a pipeline’s pipelineIdentifier
pass a
VkPipelinePropertiesIdentifierEXT structure in
pPipelineProperties
.
Each pipeline is associated with a pipelineIdentifier
and the
identifier is implementation specific.
The VkPipelinePropertiesIdentifierEXT
structure is defined as:
// Provided by VK_EXT_pipeline_properties
typedef struct VkPipelinePropertiesIdentifierEXT {
VkStructureType sType;
void* pNext;
uint8_t pipelineIdentifier[VK_UUID_SIZE];
} VkPipelinePropertiesIdentifierEXT;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
pipelineIdentifier
is an array ofVK_UUID_SIZE
uint8_t
values into which the pipeline identifier will be written.
The VkPipelineInfoKHR
structure is defined as:
// Provided by VK_KHR_pipeline_executable_properties
typedef struct VkPipelineInfoKHR {
VkStructureType sType;
const void* pNext;
VkPipeline pipeline;
} VkPipelineInfoKHR;
or the equivalent
// Provided by VK_EXT_pipeline_properties
typedef VkPipelineInfoKHR VkPipelineInfoEXT;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
pipeline
is aVkPipeline
handle.
Each pipeline executable may have a set of statistics associated with it that are generated by the pipeline compilation process. These statistics may include things such as instruction counts, amount of spilling (if any), maximum number of simultaneous threads, or anything else which may aid developers in evaluating the expected performance of a shader. To query the compile time statistics associated with a pipeline executable, call:
// Provided by VK_KHR_pipeline_executable_properties
VkResult vkGetPipelineExecutableStatisticsKHR(
VkDevice device,
const VkPipelineExecutableInfoKHR* pExecutableInfo,
uint32_t* pStatisticCount,
VkPipelineExecutableStatisticKHR* pStatistics);
-
device
is the device that created the pipeline. -
pExecutableInfo
describes the pipeline executable being queried. -
pStatisticCount
is a pointer to an integer related to the number of statistics available or queried, as described below. -
pStatistics
is eitherNULL
or a pointer to an array of VkPipelineExecutableStatisticKHR structures.
If pStatistics
is NULL
, then the number of statistics associated
with the pipeline executable is returned in pStatisticCount
.
Otherwise, pStatisticCount
must point to a variable set by the
application 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;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
pipeline
is the pipeline to query. -
executableIndex
is the index of the pipeline executable to query in the array of executable properties returned by vkGetPipelineExecutablePropertiesKHR.
The VkPipelineExecutableStatisticKHR
structure is defined as:
// Provided by VK_KHR_pipeline_executable_properties
typedef struct VkPipelineExecutableStatisticKHR {
VkStructureType sType;
void* pNext;
char name[VK_MAX_DESCRIPTION_SIZE];
char description[VK_MAX_DESCRIPTION_SIZE];
VkPipelineExecutableStatisticFormatKHR format;
VkPipelineExecutableStatisticValueKHR value;
} VkPipelineExecutableStatisticKHR;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
name
is an array ofVK_MAX_DESCRIPTION_SIZE
char
containing a null-terminated UTF-8 string which is a short human readable name for this statistic. -
description
is an array ofVK_MAX_DESCRIPTION_SIZE
char
containing a null-terminated UTF-8 string which is a human readable description for this statistic. -
format
is a VkPipelineExecutableStatisticFormatKHR value specifying the format of the data found invalue
. -
value
is 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_KHR
specifies that the statistic is returned as a 32-bit boolean value which must be eitherVK_TRUE
orVK_FALSE
and should be read from theb32
field ofVkPipelineExecutableStatisticValueKHR
. -
VK_PIPELINE_EXECUTABLE_STATISTIC_FORMAT_INT64_KHR
specifies that the statistic is returned as a signed 64-bit integer and should be read from thei64
field ofVkPipelineExecutableStatisticValueKHR
. -
VK_PIPELINE_EXECUTABLE_STATISTIC_FORMAT_UINT64_KHR
specifies that the statistic is returned as an unsigned 64-bit integer and should be read from theu64
field ofVkPipelineExecutableStatisticValueKHR
. -
VK_PIPELINE_EXECUTABLE_STATISTIC_FORMAT_FLOAT64_KHR
specifies that the statistic is returned as a 64-bit floating-point value and should be read from thef64
field 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;
-
b32
is the 32-bit boolean value if theVkPipelineExecutableStatisticFormatKHR
isVK_PIPELINE_EXECUTABLE_STATISTIC_FORMAT_BOOL32_KHR
. -
i64
is the signed 64-bit integer value if theVkPipelineExecutableStatisticFormatKHR
isVK_PIPELINE_EXECUTABLE_STATISTIC_FORMAT_INT64_KHR
. -
u64
is the unsigned 64-bit integer value if theVkPipelineExecutableStatisticFormatKHR
isVK_PIPELINE_EXECUTABLE_STATISTIC_FORMAT_UINT64_KHR
. -
f64
is the 64-bit floating-point value if theVkPipelineExecutableStatisticFormatKHR
isVK_PIPELINE_EXECUTABLE_STATISTIC_FORMAT_FLOAT64_KHR
.
Each pipeline executable may have one or more text or binary internal representations associated with it which are generated as part of the compile process. These may include the final shader assembly, a binary form of the compiled shader, or the shader compiler’s internal representation at any number of intermediate compile steps. To query the internal representations associated with a pipeline executable, call:
// Provided by VK_KHR_pipeline_executable_properties
VkResult vkGetPipelineExecutableInternalRepresentationsKHR(
VkDevice device,
const VkPipelineExecutableInfoKHR* pExecutableInfo,
uint32_t* pInternalRepresentationCount,
VkPipelineExecutableInternalRepresentationKHR* pInternalRepresentations);
-
device
is the device that created the pipeline. -
pExecutableInfo
describes the pipeline executable being queried. -
pInternalRepresentationCount
is a pointer to an integer related to the number of internal representations available or queried, as described below. -
pInternalRepresentations
is eitherNULL
or a pointer to an array of VkPipelineExecutableInternalRepresentationKHR structures.
If pInternalRepresentations
is NULL
, then the number of internal
representations associated with the pipeline executable is returned in
pInternalRepresentationCount
.
Otherwise, pInternalRepresentationCount
must point to a variable set
by the application 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;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
name
is an array ofVK_MAX_DESCRIPTION_SIZE
char
containing a null-terminated UTF-8 string which is a short human readable name for this internal representation. -
description
is an array ofVK_MAX_DESCRIPTION_SIZE
char
containing a null-terminated UTF-8 string which is a human readable description for this internal representation. -
isText
specifies whether the returned data is text or opaque data. IfisText
isVK_TRUE
then the data returned inpData
is text and is guaranteed to be a null-terminated UTF-8 string. -
dataSize
is an integer related to the size, in bytes, of the internal representation’s data, as described below. -
pData
is eitherNULL
or a pointer to a block of data into which the implementation will write the internal representation.
If pData
is NULL
, then the size, in bytes, of the internal
representation data is returned in dataSize
.
Otherwise, dataSize
must be the size of the buffer, in bytes, pointed
to by pData
and on return dataSize
is overwritten with the
number of bytes of data actually written to pData
including any
trailing null character.
If dataSize
is less than the size, in bytes, of the internal
representation’s data, at most dataSize
bytes of data will be written
to pData
, and VK_INCOMPLETE
will be returned instead of
VK_SUCCESS
, to indicate that not all the available representation was
returned.
If isText
is VK_TRUE
and pData
is not NULL
and
dataSize
is not zero, the last byte written to pData
will be a
null character.
Information about a particular shader that has been compiled as part of a pipeline object can be extracted by calling:
// Provided by VK_AMD_shader_info
VkResult vkGetShaderInfoAMD(
VkDevice device,
VkPipeline pipeline,
VkShaderStageFlagBits shaderStage,
VkShaderInfoTypeAMD infoType,
size_t* pInfoSize,
void* pInfo);
-
device
is the device that createdpipeline
. -
pipeline
is the target of the query. -
shaderStage
is a VkShaderStageFlagBits specifying the particular shader within the pipeline about which information is being queried. -
infoType
describes what kind of information is being queried. -
pInfoSize
is a pointer to a value related to the amount of data the query returns, as described below. -
pInfo
is eitherNULL
or a pointer to a buffer.
If pInfo
is NULL
, then the maximum size of the information that can
be retrieved about the shader, in bytes, is returned in pInfoSize
.
Otherwise, pInfoSize
must point to a variable set by the application
to the size of the buffer, in bytes, pointed to by pInfo
, and on
return the variable is overwritten with the amount of data actually written
to pInfo
.
If pInfoSize
is less than the maximum size that can be retrieved by
the pipeline cache, then at most pInfoSize
bytes will be written to
pInfo
, and VK_INCOMPLETE
will be returned, instead of
VK_SUCCESS
, to indicate that not all required of the pipeline cache
was returned.
Not all information is available for every shader and implementations may
not support all kinds of information for any shader.
When a certain type of information is unavailable, the function returns
VK_ERROR_FEATURE_NOT_PRESENT
.
If information is successfully and fully queried, the function will return
VK_SUCCESS
.
For infoType
VK_SHADER_INFO_TYPE_STATISTICS_AMD
, a
VkShaderStatisticsInfoAMD
structure will be written to the buffer
pointed to by pInfo
.
This structure will be populated with statistics regarding the physical
device resources used by that shader along with other miscellaneous
information and is described in further detail below.
For infoType
VK_SHADER_INFO_TYPE_DISASSEMBLY_AMD
, pInfo
is
a pointer to a null-terminated UTF-8 string containing human-readable
disassembly.
The exact formatting and contents of the disassembly string are
vendor-specific.
The formatting and contents of all other types of information, including
infoType
VK_SHADER_INFO_TYPE_BINARY_AMD
, are left to the vendor
and are not further specified by this extension.
Possible values of vkGetShaderInfoAMD::infoType
, specifying the
information being queried from a shader, are:
// Provided by VK_AMD_shader_info
typedef enum VkShaderInfoTypeAMD {
VK_SHADER_INFO_TYPE_STATISTICS_AMD = 0,
VK_SHADER_INFO_TYPE_BINARY_AMD = 1,
VK_SHADER_INFO_TYPE_DISASSEMBLY_AMD = 2,
} VkShaderInfoTypeAMD;
-
VK_SHADER_INFO_TYPE_STATISTICS_AMD
specifies that device resources used by a shader will be queried. -
VK_SHADER_INFO_TYPE_BINARY_AMD
specifies that implementation-specific information will be queried. -
VK_SHADER_INFO_TYPE_DISASSEMBLY_AMD
specifies that human-readable disassembly of a shader.
The VkShaderStatisticsInfoAMD
structure is defined as:
// Provided by VK_AMD_shader_info
typedef struct VkShaderStatisticsInfoAMD {
VkShaderStageFlags shaderStageMask;
VkShaderResourceUsageAMD resourceUsage;
uint32_t numPhysicalVgprs;
uint32_t numPhysicalSgprs;
uint32_t numAvailableVgprs;
uint32_t numAvailableSgprs;
uint32_t computeWorkGroupSize[3];
} VkShaderStatisticsInfoAMD;
-
shaderStageMask
are the combination of logical shader stages contained within this shader. -
resourceUsage
is a VkShaderResourceUsageAMD structure describing internal physical device resources used by this shader. -
numPhysicalVgprs
is the maximum number of vector instruction general-purpose registers (VGPRs) available to the physical device. -
numPhysicalSgprs
is the maximum number of scalar instruction general-purpose registers (SGPRs) available to the physical device. -
numAvailableVgprs
is the maximum limit of VGPRs made available to the shader compiler. -
numAvailableSgprs
is the maximum limit of SGPRs made available to the shader compiler. -
computeWorkGroupSize
is the local workgroup size of this shader in { X, Y, Z } dimensions.
Some implementations may merge multiple logical shader stages together in a
single shader.
In such cases, shaderStageMask
will contain a bitmask of all of the
stages that are active within that shader.
Consequently, if specifying those stages as input to
vkGetShaderInfoAMD, the same output information may be returned for
all such shader stage queries.
The number of available VGPRs and SGPRs (numAvailableVgprs
and
numAvailableSgprs
respectively) are the shader-addressable subset of
physical registers that is given as a limit to the compiler for register
assignment.
These values may further be limited by implementations due to performance
optimizations where register pressure is a bottleneck.
The VkShaderResourceUsageAMD
structure is defined as:
// Provided by VK_AMD_shader_info
typedef struct VkShaderResourceUsageAMD {
uint32_t numUsedVgprs;
uint32_t numUsedSgprs;
uint32_t ldsSizePerLocalWorkGroup;
size_t ldsUsageSizeInBytes;
size_t scratchMemUsageInBytes;
} VkShaderResourceUsageAMD;
-
numUsedVgprs
is the number of vector instruction general-purpose registers used by this shader. -
numUsedSgprs
is the number of scalar instruction general-purpose registers used by this shader. -
ldsSizePerLocalWorkGroup
is the maximum local data store size per work group in bytes. -
ldsUsageSizeInBytes
is the LDS usage size in bytes per work group by this shader. -
scratchMemUsageInBytes
is the scratch memory usage in bytes by this shader.
Pipeline Compiler Control
The compilation of a pipeline can be tuned by adding a
VkPipelineCompilerControlCreateInfoAMD
structure to the pNext
chain of VkGraphicsPipelineCreateInfo or
VkComputePipelineCreateInfo.
// Provided by VK_AMD_pipeline_compiler_control
typedef struct VkPipelineCompilerControlCreateInfoAMD {
VkStructureType sType;
const void* pNext;
VkPipelineCompilerControlFlagsAMD compilerControlFlags;
} VkPipelineCompilerControlCreateInfoAMD;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
compilerControlFlags
is a bitmask of VkPipelineCompilerControlFlagBitsAMD affecting how the pipeline will be compiled.
There are currently no available flags for this extension; flags will be added by future versions of this extension.
// Provided by VK_AMD_pipeline_compiler_control
typedef enum VkPipelineCompilerControlFlagBitsAMD {
} VkPipelineCompilerControlFlagBitsAMD;
// Provided by VK_AMD_pipeline_compiler_control
typedef VkFlags VkPipelineCompilerControlFlagsAMD;
VkPipelineCompilerControlFlagsAMD
is a bitmask type for setting a mask
of zero or more VkPipelineCompilerControlFlagBitsAMD.
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,
VkRayTracingPipelineCreateInfoNV,
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;
or the equivalent
// Provided by VK_EXT_pipeline_creation_feedback
typedef VkPipelineCreationFeedbackCreateInfo VkPipelineCreationFeedbackCreateInfoEXT;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
pPipelineCreationFeedback
is a pointer to a VkPipelineCreationFeedback structure. -
pipelineStageCreationFeedbackCount
is the number of elements inpPipelineStageCreationFeedbacks
. -
pPipelineStageCreationFeedbacks
is a pointer to an array ofpipelineStageCreationFeedbackCount
VkPipelineCreationFeedback 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
.
One common scenario for an implementation to skip per-stage feedback is when
|
When chained to
VkRayTracingPipelineCreateInfoKHR,
VkRayTracingPipelineCreateInfoNV,
or
VkGraphicsPipelineCreateInfo, the i
element of
pPipelineStageCreationFeedbacks
corresponds to the i
element of
VkRayTracingPipelineCreateInfoKHR::pStages
,
VkRayTracingPipelineCreateInfoNV::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;
or the equivalent
// Provided by VK_EXT_pipeline_creation_feedback
typedef VkPipelineCreationFeedback VkPipelineCreationFeedbackEXT;
-
flags
is a bitmask of VkPipelineCreationFeedbackFlagBits providing feedback about the creation of a pipeline or of a pipeline stage. -
duration
is 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;
or the equivalent
// Provided by VK_EXT_pipeline_creation_feedback
typedef VkPipelineCreationFeedbackFlagBits VkPipelineCreationFeedbackFlagBitsEXT;
-
VK_PIPELINE_CREATION_FEEDBACK_VALID_BIT
indicates that the feedback information is valid. -
VK_PIPELINE_CREATION_FEEDBACK_APPLICATION_PIPELINE_CACHE_HIT_BIT
indicates that a readily usable pipeline or pipeline stage was found in thepipelineCache
specified by the application in the pipeline creation command.An implementation should set the
VK_PIPELINE_CREATION_FEEDBACK_APPLICATION_PIPELINE_CACHE_HIT_BIT
bit if it was able to avoid the large majority of pipeline or pipeline stage creation work by using thepipelineCache
parameter of vkCreateGraphicsPipelines, vkCreateRayTracingPipelinesKHR, vkCreateRayTracingPipelinesNV, or vkCreateComputePipelines. When an implementation sets this bit for the entire pipeline, it may leave it unset for any stage.Implementations 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_BIT
indicates that the base pipeline specified by thebasePipelineHandle
orbasePipelineIndex
member of theVk*PipelineCreateInfo
structure was used to accelerate the creation of the pipeline.An implementation should set the
VK_PIPELINE_CREATION_FEEDBACK_BASE_PIPELINE_ACCELERATION_BIT
bit if it was able to avoid a significant amount of work by using the base pipeline.While “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;
or the equivalent
// Provided by VK_EXT_pipeline_creation_feedback
typedef VkPipelineCreationFeedbackFlags VkPipelineCreationFeedbackFlagsEXT;
VkPipelineCreationFeedbackFlags
is a bitmask type for providing zero
or more VkPipelineCreationFeedbackFlagBits.