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 the pCreateInfos
and
pPipelines
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
is NULL
or a pointer to an extension-specific structure.
flags
is a bitmask of VkPipelineCreateFlagBits
controlling
how the pipeline will be generated, as described below.
stageCount
is the number of entries in the pStages
array.
pStages
is an array of size stageCount
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, or NULL
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, or NULL
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
, or NULL
if the pipeline
has rasterization disabled.
pDepthStencilState
is a pointer to an instance of the
VkPipelineDepthStencilStateCreateInfo
structure, or NULL
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, or NULL
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 be NULL
, which means no state in the pipeline is considered
dynamic.
layout
is the description of binding locations used by both the
pipeline and descriptor sets used with the pipeline.
renderPass
is a handle to a render pass object describing the
environment in which the pipeline will be used; the pipeline must only
be used with an instance of any render pass compatible with the one
provided.
See Render Pass Compatibility for more
information.
subpass
is the index of the subpass in the render pass where this
pipeline will be used.
basePipelineHandle
is a pipeline to derive from.
basePipelineIndex
is an index into the pCreateInfos
parameter to use as a pipeline to derive from.
The parameters basePipelineHandle
and basePipelineIndex
are
described in more detail in Pipeline Derivatives.
pStages
points to an array of VkPipelineShaderStageCreateInfo
structures, which were previously described in Compute Pipelines.
Bits which can be set in flags
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
.
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.
pDynamicState
points to a structure of type
VkPipelineDynamicStateCreateInfo
.
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
is NULL
or a pointer to an extension-specific structure.
flags
is reserved for future use.
dynamicStateCount
is the number of elements in the
pDynamicStates
array.
pDynamicStates
is an array of VkDynamicState
enums which
indicate which pieces of pipeline state will use the values from dynamic
state commands rather than from the pipeline state creation info.
The source of difference pieces of dynamic state is determined by the
VkPipelineDynamicStateCreateInfo
::pDynamicStates
property of the
currently active pipeline, which takes the following 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
indicates that the pViewports
state in VkPipelineViewportStateCreateInfo
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 the
viewportCount
member of VkPipelineViewportStateCreateInfo
.
VK_DYNAMIC_STATE_SCISSOR
indicates that the pScissors
state
in VkPipelineViewportStateCreateInfo
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 the scissorCount
member of
VkPipelineViewportStateCreateInfo
.
VK_DYNAMIC_STATE_LINE_WIDTH
indicates that the lineWidth
state in VkPipelineRasterizationStateCreateInfo
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
indicates that the
depthBiasConstantFactor
, depthBiasClamp
and
depthBiasSlopeFactor
states in
VkPipelineRasterizationStateCreateInfo
will be ignored and must
be set dynamically with vkCmdSetDepthBias
before any draws are
performed with depthBiasEnable
in
VkPipelineRasterizationStateCreateInfo
set to VK_TRUE
.
VK_DYNAMIC_STATE_BLEND_CONSTANTS
indicates that the
blendConstants
state in VkPipelineColorBlendStateCreateInfo
will be ignored and must be set dynamically with
vkCmdSetBlendConstants
before any draws are performed with a
pipeline state with VkPipelineColorBlendAttachmentState
member
blendEnable
set to VK_TRUE
and any of the blend functions
using a constant blend color.
VK_DYNAMIC_STATE_DEPTH_BOUNDS
indicates that the
minDepthBounds
and maxDepthBounds
states of
VkPipelineDepthStencilStateCreateInfo
will be ignored and must be
set dynamically with vkCmdSetDepthBounds
before any draws are
performed with a pipeline state with
VkPipelineDepthStencilStateCreateInfo
member
depthBoundsTestEnable
set to VK_TRUE
.
VK_DYNAMIC_STATE_STENCIL_COMPARE_MASK
indicates that the
compareMask
state in VkPipelineDepthStencilStateCreateInfo
for both front
and back
will be ignored and must be set
dynamically with vkCmdSetStencilCompareMask
before any draws are
performed with a pipeline state with
VkPipelineDepthStencilStateCreateInfo
member
stencilTestEnable
set to VK_TRUE
VK_DYNAMIC_STATE_STENCIL_WRITE_MASK
indicates that the
writeMask
state in VkPipelineDepthStencilStateCreateInfo
for
both front
and back
will be ignored and must be set
dynamically with vkCmdSetStencilWriteMask
before any draws are
performed with a pipeline state with
VkPipelineDepthStencilStateCreateInfo
member
stencilTestEnable
set to VK_TRUE
VK_DYNAMIC_STATE_STENCIL_REFERENCE
indicates that the
reference
state in VkPipelineDepthStencilStateCreateInfo
for
both front
and back
will be ignored and must be set
dynamically with vkCmdSetStencilReference
before any draws are
performed with a pipeline state with
VkPipelineDepthStencilStateCreateInfo
member
stencilTestEnable
set to VK_TRUE
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, the results of fragment processing are undefined. Specifically, any fragment color outputs are considered to have undefined values, and the fragment depth is considered to be unmodified. This can be useful for depth-only rendering.
Presence of a shader stage in a pipeline is indicated by including a valid
VkPipelineShaderStageCreateInfo
with module
and pName
selecting an entry point from a shader module, where that entry point is
valid for the stage specified by stage
.
Presence of some of the fixed-function stages in the pipeline is implicitly derived from enabled shaders and provided state. For example, the fixed-function tessellator is always present when the pipeline has valid Tessellation Control and Tessellation Evaluation shaders.
For example:
Depth/stencil-only rendering in a subpass with no color attachments
Active Pipeline Shader Stages
Required: Fixed-Function Pipeline Stages
Color-only rendering in a subpass with no depth/stencil attachment
Active Pipeline Shader Stages
Required: Fixed-Function Pipeline Stages
Rendering pipeline with tessellation and geometry shaders
Active Pipeline Shader Stages
Required: Fixed-Function Pipeline Stages