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