9. 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 or a compute pipeline.
The first stage of the graphics pipeline (Input Assembler) assembles vertices to form geometric primitives such as points, lines, and triangles, based on a requested primitive topology. In the next stage (Vertex Shader) vertices can be transformed, computing positions and attributes for each vertex. If tessellation and/or geometry shaders are supported, they can then generate multiple primitives from a single input primitive, possibly changing the primitive topology or generating additional attribute data in the process.
The final resulting primitives are clipped to a clip volume in preparation for the next stage, Rasterization. The rasterizer produces a series of framebuffer addresses and values using a two-dimensional description of a point, line segment, or triangle. Each fragment so produced is fed to the next stage (Fragment Shader) that performs operations on individual fragments before they finally alter the framebuffer. These operations include conditional updates into the framebuffer based on incoming and previously stored depth values (to effect depth buffering), blending of incoming fragment colors with stored colors, as well as masking, stenciling, and other logical operations on fragment values.
Framebuffer operations read and write the color and depth/stencil attachments of the framebuffer for a given subpass of a render pass instance. The attachments can be used as input attachments in the fragment shader in a later subpass of the same render pass.
The compute pipeline is a separate pipeline from the graphics pipeline, which operates on one-, two-, or three-dimensional workgroups which can read from and write to buffer and image memory.
This ordering is meant only as a tool for describing Vulkan, not as a strict rule of how Vulkan is implemented, and we present it only as a means to organize the various operations of the pipelines. Actual ordering guarantees between pipeline stages are explained in detail in the synchronization chapter.
Each pipeline is controlled by a monolithic object created from a description of all of the shader stages and any relevant fixed-function stages. Linking the whole pipeline together allows the optimization of shaders based on their input/outputs and eliminates expensive draw time state validation.
A pipeline object is bound to the current state using vkCmdBindPipeline. Any pipeline object state that is specified as dynamic is not applied to the current state when the pipeline object is bound, but is instead set by dynamic state setting commands.
No state, including dynamic state, is inherited from one command buffer to another.
Compute and graphics pipelines are each represented by VkPipeline
handles:
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkPipeline)
9.1. Compute Pipelines
Compute pipelines consist of a single static compute shader stage and the pipeline layout.
The compute pipeline represents a compute shader and is created by calling
vkCreateComputePipelines
with module
and pName
selecting
an entry point from a shader module, where that entry point defines a valid
compute shader, in the VkPipelineShaderStageCreateInfo
structure
contained within the VkComputePipelineCreateInfo
structure.
To create compute pipelines, call:
VkResult vkCreateComputePipelines(
VkDevice device,
VkPipelineCache pipelineCache,
uint32_t createInfoCount,
const VkComputePipelineCreateInfo* pCreateInfos,
const VkAllocationCallbacks* pAllocator,
VkPipeline* pPipelines);
-
device
is the logical device that creates the compute pipelines. -
pipelineCache
is either VK_NULL_HANDLE, indicating that pipeline caching is disabled; or the handle of a valid pipeline cache object, in which case use of that cache is enabled for the duration of the command. -
createInfoCount
is the length of thepCreateInfos
andpPipelines
arrays. -
pCreateInfos
is an array of VkComputePipelineCreateInfo structures. -
pAllocator
controls host memory allocation as described in the Memory Allocation chapter. -
pPipelines
is a pointer to an array in which the resulting compute pipeline objects are returned.
The VkComputePipelineCreateInfo
structure is defined as:
typedef struct VkComputePipelineCreateInfo {
VkStructureType sType;
const void* pNext;
VkPipelineCreateFlags flags;
VkPipelineShaderStageCreateInfo stage;
VkPipelineLayout layout;
VkPipeline basePipelineHandle;
int32_t basePipelineIndex;
} VkComputePipelineCreateInfo;
-
sType
is the type of this structure. -
pNext
isNULL
or a pointer to an extension-specific structure. -
flags
is a bitmask of VkPipelineCreateFlagBits specifying how the pipeline will be generated. -
stage
is a VkPipelineShaderStageCreateInfo describing the compute shader. -
layout
is the description of binding locations used by both the pipeline and descriptor sets used with the pipeline. -
basePipelineHandle
is a pipeline to derive from -
basePipelineIndex
is an index into thepCreateInfos
parameter to use as a pipeline to derive from
The parameters basePipelineHandle
and basePipelineIndex
are
described in more detail in Pipeline
Derivatives.
stage
points to a structure of type
VkPipelineShaderStageCreateInfo
.
The VkPipelineShaderStageCreateInfo
structure is defined as:
typedef struct VkPipelineShaderStageCreateInfo {
VkStructureType sType;
const void* pNext;
VkPipelineShaderStageCreateFlags flags;
VkShaderStageFlagBits stage;
VkShaderModule module;
const char* pName;
const VkSpecializationInfo* pSpecializationInfo;
} VkPipelineShaderStageCreateInfo;
-
sType
is the type of this structure. -
pNext
isNULL
or a pointer to an extension-specific structure. -
flags
is reserved for future use. -
stage
is a VkShaderStageFlagBits value specifying a single pipeline stage. -
module
is a VkShaderModule object that contains the shader for this stage. -
pName
is a pointer to a null-terminated UTF-8 string specifying the entry point name of the shader for this stage. -
pSpecializationInfo
is a pointer to VkSpecializationInfo, as described in Specialization Constants, and can beNULL
.
typedef VkFlags VkPipelineShaderStageCreateFlags;
VkPipelineShaderStageCreateFlags
is a bitmask type for setting a mask,
but is currently reserved for future use.
Commands and structures which need to specify one or more shader stages do so using a bitmask whose bits correspond to stages. Bits which can be set to specify shader stages are:
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,
} VkShaderStageFlagBits;
-
VK_SHADER_STAGE_VERTEX_BIT
specifies the vertex stage. -
VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT
specifies the tessellation control stage. -
VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT
specifies the tessellation evaluation stage. -
VK_SHADER_STAGE_GEOMETRY_BIT
specifies the geometry stage. -
VK_SHADER_STAGE_FRAGMENT_BIT
specifies the fragment stage. -
VK_SHADER_STAGE_COMPUTE_BIT
specifies the compute stage. -
VK_SHADER_STAGE_ALL_GRAPHICS
is a combination of bits used as shorthand to specify all graphics stages defined above (excluding the compute stage). -
VK_SHADER_STAGE_ALL
is a combination of bits used as shorthand to specify all shader stages supported by the device, including all additional stages which are introduced by extensions.
Note
|
typedef VkFlags VkShaderStageFlags;
VkShaderStageFlags
is a bitmask type for setting a mask of zero or
more VkShaderStageFlagBits.
9.2. Graphics Pipelines
Graphics pipelines consist of multiple shader stages, multiple fixed-function pipeline stages, and a pipeline layout.
To create graphics pipelines, call:
VkResult vkCreateGraphicsPipelines(
VkDevice device,
VkPipelineCache pipelineCache,
uint32_t createInfoCount,
const VkGraphicsPipelineCreateInfo* pCreateInfos,
const VkAllocationCallbacks* pAllocator,
VkPipeline* pPipelines);
-
device
is the logical device that creates the graphics pipelines. -
pipelineCache
is either VK_NULL_HANDLE, indicating that pipeline caching is disabled; or the handle of a valid pipeline cache object, in which case use of that cache is enabled for the duration of the command. -
createInfoCount
is the length of thepCreateInfos
andpPipelines
arrays. -
pCreateInfos
is an array of VkGraphicsPipelineCreateInfo structures. -
pAllocator
controls host memory allocation as described in the Memory Allocation chapter. -
pPipelines
is a pointer to an array in which the resulting graphics pipeline objects are returned.
The VkGraphicsPipelineCreateInfo structure includes an array of shader create info structures containing all the desired active shader stages, as well as creation info to define all relevant fixed-function stages, and a pipeline layout.
The VkGraphicsPipelineCreateInfo
structure is defined as:
typedef struct VkGraphicsPipelineCreateInfo {
VkStructureType sType;
const void* pNext;
VkPipelineCreateFlags flags;
uint32_t stageCount;
const VkPipelineShaderStageCreateInfo* pStages;
const VkPipelineVertexInputStateCreateInfo* pVertexInputState;
const VkPipelineInputAssemblyStateCreateInfo* pInputAssemblyState;
const VkPipelineTessellationStateCreateInfo* pTessellationState;
const VkPipelineViewportStateCreateInfo* pViewportState;
const VkPipelineRasterizationStateCreateInfo* pRasterizationState;
const VkPipelineMultisampleStateCreateInfo* pMultisampleState;
const VkPipelineDepthStencilStateCreateInfo* pDepthStencilState;
const VkPipelineColorBlendStateCreateInfo* pColorBlendState;
const VkPipelineDynamicStateCreateInfo* pDynamicState;
VkPipelineLayout layout;
VkRenderPass renderPass;
uint32_t subpass;
VkPipeline basePipelineHandle;
int32_t basePipelineIndex;
} VkGraphicsPipelineCreateInfo;
-
sType
is the type of this structure. -
pNext
isNULL
or a pointer to an extension-specific structure. -
flags
is a bitmask of VkPipelineCreateFlagBits specifying how the pipeline will be generated. -
stageCount
is the number of entries in thepStages
array. -
pStages
is an array of sizestageCount
structures of type VkPipelineShaderStageCreateInfo describing the set of the shader stages to be included in the graphics pipeline. -
pVertexInputState
is a pointer to an instance of the VkPipelineVertexInputStateCreateInfo structure. -
pInputAssemblyState
is a pointer to an instance of the VkPipelineInputAssemblyStateCreateInfo structure which determines input assembly behavior, as described in Drawing Commands. -
pTessellationState
is a pointer to an instance of the VkPipelineTessellationStateCreateInfo structure, and is ignored if the pipeline does not include a tessellation control shader stage and tessellation evaluation shader stage. -
pViewportState
is a pointer to an instance of the VkPipelineViewportStateCreateInfo structure, and is ignored if the pipeline has rasterization disabled. -
pRasterizationState
is a pointer to an instance of the VkPipelineRasterizationStateCreateInfo structure. -
pMultisampleState
is a pointer to an instance of the VkPipelineMultisampleStateCreateInfo, and is ignored if the pipeline has rasterization disabled. -
pDepthStencilState
is a pointer to an instance of the VkPipelineDepthStencilStateCreateInfo structure, and is ignored if the pipeline has rasterization disabled or if the subpass of the render pass the pipeline is created against does not use a depth/stencil attachment. -
pColorBlendState
is a pointer to an instance of the VkPipelineColorBlendStateCreateInfo structure, and is ignored if the pipeline has rasterization disabled or if the subpass of the render pass the pipeline is created against does not use any color attachments. -
pDynamicState
is a pointer to VkPipelineDynamicStateCreateInfo and is used to indicate which properties of the pipeline state object are dynamic and can be changed independently of the pipeline state. This can beNULL
, which means no state in the pipeline is considered dynamic. -
layout
is the description of binding locations used by both the pipeline and descriptor sets used with the pipeline. -
renderPass
is a handle to a render pass object describing the environment in which the pipeline will be used; the pipeline must only be used with an instance of any render pass compatible with the one provided. See Render Pass Compatibility for more information. -
subpass
is the index of the subpass in the render pass where this pipeline will be used. -
basePipelineHandle
is a pipeline to derive from. -
basePipelineIndex
is an index into thepCreateInfos
parameter to use as a pipeline to derive from.
The parameters basePipelineHandle
and basePipelineIndex
are
described in more detail in Pipeline
Derivatives.
pStages
points to an array of VkPipelineShaderStageCreateInfo
structures, which were previously described in Compute
Pipelines.
pDynamicState
points to a structure of type
VkPipelineDynamicStateCreateInfo.
Possible values of the flags
member of
VkGraphicsPipelineCreateInfo and VkComputePipelineCreateInfo,
specifying how a pipeline is created, are:
typedef enum VkPipelineCreateFlagBits {
VK_PIPELINE_CREATE_DISABLE_OPTIMIZATION_BIT = 0x00000001,
VK_PIPELINE_CREATE_ALLOW_DERIVATIVES_BIT = 0x00000002,
VK_PIPELINE_CREATE_DERIVATIVE_BIT = 0x00000004,
} VkPipelineCreateFlagBits;
-
VK_PIPELINE_CREATE_DISABLE_OPTIMIZATION_BIT
specifies that the created pipeline will not be optimized. Using this flag may reduce the time taken to create the pipeline. -
VK_PIPELINE_CREATE_ALLOW_DERIVATIVES_BIT
specifies that the pipeline to be created is allowed to be the parent of a pipeline that will be created in a subsequent call to vkCreateGraphicsPipelines or vkCreateComputePipelines. -
VK_PIPELINE_CREATE_DERIVATIVE_BIT
specifies that the pipeline to be created will be a child of a previously created parent pipeline.
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.
typedef VkFlags VkPipelineCreateFlags;
VkPipelineCreateFlags
is a bitmask type for setting a mask of zero or
more VkPipelineCreateFlagBits.
The VkPipelineDynamicStateCreateInfo
structure is defined as:
typedef struct VkPipelineDynamicStateCreateInfo {
VkStructureType sType;
const void* pNext;
VkPipelineDynamicStateCreateFlags flags;
uint32_t dynamicStateCount;
const VkDynamicState* pDynamicStates;
} VkPipelineDynamicStateCreateInfo;
-
sType
is the type of this structure. -
pNext
isNULL
or a pointer to an extension-specific structure. -
flags
is reserved for future use. -
dynamicStateCount
is the number of elements in thepDynamicStates
array. -
pDynamicStates
is an array of VkDynamicState values specifying which pieces of pipeline state will use the values from dynamic state commands rather than from pipeline state creation info.
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:
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,
} VkDynamicState;
-
VK_DYNAMIC_STATE_VIEWPORT
specifies that thepViewports
state inVkPipelineViewportStateCreateInfo
will be ignored and must be set dynamically with vkCmdSetViewport before any draw commands. The number of viewports used by a pipeline is still specified by theviewportCount
member ofVkPipelineViewportStateCreateInfo
. -
VK_DYNAMIC_STATE_SCISSOR
specifies that thepScissors
state inVkPipelineViewportStateCreateInfo
will be ignored and must be set dynamically with vkCmdSetScissor before any draw commands. The number of scissor rectangles used by a pipeline is still specified by thescissorCount
member ofVkPipelineViewportStateCreateInfo
. -
VK_DYNAMIC_STATE_LINE_WIDTH
specifies that thelineWidth
state inVkPipelineRasterizationStateCreateInfo
will be ignored and must be set dynamically with vkCmdSetLineWidth before any draw commands that generate line primitives for the rasterizer. -
VK_DYNAMIC_STATE_DEPTH_BIAS
specifies that thedepthBiasConstantFactor
,depthBiasClamp
anddepthBiasSlopeFactor
states inVkPipelineRasterizationStateCreateInfo
will be ignored and must be set dynamically with vkCmdSetDepthBias before any draws are performed withdepthBiasEnable
inVkPipelineRasterizationStateCreateInfo
set toVK_TRUE
. -
VK_DYNAMIC_STATE_BLEND_CONSTANTS
specifies that theblendConstants
state inVkPipelineColorBlendStateCreateInfo
will be ignored and must be set dynamically with vkCmdSetBlendConstants before any draws are performed with a pipeline state withVkPipelineColorBlendAttachmentState
memberblendEnable
set toVK_TRUE
and any of the blend functions using a constant blend color. -
VK_DYNAMIC_STATE_DEPTH_BOUNDS
specifies that theminDepthBounds
andmaxDepthBounds
states of VkPipelineDepthStencilStateCreateInfo will be ignored and must be set dynamically with vkCmdSetDepthBounds before any draws are performed with a pipeline state withVkPipelineDepthStencilStateCreateInfo
memberdepthBoundsTestEnable
set toVK_TRUE
. -
VK_DYNAMIC_STATE_STENCIL_COMPARE_MASK
specifies that thecompareMask
state inVkPipelineDepthStencilStateCreateInfo
for bothfront
andback
will be ignored and must be set dynamically with vkCmdSetStencilCompareMask before any draws are performed with a pipeline state withVkPipelineDepthStencilStateCreateInfo
memberstencilTestEnable
set toVK_TRUE
-
VK_DYNAMIC_STATE_STENCIL_WRITE_MASK
specifies that thewriteMask
state inVkPipelineDepthStencilStateCreateInfo
for bothfront
andback
will be ignored and must be set dynamically with vkCmdSetStencilWriteMask before any draws are performed with a pipeline state withVkPipelineDepthStencilStateCreateInfo
memberstencilTestEnable
set toVK_TRUE
-
VK_DYNAMIC_STATE_STENCIL_REFERENCE
specifies that thereference
state inVkPipelineDepthStencilStateCreateInfo
for bothfront
andback
will be ignored and must be set dynamically with vkCmdSetStencilReference before any draws are performed with a pipeline state withVkPipelineDepthStencilStateCreateInfo
memberstencilTestEnable
set toVK_TRUE
9.2.1. Valid Combinations of Stages for Graphics Pipelines
If tessellation shader stages are omitted, the tessellation shading and fixed-function stages of the pipeline are skipped.
If a geometry shader is omitted, the geometry shading stage is skipped.
If a fragment shader is omitted, fragment color outputs have undefined values, and the fragment depth value is unmodified. This can be useful for depth-only rendering.
Presence of a shader stage in a pipeline is indicated by including a valid
VkPipelineShaderStageCreateInfo
with module
and pName
selecting an entry point from a shader module, where that entry point is
valid for the stage specified by stage
.
Presence of some of the fixed-function stages in the pipeline is implicitly derived from enabled shaders and provided state. For example, the fixed-function tessellator is always present when the pipeline has valid Tessellation Control and Tessellation Evaluation shaders.
-
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
-
9.3. Pipeline destruction
To destroy a graphics or compute pipeline, call:
void vkDestroyPipeline(
VkDevice device,
VkPipeline pipeline,
const VkAllocationCallbacks* pAllocator);
-
device
is the logical device that destroys the pipeline. -
pipeline
is the handle of the pipeline to destroy. -
pAllocator
controls host memory allocation as described in the Memory Allocation chapter.
9.4. Multiple Pipeline Creation
Multiple pipelines can be created simultaneously by passing an array of
VkGraphicsPipelineCreateInfo
or VkComputePipelineCreateInfo
structures into the vkCreateGraphicsPipelines and
vkCreateComputePipelines commands, respectively.
Applications can group together similar pipelines to be created in a single
call, and implementations are encouraged to look for reuse opportunities
within a group-create.
When an application attempts to create many pipelines in a single command,
it is possible that some subset may fail creation.
In that case, the corresponding entries in the pPipelines
output array
will be filled with VK_NULL_HANDLE values.
If any pipeline fails creation (for example, due to out of memory errors),
the vkCreate*Pipelines
commands will return an error code.
The implementation will attempt to create all pipelines, and only return
VK_NULL_HANDLE values for those that actually failed.
9.5. 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.
9.6. 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:
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkPipelineCache)
To create pipeline cache objects, call:
VkResult vkCreatePipelineCache(
VkDevice device,
const VkPipelineCacheCreateInfo* pCreateInfo,
const VkAllocationCallbacks* pAllocator,
VkPipelineCache* pPipelineCache);
-
device
is the logical device that creates the pipeline cache object. -
pCreateInfo
is a pointer to a VkPipelineCacheCreateInfo structure that contains the initial parameters for the pipeline cache object. -
pAllocator
controls host memory allocation as described in the Memory Allocation chapter. -
pPipelineCache
is a pointer to a VkPipelineCache handle in which the resulting pipeline cache object is returned.
Note
Applications can track and manage the total host memory size of a pipeline
cache object using the |
Once created, a pipeline cache can be passed to the
vkCreateGraphicsPipelines
and vkCreateComputePipelines
commands.
If the pipeline cache passed into these commands is not
VK_NULL_HANDLE, the implementation will query it for possible reuse
opportunities and update it with new content.
The use of the pipeline cache object in these commands is internally
synchronized, and the same pipeline cache object can be used in multiple
threads simultaneously.
Note
Implementations should make every effort to limit any critical sections to
the actual accesses to the cache, which is expected to be significantly
shorter than the duration of the |
The VkPipelineCacheCreateInfo
structure is defined as:
typedef struct VkPipelineCacheCreateInfo {
VkStructureType sType;
const void* pNext;
VkPipelineCacheCreateFlags flags;
size_t initialDataSize;
const void* pInitialData;
} VkPipelineCacheCreateInfo;
-
sType
is the type of this structure. -
pNext
isNULL
or a pointer to an extension-specific structure. -
flags
is reserved for future use. -
initialDataSize
is the number of bytes inpInitialData
. IfinitialDataSize
is zero, the pipeline cache will initially be empty. -
pInitialData
is a pointer to previously retrieved pipeline cache data. If the pipeline cache data is incompatible (as defined below) with the device, the pipeline cache will be initially empty. IfinitialDataSize
is zero,pInitialData
is ignored.
typedef VkFlags VkPipelineCacheCreateFlags;
VkPipelineCacheCreateFlags
is a bitmask type for setting a mask, but
is currently reserved for future use.
Pipeline cache objects can be merged using the command:
VkResult vkMergePipelineCaches(
VkDevice device,
VkPipelineCache dstCache,
uint32_t srcCacheCount,
const VkPipelineCache* pSrcCaches);
-
device
is the logical device that owns the pipeline cache objects. -
dstCache
is the handle of the pipeline cache to merge results into. -
srcCacheCount
is the length of thepSrcCaches
array. -
pSrcCaches
is an array of pipeline cache handles, which will be merged intodstCache
. The previous contents ofdstCache
are included after the merge.
Note
The details of the merge operation are implementation dependent, but implementations should merge the contents of the specified pipelines and prune duplicate entries. |
Data can be retrieved from a pipeline cache object using the command:
VkResult vkGetPipelineCacheData(
VkDevice device,
VkPipelineCache pipelineCache,
size_t* pDataSize,
void* pData);
-
device
is the logical device that owns the pipeline cache. -
pipelineCache
is the pipeline cache to retrieve data from. -
pDataSize
is a pointer to a value related to the amount of data in the pipeline cache, as described below. -
pData
is eitherNULL
or a pointer to a buffer.
If pData
is NULL
, then the maximum size of the data that can be
retrieved from the pipeline cache, in bytes, is returned in pDataSize
.
Otherwise, pDataSize
must point to a variable set by the user to the
size of the buffer, in bytes, pointed to by pData
, and on return the
variable is overwritten with the amount of data actually written to
pData
.
If pDataSize
is less than the maximum size that can be retrieved by
the pipeline cache, at most pDataSize
bytes will be written to
pData
, and vkGetPipelineCacheData
will return
VK_INCOMPLETE
.
Any data written to pData
is valid and can be provided as the
pInitialData
member of the VkPipelineCacheCreateInfo
structure
passed to vkCreatePipelineCache
.
Two calls to vkGetPipelineCacheData
with the same parameters must
retrieve the same data unless a command that modifies the contents of the
cache is called between them.
Applications can store the data retrieved from the pipeline cache, and use
these data, possibly in a future run of the application, to populate new
pipeline cache objects.
The results of pipeline compiles, however, may depend on the vendor ID,
device ID, driver version, and other details of the device.
To enable applications to detect when previously retrieved data is
incompatible with the device, the initial bytes written to pData
must
be a header consisting of the following members:
Offset | Size | Meaning |
---|---|---|
0 |
4 |
length in bytes of the entire pipeline cache header written as a stream of bytes, with the least significant byte first |
4 |
4 |
a VkPipelineCacheHeaderVersion value written as a stream of bytes, with the least significant byte first |
8 |
4 |
a vendor ID equal to
|
12 |
4 |
a device ID equal to
|
16 |
|
a pipeline cache ID equal to
|
The first four bytes encode the length of the entire pipeline cache header, in bytes. This value includes all fields in the header including the pipeline cache version field and the size of the length field.
The next four bytes encode the pipeline cache version, as described for VkPipelineCacheHeaderVersion. A consumer of the pipeline cache should use the cache version to interpret the remainder of the cache header.
If pDataSize
is less than what is necessary to store this header,
nothing will be written to pData
and zero will be written to
pDataSize
.
Possible values of the second group of four bytes in the header returned by vkGetPipelineCacheData, encoding the pipeline cache version, are:
typedef enum VkPipelineCacheHeaderVersion {
VK_PIPELINE_CACHE_HEADER_VERSION_ONE = 1,
} VkPipelineCacheHeaderVersion;
-
VK_PIPELINE_CACHE_HEADER_VERSION_ONE
specifies version one of the pipeline cache.
To destroy a pipeline cache, call:
void vkDestroyPipelineCache(
VkDevice device,
VkPipelineCache pipelineCache,
const VkAllocationCallbacks* pAllocator);
-
device
is the logical device that destroys the pipeline cache object. -
pipelineCache
is the handle of the pipeline cache to destroy. -
pAllocator
controls host memory allocation as described in the Memory Allocation chapter.
9.7. Specialization Constants
Specialization constants are a mechanism whereby constants in a SPIR-V
module can have their constant value specified at the time the
VkPipeline
is created.
This allows a SPIR-V module to have constants that can be modified while
executing an application that uses the Vulkan API.
Note
Specialization constants are useful to allow a compute shader to have its local workgroup size changed at runtime by the user, for example. |
Each instance of the VkPipelineShaderStageCreateInfo
structure
contains a parameter pSpecializationInfo
, which can be NULL
to
indicate no specialization constants, or point to a
VkSpecializationInfo
structure.
The VkSpecializationInfo
structure is defined as:
typedef struct VkSpecializationInfo {
uint32_t mapEntryCount;
const VkSpecializationMapEntry* pMapEntries;
size_t dataSize;
const void* pData;
} VkSpecializationInfo;
-
mapEntryCount
is the number of entries in thepMapEntries
array. -
pMapEntries
is a pointer to an array ofVkSpecializationMapEntry
which maps constant IDs to offsets inpData
. -
dataSize
is the byte size of thepData
buffer. -
pData
contains the actual constant values to specialize with.
pMapEntries
points to a structure of type
VkSpecializationMapEntry.
The VkSpecializationMapEntry
structure is defined as:
typedef struct VkSpecializationMapEntry {
uint32_t constantID;
uint32_t offset;
size_t size;
} VkSpecializationMapEntry;
-
constantID
is the ID of the specialization constant in SPIR-V. -
offset
is the byte offset of the specialization constant value within the supplied data buffer. -
size
is the byte size of the specialization constant value within the supplied data buffer.
If a constantID
value is not a specialization constant ID used in the
shader, that map entry does not affect the behavior of the pipeline.
In human readable SPIR-V:
OpDecorate %x SpecId 13 ; decorate .x component of WorkgroupSize with ID 13
OpDecorate %y SpecId 42 ; decorate .y component of WorkgroupSize with ID 42
OpDecorate %z SpecId 3 ; decorate .z component of WorkgroupSize with ID 3
OpDecorate %wgsize BuiltIn WorkgroupSize ; decorate WorkgroupSize onto constant
%i32 = OpTypeInt 32 0 ; declare an unsigned 32-bit type
%uvec3 = OpTypeVector %i32 3 ; declare a 3 element vector type of unsigned 32-bit
%x = OpSpecConstant %i32 1 ; declare the .x component of WorkgroupSize
%y = OpSpecConstant %i32 1 ; declare the .y component of WorkgroupSize
%z = OpSpecConstant %i32 1 ; declare the .z component of WorkgroupSize
%wgsize = OpSpecConstantComposite %uvec3 %x %y %z ; declare WorkgroupSize
From the above we have three specialization constants, one for each of the x, y & z elements of the WorkgroupSize vector.
Now to specialize the above via the specialization constants mechanism:
const VkSpecializationMapEntry entries[] =
{
{
13, // constantID
0 * sizeof(uint32_t), // offset
sizeof(uint32_t) // size
},
{
42, // constantID
1 * sizeof(uint32_t), // offset
sizeof(uint32_t) // size
},
{
3, // constantID
2 * sizeof(uint32_t), // offset
sizeof(uint32_t) // size
}
};
const uint32_t data[] = { 16, 8, 4 }; // our workgroup size is 16x8x4
const VkSpecializationInfo info =
{
3, // mapEntryCount
entries, // pMapEntries
3 * sizeof(uint32_t), // dataSize
data, // pData
};
Then when calling vkCreateComputePipelines, and passing the
VkSpecializationInfo
we defined as the pSpecializationInfo
parameter of VkPipelineShaderStageCreateInfo, we will create a compute
pipeline with the runtime specified local workgroup size.
Another example would be that an application has a SPIR-V module that has some platform-dependent constants they wish to use.
In human readable SPIR-V:
OpDecorate %1 SpecId 0 ; decorate our signed 32-bit integer constant
OpDecorate %2 SpecId 12 ; decorate our 32-bit floating-point constant
%i32 = OpTypeInt 32 1 ; declare a signed 32-bit type
%float = OpTypeFloat 32 ; declare a 32-bit floating-point type
%1 = OpSpecConstant %i32 -1 ; some signed 32-bit integer constant
%2 = OpSpecConstant %float 0.5 ; some 32-bit floating-point constant
From the above we have two specialization constants, one is a signed 32-bit integer and the second is a 32-bit floating-point.
Now to specialize the above via the specialization constants mechanism:
struct SpecializationData {
int32_t data0;
float data1;
};
const VkSpecializationMapEntry entries[] =
{
{
0, // constantID
offsetof(SpecializationData, data0), // offset
sizeof(SpecializationData::data0) // size
},
{
12, // constantID
offsetof(SpecializationData, data1), // offset
sizeof(SpecializationData::data1) // size
}
};
SpecializationData data;
data.data0 = -42; // set the data for the 32-bit integer
data.data1 = 42.0f; // set the data for the 32-bit floating-point
const VkSpecializationInfo info =
{
2, // mapEntryCount
entries, // pMapEntries
sizeof(data), // dataSize
&data, // pData
};
It is legal for a SPIR-V module with specializations to be compiled into a pipeline where no specialization info was provided. SPIR-V specialization constants contain default values such that if a specialization is not provided, the default value will be used. In the examples above, it would be valid for an application to only specialize some of the specialization constants within the SPIR-V module, and let the other constants use their default values encoded within the OpSpecConstant declarations.
9.8. Pipeline Binding
Once a pipeline has been created, it can be bound to the command buffer using the command:
void vkCmdBindPipeline(
VkCommandBuffer commandBuffer,
VkPipelineBindPoint pipelineBindPoint,
VkPipeline pipeline);
-
commandBuffer
is the command buffer that the pipeline will be bound to. -
pipelineBindPoint
is a VkPipelineBindPoint value specifying whether to bind to the compute or graphics bind point. Binding one does not disturb the other. -
pipeline
is the pipeline to be bound.
Once bound, a pipeline binding affects subsequent graphics or compute
commands in the command buffer until a different pipeline is bound to the
bind point.
The pipeline bound to VK_PIPELINE_BIND_POINT_COMPUTE
controls the
behavior of vkCmdDispatch and vkCmdDispatchIndirect.
The pipeline bound to VK_PIPELINE_BIND_POINT_GRAPHICS
controls the
behavior of all drawing commands.
No other commands are affected by the pipeline state.
Possible values of vkCmdBindPipeline::pipelineBindPoint
,
specifying the bind point of a pipeline object, are:
typedef enum VkPipelineBindPoint {
VK_PIPELINE_BIND_POINT_GRAPHICS = 0,
VK_PIPELINE_BIND_POINT_COMPUTE = 1,
} VkPipelineBindPoint;
-
VK_PIPELINE_BIND_POINT_COMPUTE
specifies binding as a compute pipeline. -
VK_PIPELINE_BIND_POINT_GRAPHICS
specifies binding as a graphics pipeline.
9.9. Dynamic State
When a pipeline object is bound, any pipeline object state that is not specified as dynamic is applied to the command buffer state. Pipeline object state that is specified as dynamic is not applied to the command buffer state at this time. Instead, dynamic state can be modified at any time and persists for the lifetime of the command buffer, or until modified by another dynamic state setting command or another pipeline bind.
When a pipeline object is bound, the following applies to each state parameter:
-
If the state is not specified as dynamic in the new pipeline object, then that command buffer state is overwritten by the state in the new pipeline object.
-
If the state is specified as dynamic in both the new and the previous pipeline object, then that command buffer state is not disturbed.
-
If the state is specified as dynamic in the new pipeline object but is not specified as dynamic in the previous pipeline object, then that command buffer state becomes undefined. If the state is an array, then the entire array becomes undefined.
-
If the state is an array specified as dynamic in both the new and the previous pipeline object, and the array size is not the same in both pipeline objects, then that command buffer state becomes undefined.
Dynamic state setting commands must not be issued for state that is not specified as dynamic in the bound pipeline object.
Dynamic state that does not affect the result of operations can be left undefined.
Note
For example, if blending is disabled by the pipeline object state then the dynamic color blend constants do not need to be specified in the command buffer, even if this state is specified as dynamic in the pipeline object. |