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 fetch 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);-
deviceis the logical device that creates the compute pipelines. -
pipelineCacheis either VK_NULL_HANDLE, indicating that pipeline caching is disabled; or the handle of a valid pipeline cache object, in which case use of that cache is enabled for the duration of the command. -
createInfoCountis the length of thepCreateInfosandpPipelinesarrays. -
pCreateInfosis a pointer to an array of VkComputePipelineCreateInfo structures. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter. -
pPipelinesis a pointer to an array of VkPipeline handles in which the resulting compute pipeline objects are returned.
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;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis a bitmask of VkPipelineCreateFlagBits specifying how the pipeline will be generated. -
stageis a VkPipelineShaderStageCreateInfo structure describing the compute shader. -
layoutis the description of binding locations used by both the pipeline and descriptor sets used with the pipeline. -
basePipelineHandleis a pipeline to derive from. -
basePipelineIndexis an index into thepCreateInfosparameter to use as a pipeline to derive from.
The parameters basePipelineHandle and basePipelineIndex are
described in more detail in Pipeline Derivatives.
If the pNext chain includes a VkPipelineCreateFlags2CreateInfo
structure, VkPipelineCreateFlags2CreateInfo::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;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis a bitmask of VkPipelineShaderStageCreateFlagBits specifying how the pipeline shader stage will be generated. -
stageis a VkShaderStageFlagBits value specifying a single pipeline stage. -
moduleis optionally a VkShaderModule object containing the shader code for this stage. -
pNameis a pointer to a null-terminated UTF-8 string specifying the entry point name of the shader for this stage. -
pSpecializationInfois a pointer to a VkSpecializationInfo structure, as described in Specialization Constants, orNULL.
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 structure 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_BITspecifies that theSubgroupSizemay vary in the shader stage. -
VK_PIPELINE_SHADER_STAGE_CREATE_REQUIRE_FULL_SUBGROUPS_BITspecifies that the subgroup sizes must be launched with all invocations active in the 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_BITspecifies the vertex stage. -
VK_SHADER_STAGE_TESSELLATION_CONTROL_BITspecifies the tessellation control stage. -
VK_SHADER_STAGE_TESSELLATION_EVALUATION_BITspecifies the tessellation evaluation stage. -
VK_SHADER_STAGE_GEOMETRY_BITspecifies the geometry stage. -
VK_SHADER_STAGE_FRAGMENT_BITspecifies the fragment stage. -
VK_SHADER_STAGE_COMPUTE_BITspecifies the compute stage. -
VK_SHADER_STAGE_ALL_GRAPHICSis a combination of bits used as shorthand to specify all graphics stages defined above (excluding the compute stage). -
VK_SHADER_STAGE_ALLis a combination of bits used as shorthand to specify all shader stages supported by the device, including all additional stages which are introduced by extensions. -
VK_SHADER_STAGE_TASK_BIT_EXTspecifies the task stage. -
VK_SHADER_STAGE_MESH_BIT_EXTspecifies the mesh stage. -
VK_SHADER_STAGE_CLUSTER_CULLING_BIT_HUAWEIspecifies the cluster culling stage. -
VK_SHADER_STAGE_RAYGEN_BIT_KHRspecifies the ray generation stage. -
VK_SHADER_STAGE_ANY_HIT_BIT_KHRspecifies the any-hit stage. -
VK_SHADER_STAGE_CLOSEST_HIT_BIT_KHRspecifies the closest hit stage. -
VK_SHADER_STAGE_MISS_BIT_KHRspecifies the miss stage. -
VK_SHADER_STAGE_INTERSECTION_BIT_KHRspecifies the intersection stage. -
VK_SHADER_STAGE_CALLABLE_BIT_KHRspecifies the callable stage.
|
|
// 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;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
requiredSubgroupSizeis 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;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
renderPassis a handle to a render pass object describing the environment in which the pipeline will be used. The pipeline must only be used with a render pass instance compatible with the one provided. See Render Pass Compatibility for more information. -
subpassis the index of the subpass in the render pass where this pipeline will be used.
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);-
deviceis a handle to a local device object that was used to create the given render pass. -
renderPassis a handle to a render pass object describing the environment in which the pipeline will be used. The pipeline must only be used with a render pass instance compatible with the one provided. See Render Pass Compatibility for more information. -
pMaxWorkgroupSizeis a pointer to a VkExtent2D structure.
The VkPipelineRobustnessCreateInfo structure is defined as:
// Provided by VK_VERSION_1_4
typedef struct VkPipelineRobustnessCreateInfo {
VkStructureType sType;
const void* pNext;
VkPipelineRobustnessBufferBehavior storageBuffers;
VkPipelineRobustnessBufferBehavior uniformBuffers;
VkPipelineRobustnessBufferBehavior vertexInputs;
VkPipelineRobustnessImageBehavior images;
} VkPipelineRobustnessCreateInfo;or the equivalent
// Provided by VK_EXT_pipeline_robustness
typedef VkPipelineRobustnessCreateInfo VkPipelineRobustnessCreateInfoEXT;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
storageBufferssets 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
-
-
uniformBuffersdescribes 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
-
-
vertexInputsdescribes the behavior of out of bounds accesses made to vertex input attributes -
imagesdescribes 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 VkPipelineRobustnessCreateInfo depends on
which structure’s pNext chain it is included in.
-
VkGraphicsPipelineCreateInfo,VkRayTracingPipelineCreateInfoKHR,VkComputePipelineCreateInfo:
The robustness behavior described byVkPipelineRobustnessCreateInfoapplies to all accesses through this pipeline -
VkPipelineShaderStageCreateInfo:
The robustness behavior described byVkPipelineRobustnessCreateInfoapplies to all accesses emanating from the shader code of this shader stage
If VkPipelineRobustnessCreateInfo is specified for both a pipeline and
a pipeline stage, the VkPipelineRobustnessCreateInfo specified for the
pipeline stage will take precedence.
When VkPipelineRobustnessCreateInfo 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 VkPipelineRobustnessCreateInfo are:
// Provided by VK_VERSION_1_4
typedef enum VkPipelineRobustnessBufferBehavior {
VK_PIPELINE_ROBUSTNESS_BUFFER_BEHAVIOR_DEVICE_DEFAULT = 0,
VK_PIPELINE_ROBUSTNESS_BUFFER_BEHAVIOR_DISABLED = 1,
VK_PIPELINE_ROBUSTNESS_BUFFER_BEHAVIOR_ROBUST_BUFFER_ACCESS = 2,
VK_PIPELINE_ROBUSTNESS_BUFFER_BEHAVIOR_ROBUST_BUFFER_ACCESS_2 = 3,
// Provided by VK_EXT_pipeline_robustness
VK_PIPELINE_ROBUSTNESS_BUFFER_BEHAVIOR_DEVICE_DEFAULT_EXT = VK_PIPELINE_ROBUSTNESS_BUFFER_BEHAVIOR_DEVICE_DEFAULT,
// Provided by VK_EXT_pipeline_robustness
VK_PIPELINE_ROBUSTNESS_BUFFER_BEHAVIOR_DISABLED_EXT = VK_PIPELINE_ROBUSTNESS_BUFFER_BEHAVIOR_DISABLED,
// Provided by VK_EXT_pipeline_robustness
VK_PIPELINE_ROBUSTNESS_BUFFER_BEHAVIOR_ROBUST_BUFFER_ACCESS_EXT = VK_PIPELINE_ROBUSTNESS_BUFFER_BEHAVIOR_ROBUST_BUFFER_ACCESS,
// Provided by VK_EXT_pipeline_robustness
VK_PIPELINE_ROBUSTNESS_BUFFER_BEHAVIOR_ROBUST_BUFFER_ACCESS_2_EXT = VK_PIPELINE_ROBUSTNESS_BUFFER_BEHAVIOR_ROBUST_BUFFER_ACCESS_2,
} VkPipelineRobustnessBufferBehavior;or the equivalent
// Provided by VK_EXT_pipeline_robustness
typedef VkPipelineRobustnessBufferBehavior VkPipelineRobustnessBufferBehaviorEXT;-
VK_PIPELINE_ROBUSTNESS_BUFFER_BEHAVIOR_DEVICE_DEFAULTspecifies that this pipeline stage follows the behavior of robustness features that are enabled that created this pipeline -
VK_PIPELINE_ROBUSTNESS_BUFFER_BEHAVIOR_DISABLEDspecifies 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_ACCESSspecifies that out of bounds accesses by this pipeline stage to the relevant resource types behave as if therobustBufferAccessfeature is enabled -
VK_PIPELINE_ROBUSTNESS_BUFFER_BEHAVIOR_ROBUST_BUFFER_ACCESS_2specifies that out of bounds accesses by this pipeline stage to the relevant resource types behave as if therobustBufferAccess2feature is enabled
Possible values of the images member of
VkPipelineRobustnessCreateInfo are:
// Provided by VK_VERSION_1_4
typedef enum VkPipelineRobustnessImageBehavior {
VK_PIPELINE_ROBUSTNESS_IMAGE_BEHAVIOR_DEVICE_DEFAULT = 0,
VK_PIPELINE_ROBUSTNESS_IMAGE_BEHAVIOR_DISABLED = 1,
VK_PIPELINE_ROBUSTNESS_IMAGE_BEHAVIOR_ROBUST_IMAGE_ACCESS = 2,
VK_PIPELINE_ROBUSTNESS_IMAGE_BEHAVIOR_ROBUST_IMAGE_ACCESS_2 = 3,
// Provided by VK_EXT_pipeline_robustness
VK_PIPELINE_ROBUSTNESS_IMAGE_BEHAVIOR_DEVICE_DEFAULT_EXT = VK_PIPELINE_ROBUSTNESS_IMAGE_BEHAVIOR_DEVICE_DEFAULT,
// Provided by VK_EXT_pipeline_robustness
VK_PIPELINE_ROBUSTNESS_IMAGE_BEHAVIOR_DISABLED_EXT = VK_PIPELINE_ROBUSTNESS_IMAGE_BEHAVIOR_DISABLED,
// Provided by VK_EXT_pipeline_robustness
VK_PIPELINE_ROBUSTNESS_IMAGE_BEHAVIOR_ROBUST_IMAGE_ACCESS_EXT = VK_PIPELINE_ROBUSTNESS_IMAGE_BEHAVIOR_ROBUST_IMAGE_ACCESS,
// Provided by VK_EXT_pipeline_robustness
VK_PIPELINE_ROBUSTNESS_IMAGE_BEHAVIOR_ROBUST_IMAGE_ACCESS_2_EXT = VK_PIPELINE_ROBUSTNESS_IMAGE_BEHAVIOR_ROBUST_IMAGE_ACCESS_2,
} VkPipelineRobustnessImageBehavior;or the equivalent
// Provided by VK_EXT_pipeline_robustness
typedef VkPipelineRobustnessImageBehavior VkPipelineRobustnessImageBehaviorEXT;-
VK_PIPELINE_ROBUSTNESS_IMAGE_BEHAVIOR_DEVICE_DEFAULTspecifies 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_DISABLEDspecifies 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_ACCESSspecifies that out of bounds accesses by this pipeline stage to images behave as if therobustImageAccessfeature is enabled -
VK_PIPELINE_ROBUSTNESS_IMAGE_BEHAVIOR_ROBUST_IMAGE_ACCESS_2specifies that out of bounds accesses by this pipeline stage to images behave as if therobustImageAccess2feature 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;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
identifierSizeis the size, in bytes, of the buffer pointed to bypIdentifier. -
pIdentifieris 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;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
deviceAddressis the address where the pipeline’s metadata will be stored. -
sizeis the size of pipeline’s metadata that was queried using vkGetPipelineIndirectMemoryRequirementsNV. -
pipelineDeviceAddressCaptureReplayis the device address where pipeline’s metadata was originally saved and can now be used to re-populatedeviceAddressfor 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);-
commandBufferis the command buffer into which the command will be recorded. -
pipelineBindPointis a VkPipelineBindPoint value specifying the type of pipeline whose metadata will be saved. -
pipelineis 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);-
deviceis the logical device that creates the graphics pipelines. -
pipelineCacheis either VK_NULL_HANDLE, indicating that pipeline caching is disabled; or the handle of a valid pipeline cache object, in which case use of that cache is enabled for the duration of the command. -
createInfoCountis the length of thepCreateInfosandpPipelinesarrays. -
pCreateInfosis a pointer to an array of VkGraphicsPipelineCreateInfo structures. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter. -
pPipelinesis a pointer to an array of VkPipeline handles in which the resulting graphics pipeline objects are returned.
The VkGraphicsPipelineCreateInfo structure includes an array of VkPipelineShaderStageCreateInfo structures for each of the desired active shader stages, as well as creation information for all relevant fixed-function stages, and a pipeline layout.
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;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis a bitmask of VkPipelineCreateFlagBits specifying how the pipeline will be generated. -
stageCountis the number of entries in thepStagesarray. -
pStagesis a pointer to an array ofstageCountVkPipelineShaderStageCreateInfo structures describing the set of the shader stages to be included in the graphics pipeline. -
pVertexInputStateis a pointer to a VkPipelineVertexInputStateCreateInfo structure. It is ignored if the pipeline includes a mesh shader stage. It can beNULLif the pipeline is created with theVK_DYNAMIC_STATE_VERTEX_INPUT_EXTdynamic state set. -
pInputAssemblyStateis a pointer to a VkPipelineInputAssemblyStateCreateInfo structure which determines input assembly behavior for vertex shading, as described in Drawing Commands. If theVK_EXT_extended_dynamic_state3extension is enabled, it can beNULLif the pipeline is created with bothVK_DYNAMIC_STATE_PRIMITIVE_RESTART_ENABLE, andVK_DYNAMIC_STATE_PRIMITIVE_TOPOLOGYdynamic states set anddynamicPrimitiveTopologyUnrestrictedisVK_TRUE. It is ignored if the pipeline includes a mesh shader stage. -
pTessellationStateis a pointer to a VkPipelineTessellationStateCreateInfo structure defining tessellation state used by tessellation shaders. It can beNULLif the pipeline is created with theVK_DYNAMIC_STATE_PATCH_CONTROL_POINTS_EXTdynamic state set. -
pViewportStateis a pointer to a VkPipelineViewportStateCreateInfo structure defining viewport state used when rasterization is enabled. If theVK_EXT_extended_dynamic_state3extension is enabled, it can beNULLif the pipeline is created with bothVK_DYNAMIC_STATE_VIEWPORT_WITH_COUNT, andVK_DYNAMIC_STATE_SCISSOR_WITH_COUNTdynamic states set. -
pRasterizationStateis a pointer to a VkPipelineRasterizationStateCreateInfo structure defining rasterization state. If theVK_EXT_extended_dynamic_state3extension is enabled, it can beNULLif 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_WIDTHdynamic states set. -
pMultisampleStateis a pointer to a VkPipelineMultisampleStateCreateInfo structure defining multisample state used when rasterization is enabled. If theVK_EXT_extended_dynamic_state3extension is enabled, it can beNULLif 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_EXTdynamic states set, and either the alphaToOne feature is not enabled orVK_DYNAMIC_STATE_ALPHA_TO_ONE_ENABLE_EXTis set, in which case VkPipelineMultisampleStateCreateInfo::sampleShadingEnableis assumed to beVK_FALSE. -
pDepthStencilStateis 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_state3extension is enabled, it can beNULLif 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_BOUNDSdynamic states set. -
pColorBlendStateis 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_state3extension is enabled, it can beNULLif 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_CONSTANTSdynamic states set. -
pDynamicStateis a pointer to a VkPipelineDynamicStateCreateInfo structure defining which properties of the pipeline state object are dynamic and can be changed independently of the pipeline state. This can beNULL, which means no state in the pipeline is considered dynamic. -
layoutis the description of binding locations used by both the pipeline and descriptor sets used with the pipeline. -
renderPassis a handle to a render pass object describing the environment in which the pipeline will be used. The pipeline must only be used with a render pass instance compatible with the one provided. See Render Pass Compatibility for more information. -
subpassis the index of the subpass in the render pass where this pipeline will be used. -
basePipelineHandleis a pipeline to derive from. -
basePipelineIndexis an index into thepCreateInfosparameter to use as a pipeline to derive from.
The parameters basePipelineHandle and basePipelineIndex are
described in more detail in Pipeline Derivatives.
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_EXTwas specified.-
If
VK_PIPELINE_LAYOUT_CREATE_INDEPENDENT_SETS_BIT_EXTwas not specified, the full pipeline layout must be specified.
-
-
VkRenderPass and
subpassparameter -
The
viewMaskparameter of VkPipelineRenderingCreateInfo (formats are ignored)
This state must be specified to create a complete graphics pipeline.
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_EXTwas specified.-
If
VK_PIPELINE_LAYOUT_CREATE_INDEPENDENT_SETS_BIT_EXTwas not specified, the full pipeline layout must be specified.
-
-
VkPipelineMultisampleStateCreateInfo if sample shading is enabled or
renderpassis not VK_NULL_HANDLE -
VkRenderPass and
subpassparameter -
The
viewMaskparameter of VkPipelineRenderingCreateInfo (formats are ignored) -
Inclusion/omission of the
VK_PIPELINE_RASTERIZATION_STATE_CREATE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHRflag -
Inclusion/omission of the
VK_PIPELINE_RASTERIZATION_STATE_CREATE_FRAGMENT_DENSITY_MAP_ATTACHMENT_BIT_EXTflag
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
subpassparameter -
Inclusion/omission of the
VK_PIPELINE_CREATE_COLOR_ATTACHMENT_FEEDBACK_LOOP_BIT_EXTandVK_PIPELINE_CREATE_DEPTH_STENCIL_ATTACHMENT_FEEDBACK_LOOP_BIT_EXTflags -
Inclusion/omission of the
VK_PIPELINE_CREATE_2_ENABLE_LEGACY_DITHERING_BIT_EXTflag
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 VkPipelineCreateFlags2CreateInfo
structure, VkPipelineCreateFlags2CreateInfo::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;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
viewMaskis the viewMask used for rendering. -
colorAttachmentCountis the number of entries inpColorAttachmentFormats -
pColorAttachmentFormatsis a pointer to an array of VkFormat values defining the format of color attachments used in this pipeline. -
depthAttachmentFormatis a VkFormat value defining the format of the depth attachment used in this pipeline. -
stencilAttachmentFormatis a VkFormat value defining the format of the stencil attachment used in this pipeline.
When a pipeline is created without a VkRenderPass, if 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 VkPipelineCreateFlags2CreateInfo structure is defined as:
// Provided by VK_VERSION_1_4
typedef struct VkPipelineCreateFlags2CreateInfo {
VkStructureType sType;
const void* pNext;
VkPipelineCreateFlags2 flags;
} VkPipelineCreateFlags2CreateInfo;or the equivalent
// Provided by VK_KHR_maintenance5
typedef VkPipelineCreateFlags2CreateInfo VkPipelineCreateFlags2CreateInfoKHR;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis a bitmask of VkPipelineCreateFlagBits2 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
VkPipelineCreateFlags2CreateInfo::flags, specifying how a
pipeline is created, are:
// Provided by VK_VERSION_1_4
// Flag bits for VkPipelineCreateFlagBits2
typedef VkFlags64 VkPipelineCreateFlagBits2;
static const VkPipelineCreateFlagBits2 VK_PIPELINE_CREATE_2_DISABLE_OPTIMIZATION_BIT = 0x00000001ULL;
static const VkPipelineCreateFlagBits2 VK_PIPELINE_CREATE_2_ALLOW_DERIVATIVES_BIT = 0x00000002ULL;
static const VkPipelineCreateFlagBits2 VK_PIPELINE_CREATE_2_DERIVATIVE_BIT = 0x00000004ULL;
static const VkPipelineCreateFlagBits2 VK_PIPELINE_CREATE_2_VIEW_INDEX_FROM_DEVICE_INDEX_BIT = 0x00000008ULL;
static const VkPipelineCreateFlagBits2 VK_PIPELINE_CREATE_2_DISPATCH_BASE_BIT = 0x00000010ULL;
static const VkPipelineCreateFlagBits2 VK_PIPELINE_CREATE_2_FAIL_ON_PIPELINE_COMPILE_REQUIRED_BIT = 0x00000100ULL;
static const VkPipelineCreateFlagBits2 VK_PIPELINE_CREATE_2_EARLY_RETURN_ON_FAILURE_BIT = 0x00000200ULL;
static const VkPipelineCreateFlagBits2 VK_PIPELINE_CREATE_2_NO_PROTECTED_ACCESS_BIT = 0x08000000ULL;
static const VkPipelineCreateFlagBits2 VK_PIPELINE_CREATE_2_PROTECTED_ACCESS_ONLY_BIT = 0x40000000ULL;
#ifdef VK_ENABLE_BETA_EXTENSIONS
// Provided by VK_AMDX_shader_enqueue with VK_KHR_maintenance5 or VK_VERSION_1_4
static const VkPipelineCreateFlagBits2 VK_PIPELINE_CREATE_2_EXECUTION_GRAPH_BIT_AMDX = 0x100000000ULL;
#endif
// Provided by VK_KHR_ray_tracing_pipeline
static const VkPipelineCreateFlagBits2 VK_PIPELINE_CREATE_2_RAY_TRACING_SKIP_BUILT_IN_PRIMITIVES_BIT_KHR = 0x00001000ULL;
// Provided by VK_NV_ray_tracing_linear_swept_spheres
static const VkPipelineCreateFlagBits2 VK_PIPELINE_CREATE_2_RAY_TRACING_ALLOW_SPHERES_AND_LINEAR_SWEPT_SPHERES_BIT_NV = 0x200000000ULL;
// Provided by VK_EXT_legacy_dithering with (VK_KHR_dynamic_rendering or VK_VERSION_1_3) and (VK_KHR_maintenance5 or VK_VERSION_1_4)
static const VkPipelineCreateFlagBits2 VK_PIPELINE_CREATE_2_ENABLE_LEGACY_DITHERING_BIT_EXT = 0x400000000ULL;
// Provided by VK_KHR_maintenance5
static const VkPipelineCreateFlagBits2 VK_PIPELINE_CREATE_2_DISABLE_OPTIMIZATION_BIT_KHR = 0x00000001ULL;
// Provided by VK_KHR_maintenance5
static const VkPipelineCreateFlagBits2 VK_PIPELINE_CREATE_2_ALLOW_DERIVATIVES_BIT_KHR = 0x00000002ULL;
// Provided by VK_KHR_maintenance5
static const VkPipelineCreateFlagBits2 VK_PIPELINE_CREATE_2_DERIVATIVE_BIT_KHR = 0x00000004ULL;
// Provided by VK_KHR_maintenance5
static const VkPipelineCreateFlagBits2 VK_PIPELINE_CREATE_2_VIEW_INDEX_FROM_DEVICE_INDEX_BIT_KHR = 0x00000008ULL;
// Provided by VK_KHR_maintenance5
static const VkPipelineCreateFlagBits2 VK_PIPELINE_CREATE_2_DISPATCH_BASE_BIT_KHR = 0x00000010ULL;
// Provided by VK_KHR_maintenance5 with VK_NV_ray_tracing
static const VkPipelineCreateFlagBits2 VK_PIPELINE_CREATE_2_DEFER_COMPILE_BIT_NV = 0x00000020ULL;
// Provided by VK_KHR_maintenance5 with VK_KHR_pipeline_executable_properties
static const VkPipelineCreateFlagBits2 VK_PIPELINE_CREATE_2_CAPTURE_STATISTICS_BIT_KHR = 0x00000040ULL;
// Provided by VK_KHR_maintenance5 with VK_KHR_pipeline_executable_properties
static const VkPipelineCreateFlagBits2 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 VkPipelineCreateFlagBits2 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 VkPipelineCreateFlagBits2 VK_PIPELINE_CREATE_2_EARLY_RETURN_ON_FAILURE_BIT_KHR = 0x00000200ULL;
// Provided by VK_KHR_maintenance5 with VK_EXT_graphics_pipeline_library
static const VkPipelineCreateFlagBits2 VK_PIPELINE_CREATE_2_LINK_TIME_OPTIMIZATION_BIT_EXT = 0x00000400ULL;
// Provided by VK_KHR_maintenance5 with VK_EXT_graphics_pipeline_library
static const VkPipelineCreateFlagBits2 VK_PIPELINE_CREATE_2_RETAIN_LINK_TIME_OPTIMIZATION_INFO_BIT_EXT = 0x00800000ULL;
// Provided by VK_KHR_maintenance5 with VK_KHR_pipeline_library
static const VkPipelineCreateFlagBits2 VK_PIPELINE_CREATE_2_LIBRARY_BIT_KHR = 0x00000800ULL;
// Provided by VK_KHR_maintenance5 with VK_KHR_ray_tracing_pipeline
static const VkPipelineCreateFlagBits2 VK_PIPELINE_CREATE_2_RAY_TRACING_SKIP_TRIANGLES_BIT_KHR = 0x00001000ULL;
// Provided by VK_KHR_maintenance5 with VK_KHR_ray_tracing_pipeline
static const VkPipelineCreateFlagBits2 VK_PIPELINE_CREATE_2_RAY_TRACING_SKIP_AABBS_BIT_KHR = 0x00002000ULL;
// Provided by VK_KHR_maintenance5 with VK_KHR_ray_tracing_pipeline
static const VkPipelineCreateFlagBits2 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 VkPipelineCreateFlagBits2 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 VkPipelineCreateFlagBits2 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 VkPipelineCreateFlagBits2 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 VkPipelineCreateFlagBits2 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 VkPipelineCreateFlagBits2 VK_PIPELINE_CREATE_2_INDIRECT_BINDABLE_BIT_NV = 0x00040000ULL;
// Provided by VK_KHR_maintenance5 with VK_NV_ray_tracing_motion_blur
static const VkPipelineCreateFlagBits2 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 VkPipelineCreateFlagBits2 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 VkPipelineCreateFlagBits2 VK_PIPELINE_CREATE_2_RENDERING_FRAGMENT_DENSITY_MAP_ATTACHMENT_BIT_EXT = 0x00400000ULL;
// Provided by VK_KHR_maintenance5 with VK_EXT_opacity_micromap
static const VkPipelineCreateFlagBits2 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 VkPipelineCreateFlagBits2 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 VkPipelineCreateFlagBits2 VK_PIPELINE_CREATE_2_DEPTH_STENCIL_ATTACHMENT_FEEDBACK_LOOP_BIT_EXT = 0x04000000ULL;
// Provided by VK_KHR_maintenance5 with VK_VERSION_1_4 or VK_EXT_pipeline_protected_access
static const VkPipelineCreateFlagBits2 VK_PIPELINE_CREATE_2_NO_PROTECTED_ACCESS_BIT_EXT = 0x08000000ULL;
// Provided by VK_KHR_maintenance5 with VK_VERSION_1_4 or VK_EXT_pipeline_protected_access
static const VkPipelineCreateFlagBits2 VK_PIPELINE_CREATE_2_PROTECTED_ACCESS_ONLY_BIT_EXT = 0x40000000ULL;
// Provided by VK_KHR_maintenance5 with VK_NV_displacement_micromap
static const VkPipelineCreateFlagBits2 VK_PIPELINE_CREATE_2_RAY_TRACING_DISPLACEMENT_MICROMAP_BIT_NV = 0x10000000ULL;
// Provided by VK_KHR_maintenance5 with VK_EXT_descriptor_buffer
static const VkPipelineCreateFlagBits2 VK_PIPELINE_CREATE_2_DESCRIPTOR_BUFFER_BIT_EXT = 0x20000000ULL;
// Provided by VK_KHR_maintenance5 with VK_ARM_pipeline_opacity_micromap, VK_ARM_pipeline_opacity_micromap
static const VkPipelineCreateFlagBits2 VK_PIPELINE_CREATE_2_DISALLOW_OPACITY_MICROMAP_BIT_ARM = 0x2000000000ULL;
// Provided by VK_KHR_pipeline_binary
static const VkPipelineCreateFlagBits2 VK_PIPELINE_CREATE_2_CAPTURE_DATA_BIT_KHR = 0x80000000ULL;
// Provided by VK_EXT_device_generated_commands
static const VkPipelineCreateFlagBits2 VK_PIPELINE_CREATE_2_INDIRECT_BINDABLE_BIT_EXT = 0x4000000000ULL;or the equivalent
// Provided by VK_KHR_maintenance5
typedef VkPipelineCreateFlagBits2 VkPipelineCreateFlagBits2KHR;-
VK_PIPELINE_CREATE_2_DISABLE_OPTIMIZATION_BITspecifies that the created pipeline will not be optimized. Using this flag may reduce the time taken to create the pipeline. -
VK_PIPELINE_CREATE_2_ALLOW_DERIVATIVES_BITspecifies that the pipeline to be created is allowed to be the parent of a pipeline that will be created in a subsequent pipeline creation call. -
VK_PIPELINE_CREATE_2_DERIVATIVE_BITspecifies 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_BITspecifies that any shader input variables decorated asViewIndexwill be assigned values as if they were decorated asDeviceIndex. -
VK_PIPELINE_CREATE_2_DISPATCH_BASE_BITspecifies that a compute pipeline can be used with vkCmdDispatchBase with a non-zero base workgroup. -
VK_PIPELINE_CREATE_2_DEFER_COMPILE_BIT_NVspecifies 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_KHRspecifies that the shader compiler should capture statistics for the pipeline executables produced by the compile process which can later be retrieved by calling vkGetPipelineExecutableStatisticsKHR. Enabling this flag must not affect the final compiled pipeline but may disable pipeline caching or otherwise affect pipeline creation time. -
VK_PIPELINE_CREATE_2_CAPTURE_INTERNAL_REPRESENTATIONS_BIT_KHRspecifies that the shader compiler should capture the internal representations of pipeline executables produced by the compile process which can later be retrieved by calling vkGetPipelineExecutableInternalRepresentationsKHR. Enabling this flag must not affect the final compiled pipeline but may disable pipeline caching or otherwise affect pipeline creation time. When capturing IR from pipelines created with pipeline libraries, there is no guarantee that IR from libraries can be retrieved from the linked pipeline. Applications should retrieve IR from each library, and any linked pipelines, separately. -
VK_PIPELINE_CREATE_2_LIBRARY_BIT_KHRspecifies that the pipeline cannot be used directly, and instead defines a pipeline library that can be combined with other pipelines using the VkPipelineLibraryCreateInfoKHR structure. This is available in ray tracing and graphics pipelines. -
VK_PIPELINE_CREATE_2_RAY_TRACING_NO_NULL_ANY_HIT_SHADERS_BIT_KHRspecifies that an any-hit shader will always be present when an any-hit shader would be executed. A NULL any-hit shader is an any-hit shader which is effectivelyVK_SHADER_UNUSED_KHR, such as from a shader group consisting entirely of zeros. -
VK_PIPELINE_CREATE_2_RAY_TRACING_NO_NULL_CLOSEST_HIT_SHADERS_BIT_KHRspecifies that a closest hit shader will always be present when a closest hit shader would be executed. A NULL closest hit shader is a closest hit shader which is effectivelyVK_SHADER_UNUSED_KHR, such as from a shader group consisting entirely of zeros. -
VK_PIPELINE_CREATE_2_RAY_TRACING_NO_NULL_MISS_SHADERS_BIT_KHRspecifies that a miss shader will always be present when a miss shader would be executed. A NULL miss shader is a miss shader which is effectivelyVK_SHADER_UNUSED_KHR, such as from a shader group consisting entirely of zeros. -
VK_PIPELINE_CREATE_2_RAY_TRACING_NO_NULL_INTERSECTION_SHADERS_BIT_KHRspecifies that an intersection shader will always be present when an intersection shader would be executed. A NULL intersection shader is an intersection shader which is effectivelyVK_SHADER_UNUSED_KHR, such as from a shader group consisting entirely of zeros. -
VK_PIPELINE_CREATE_2_RAY_TRACING_SKIP_TRIANGLES_BIT_KHRspecifies that all built-in primitives including triangles, spheres and LSS primitives will be skipped during traversal using pipeline trace ray instructions. -
VK_PIPELINE_CREATE_2_RAY_TRACING_SKIP_BUILT_IN_PRIMITIVES_BIT_KHRis an alias forVK_PIPELINE_CREATE_2_RAY_TRACING_SKIP_TRIANGLES_BIT_KHR. -
VK_PIPELINE_CREATE_2_RAY_TRACING_SKIP_AABBS_BIT_KHRspecifies 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_KHRspecifies that the shader group handles can be saved and reused on a subsequent run (e.g. for trace capture and replay). -
VK_PIPELINE_CREATE_2_RAY_TRACING_ALLOW_SPHERES_AND_LINEAR_SWEPT_SPHERES_BIT_NVspecifies that the pipeline is allowed to use spheres or linear swept spheres as a geometry type in the acceleration structures. Using this flag may affect performance. -
VK_PIPELINE_CREATE_2_INDIRECT_BINDABLE_BIT_NVspecifies that the pipeline can be used in combination with Device-Generated Commands. -
VK_PIPELINE_CREATE_2_INDIRECT_BINDABLE_BIT_EXTspecifies that the pipeline can be used in aVkIndirectExecutionSetEXT. -
VK_PIPELINE_CREATE_2_FAIL_ON_PIPELINE_COMPILE_REQUIRED_BITspecifies that pipeline creation will fail if a compile is required for creation of a valid VkPipeline object;VK_PIPELINE_COMPILE_REQUIREDwill be returned by pipeline creation, and the VkPipeline will be VK_NULL_HANDLE. -
When creating multiple pipelines,
VK_PIPELINE_CREATE_2_EARLY_RETURN_ON_FAILURE_BITspecifies that control will be returned to the application if any individual pipeline returns a result which is notVK_SUCCESSrather than continuing to create additional pipelines. -
VK_PIPELINE_CREATE_2_RAY_TRACING_ALLOW_MOTION_BIT_NVspecifies that the pipeline is allowed to useOpTraceRayMotionNV. -
VK_PIPELINE_CREATE_2_RENDERING_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHRspecifies that the pipeline will be used with a fragment shading rate attachment. -
VK_PIPELINE_CREATE_2_RENDERING_FRAGMENT_DENSITY_MAP_ATTACHMENT_BIT_EXTspecifies that the pipeline will be used with a fragment density map attachment. -
VK_PIPELINE_CREATE_2_LINK_TIME_OPTIMIZATION_BIT_EXTspecifies 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_EXTspecifies 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_EXTspecifies that a pipeline will be used with descriptor buffers, rather than descriptor sets. -
VK_PIPELINE_CREATE_2_COLOR_ATTACHMENT_FEEDBACK_LOOP_BIT_EXTspecifies that the pipeline may be used with an attachment feedback loop including color attachments. -
VK_PIPELINE_CREATE_2_DEPTH_STENCIL_ATTACHMENT_FEEDBACK_LOOP_BIT_EXTspecifies that the pipeline may be used with an attachment feedback loop including depth-stencil attachments. -
VK_PIPELINE_CREATE_2_RAY_TRACING_OPACITY_MICROMAP_BIT_EXTspecifies 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_NVspecifies 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_EXTspecifies that the pipeline must not be bound to a protected command buffer. -
VK_PIPELINE_CREATE_2_PROTECTED_ACCESS_ONLY_BIT_EXTspecifies that the pipeline must not be bound to an unprotected command buffer. -
VK_PIPELINE_CREATE_2_CAPTURE_DATA_BIT_KHRspecifies thatVkPipelineBinaryKHRobjects can be created from the pipeline. IfVK_PIPELINE_CREATE_2_CAPTURE_DATA_BIT_KHRis used, implementations should not store pipeline data to an internal cache, if such a cache exists as stated bypipelineBinaryInternalCache. IfpipelineBinaryPrefersInternalCacheisVK_TRUE, applications should not useVK_PIPELINE_CREATE_2_CAPTURE_DATA_BIT_KHR. -
VK_PIPELINE_CREATE_2_ENABLE_LEGACY_DITHERING_BIT_EXTspecifies 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_AMDXspecifies that the pipeline will be used in an execution graph -
VK_PIPELINE_CREATE_2_DISALLOW_OPACITY_MICROMAP_BIT_ARMspecifies that the pipeline must not be used with acceleration structures which reference an opacity micromap array.
It is valid to set both VK_PIPELINE_CREATE_2_ALLOW_DERIVATIVES_BIT and
VK_PIPELINE_CREATE_2_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_2_LINK_TIME_OPTIMIZATION_BIT_EXT if available,
whether or not that bit was specified.
|
Using |
// Provided by VK_VERSION_1_4
typedef VkFlags64 VkPipelineCreateFlags2;or the equivalent
// Provided by VK_KHR_maintenance5
typedef VkPipelineCreateFlags2 VkPipelineCreateFlags2KHR;VkPipelineCreateFlags2 is a bitmask type for setting a mask of zero or
more VkPipelineCreateFlagBits2.
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_VERSION_1_4
VK_PIPELINE_CREATE_NO_PROTECTED_ACCESS_BIT = 0x08000000,
// Provided by VK_VERSION_1_4
VK_PIPELINE_CREATE_PROTECTED_ACCESS_ONLY_BIT = 0x40000000,
// 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_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,
// Provided by VK_EXT_pipeline_protected_access
VK_PIPELINE_CREATE_NO_PROTECTED_ACCESS_BIT_EXT = VK_PIPELINE_CREATE_NO_PROTECTED_ACCESS_BIT,
// Provided by VK_EXT_pipeline_protected_access
VK_PIPELINE_CREATE_PROTECTED_ACCESS_ONLY_BIT_EXT = VK_PIPELINE_CREATE_PROTECTED_ACCESS_ONLY_BIT,
} VkPipelineCreateFlagBits;-
VK_PIPELINE_CREATE_DISABLE_OPTIMIZATION_BITspecifies that the created pipeline will not be optimized. Using this flag may reduce the time taken to create the pipeline. -
VK_PIPELINE_CREATE_ALLOW_DERIVATIVES_BITspecifies that the pipeline to be created is allowed to be the parent of a pipeline that will be created in a subsequent pipeline creation call. -
VK_PIPELINE_CREATE_DERIVATIVE_BITspecifies that the pipeline to be created will be a child of a previously created parent pipeline. -
VK_PIPELINE_CREATE_VIEW_INDEX_FROM_DEVICE_INDEX_BITspecifies that any shader input variables decorated asViewIndexwill be assigned values as if they were decorated asDeviceIndex. -
VK_PIPELINE_CREATE_DISPATCH_BASEspecifies that a compute pipeline can be used with vkCmdDispatchBase with a non-zero base workgroup. -
VK_PIPELINE_CREATE_DEFER_COMPILE_BIT_NVspecifies 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_KHRspecifies that the shader compiler should capture statistics for the pipeline executables produced by the compile process which can later be retrieved by calling vkGetPipelineExecutableStatisticsKHR. Enabling this flag must not affect the final compiled pipeline but may disable pipeline caching or otherwise affect pipeline creation time. -
VK_PIPELINE_CREATE_CAPTURE_INTERNAL_REPRESENTATIONS_BIT_KHRspecifies that the shader compiler should capture the internal representations of pipeline executables produced by the compile process which can later be retrieved by calling vkGetPipelineExecutableInternalRepresentationsKHR. Enabling this flag must not affect the final compiled pipeline but may disable pipeline caching or otherwise affect pipeline creation time. When capturing IR from pipelines created with pipeline libraries, there is no guarantee that IR from libraries can be retrieved from the linked pipeline. Applications should retrieve IR from each library, and any linked pipelines, separately. -
VK_PIPELINE_CREATE_LIBRARY_BIT_KHRspecifies that the pipeline cannot be used directly, and instead defines a pipeline library that can be combined with other pipelines using the VkPipelineLibraryCreateInfoKHR structure. This is available in ray tracing and graphics pipelines. -
VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_ANY_HIT_SHADERS_BIT_KHRspecifies that an any-hit shader will always be present when an any-hit shader would be executed. A NULL any-hit shader is an any-hit shader which is effectivelyVK_SHADER_UNUSED_KHR, such as from a shader group consisting entirely of zeros. -
VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_CLOSEST_HIT_SHADERS_BIT_KHRspecifies that a closest hit shader will always be present when a closest hit shader would be executed. A NULL closest hit shader is a closest hit shader which is effectivelyVK_SHADER_UNUSED_KHR, such as from a shader group consisting entirely of zeros. -
VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_MISS_SHADERS_BIT_KHRspecifies that a miss shader will always be present when a miss shader would be executed. A NULL miss shader is a miss shader which is effectivelyVK_SHADER_UNUSED_KHR, such as from a shader group consisting entirely of zeros. -
VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_INTERSECTION_SHADERS_BIT_KHRspecifies that an intersection shader will always be present when an intersection shader would be executed. A NULL intersection shader is an intersection shader which is effectivelyVK_SHADER_UNUSED_KHR, such as from a shader group consisting entirely of zeros. -
VK_PIPELINE_CREATE_RAY_TRACING_SKIP_TRIANGLES_BIT_KHRspecifies that sphere, LSS and triangle primitives will be skipped during traversal using pipeline trace ray instructions. -
VK_PIPELINE_CREATE_RAY_TRACING_SKIP_AABBS_BIT_KHRspecifies that AABB primitives will be skipped during traversal using pipeline trace ray instructions. -
VK_PIPELINE_CREATE_RAY_TRACING_SHADER_GROUP_HANDLE_CAPTURE_REPLAY_BIT_KHRspecifies that the shader group handles can be saved and reused on a subsequent run (e.g. for trace capture and replay). -
VK_PIPELINE_CREATE_INDIRECT_BINDABLE_BIT_NVspecifies that the pipeline can be used in combination with Device-Generated Commands. -
VK_PIPELINE_CREATE_FAIL_ON_PIPELINE_COMPILE_REQUIRED_BITspecifies that pipeline creation will fail if a compile is required for creation of a valid VkPipeline object;VK_PIPELINE_COMPILE_REQUIREDwill be returned by pipeline creation, and the VkPipeline will be VK_NULL_HANDLE. -
When creating multiple pipelines,
VK_PIPELINE_CREATE_EARLY_RETURN_ON_FAILURE_BITspecifies that control will be returned to the application if any individual pipeline returns a result which is notVK_SUCCESSrather than continuing to create additional pipelines. -
VK_PIPELINE_CREATE_RAY_TRACING_ALLOW_MOTION_BIT_NVspecifies that the pipeline is allowed to useOpTraceRayMotionNV. -
VK_PIPELINE_CREATE_RENDERING_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHRspecifies that the pipeline will be used with a fragment shading rate attachment and dynamic rendering. -
VK_PIPELINE_CREATE_RENDERING_FRAGMENT_DENSITY_MAP_ATTACHMENT_BIT_EXTspecifies that the pipeline will be used with a fragment density map attachment and dynamic rendering. -
VK_PIPELINE_CREATE_LINK_TIME_OPTIMIZATION_BIT_EXTspecifies 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_EXTspecifies 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_EXTspecifies that a pipeline will be used with descriptor buffers, rather than descriptor sets. -
VK_PIPELINE_CREATE_COLOR_ATTACHMENT_FEEDBACK_LOOP_BIT_EXTspecifies that the pipeline may be used with an attachment feedback loop including color attachments. It is ignored ifVK_DYNAMIC_STATE_ATTACHMENT_FEEDBACK_LOOP_ENABLE_EXTis set inpDynamicStates. -
VK_PIPELINE_CREATE_DEPTH_STENCIL_ATTACHMENT_FEEDBACK_LOOP_BIT_EXTspecifies 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_EXTis set inpDynamicStates. -
VK_PIPELINE_CREATE_RAY_TRACING_OPACITY_MICROMAP_BIT_EXTspecifies 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_NVspecifies that the ray tracing pipeline can be used with acceleration structures which reference a displacement micromap array. -
VK_PIPELINE_CREATE_NO_PROTECTED_ACCESS_BITspecifies that the pipeline must not be bound to a protected command buffer. -
VK_PIPELINE_CREATE_PROTECTED_ACCESS_ONLY_BITspecifies 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;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
binaryCountis the number of elements in thepPipelineBinariesarray. -
pPipelineBinariesis 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;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis 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_EXTspecifies that a pipeline will include vertex input interface state. -
VK_GRAPHICS_PIPELINE_LIBRARY_PRE_RASTERIZATION_SHADERS_BIT_EXTspecifies that a pipeline will include pre-rasterization shader state. -
VK_GRAPHICS_PIPELINE_LIBRARY_FRAGMENT_SHADER_BIT_EXTspecifies that a pipeline will include fragment shader state. -
VK_GRAPHICS_PIPELINE_LIBRARY_FRAGMENT_OUTPUT_INTERFACE_BIT_EXTspecifies 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;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis reserved for future use. -
dynamicStateCountis the number of elements in thepDynamicStatesarray. -
pDynamicStatesis a pointer to an array of VkDynamicState values specifying which pieces of pipeline state will use the values from dynamic state commands rather than from pipeline state creation information.
// Provided by VK_VERSION_1_0
typedef VkFlags VkPipelineDynamicStateCreateFlags;VkPipelineDynamicStateCreateFlags is a bitmask type for setting a
mask, but is currently reserved for future use.
The source of different pieces of dynamic state is specified by the
VkPipelineDynamicStateCreateInfo::pDynamicStates property of the
currently active pipeline, each of whose elements must be one of the
values:
// Provided by VK_VERSION_1_0
typedef enum VkDynamicState {
VK_DYNAMIC_STATE_VIEWPORT = 0,
VK_DYNAMIC_STATE_SCISSOR = 1,
VK_DYNAMIC_STATE_LINE_WIDTH = 2,
VK_DYNAMIC_STATE_DEPTH_BIAS = 3,
VK_DYNAMIC_STATE_BLEND_CONSTANTS = 4,
VK_DYNAMIC_STATE_DEPTH_BOUNDS = 5,
VK_DYNAMIC_STATE_STENCIL_COMPARE_MASK = 6,
VK_DYNAMIC_STATE_STENCIL_WRITE_MASK = 7,
VK_DYNAMIC_STATE_STENCIL_REFERENCE = 8,
// Provided by VK_VERSION_1_3
VK_DYNAMIC_STATE_CULL_MODE = 1000267000,
// Provided by VK_VERSION_1_3
VK_DYNAMIC_STATE_FRONT_FACE = 1000267001,
// Provided by VK_VERSION_1_3
VK_DYNAMIC_STATE_PRIMITIVE_TOPOLOGY = 1000267002,
// Provided by VK_VERSION_1_3
VK_DYNAMIC_STATE_VIEWPORT_WITH_COUNT = 1000267003,
// Provided by VK_VERSION_1_3
VK_DYNAMIC_STATE_SCISSOR_WITH_COUNT = 1000267004,
// Provided by VK_VERSION_1_3
VK_DYNAMIC_STATE_VERTEX_INPUT_BINDING_STRIDE = 1000267005,
// Provided by VK_VERSION_1_3
VK_DYNAMIC_STATE_DEPTH_TEST_ENABLE = 1000267006,
// Provided by VK_VERSION_1_3
VK_DYNAMIC_STATE_DEPTH_WRITE_ENABLE = 1000267007,
// Provided by VK_VERSION_1_3
VK_DYNAMIC_STATE_DEPTH_COMPARE_OP = 1000267008,
// Provided by VK_VERSION_1_3
VK_DYNAMIC_STATE_DEPTH_BOUNDS_TEST_ENABLE = 1000267009,
// Provided by VK_VERSION_1_3
VK_DYNAMIC_STATE_STENCIL_TEST_ENABLE = 1000267010,
// Provided by VK_VERSION_1_3
VK_DYNAMIC_STATE_STENCIL_OP = 1000267011,
// Provided by VK_VERSION_1_3
VK_DYNAMIC_STATE_RASTERIZER_DISCARD_ENABLE = 1000377001,
// Provided by VK_VERSION_1_3
VK_DYNAMIC_STATE_DEPTH_BIAS_ENABLE = 1000377002,
// Provided by VK_VERSION_1_3
VK_DYNAMIC_STATE_PRIMITIVE_RESTART_ENABLE = 1000377004,
// Provided by VK_VERSION_1_4
VK_DYNAMIC_STATE_LINE_STIPPLE = 1000259000,
// 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_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,
// 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,
// Provided by VK_KHR_line_rasterization
VK_DYNAMIC_STATE_LINE_STIPPLE_KHR = VK_DYNAMIC_STATE_LINE_STIPPLE,
} VkDynamicState;-
VK_DYNAMIC_STATE_VIEWPORTspecifies that thepViewportsstate in VkPipelineViewportStateCreateInfo will be ignored and must be set dynamically with vkCmdSetViewport before any drawing commands. The number of viewports used by a pipeline is still specified by theviewportCountmember of VkPipelineViewportStateCreateInfo. -
VK_DYNAMIC_STATE_SCISSORspecifies that thepScissorsstate in VkPipelineViewportStateCreateInfo will be ignored and must be set dynamically with vkCmdSetScissor before any drawing commands. The number of scissor rectangles used by a pipeline is still specified by thescissorCountmember of VkPipelineViewportStateCreateInfo. -
VK_DYNAMIC_STATE_LINE_WIDTHspecifies that thelineWidthstate in VkPipelineRasterizationStateCreateInfo will be ignored and must be set dynamically with vkCmdSetLineWidth before any drawing commands that generate line primitives for the rasterizer. -
VK_DYNAMIC_STATE_DEPTH_BIASspecifies that any instance of VkDepthBiasRepresentationInfoEXT included in thepNextchain of VkPipelineRasterizationStateCreateInfo as well as thedepthBiasConstantFactor,depthBiasClampanddepthBiasSlopeFactorstates 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_CONSTANTSspecifies that theblendConstantsstate in VkPipelineColorBlendStateCreateInfo will be ignored and must be set dynamically with vkCmdSetBlendConstants before any draws are performed with a pipeline state withVkPipelineColorBlendAttachmentStatememberblendEnableset toVK_TRUEand any of the blend functions using a constant blend color. -
VK_DYNAMIC_STATE_DEPTH_BOUNDSspecifies that theminDepthBoundsandmaxDepthBoundsstates of VkPipelineDepthStencilStateCreateInfo will be ignored and must be set dynamically with vkCmdSetDepthBounds before any draws are performed with a pipeline state with VkPipelineDepthStencilStateCreateInfo memberdepthBoundsTestEnableset toVK_TRUE. -
VK_DYNAMIC_STATE_STENCIL_COMPARE_MASKspecifies that thecompareMaskstate in VkPipelineDepthStencilStateCreateInfo for bothfrontandbackwill be ignored and must be set dynamically with vkCmdSetStencilCompareMask before any draws are performed with a pipeline state with VkPipelineDepthStencilStateCreateInfo memberstencilTestEnableset toVK_TRUE -
VK_DYNAMIC_STATE_STENCIL_WRITE_MASKspecifies that thewriteMaskstate in VkPipelineDepthStencilStateCreateInfo for bothfrontandbackwill be ignored and must be set dynamically with vkCmdSetStencilWriteMask before any draws are performed with a pipeline state with VkPipelineDepthStencilStateCreateInfo memberstencilTestEnableset toVK_TRUE -
VK_DYNAMIC_STATE_STENCIL_REFERENCEspecifies that thereferencestate in VkPipelineDepthStencilStateCreateInfo for bothfrontandbackwill be ignored and must be set dynamically with vkCmdSetStencilReference before any draws are performed with a pipeline state with VkPipelineDepthStencilStateCreateInfo memberstencilTestEnableset toVK_TRUE -
VK_DYNAMIC_STATE_VIEWPORT_W_SCALING_NVspecifies that thepViewportWScalingsstate in VkPipelineViewportWScalingStateCreateInfoNV will be ignored and must be set dynamically with vkCmdSetViewportWScalingNV before any draws are performed with a pipeline state with VkPipelineViewportWScalingStateCreateInfoNV memberviewportScalingEnableset toVK_TRUE -
VK_DYNAMIC_STATE_DISCARD_RECTANGLE_EXTspecifies that thepDiscardRectanglesstate in VkPipelineDiscardRectangleStateCreateInfoEXT will be ignored and must be set dynamically with vkCmdSetDiscardRectangleEXT before any draw or clear commands. -
VK_DYNAMIC_STATE_DISCARD_RECTANGLE_ENABLE_EXTspecifies that the presence of the VkPipelineDiscardRectangleStateCreateInfoEXT structure in the VkGraphicsPipelineCreateInfo chain with adiscardRectangleCountgreater 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 leastspecVersion2of theVK_EXT_discard_rectanglesextension. -
VK_DYNAMIC_STATE_DISCARD_RECTANGLE_MODE_EXTspecifies that thediscardRectangleModestate in VkPipelineDiscardRectangleStateCreateInfoEXT will be ignored and must be set dynamically with vkCmdSetDiscardRectangleModeEXT before any draw commands. This is available on implementations that support at leastspecVersion2of theVK_EXT_discard_rectanglesextension. -
VK_DYNAMIC_STATE_SAMPLE_LOCATIONS_EXTspecifies that thesampleLocationsInfostate 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 thesampleLocationsEnablemember of VkPipelineSampleLocationsStateCreateInfoEXT. -
VK_DYNAMIC_STATE_EXCLUSIVE_SCISSOR_NVspecifies that thepExclusiveScissorsstate in VkPipelineViewportExclusiveScissorStateCreateInfoNV will be ignored and must be set dynamically with vkCmdSetExclusiveScissorNV before any drawing commands. -
VK_DYNAMIC_STATE_EXCLUSIVE_SCISSOR_ENABLE_NVspecifies that the exclusive scissors must be explicitly enabled with vkCmdSetExclusiveScissorEnableNV and theexclusiveScissorCountvalue in VkPipelineViewportExclusiveScissorStateCreateInfoNV will not implicitly enable them. This is available on implementations that support at leastspecVersion2of theVK_NV_scissor_exclusiveextension. -
VK_DYNAMIC_STATE_VIEWPORT_SHADING_RATE_PALETTE_NVspecifies that thepShadingRatePalettesstate in VkPipelineViewportShadingRateImageStateCreateInfoNV will be ignored and must be set dynamically with vkCmdSetViewportShadingRatePaletteNV before any drawing commands. -
VK_DYNAMIC_STATE_VIEWPORT_COARSE_SAMPLE_ORDER_NVspecifies 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_STIPPLEspecifies that thelineStippleFactorandlineStipplePatternstate in VkPipelineRasterizationLineStateCreateInfo will be ignored and must be set dynamically with vkCmdSetLineStipple before any draws are performed with a pipeline state with VkPipelineRasterizationLineStateCreateInfo memberstippledLineEnableset toVK_TRUE. -
VK_DYNAMIC_STATE_CULL_MODEspecifies that thecullModestate in VkPipelineRasterizationStateCreateInfo will be ignored and must be set dynamically with vkCmdSetCullMode before any drawing commands. -
VK_DYNAMIC_STATE_FRONT_FACEspecifies that thefrontFacestate in VkPipelineRasterizationStateCreateInfo will be ignored and must be set dynamically with vkCmdSetFrontFace before any drawing commands. -
VK_DYNAMIC_STATE_PRIMITIVE_TOPOLOGYspecifies that thetopologystate in VkPipelineInputAssemblyStateCreateInfo only specifies the topology class, and the specific topology order and adjacency must be set dynamically with vkCmdSetPrimitiveTopology before any drawing commands. -
VK_DYNAMIC_STATE_VIEWPORT_WITH_COUNTspecifies that theviewportCountandpViewportsstate in VkPipelineViewportStateCreateInfo will be ignored and must be set dynamically with vkCmdSetViewportWithCount before any draw call. -
VK_DYNAMIC_STATE_SCISSOR_WITH_COUNTspecifies that thescissorCountandpScissorsstate in VkPipelineViewportStateCreateInfo will be ignored and must be set dynamically with vkCmdSetScissorWithCount before any draw call. -
VK_DYNAMIC_STATE_VERTEX_INPUT_BINDING_STRIDEspecifies that thestridestate in VkVertexInputBindingDescription will be ignored and must be set dynamically with vkCmdBindVertexBuffers2 before any draw call. -
VK_DYNAMIC_STATE_DEPTH_TEST_ENABLEspecifies that thedepthTestEnablestate in VkPipelineDepthStencilStateCreateInfo will be ignored and must be set dynamically with vkCmdSetDepthTestEnable before any draw call. -
VK_DYNAMIC_STATE_DEPTH_WRITE_ENABLEspecifies that thedepthWriteEnablestate in VkPipelineDepthStencilStateCreateInfo will be ignored and must be set dynamically with vkCmdSetDepthWriteEnable before any draw call. -
VK_DYNAMIC_STATE_DEPTH_COMPARE_OPspecifies that thedepthCompareOpstate in VkPipelineDepthStencilStateCreateInfo will be ignored and must be set dynamically with vkCmdSetDepthCompareOp before any draw call. -
VK_DYNAMIC_STATE_DEPTH_BOUNDS_TEST_ENABLEspecifies that thedepthBoundsTestEnablestate in VkPipelineDepthStencilStateCreateInfo will be ignored and must be set dynamically with vkCmdSetDepthBoundsTestEnable before any draw call. -
VK_DYNAMIC_STATE_STENCIL_TEST_ENABLEspecifies that thestencilTestEnablestate in VkPipelineDepthStencilStateCreateInfo will be ignored and must be set dynamically with vkCmdSetStencilTestEnable before any draw call. -
VK_DYNAMIC_STATE_STENCIL_OPspecifies that thefailOp,passOp,depthFailOp, andcompareOpstates inVkPipelineDepthStencilStateCreateInfofor bothfrontandbackwill be ignored and must be set dynamically with vkCmdSetStencilOp before any draws are performed with a pipeline state withVkPipelineDepthStencilStateCreateInfomemberstencilTestEnableset toVK_TRUE -
VK_DYNAMIC_STATE_PATCH_CONTROL_POINTS_EXTspecifies that thepatchControlPointsstate in VkPipelineTessellationStateCreateInfo will be ignored and must be set dynamically with vkCmdSetPatchControlPointsEXT before any drawing commands. -
VK_DYNAMIC_STATE_RASTERIZER_DISCARD_ENABLEspecifies that therasterizerDiscardEnablestate in VkPipelineRasterizationStateCreateInfo will be ignored and must be set dynamically with vkCmdSetRasterizerDiscardEnable before any drawing commands. -
VK_DYNAMIC_STATE_DEPTH_BIAS_ENABLEspecifies that thedepthBiasEnablestate in VkPipelineRasterizationStateCreateInfo will be ignored and must be set dynamically with vkCmdSetDepthBiasEnable before any drawing commands. -
VK_DYNAMIC_STATE_LOGIC_OP_EXTspecifies that thelogicOpstate in VkPipelineColorBlendStateCreateInfo will be ignored and must be set dynamically with vkCmdSetLogicOpEXT before any drawing commands. -
VK_DYNAMIC_STATE_PRIMITIVE_RESTART_ENABLEspecifies that theprimitiveRestartEnablestate in VkPipelineInputAssemblyStateCreateInfo will be ignored and must be set dynamically with vkCmdSetPrimitiveRestartEnable before any drawing commands. -
VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHRspecifies that state in VkPipelineFragmentShadingRateStateCreateInfoKHR 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_KHRspecifies that the default stack size computation for the pipeline will be ignored and must be set dynamically with vkCmdSetRayTracingPipelineStackSizeKHR before any ray tracing calls are performed. -
VK_DYNAMIC_STATE_VERTEX_INPUT_EXTspecifies that thepVertexInputStatestate will be ignored and must be set dynamically with vkCmdSetVertexInputEXT before any drawing commands -
VK_DYNAMIC_STATE_COLOR_WRITE_ENABLE_EXTspecifies that thepColorWriteEnablesstate in VkPipelineColorWriteCreateInfoEXT will be ignored and must be set dynamically with vkCmdSetColorWriteEnableEXT before any draw call. -
VK_DYNAMIC_STATE_TESSELLATION_DOMAIN_ORIGIN_EXTspecifies that thedomainOriginstate in VkPipelineTessellationDomainOriginStateCreateInfo will be ignored and must be set dynamically with vkCmdSetTessellationDomainOriginEXT before any draw call. -
VK_DYNAMIC_STATE_DEPTH_CLAMP_ENABLE_EXTspecifies that thedepthClampEnablestate in VkPipelineRasterizationStateCreateInfo will be ignored and must be set dynamically with vkCmdSetDepthClampEnableEXT before any draw call. -
VK_DYNAMIC_STATE_POLYGON_MODE_EXTspecifies that thepolygonModestate in VkPipelineRasterizationStateCreateInfo will be ignored and must be set dynamically with vkCmdSetPolygonModeEXT before any draw call. -
VK_DYNAMIC_STATE_RASTERIZATION_SAMPLES_EXTspecifies that therasterizationSamplesstate in VkPipelineMultisampleStateCreateInfo will be ignored and must be set dynamically with vkCmdSetRasterizationSamplesEXT before any draw call. -
VK_DYNAMIC_STATE_SAMPLE_MASK_EXTspecifies that thepSampleMaskstate in VkPipelineMultisampleStateCreateInfo will be ignored and must be set dynamically with vkCmdSetSampleMaskEXT before any draw call. -
VK_DYNAMIC_STATE_ALPHA_TO_COVERAGE_ENABLE_EXTspecifies that thealphaToCoverageEnablestate in VkPipelineMultisampleStateCreateInfo will be ignored and must be set dynamically with vkCmdSetAlphaToCoverageEnableEXT before any draw call. -
VK_DYNAMIC_STATE_ALPHA_TO_ONE_ENABLE_EXTspecifies that thealphaToOneEnablestate in VkPipelineMultisampleStateCreateInfo will be ignored and must be set dynamically with vkCmdSetAlphaToOneEnableEXT before any draw call. -
VK_DYNAMIC_STATE_LOGIC_OP_ENABLE_EXTspecifies that thelogicOpEnablestate in VkPipelineColorBlendStateCreateInfo will be ignored and must be set dynamically with vkCmdSetLogicOpEnableEXT before any draw call. -
VK_DYNAMIC_STATE_COLOR_BLEND_ENABLE_EXTspecifies that theblendEnablestate in VkPipelineColorBlendAttachmentState will be ignored and must be set dynamically with vkCmdSetColorBlendEnableEXT before any draw call. -
VK_DYNAMIC_STATE_COLOR_BLEND_EQUATION_EXTspecifies that thesrcColorBlendFactor,dstColorBlendFactor,colorBlendOp,srcAlphaBlendFactor,dstAlphaBlendFactor, andalphaBlendOpstates in VkPipelineColorBlendAttachmentState will be ignored and must be set dynamically with vkCmdSetColorBlendEquationEXT before any draw call. -
VK_DYNAMIC_STATE_COLOR_WRITE_MASK_EXTspecifies that thecolorWriteMaskstate in VkPipelineColorBlendAttachmentState will be ignored and must be set dynamically with vkCmdSetColorWriteMaskEXT before any draw call. -
VK_DYNAMIC_STATE_RASTERIZATION_STREAM_EXTspecifies that therasterizationStreamstate in VkPipelineRasterizationStateStreamCreateInfoEXT will be ignored and must be set dynamically with vkCmdSetRasterizationStreamEXT before any draw call. -
VK_DYNAMIC_STATE_CONSERVATIVE_RASTERIZATION_MODE_EXTspecifies that theconservativeRasterizationModestate in VkPipelineRasterizationConservativeStateCreateInfoEXT will be ignored and must be set dynamically with vkCmdSetConservativeRasterizationModeEXT before any draw call. -
VK_DYNAMIC_STATE_EXTRA_PRIMITIVE_OVERESTIMATION_SIZE_EXTspecifies that theextraPrimitiveOverestimationSizestate in VkPipelineRasterizationConservativeStateCreateInfoEXT will be ignored and must be set dynamically with vkCmdSetExtraPrimitiveOverestimationSizeEXT before any draw call. -
VK_DYNAMIC_STATE_DEPTH_CLIP_ENABLE_EXTspecifies that thedepthClipEnablestate in VkPipelineRasterizationDepthClipStateCreateInfoEXT will be ignored and must be set dynamically with vkCmdSetDepthClipEnableEXT before any draw call. -
VK_DYNAMIC_STATE_SAMPLE_LOCATIONS_ENABLE_EXTspecifies that thesampleLocationsEnablestate in VkPipelineSampleLocationsStateCreateInfoEXT will be ignored and must be set dynamically with vkCmdSetSampleLocationsEnableEXT before any draw call. -
VK_DYNAMIC_STATE_COLOR_BLEND_ADVANCED_EXTspecifies that thecolorBlendOpstate in VkPipelineColorBlendAttachmentState, andsrcPremultiplied,dstPremultiplied, andblendOverlapstates in VkPipelineColorBlendAdvancedStateCreateInfoEXT will be ignored and must be set dynamically with vkCmdSetColorBlendAdvancedEXT before any draw call. -
VK_DYNAMIC_STATE_PROVOKING_VERTEX_MODE_EXTspecifies that theprovokingVertexModestate in VkPipelineRasterizationProvokingVertexStateCreateInfoEXT will be ignored and must be set dynamically with vkCmdSetProvokingVertexModeEXT before any draw call. -
VK_DYNAMIC_STATE_LINE_RASTERIZATION_MODE_EXTspecifies that thelineRasterizationModestate in VkPipelineRasterizationLineStateCreateInfo will be ignored and must be set dynamically with vkCmdSetLineRasterizationModeEXT before any draw call. -
VK_DYNAMIC_STATE_LINE_STIPPLE_ENABLE_EXTspecifies that thestippledLineEnablestate in VkPipelineRasterizationLineStateCreateInfo will be ignored and must be set dynamically with vkCmdSetLineStippleEnableEXT before any draw call. -
VK_DYNAMIC_STATE_DEPTH_CLIP_NEGATIVE_ONE_TO_ONE_EXTspecifies that thenegativeOneToOnestate in VkPipelineViewportDepthClipControlCreateInfoEXT will be ignored and must be set dynamically with vkCmdSetDepthClipNegativeOneToOneEXT before any draw call. -
VK_DYNAMIC_STATE_DEPTH_CLAMP_RANGE_EXTspecifies that thedepthClampModeandpDepthClampRangestate in VkPipelineViewportDepthClampControlCreateInfoEXT will be ignored and must be set dynamically with vkCmdSetDepthClampRangeEXT before any draw call. -
VK_DYNAMIC_STATE_VIEWPORT_W_SCALING_ENABLE_NVspecifies that theviewportWScalingEnablestate in VkPipelineViewportWScalingStateCreateInfoNV will be ignored and must be set dynamically with vkCmdSetViewportWScalingEnableNV before any draw call. -
VK_DYNAMIC_STATE_VIEWPORT_SWIZZLE_NVspecifies that theviewportCount, andpViewportSwizzlesstates in VkPipelineViewportSwizzleStateCreateInfoNV will be ignored and must be set dynamically with vkCmdSetViewportSwizzleNV before any draw call. -
VK_DYNAMIC_STATE_COVERAGE_TO_COLOR_ENABLE_NVspecifies that thecoverageToColorEnablestate in VkPipelineCoverageToColorStateCreateInfoNV will be ignored and must be set dynamically with vkCmdSetCoverageToColorEnableNV before any draw call. -
VK_DYNAMIC_STATE_COVERAGE_TO_COLOR_LOCATION_NVspecifies that thecoverageToColorLocationstate in VkPipelineCoverageToColorStateCreateInfoNV will be ignored and must be set dynamically with vkCmdSetCoverageToColorLocationNV before any draw call. -
VK_DYNAMIC_STATE_COVERAGE_MODULATION_MODE_NVspecifies that thecoverageModulationModestate in VkPipelineCoverageModulationStateCreateInfoNV will be ignored and must be set dynamically with vkCmdSetCoverageModulationModeNV before any draw call. -
VK_DYNAMIC_STATE_COVERAGE_MODULATION_TABLE_ENABLE_NVspecifies that thecoverageModulationTableEnablestate in VkPipelineCoverageModulationStateCreateInfoNV will be ignored and must be set dynamically with vkCmdSetCoverageModulationTableEnableNV before any draw call. -
VK_DYNAMIC_STATE_COVERAGE_MODULATION_TABLE_NVspecifies that thecoverageModulationTableCount, andpCoverageModulationTablestates in VkPipelineCoverageModulationStateCreateInfoNV will be ignored and must be set dynamically with vkCmdSetCoverageModulationTableNV before any draw call. -
VK_DYNAMIC_STATE_SHADING_RATE_IMAGE_ENABLE_NVspecifies that theshadingRateImageEnablestate in VkPipelineViewportShadingRateImageStateCreateInfoNV will be ignored and must be set dynamically with vkCmdSetShadingRateImageEnableNV before any draw call. -
VK_DYNAMIC_STATE_REPRESENTATIVE_FRAGMENT_TEST_ENABLE_NVspecifies that therepresentativeFragmentTestEnablestate in VkPipelineRepresentativeFragmentTestStateCreateInfoNV will be ignored and must be set dynamically with vkCmdSetRepresentativeFragmentTestEnableNV before any draw call. -
VK_DYNAMIC_STATE_COVERAGE_REDUCTION_MODE_NVspecifies that thecoverageReductionModestate in VkPipelineCoverageReductionStateCreateInfoNV will be ignored and must be set dynamically with vkCmdSetCoverageReductionModeNV before any draw call. -
VK_DYNAMIC_STATE_ATTACHMENT_FEEDBACK_LOOP_ENABLE_EXTspecifies that theVK_PIPELINE_CREATE_COLOR_ATTACHMENT_FEEDBACK_LOOP_BIT_EXTandVK_PIPELINE_CREATE_DEPTH_STENCIL_ATTACHMENT_FEEDBACK_LOOP_BIT_EXTflags 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;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
groupCountis the number of elements in thepGroupsarray. -
pGroupsis a pointer to an array of VkGraphicsShaderGroupCreateInfoNV structures specifying which state of the original VkGraphicsPipelineCreateInfo each shader group overrides. -
pipelineCountis the number of elements in thepPipelinesarray. -
pPipelinesis a pointer to an array of graphicsVkPipelinestructures 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;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
stageCountis the number of entries in thepStagesarray. -
pStagesis a pointer to an array VkPipelineShaderStageCreateInfo structures specifying the set of the shader stages to be included in this shader group. -
pVertexInputStateis a pointer to a VkPipelineVertexInputStateCreateInfo structure. -
pTessellationStateis 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_KHRTo 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);-
deviceis the logical device that creates the ray tracing pipelines. -
pipelineCacheis either VK_NULL_HANDLE, indicating that pipeline caching is disabled, or the handle of a valid pipeline cache object, in which case use of that cache is enabled for the duration of the command. -
createInfoCountis the length of thepCreateInfosandpPipelinesarrays. -
pCreateInfosis a pointer to an array of VkRayTracingPipelineCreateInfoNV structures. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter. -
pPipelinesis a pointer to an array in which the resulting ray tracing pipeline objects are returned.
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);-
deviceis the logical device that creates the ray tracing pipelines. -
deferredOperationis VK_NULL_HANDLE or the handle of a valid VkDeferredOperationKHR request deferral object for this command. -
pipelineCacheis either VK_NULL_HANDLE, indicating that pipeline caching is disabled, or the handle of a valid pipeline cache object, in which case use of that cache is enabled for the duration of the command. -
createInfoCountis the length of thepCreateInfosandpPipelinesarrays. -
pCreateInfosis a pointer to an array of VkRayTracingPipelineCreateInfoKHR structures. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter. -
pPipelinesis a pointer to an array in which the resulting ray tracing pipeline objects are returned.
The VK_ERROR_INVALID_OPAQUE_CAPTURE_ADDRESS error is returned if the
implementation is unable to 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;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis a bitmask of VkPipelineCreateFlagBits specifying how the pipeline will be generated. -
stageCountis the number of entries in thepStagesarray. -
pStagesis a pointer to an array of VkPipelineShaderStageCreateInfo structures specifying the set of the shader stages to be included in the ray tracing pipeline. -
groupCountis the number of entries in thepGroupsarray. -
pGroupsis a pointer to an array of VkRayTracingShaderGroupCreateInfoNV structures describing the set of the shader stages to be included in each shader group in the ray tracing pipeline. -
maxRecursionDepthis the maximum recursion depth of shaders executed by this pipeline. -
layoutis the description of binding locations used by both the pipeline and descriptor sets used with the pipeline. -
basePipelineHandleis a pipeline to derive from. -
basePipelineIndexis an index into thepCreateInfosparameter to use as a pipeline to derive from.
The parameters basePipelineHandle and basePipelineIndex are
described in more detail in Pipeline Derivatives.
If the pNext chain includes a VkPipelineCreateFlags2CreateInfo
structure, VkPipelineCreateFlags2CreateInfo::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;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis a bitmask of VkPipelineCreateFlagBits specifying how the pipeline will be generated. -
stageCountis the number of entries in thepStagesarray. -
pStagesis a pointer to an array ofstageCountVkPipelineShaderStageCreateInfo structures describing the set of the shader stages to be included in the ray tracing pipeline. -
groupCountis the number of entries in thepGroupsarray. -
pGroupsis a pointer to an array ofgroupCountVkRayTracingShaderGroupCreateInfoKHR structures describing the set of the shader stages to be included in each shader group in the ray tracing pipeline. -
maxPipelineRayRecursionDepthis the maximum recursion depth of shaders executed by this pipeline. -
pLibraryInfois a pointer to a VkPipelineLibraryCreateInfoKHR structure defining pipeline libraries to include. -
pLibraryInterfaceis a pointer to a VkRayTracingPipelineInterfaceCreateInfoKHR structure defining additional information when using pipeline libraries. -
pDynamicStateis a pointer to a VkPipelineDynamicStateCreateInfo structure, and is used to indicate which properties of the pipeline state object are dynamic and can be changed independently of the pipeline state. This can beNULL, which means no state in the pipeline is considered dynamic. -
layoutis the description of binding locations used by both the pipeline and descriptor sets used with the pipeline. -
basePipelineHandleis a pipeline to derive from. -
basePipelineIndexis an index into thepCreateInfosparameter to use as a pipeline to derive from.
The parameters basePipelineHandle and basePipelineIndex are
described in more detail in Pipeline Derivatives.
When VK_PIPELINE_CREATE_LIBRARY_BIT_KHR is specified, this pipeline
defines a pipeline library which cannot be bound as a ray tracing
pipeline directly.
Instead, pipeline libraries define common shaders and shader groups which
can be included in future pipeline creation.
If pipeline libraries are included in pLibraryInfo, shaders defined in
those libraries are treated as if they were defined as additional entries in
pStages, appended in the order they appear in the pLibraries
array and in the pStages array when those libraries were defined.
When referencing shader groups in order to obtain a shader group handle,
groups defined in those libraries are treated as if they were defined as
additional entries in pGroups, appended in the order they appear in
the pLibraries array and in the pGroups array when those
libraries were defined.
The shaders these groups reference are set when the pipeline library is
created, referencing those specified in the pipeline library, not in the
pipeline that includes it.
The default stack size for a pipeline if
VK_DYNAMIC_STATE_RAY_TRACING_PIPELINE_STACK_SIZE_KHR is not provided
is computed as described in Ray Tracing Pipeline Stack.
If the pNext chain includes a VkPipelineCreateFlags2CreateInfo
structure, VkPipelineCreateFlags2CreateInfo::flags from that
structure is used instead of flags from this structure.
If the pNext chain includes a
VkRayTracingPipelineClusterAccelerationStructureCreateInfoNV
structure, then that structure controls whether cluster acceleration
structures are allowed in this ray tracing pipeline.
The VkRayTracingPipelineClusterAccelerationStructureCreateInfoNV structure is defined as:
// Provided by VK_KHR_ray_tracing_pipeline with VK_NV_cluster_acceleration_structure
typedef struct VkRayTracingPipelineClusterAccelerationStructureCreateInfoNV {
VkStructureType sType;
void* pNext;
VkBool32 allowClusterAccelerationStructure;
} VkRayTracingPipelineClusterAccelerationStructureCreateInfoNV;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
allowClusterAccelerationStructurecontrols if cluster acceleration structures are allowed in the ray tracing pipeline.
If no cluster acceleration structures are present in the ray tracing
pipeline, allowClusterAccelerationStructure should not be used to
prevent traversal penalty on some implementations.
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;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
typeis the type of hit group specified in this structure. -
generalShaderis the index of the ray generation, miss, or callable shader from VkRayTracingPipelineCreateInfoNV::pStagesin the group if the shader group hastypeofVK_RAY_TRACING_SHADER_GROUP_TYPE_GENERAL_NV, andVK_SHADER_UNUSED_NVotherwise. -
closestHitShaderis the optional index of the closest hit shader from VkRayTracingPipelineCreateInfoNV::pStagesin the group if the shader group hastypeofVK_RAY_TRACING_SHADER_GROUP_TYPE_TRIANGLES_HIT_GROUP_NVorVK_RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_NV, andVK_SHADER_UNUSED_NVotherwise. -
anyHitShaderis the optional index of the any-hit shader from VkRayTracingPipelineCreateInfoNV::pStagesin the group if the shader group hastypeofVK_RAY_TRACING_SHADER_GROUP_TYPE_TRIANGLES_HIT_GROUP_NVorVK_RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_NV, andVK_SHADER_UNUSED_NVotherwise. -
intersectionShaderis the index of the intersection shader from VkRayTracingPipelineCreateInfoNV::pStagesin the group if the shader group hastypeofVK_RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_NV, andVK_SHADER_UNUSED_NVotherwise.
The VkRayTracingShaderGroupCreateInfoKHR structure is defined as:
// Provided by VK_KHR_ray_tracing_pipeline
typedef struct VkRayTracingShaderGroupCreateInfoKHR {
VkStructureType sType;
const void* pNext;
VkRayTracingShaderGroupTypeKHR type;
uint32_t generalShader;
uint32_t closestHitShader;
uint32_t anyHitShader;
uint32_t intersectionShader;
const void* pShaderGroupCaptureReplayHandle;
} VkRayTracingShaderGroupCreateInfoKHR;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
typeis the type of hit group specified in this structure. -
generalShaderis the index of the ray generation, miss, or callable shader from VkRayTracingPipelineCreateInfoKHR::pStagesin the group if the shader group hastypeofVK_RAY_TRACING_SHADER_GROUP_TYPE_GENERAL_KHR, andVK_SHADER_UNUSED_KHRotherwise. -
closestHitShaderis the optional index of the closest hit shader from VkRayTracingPipelineCreateInfoKHR::pStagesin the group if the shader group hastypeofVK_RAY_TRACING_SHADER_GROUP_TYPE_TRIANGLES_HIT_GROUP_KHRorVK_RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_KHR, andVK_SHADER_UNUSED_KHRotherwise. -
anyHitShaderis the optional index of the any-hit shader from VkRayTracingPipelineCreateInfoKHR::pStagesin the group if the shader group hastypeofVK_RAY_TRACING_SHADER_GROUP_TYPE_TRIANGLES_HIT_GROUP_KHRorVK_RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_KHR, andVK_SHADER_UNUSED_KHRotherwise. -
intersectionShaderis the index of the intersection shader from VkRayTracingPipelineCreateInfoKHR::pStagesin the group if the shader group hastypeofVK_RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_KHR, andVK_SHADER_UNUSED_KHRotherwise. -
pShaderGroupCaptureReplayHandleisNULLor a pointer to replay information for this shader group queried from vkGetRayTracingCaptureReplayShaderGroupHandlesKHR, as described in Ray Tracing Capture Replay. Ignored if VkPhysicalDeviceRayTracingPipelineFeaturesKHR::rayTracingPipelineShaderGroupHandleCaptureReplayisVK_FALSE.
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_KHRspecifies that a shader group with a singleVK_SHADER_STAGE_RAYGEN_BIT_KHR,VK_SHADER_STAGE_MISS_BIT_KHR, orVK_SHADER_STAGE_CALLABLE_BIT_KHRshader in it. -
VK_RAY_TRACING_SHADER_GROUP_TYPE_TRIANGLES_HIT_GROUP_KHRspecifies that a shader group that only hits triangles and must not contain an intersection shader, only closest hit and any-hit shaders. -
VK_RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_KHRspecifies that 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;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
maxPipelineRayPayloadSizeis the maximum payload size in bytes used by any shader in the pipeline. -
maxPipelineRayHitAttributeSizeis the maximum attribute structure size in bytes used by any shader in the pipeline.
maxPipelineRayPayloadSize is calculated as the maximum size of the
block (in bytes) declared in the RayPayloadKHR or
IncomingRayPayloadKHR storage classes.
maxPipelineRayHitAttributeSize is calculated as the maximum size of
any block (in bytes) 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);-
deviceis the logical device containing the ray tracing pipeline. -
pipelineis the ray tracing pipeline object containing the shaders. -
firstGroupis the index of the first group to retrieve a handle for from the VkRayTracingPipelineCreateInfoKHR::pGroupsor VkRayTracingPipelineCreateInfoNV::pGroupsarray. -
groupCountis the number of shader handles to retrieve. -
dataSizeis the size in bytes of the buffer pointed to bypData. -
pDatais 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);-
deviceis the logical device containing the ray tracing pipeline. -
pipelineis the ray tracing pipeline object containing the shaders. -
firstGroupis the index of the first group to retrieve a handle for from the VkRayTracingPipelineCreateInfoKHR::pGroupsarray. -
groupCountis the number of shader handles to retrieve. -
dataSizeis the size in bytes of the buffer pointed to bypData. -
pDatais a pointer to 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);-
deviceis the logical device containing the ray tracing pipeline. -
pipelineis the ray tracing pipeline object containing the shaders. -
shaderis 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);-
deviceis the logical device containing the ray tracing pipeline. -
pipelineis the ray tracing pipeline object containing the shaders groups. -
groupis the index of the shader group to query. -
groupShaderis the type of shader from the group to query.
The return value is the ray tracing pipeline stack size in bytes for the specified shader as called from the specified shader group.
Possible values of groupShader in
vkGetRayTracingShaderGroupStackSizeKHR are:
// Provided by VK_KHR_ray_tracing_pipeline
typedef enum VkShaderGroupShaderKHR {
VK_SHADER_GROUP_SHADER_GENERAL_KHR = 0,
VK_SHADER_GROUP_SHADER_CLOSEST_HIT_KHR = 1,
VK_SHADER_GROUP_SHADER_ANY_HIT_KHR = 2,
VK_SHADER_GROUP_SHADER_INTERSECTION_KHR = 3,
} VkShaderGroupShaderKHR;-
VK_SHADER_GROUP_SHADER_GENERAL_KHRuses the shader specified in the group with VkRayTracingShaderGroupCreateInfoKHR::generalShader -
VK_SHADER_GROUP_SHADER_CLOSEST_HIT_KHRuses the shader specified in the group with VkRayTracingShaderGroupCreateInfoKHR::closestHitShader -
VK_SHADER_GROUP_SHADER_ANY_HIT_KHRuses the shader specified in the group with VkRayTracingShaderGroupCreateInfoKHR::anyHitShader -
VK_SHADER_GROUP_SHADER_INTERSECTION_KHRuses the shader specified in the group with VkRayTracingShaderGroupCreateInfoKHR::intersectionShader
To dynamically set the stack size for a ray tracing pipeline, call:
// Provided by VK_KHR_ray_tracing_pipeline
void vkCmdSetRayTracingPipelineStackSizeKHR(
VkCommandBuffer commandBuffer,
uint32_t pipelineStackSize);-
commandBufferis the command buffer into which the command will be recorded. -
pipelineStackSizeis the stack size to use for subsequent ray tracing trace commands.
This command sets the stack size for subsequent ray tracing commands when
the ray tracing pipeline is created with
VK_DYNAMIC_STATE_RAY_TRACING_PIPELINE_STACK_SIZE_KHR set in
VkPipelineDynamicStateCreateInfo::pDynamicStates.
Otherwise, the stack size is computed as described in
Ray Tracing Pipeline Stack.
Pipeline Destruction
To destroy a pipeline, call:
// Provided by VK_VERSION_1_0
void vkDestroyPipeline(
VkDevice device,
VkPipeline pipeline,
const VkAllocationCallbacks* pAllocator);-
deviceis the logical device that destroys the pipeline. -
pipelineis the handle of the pipeline to destroy. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter.
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);-
deviceis the logical device that creates the pipeline cache object. -
pCreateInfois a pointer to a VkPipelineCacheCreateInfo structure containing initial parameters for the pipeline cache object. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter. -
pPipelineCacheis a pointer to a VkPipelineCache handle in which the resulting pipeline cache object is returned.
|
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;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis a bitmask of VkPipelineCacheCreateFlagBits specifying the behavior of the pipeline cache. -
initialDataSizeis the number of bytes inpInitialData. IfinitialDataSizeis zero, the pipeline cache will initially be empty. -
pInitialDatais a pointer to previously retrieved pipeline cache data. If the pipeline cache data is incompatible (as defined below) with the device, the pipeline cache will be initially empty. IfinitialDataSizeis zero,pInitialDatais ignored.
// Provided by VK_VERSION_1_0
typedef VkFlags VkPipelineCacheCreateFlags;VkPipelineCacheCreateFlags is a bitmask type for setting a mask of
zero or more VkPipelineCacheCreateFlagBits.
Bits which can be set in VkPipelineCacheCreateInfo::flags,
specifying behavior of the pipeline cache, are:
// 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_KHR_maintenance8
VK_PIPELINE_CACHE_CREATE_INTERNALLY_SYNCHRONIZED_MERGE_BIT_KHR = 0x00000008,
// 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_BITspecifies that all commands that modify the created VkPipelineCache will be externally synchronized. When set, the implementation may skip any unnecessary processing needed to support simultaneous modification from multiple threads where allowed. -
VK_PIPELINE_CACHE_CREATE_INTERNALLY_SYNCHRONIZED_MERGE_BIT_KHRspecifies that when the created VkPipelineCache is used as thedstCacheparameter of vkMergePipelineCaches, it does not need to be externally synchronized. This flag is mutually exclusive withVK_PIPELINE_CACHE_CREATE_EXTERNALLY_SYNCHRONIZED_BIT.
Merging Pipeline Caches
Pipeline cache objects can be merged using the command:
// Provided by VK_VERSION_1_0
VkResult vkMergePipelineCaches(
VkDevice device,
VkPipelineCache dstCache,
uint32_t srcCacheCount,
const VkPipelineCache* pSrcCaches);-
deviceis the logical device that owns the pipeline cache objects. -
dstCacheis the handle of the pipeline cache to merge results into. -
srcCacheCountis the length of thepSrcCachesarray. -
pSrcCachesis a pointer to an array of pipeline cache handles, which will be merged intodstCache. The previous contents ofdstCacheare included after the merge.
|
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);-
deviceis the logical device that owns the pipeline cache. -
pipelineCacheis the pipeline cache to retrieve data from. -
pDataSizeis a pointer to asize_tvalue related to the amount of data in the pipeline cache, as described below. -
pDatais eitherNULLor a pointer to a buffer.
If pData is NULL, then the maximum size of the data that can be
retrieved from the pipeline cache, in bytes, is returned in pDataSize.
Otherwise, pDataSize must point to a variable set by the 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;-
headerSizeis the length in bytes of the pipeline cache header. -
headerVersionis 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.headerVersionmust be written as exactly 4 bytes. -
vendorIDis theVkPhysicalDeviceProperties::vendorIDof the implementation. -
deviceIDis theVkPhysicalDeviceProperties::deviceIDof the implementation. -
pipelineCacheUUIDis theVkPhysicalDeviceProperties::pipelineCacheUUIDof the implementation.
Unlike most structures declared by the Vulkan API, all fields of this structure are written with the least significant byte first, regardless of host byte-order.
The C language specification does not define the packing of structure members. This layout assumes tight structure member packing, with members laid out in the order listed in the structure, and the intended size of the structure is 32 bytes. If a compiler produces code that diverges from that pattern, applications must employ another method to set values at the correct offsets.
Possible values of the headerVersion value of the pipeline cache
header are:
// Provided by VK_VERSION_1_0
typedef enum VkPipelineCacheHeaderVersion {
VK_PIPELINE_CACHE_HEADER_VERSION_ONE = 1,
} VkPipelineCacheHeaderVersion;-
VK_PIPELINE_CACHE_HEADER_VERSION_ONEspecifies version one of the pipeline cache, 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);-
deviceis the logical device that destroys the pipeline cache object. -
pipelineCacheis the handle of the pipeline cache to destroy. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter.
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);-
deviceis the logical device that creates the pipeline object. -
pPipelineCreateInfoisNULLor a pointer to a VkPipelineCreateInfoKHR structure. -
pPipelineKeyis 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;-
sTypeis a VkStructureType value identifying this structure. -
pNextis 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;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
keySizeis the size, in bytes, of valid data returned inkey. -
keyis 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 32UCreating 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);-
deviceis the logical device that creates the pipeline binary objects. -
pCreateInfois a pointer to a VkPipelineBinaryCreateInfoKHR structure that contains the data to create the pipeline binaries from. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter. -
pBinariesis 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
pPipelineBinariesoutput array will be filled with VK_NULL_HANDLE. -
The
VkResultreturned by vkCreatePipelineBinariesKHR will contain the error value for the first entry in the output array inpBinariescontaining 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;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
pipelineBinaryCountis the number of binaries associated with this pipeline or the number of entries in thepPipelineBinariesarray. -
pPipelineBinariesisNULLor 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;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
pKeysAndDataInfoisNULLor a pointer to a VkPipelineBinaryKeysAndDataKHR structure that contains keys and data to create the pipeline binaries from. -
pipelineis VK_NULL_HANDLE or aVkPipelinethat contains data to create the pipeline binaries from. -
pPipelineCreateInfoisNULLor 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;-
binaryCountis the size of thepPipelineBinaryKeysandpPipelineBinaryDataarrays -
pPipelineBinaryKeysis a pointer to an array of VkPipelineBinaryKeyKHR structures containing the pipeline binary keys -
pPipelineBinaryDatais 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;-
dataSizeis the size of thepDatabuffer in bytes. -
pDatais a pointer to a buffer ofsizebytes 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);-
deviceis the logical device that created the pipeline binary. -
pInfois a pointer to a VkPipelineBinaryDataInfoKHR structure which describes the pipeline binary to get data from. -
pPipelineBinaryKeyis a pointer to a VkPipelineBinaryKeyKHR structure where the key for this binary will be written. -
pPipelineBinaryDataSizeis a pointer to asize_tvalue related to the amount of data in the pipeline binary, as described below. -
pPipelineBinaryDatais eitherNULLor 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 the call returns one of the success return codes, the pipeline binary key
is written to pPipelineBinaryKey, regardless of whether
pPipelineBinaryData is NULL or not.
If pipelineBinaryCompressedData is
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;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
pipelineBinaryis 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);-
deviceis the logical device that created the pipeline object. -
pInfois a pointer to a VkReleaseCapturedPipelineDataInfoKHR structure which describes the pipeline to release the data from. -
pAllocatorcontrols 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;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
pipelinethe 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);-
deviceis the logical device that created the pipeline binary object. -
pipelineBinaryis the handle of the pipeline binary object to destroy. -
pAllocatorcontrols 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;-
mapEntryCountis the number of entries in thepMapEntriesarray. -
pMapEntriesis a pointer to an array ofVkSpecializationMapEntrystructures, which map constant IDs to offsets inpData. -
dataSizeis the byte size of thepDatabuffer. -
pDatacontains the actual constant values to specialize with.
The VkSpecializationMapEntry structure is defined as:
// Provided by VK_VERSION_1_0
typedef struct VkSpecializationMapEntry {
uint32_t constantID;
uint32_t offset;
size_t size;
} VkSpecializationMapEntry;-
constantIDis the ID of the specialization constant in SPIR-V. -
offsetis the byte offset of the specialization constant value within the supplied data buffer. -
sizeis the byte size of the specialization constant value within the supplied data buffer.
If a constantID value is not a specialization constant ID used in the
shader, that map entry does not affect the behavior of the pipeline.
In human readable SPIR-V:
OpDecorate %x SpecId 13 ; decorate .x component of WorkgroupSize with ID 13
OpDecorate %y SpecId 42 ; decorate .y component of WorkgroupSize with ID 42
OpDecorate %z SpecId 3 ; decorate .z component of WorkgroupSize with ID 3
OpDecorate %wgsize BuiltIn WorkgroupSize ; decorate WorkgroupSize onto constant
%i32 = OpTypeInt 32 0 ; declare an unsigned 32-bit type
%uvec3 = OpTypeVector %i32 3 ; declare a 3 element vector type of unsigned 32-bit
%x = OpSpecConstant %i32 1 ; declare the .x component of WorkgroupSize
%y = OpSpecConstant %i32 1 ; declare the .y component of WorkgroupSize
%z = OpSpecConstant %i32 1 ; declare the .z component of WorkgroupSize
%wgsize = OpSpecConstantComposite %uvec3 %x %y %z ; declare WorkgroupSizeFrom the above we have three specialization constants, one for each of the x, y and 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 constantFrom the above we have two specialization constants, one is a signed 32-bit integer and the second is a 32-bit floating-point value.
Now to specialize the above via the specialization constants mechanism:
struct SpecializationData {
int32_t data0;
float data1;
};
const VkSpecializationMapEntry entries[] =
{
{
.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;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
libraryCountis the number of pipeline libraries inpLibraries. -
pLibrariesis a pointer to an array of VkPipeline structures specifying pipeline libraries to use when creating a pipeline.
Pipelines created with VK_PIPELINE_CREATE_LIBRARY_BIT_KHR libraries
can depend on other pipeline libraries in
VkPipelineLibraryCreateInfoKHR.
A pipeline library is considered in-use, as long as one of the linking pipelines is in-use. This applies recursively if a pipeline library includes other pipeline libraries.
Pipeline Binding
Once a pipeline has been created, it can be bound to the command buffer using the command:
// Provided by VK_VERSION_1_0
void vkCmdBindPipeline(
VkCommandBuffer commandBuffer,
VkPipelineBindPoint pipelineBindPoint,
VkPipeline pipeline);-
commandBufferis the command buffer that the pipeline will be bound to. -
pipelineBindPointis a VkPipelineBindPoint value specifying to which bind point the pipeline is bound. Binding one does not disturb the others. -
pipelineis the pipeline to be bound.
Once bound, a pipeline binding affects subsequent commands that interact with the given pipeline type in the command buffer until a different pipeline of the same type is bound to the bind point, 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_COMPUTEspecifies binding as a compute pipeline. -
VK_PIPELINE_BIND_POINT_GRAPHICSspecifies binding as a graphics pipeline. -
VK_PIPELINE_BIND_POINT_RAY_TRACING_KHRspecifies binding as a ray tracing pipeline. -
VK_PIPELINE_BIND_POINT_SUBPASS_SHADING_HUAWEIspecifies binding as a subpass shading pipeline. -
VK_PIPELINE_BIND_POINT_EXECUTION_GRAPH_AMDXspecifies 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);-
commandBufferis the command buffer that the pipeline will be bound to. -
pipelineBindPointis a VkPipelineBindPoint value specifying the bind point to which the pipeline will be bound. -
pipelineis the pipeline to be bound. -
groupIndexis 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
NULLor 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);-
deviceis the device that created the pipeline. -
pPipelineInfodescribes the pipeline being queried. -
pExecutableCountis a pointer to an integer related to the number of pipeline executables available or queried, as described below. -
pPropertiesis eitherNULLor a pointer to an array of VkPipelineExecutablePropertiesKHR structures.
If pProperties is NULL, then the number of pipeline executables
associated with the pipeline is returned in pExecutableCount.
Otherwise, pExecutableCount must point to a variable set by the
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;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
stagesis a bitmask of zero or more VkShaderStageFlagBits indicating which shader stages (if any) were principally used as inputs to compile this pipeline executable. -
nameis an array ofVK_MAX_DESCRIPTION_SIZEcharcontaining a null-terminated UTF-8 string which is a short human readable name for this pipeline executable. -
descriptionis an array ofVK_MAX_DESCRIPTION_SIZEcharcontaining a null-terminated UTF-8 string which is a human readable description for this pipeline executable. -
subgroupSizeis the subgroup size with which this pipeline executable is dispatched.
Not all implementations have a 1:1 mapping between shader stages and
pipeline executables and some implementations may reduce a given shader
stage to fixed function hardware programming such that no pipeline
executable is available.
No guarantees are provided about the mapping between shader stages and
pipeline executables and stages should be considered a best effort
hint.
Because the application cannot rely on the stages field to provide an
exact description, name and description provide a human readable
name and description which more accurately describes the given pipeline
executable.
To query the pipeline properties call:
// Provided by VK_EXT_pipeline_properties
VkResult vkGetPipelinePropertiesEXT(
VkDevice device,
const VkPipelineInfoEXT* pPipelineInfo,
VkBaseOutStructure* pPipelineProperties);-
deviceis the logical device that created the pipeline. -
pPipelineInfois a pointer to a VkPipelineInfoEXT structure which describes the pipeline being queried. -
pPipelinePropertiesis 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;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
pipelineIdentifieris an array ofVK_UUID_SIZEuint8_tvalues 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;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
pipelineis aVkPipelinehandle.
Each pipeline executable may have a set of statistics associated with it that are generated by the pipeline compilation process. These statistics may include things such as instruction counts, amount of spilling (if any), maximum number of simultaneous threads, or anything else which may aid developers in evaluating the expected performance of a shader. To query the compile time statistics associated with a pipeline executable, call:
// Provided by VK_KHR_pipeline_executable_properties
VkResult vkGetPipelineExecutableStatisticsKHR(
VkDevice device,
const VkPipelineExecutableInfoKHR* pExecutableInfo,
uint32_t* pStatisticCount,
VkPipelineExecutableStatisticKHR* pStatistics);-
deviceis the device that created the pipeline. -
pExecutableInfodescribes the pipeline executable being queried. -
pStatisticCountis a pointer to an integer related to the number of statistics available or queried, as described below. -
pStatisticsis eitherNULLor a pointer to an array of VkPipelineExecutableStatisticKHR structures.
If pStatistics is NULL, then the number of statistics associated
with the pipeline executable is returned in pStatisticCount.
Otherwise, pStatisticCount must point to a variable set by the
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;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
pipelineis the pipeline to query. -
executableIndexis the index of the pipeline executable to query in the array of executable properties returned by vkGetPipelineExecutablePropertiesKHR.
The VkPipelineExecutableStatisticKHR structure is defined as:
// Provided by VK_KHR_pipeline_executable_properties
typedef struct VkPipelineExecutableStatisticKHR {
VkStructureType sType;
void* pNext;
char name[VK_MAX_DESCRIPTION_SIZE];
char description[VK_MAX_DESCRIPTION_SIZE];
VkPipelineExecutableStatisticFormatKHR format;
VkPipelineExecutableStatisticValueKHR value;
} VkPipelineExecutableStatisticKHR;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
nameis an array ofVK_MAX_DESCRIPTION_SIZEcharcontaining a null-terminated UTF-8 string which is a short human readable name for this statistic. -
descriptionis an array ofVK_MAX_DESCRIPTION_SIZEcharcontaining a null-terminated UTF-8 string which is a human readable description for this statistic. -
formatis a VkPipelineExecutableStatisticFormatKHR value specifying the format of the data found invalue. -
valueis the value of this statistic.
The VkPipelineExecutableStatisticFormatKHR enum is defined as:
// Provided by VK_KHR_pipeline_executable_properties
typedef enum VkPipelineExecutableStatisticFormatKHR {
VK_PIPELINE_EXECUTABLE_STATISTIC_FORMAT_BOOL32_KHR = 0,
VK_PIPELINE_EXECUTABLE_STATISTIC_FORMAT_INT64_KHR = 1,
VK_PIPELINE_EXECUTABLE_STATISTIC_FORMAT_UINT64_KHR = 2,
VK_PIPELINE_EXECUTABLE_STATISTIC_FORMAT_FLOAT64_KHR = 3,
} VkPipelineExecutableStatisticFormatKHR;-
VK_PIPELINE_EXECUTABLE_STATISTIC_FORMAT_BOOL32_KHRspecifies that the statistic is returned as a 32-bit boolean value which must be eitherVK_TRUEorVK_FALSEand should be read from theb32field ofVkPipelineExecutableStatisticValueKHR. -
VK_PIPELINE_EXECUTABLE_STATISTIC_FORMAT_INT64_KHRspecifies that the statistic is returned as a signed 64-bit integer and should be read from thei64field ofVkPipelineExecutableStatisticValueKHR. -
VK_PIPELINE_EXECUTABLE_STATISTIC_FORMAT_UINT64_KHRspecifies that the statistic is returned as an unsigned 64-bit integer and should be read from theu64field ofVkPipelineExecutableStatisticValueKHR. -
VK_PIPELINE_EXECUTABLE_STATISTIC_FORMAT_FLOAT64_KHRspecifies that the statistic is returned as a 64-bit floating-point value and should be read from thef64field ofVkPipelineExecutableStatisticValueKHR.
The VkPipelineExecutableStatisticValueKHR union is defined as:
// Provided by VK_KHR_pipeline_executable_properties
typedef union VkPipelineExecutableStatisticValueKHR {
VkBool32 b32;
int64_t i64;
uint64_t u64;
double f64;
} VkPipelineExecutableStatisticValueKHR;-
b32is the 32-bit boolean value if theVkPipelineExecutableStatisticFormatKHRisVK_PIPELINE_EXECUTABLE_STATISTIC_FORMAT_BOOL32_KHR. -
i64is the signed 64-bit integer value if theVkPipelineExecutableStatisticFormatKHRisVK_PIPELINE_EXECUTABLE_STATISTIC_FORMAT_INT64_KHR. -
u64is the unsigned 64-bit integer value if theVkPipelineExecutableStatisticFormatKHRisVK_PIPELINE_EXECUTABLE_STATISTIC_FORMAT_UINT64_KHR. -
f64is the 64-bit floating-point value if theVkPipelineExecutableStatisticFormatKHRisVK_PIPELINE_EXECUTABLE_STATISTIC_FORMAT_FLOAT64_KHR.
Each pipeline executable may have one or more text or binary internal representations associated with it which are generated as part of the compile process. These may include the final shader assembly, a binary form of the compiled shader, or the shader compiler’s internal representation at any number of intermediate compile steps. To query the internal representations associated with a pipeline executable, call:
// Provided by VK_KHR_pipeline_executable_properties
VkResult vkGetPipelineExecutableInternalRepresentationsKHR(
VkDevice device,
const VkPipelineExecutableInfoKHR* pExecutableInfo,
uint32_t* pInternalRepresentationCount,
VkPipelineExecutableInternalRepresentationKHR* pInternalRepresentations);-
deviceis the device that created the pipeline. -
pExecutableInfodescribes the pipeline executable being queried. -
pInternalRepresentationCountis a pointer to an integer related to the number of internal representations available or queried, as described below. -
pInternalRepresentationsis eitherNULLor a pointer to an array of VkPipelineExecutableInternalRepresentationKHR structures.
If pInternalRepresentations is NULL, then the number of internal
representations associated with the pipeline executable is returned in
pInternalRepresentationCount.
Otherwise, pInternalRepresentationCount must point to a variable set
by the 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;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
nameis an array ofVK_MAX_DESCRIPTION_SIZEcharcontaining a null-terminated UTF-8 string which is a short human readable name for this internal representation. -
descriptionis an array ofVK_MAX_DESCRIPTION_SIZEcharcontaining a null-terminated UTF-8 string which is a human readable description for this internal representation. -
isTextspecifies whether the returned data is text or opaque data. IfisTextisVK_TRUEthen the data returned inpDatais text and is guaranteed to be a null-terminated UTF-8 string. -
dataSizeis an integer related to the size, in bytes, of the internal representation’s data, as described below. -
pDatais eitherNULLor a pointer to a block of data into which the implementation will write the internal representation.
If pData is NULL, then the size, in bytes, of the internal
representation data is returned in dataSize.
Otherwise, dataSize must be the size of the buffer, in bytes, pointed
to by pData and on return dataSize is overwritten with the
number of bytes of data actually written to pData including any
trailing null character.
If dataSize is less than the size, in bytes, of the internal
representation’s data, at most dataSize bytes of data will be written
to pData, and VK_INCOMPLETE will be returned instead of
VK_SUCCESS, to indicate that not all the available representation was
returned.
If isText is VK_TRUE and pData is not NULL and
dataSize is not zero, the last byte written to pData will be a
null character.
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);-
deviceis the device that createdpipeline. -
pipelineis the target of the query. -
shaderStageis a VkShaderStageFlagBits specifying the particular shader within the pipeline about which information is being queried. -
infoTypedescribes what kind of information is being queried. -
pInfoSizeis a pointer to a value related to the amount of data the query returns, as described below. -
pInfois eitherNULLor 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_AMDspecifies that device resources used by a shader will be queried. -
VK_SHADER_INFO_TYPE_BINARY_AMDspecifies that implementation-specific information will be queried. -
VK_SHADER_INFO_TYPE_DISASSEMBLY_AMDspecifies 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;-
shaderStageMaskare the combination of logical shader stages contained within this shader. -
resourceUsageis a VkShaderResourceUsageAMD structure describing internal physical device resources used by this shader. -
numPhysicalVgprsis the maximum number of vector instruction general-purpose registers (VGPRs) available to the physical device. -
numPhysicalSgprsis the maximum number of scalar instruction general-purpose registers (SGPRs) available to the physical device. -
numAvailableVgprsis the maximum limit of VGPRs made available to the shader compiler. -
numAvailableSgprsis the maximum limit of SGPRs made available to the shader compiler. -
computeWorkGroupSizeis 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;-
numUsedVgprsis the number of vector instruction general-purpose registers used by this shader. -
numUsedSgprsis the number of scalar instruction general-purpose registers used by this shader. -
ldsSizePerLocalWorkGroupis the maximum local data store size per work group in bytes. -
ldsUsageSizeInBytesis the LDS usage size in bytes per work group by this shader. -
scratchMemUsageInBytesis 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;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
compilerControlFlagsis 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;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
pPipelineCreationFeedbackis a pointer to a VkPipelineCreationFeedback structure. -
pipelineStageCreationFeedbackCountis the number of elements inpPipelineStageCreationFeedbacks. -
pPipelineStageCreationFeedbacksis a pointer to an array ofpipelineStageCreationFeedbackCountVkPipelineCreationFeedback structures.
An implementation should write pipeline creation feedback to
pPipelineCreationFeedback and may write pipeline stage creation
feedback to pPipelineStageCreationFeedbacks.
An implementation must set or clear the
VK_PIPELINE_CREATION_FEEDBACK_VALID_BIT in
VkPipelineCreationFeedback::flags for
pPipelineCreationFeedback and every element of
pPipelineStageCreationFeedbacks.
|
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;-
flagsis a bitmask of VkPipelineCreationFeedbackFlagBits providing feedback about the creation of a pipeline or of a pipeline stage. -
durationis the duration spent creating a pipeline or pipeline stage in nanoseconds.
If the VK_PIPELINE_CREATION_FEEDBACK_VALID_BIT is not set in
flags, an implementation must not set any other bits in flags,
and the values of all other VkPipelineCreationFeedback data members
are undefined.
Possible values of the flags member of
VkPipelineCreationFeedback are:
// Provided by VK_VERSION_1_3
typedef enum VkPipelineCreationFeedbackFlagBits {
VK_PIPELINE_CREATION_FEEDBACK_VALID_BIT = 0x00000001,
VK_PIPELINE_CREATION_FEEDBACK_APPLICATION_PIPELINE_CACHE_HIT_BIT = 0x00000002,
VK_PIPELINE_CREATION_FEEDBACK_BASE_PIPELINE_ACCELERATION_BIT = 0x00000004,
// Provided by VK_EXT_pipeline_creation_feedback
VK_PIPELINE_CREATION_FEEDBACK_VALID_BIT_EXT = VK_PIPELINE_CREATION_FEEDBACK_VALID_BIT,
// Provided by VK_EXT_pipeline_creation_feedback
VK_PIPELINE_CREATION_FEEDBACK_APPLICATION_PIPELINE_CACHE_HIT_BIT_EXT = VK_PIPELINE_CREATION_FEEDBACK_APPLICATION_PIPELINE_CACHE_HIT_BIT,
// Provided by VK_EXT_pipeline_creation_feedback
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_BITspecifies that the feedback information is valid. -
VK_PIPELINE_CREATION_FEEDBACK_APPLICATION_PIPELINE_CACHE_HIT_BITspecifies that a readily usable pipeline or pipeline stage was found in thepipelineCachespecified by the application in the pipeline creation command.An implementation should set the
VK_PIPELINE_CREATION_FEEDBACK_APPLICATION_PIPELINE_CACHE_HIT_BITbit if it was able to avoid the large majority of pipeline or pipeline stage creation work by using thepipelineCacheparameter of vkCreateGraphicsPipelines, vkCreateRayTracingPipelinesKHR, 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_BITspecifies that the base pipeline specified by thebasePipelineHandleorbasePipelineIndexmember of theVk*PipelineCreateInfostructure was used to accelerate the creation of the pipeline.An implementation should set the
VK_PIPELINE_CREATION_FEEDBACK_BASE_PIPELINE_ACCELERATION_BITbit if it was able to avoid a significant amount of work by using the base pipeline.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.