VKGRAPHICSPIPELINECR(3)

NAME
VkGraphicsPipelineCreateInfo - Structure specifying parameters of a newly created graphics pipeline

C SPECIFICATION

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;

MEMBERS

    • 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 can 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 renderPass 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.

DESCRIPTION

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.

VALID USAGE

    • sType must be VK_STRUCTURE_TYPE_GRAPHICS_PIPELINE_CREATE_INFO

    • pNext must be NULL

    • flags must be a valid combination of VkPipelineCreateFlagBits values

    • pStages must be a pointer to an array of stageCount valid VkPipelineShaderStageCreateInfo structures

    • pVertexInputState must be a pointer to a valid VkPipelineVertexInputStateCreateInfo structure

    • pInputAssemblyState must be a pointer to a valid VkPipelineInputAssemblyStateCreateInfo structure

    • pRasterizationState must be a pointer to a valid VkPipelineRasterizationStateCreateInfo structure

    • If pDynamicState is not NULL, pDynamicState must be a pointer to a valid VkPipelineDynamicStateCreateInfo structure

    • layout must be a valid VkPipelineLayout handle

    • renderPass must be a valid VkRenderPass handle

    • stageCount must be greater than 0

    • Each of layout, renderPass and basePipelineHandle that are valid handles must have been created, allocated or retrieved from the same VkDevice

    • If flags contains the VK_PIPELINE_CREATE_DERIVATIVE_BIT flag, and basePipelineIndex is not -1, basePipelineHandle must be VK_NULL_HANDLE

    • If flags contains the VK_PIPELINE_CREATE_DERIVATIVE_BIT flag, and basePipelineIndex is not -1, it must be a valid index into the calling command’s pCreateInfos parameter

    • If flags contains the VK_PIPELINE_CREATE_DERIVATIVE_BIT flag, and basePipelineHandle is not VK_NULL_HANDLE, basePipelineIndex must be -1

    • If flags contains the VK_PIPELINE_CREATE_DERIVATIVE_BIT flag, and basePipelineHandle is not VK_NULL_HANDLE, basePipelineHandle must be a valid VkPipeline handle

    • If flags contains the VK_PIPELINE_CREATE_DERIVATIVE_BIT flag, and basePipelineHandle is not VK_NULL_HANDLE, it must be a valid handle to a graphics VkPipeline

    • The stage member of each element of pStages must be unique

    • The stage member of one element of pStages must be VK_SHADER_STAGE_VERTEX_BIT

    • The stage member of any given element of pStages must not be VK_SHADER_STAGE_COMPUTE_BIT

    • If pStages includes a tessellation control shader stage, it must include a tessellation evaluation shader stage

    • If pStages includes a tessellation evaluation shader stage, it must include a tessellation control shader stage

    • If pStages includes a tessellation control shader stage and a tessellation evaluation shader stage, pTessellationState must not be NULL

    • If pStages includes tessellation shader stages, the shader code of at least one stage must contain an OpExecutionMode instruction that specifies the type of subdivision in the pipeline

    • If pStages includes tessellation shader stages, and the shader code of both stages contain an OpExecutionMode instruction that specifies the type of subdivision in the pipeline, they must both specify the same subdivision mode

    • If pStages includes tessellation shader stages, the shader code of at least one stage must contain an OpExecutionMode instruction that specifies the output patch size in the pipeline

    • If pStages includes tessellation shader stages, and the shader code of both contain an OpExecutionMode instruction that specifies the out patch size in the pipeline, they must both specify the same patch size

    • If pStages includes tessellation shader stages, the topology member of pInputAssembly must be VK_PRIMITIVE_TOPOLOGY_PATCH_LIST

    • If the topology member of pInputAssembly is VK_PRIMITIVE_TOPOLOGY_PATCH_LIST, pStages must include tessellation shader stages

    • If pStages includes a geometry shader stage, and does not include any tessellation shader stages, its shader code must contain an OpExecutionMode instruction that specifies an input primitive type that is compatible with the primitive topology specified in pInputAssembly

    • If pStages includes a geometry shader stage, and also includes tessellation shader stages, its shader code must contain an OpExecutionMode instruction that specifies an input primitive type that is compatible with the primitive topology that is output by the tessellation stages

    • If pStages includes a fragment shader stage and a geometry shader stage, and the fragment shader code reads from an input variable that is decorated with PrimitiveID, then the geometry shader code must write to a matching output variable, decorated with PrimitiveID, in all execution paths

    • If pStages includes a fragment shader stage, its shader code must not read from any input attachment that is defined as VK_ATTACHMENT_UNUSED in subpass

    • The shader code for the entry points identified by pStages, and the rest of the state identified by this structure must adhere to the pipeline linking rules described in the Shader Interfaces chapter

    • If subpass uses a depth/stencil attachment in renderpass that has a layout of VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL in the VkAttachmentReference defined by subpass, and pDepthStencilState is not NULL, the depthWriteEnable member of pDepthStencilState must be VK_FALSE

    • If subpass uses a depth/stencil attachment in renderpass that has a layout of VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL in the VkAttachmentReference defined by subpass, and pDepthStencilState is not NULL, the failOp, passOp and depthFailOp members of each of the front and back members of pDepthStencilState must be VK_STENCIL_OP_KEEP

    • If pColorBlendState is not NULL, the blendEnable member of each element of the pAttachment member of pColorBlendState must be VK_FALSE if the format of the attachment referred to in subpass of renderPass does not support color blend operations, as specified by the VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BLEND_BIT flag in VkFormatProperties::linearTilingFeatures or VkFormatProperties::optimalTilingFeatures returned by vkGetPhysicalDeviceFormatProperties

    • If pColorBlendState is not NULL, The attachmentCount member of pColorBlendState must be equal to the colorAttachmentCount used to create subpass

    • If no element of the pDynamicStates member of pDynamicState is VK_DYNAMIC_STATE_VIEWPORT, the pViewports member of pViewportState must be a pointer to an array of pViewportState→viewportCount VkViewport structures

    • If no element of the pDynamicStates member of pDynamicState is VK_DYNAMIC_STATE_SCISSOR, the pScissors member of pViewportState must be a pointer to an array of pViewportState→scissorCount VkRect2D structures

    • If the wide lines feature is not enabled, and no element of the pDynamicStates member of pDynamicState is VK_DYNAMIC_STATE_LINE_WIDTH, the lineWidth member of pRasterizationState must be 1.0

    • If the rasterizerDiscardEnable member of pRasterizationState is VK_FALSE, pViewportState must be a pointer to a valid VkPipelineViewportStateCreateInfo structure

    • If the rasterizerDiscardEnable member of pRasterizationState is VK_FALSE, pMultisampleState must be a pointer to a valid VkPipelineMultisampleStateCreateInfo structure

    • If the rasterizerDiscardEnable member of pRasterizationState is VK_FALSE, and subpass uses a depth/stencil attachment, pDepthStencilState must be a pointer to a valid VkPipelineDepthStencilStateCreateInfo structure

    • If the rasterizerDiscardEnable member of pRasterizationState is VK_FALSE, and subpass uses color attachments, pColorBlendState must be a pointer to a valid VkPipelineColorBlendStateCreateInfo structure

    • If the depth bias clamping feature is not enabled, no element of the pDynamicStates member of pDynamicState is VK_DYNAMIC_STATE_DEPTH_BIAS, and the depthBiasEnable member of pDepthStencil is VK_TRUE, the depthBiasClamp member of pDepthStencil must be 0.0

    • If no element of the pDynamicStates member of pDynamicState is VK_DYNAMIC_STATE_DEPTH_BOUNDS, and the depthBoundsTestEnable member of pDepthStencil is VK_TRUE, the minDepthBounds and maxDepthBounds members of pDepthStencil must be between 0.0 and 1.0, inclusive

    • layout must be consistent with all shaders specified in pStages

    • If subpass uses color and/or depth/stencil attachments, then the rasterizationSamples member of pMultisampleState must be the same as the sample count for those subpass attachments

    • If subpass does not use any color and/or depth/stencil attachments, then the rasterizationSamples member of pMultisampleState must follow the rules for a zero-attachment subpass

    • subpass must be a valid subpass within renderpass

SEE ALSO

VkPipeline, VkPipelineColorBlendStateCreateInfo, VkPipelineCreateFlags, VkPipelineDepthStencilStateCreateInfo, VkPipelineDynamicStateCreateInfo, VkPipelineInputAssemblyStateCreateInfo, VkPipelineLayout, VkPipelineMultisampleStateCreateInfo, VkPipelineRasterizationStateCreateInfo, VkPipelineShaderStageCreateInfo, VkPipelineTessellationStateCreateInfo, VkPipelineVertexInputStateCreateInfo, VkPipelineViewportStateCreateInfo, VkRenderPass, VkStructureType, vkCreateGraphicsPipelines

DOCUMENT NOTES

For more information, see the Vulkan Specification at URL

https://www.khronos.org/registry/vulkan/specs/1.0/xhtml/vkspec.html#VkGraphicsPipelineCreateInfo

This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification,not directly.

COPYRIGHT

Copyright (c) 2014-2016 Khronos Group. This work is licensed under a Creative Commons Attribution 4.0 International License.

AUTHOR

Khronos Group
    Author.