Vulkan规范：第九章 9.2

9.2. 图形管线

图形管线由多个着色器阶段、多个固定功能管线阶段和管线布局组成。

想创建图形管线，可调用：

VkResult vkCreateGraphicsPipelines(
    VkDevice                                    device,
    VkPipelineCache                             pipelineCache,
    uint32_t                                    createInfoCount,
    const VkGraphicsPipelineCreateInfo*         pCreateInfos,
    const VkAllocationCallbacks*                pAllocator,
    VkPipeline*                                 pPipelines);

• device 是创建图形管线的逻辑设备。

• pipelineCache 或者是 VK_NULL_HANDLE，表示禁用管线缓存；或者是一个pipeline cache 对象有效的handle，此时 该命令运行期间将启用该缓存。

• createInfoCount 是 pCreateInfos 和 pPipelines 数组的长度。

• pCreateInfos 是一个 VkGraphicsPipelineCreateInfo 数组。

• pAllocator 控制了CPU端内存分配，如 Memory Allocation 一章所描述。

• pPipelines 是一个指针，指向了存储被返回的图形管线对象的数组。

VkGraphicsPipelineCreateInfo 数据结构包含一个数组的着色器创建信息， 包括了所有想要的活跃的着色器阶段， 也包含了等译所有相关的固定管线阶段和管线布局。

正确使用

• If the flags member of any given element of pCreateInfos contains the VK_PIPELINE_CREATE_DERIVATIVE_BIT flag, and the basePipelineIndex member of that same element is not -1, basePipelineIndex must be less than the index into pCreateInfos that corresponds to that element

• If the flags member of any given element of pCreateInfos contains the VK_PIPELINE_CREATE_DERIVATIVE_BIT flag, the base pipeline must have been created with the VK_PIPELINE_CREATE_ALLOW_DERIVATIVES_BIT flag set

Valid Usage (Implicit)

• device must be a valid VkDevice handle

• If pipelineCache is not VK_NULL_HANDLE, pipelineCache must be a valid VkPipelineCache handle

• pCreateInfos must be a pointer to an array of createInfoCount valid VkGraphicsPipelineCreateInfo structures

• If pAllocator is not NULL, pAllocator must be a pointer to a valid VkAllocationCallbacks structure

• pPipelines must be a pointer to an array of createInfoCount VkPipeline handles

• createInfoCount must be greater than 0

• If pipelineCache is a valid handle, it must have been created, allocated, or retrieved from device

Return Codes

Success

• VK_SUCCESS

Failure

• VK_ERROR_OUT_OF_HOST_MEMORY

• VK_ERROR_OUT_OF_DEVICE_MEMORY

VkGraphicsPipelineCreateInfo 数据结构定义如下：

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 是数据结构的类型。

• pNext 是 NULL 或者一个指向拓展特定的数据结构的指针。

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

basePipelineHandle 和 basePipelineIndex 参数在 Pipeline Derivatives 中有详细的描述。

pStages 指向了一个 VkPipelineShaderStageCreateInfo 数组，此类型在之前的 Compute Pipelines中讲解过。

flags 有如下可选枚举值：

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 指定了创建的管线将不会被优化。使用这个标志位将减少创建管线的时间。

• VK_PIPELINE_CREATE_ALLOW_DERIVATIVES_BIT 指定了将要创建的管线可以是另外一个管线的父，子管线可以在接下来的一次vkCreateGraphicsPipelines调用中创建。

• VK_PIPELINE_CREATE_DERIVATIVE_BIT 指定了当前被创建的管线是之前被创建的管线的子。

同时设置VK_PIPELINE_CREATE_ALLOW_DERIVATIVES_BIT 和 VK_PIPELINE_CREATE_DERIVATIVE_BIT也是合法的。这将允许管线即是父，也是子。 参考Pipeline Derivatives 获取更多详细信息。

pDynamicState 指向一个类型为VkPipelineDynamicStateCreateInfo的数据结构。

正确使用

• If flags contains the VK_PIPELINE_CREATE_DERIVATIVE_BIT flag, and basePipelineIndex is -1, basePipelineHandle must be a valid handle to a graphics VkPipeline

• If flags contains the VK_PIPELINE_CREATE_DERIVATIVE_BIT flag, and basePipelineHandle is VK_NULL_HANDLE,basePipelineIndex must be a valid index into the calling command’s pCreateInfos parameter

• 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 basePipelineHandle is not VK_NULL_HANDLE,basePipelineIndex must be -1

• 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, pTessellationStatemust not be NULL

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

• If pStages includes tessellation shader stages, and the shader code of both stages contain an OpExecutionModeinstruction 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 OpExecutionModeinstruction 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 beVK_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 mustcontain 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 mustadhere to the pipeline linking rules described in the Shader Interfaces chapter

• If subpass uses a depth/stencil attachment in renderpass that has a layout ofVK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL in the VkAttachmentReference defined by subpass, andpDepthStencilState 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 ofVK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL in the VkAttachmentReference defined by subpass, andpDepthStencilState is not NULL, the failOp, passOp and depthFailOp members of each of the front and backmembers 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 inVkFormatProperties::linearTilingFeatures or VkFormatProperties::optimalTilingFeatures returned byvkGetPhysicalDeviceFormatProperties

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

• If no element of the pDynamicStates member of pDynamicState is VK_DYNAMIC_STATE_VIEWPORT, the pViewportsmember of pViewportState must be a pointer to an array of pViewportState::viewportCount VkViewportstructures

• If no element of the pDynamicStates member of pDynamicState is VK_DYNAMIC_STATE_SCISSOR, the pScissorsmember 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 isVK_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 isVK_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 thedepthBoundsTestEnable member of pDepthStencil is VK_TRUE, the minDepthBounds and maxDepthBoundsmembers 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 ofpMultisampleState must follow the rules for a zero-attachment subpass

• subpass must be a valid subpass within renderpass

Valid Usage (Implicit)

• 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 VkPipelineDynamicStateCreateInfostructure

• layout must be a valid VkPipelineLayout handle

• renderPass must be a valid VkRenderPass handle

• stageCount must be greater than 0

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

VkPipelineDynamicStateCreateInfo 类型数据结构定义如下：

typedef struct VkPipelineDynamicStateCreateInfo {
    VkStructureType                      sType;
    const void*                          pNext;
    VkPipelineDynamicStateCreateFlags    flags;
    uint32_t                             dynamicStateCount;
    const VkDynamicState*                pDynamicStates;
} VkPipelineDynamicStateCreateInfo;

• sType 是数据结构的类型。

• pNext 是 NULL 或者一个指向拓展特定的数据结构的指针。

• flags 被保留。

• dynamicStateCount 是 pDynamicStates 数组的元素个数。

• pDynamicStates是一个VkDynamicState枚举类型的数组，管线阶段的哪一部分将从动态命令中而不是从管线创建信息中使用值。

Valid Usage (Implicit)

• sType must be VK_STRUCTURE_TYPE_PIPELINE_DYNAMIC_STATE_CREATE_INFO

• pNext must be NULL

• flags must be 0

• pDynamicStates must be a pointer to an array of dynamicStateCount valid VkDynamicState values

• dynamicStateCount must be greater than 0

The source of difference pieces of dynamic state is determined by theVkPipelineDynamicStateCreateInfo::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 ofVkPipelineViewportStateCreateInfo.

• VK_DYNAMIC_STATE_LINE_WIDTH indicates that the lineWidth state in VkPipelineRasterizationStateCreateInfowill 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 anddepthBiasSlopeFactor states in VkPipelineRasterizationStateCreateInfo will be ignored and must be set dynamically with vkCmdSetDepthBias before any draws are performed with depthBiasEnable inVkPipelineRasterizationStateCreateInfo set to VK_TRUE.

• VK_DYNAMIC_STATE_BLEND_CONSTANTS indicates that the blendConstants state in VkPipelineColorBlendStateCreateInfo will be ignored and must be set dynamically withvkCmdSetBlendConstants 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 ofVkPipelineDepthStencilStateCreateInfo will be ignored and must be set dynamically with vkCmdSetDepthBounds before any draws are performed with a pipeline state withVkPipelineDepthStencilStateCreateInfo 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 withVkPipelineDepthStencilStateCreateInfo 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 withVkPipelineDepthStencilStateCreateInfo 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 withVkPipelineDepthStencilStateCreateInfo member stencilTestEnable set to VK_TRUE

9.2.1. Valid Combinations of Stages for Graphics Pipelines

如果省略了细分着色器阶段，那么细分着色和这个管线的固定功能就被跳过了。

若省略了几何着色器，几何着色阶段就被跳过。

若省略了片元着色器，片元处理的结果就是未定义的。 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

    • Vertex Shader

  • Required: Fixed-Function Pipeline Stages

    • VkPipelineVertexInputStateCreateInfo

    • VkPipelineInputAssemblyStateCreateInfo

    • VkPipelineViewportStateCreateInfo

    • VkPipelineRasterizationStateCreateInfo

    • VkPipelineMultisampleStateCreateInfo

    • VkPipelineDepthStencilStateCreateInfo

• Color-only rendering in a subpass with no depth/stencil attachment

  • Active Pipeline Shader Stages

    • Vertex Shader

    • Fragment Shader

  • Required: Fixed-Function Pipeline Stages

    • VkPipelineVertexInputStateCreateInfo

    • VkPipelineInputAssemblyStateCreateInfo

    • VkPipelineViewportStateCreateInfo

    • VkPipelineRasterizationStateCreateInfo

    • VkPipelineMultisampleStateCreateInfo

    • VkPipelineColorBlendStateCreateInfo

• 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

    • VkPipelineVertexInputStateCreateInfo

    • VkPipelineInputAssemblyStateCreateInfo

    • VkPipelineTessellationStateCreateInfo

    • VkPipelineViewportStateCreateInfo

    • VkPipelineRasterizationStateCreateInfo

    • VkPipelineMultisampleStateCreateInfo

    • VkPipelineDepthStencilStateCreateInfo

    • VkPipelineColorBlendStateCreateInfo