Vulkan规范：第九章 9.1

9.1. 计算管线

计算管线有单个静态计算着色器阶段和管线布局组成。

计算管线代表着一个计算着色器，通过参数module 和 pName从计算着色器中选择一个入口点来 调用vkCreateComputePipelines， 这个入口点定义了一个有效的计算着色器，包含在VkComputePipelineCreateInfo数据结构中的VkPipelineShaderStageCreateInfo。

可调用如下命令来创建计算管线：

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

• device 是创建计算管线的逻辑设备。

• pipelineCache 要么是 VK_NULL_HANDLE，表示禁止使用管线缓存；要么是一个有效的 pipeline cache 对象的 handle， 此时命令执行期间启用管线缓存。

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

• pCreateInfos 是一个 VkComputePipelineCreateInfo 数组。

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

• pPipelines 是一个指针，指向了承载被返回的计算管线对象的数组。

  editing-note

  TODO (Jon) - Should we say something like ``the i’th element of the pPipelines array is created based on the corresponding element of the pCreateInfos array''? Also for vkCreateGraphicsPipelinesbelow.

正确使用

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

VkComputePipelineCreateInfo 数据结构定义如下：

typedef struct VkComputePipelineCreateInfo {    VkStructureType                    sType;    const void*                        pNext;    VkPipelineCreateFlags              flags;    VkPipelineShaderStageCreateInfo    stage;    VkPipelineLayout                   layout;    VkPipeline                         basePipelineHandle;    int32_t                            basePipelineIndex;} VkComputePipelineCreateInfo;

• sType 是数据结构的类型。

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

• flags 提供了管线创建的可选信息，枚举类型为 VkPipelineCreateFlagBits。

• stage 是一个 VkPipelineShaderStageCreateInfo，描述了计算着色器。

• 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 the pCreateInfos parameter to use as a pipeline to derive from

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

stage 指向一个类型为VkPipelineShaderStageCreateInfo的数据

正确使用

• If flags contains the VK_PIPELINE_CREATE_DERIVATIVE_BIT flag, and basePipelineIndex is -1, basePipelineHandle must be a valid handle to a compute 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 stage must be VK_SHADER_STAGE_COMPUTE_BIT

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

• layout must be consistent with the layout of the compute shader specified in stage

Valid Usage (Implicit)

• sType must be VK_STRUCTURE_TYPE_COMPUTE_PIPELINE_CREATE_INFO

• pNext must be NULL

• flags must be a valid combination of VkPipelineCreateFlagBits values

• stage must be a valid VkPipelineShaderStageCreateInfo structure

• layout must be a valid VkPipelineLayout handle

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

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

typedef struct VkPipelineShaderStageCreateInfo {    VkStructureType                     sType;    const void*                         pNext;    VkPipelineShaderStageCreateFlags    flags;    VkShaderStageFlagBits               stage;    VkShaderModule                      module;    const char*                         pName;    const VkSpecializationInfo*         pSpecializationInfo;} VkPipelineShaderStageCreateInfo;

• sType 是数据结构的类型。

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

• flags 被保留。

• stage 是给管线阶段起的名字。 Bits which can be set include:

  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;

• module 是一个 VkShaderModule 类型对象，包含了这个阶段的着色器。

• pName 是一个指针，指向了一个以null结尾的UTF-8字符串，指定了这个阶段着色器入口的名字。

• pSpecializationInfo 是一个指针，指向了一个VkSpecializationInfo，在 Specialization Constants中有详细描述， 可以为 NULL。

正确使用

• If the geometry shaders feature is not enabled, stage must not be VK_SHADER_STAGE_GEOMETRY_BIT

• If the tessellation shaders feature is not enabled, stage must not be VK_SHADER_STAGE_TESSELLATION_CONTROL_BITor VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT

• stage must not be VK_SHADER_STAGE_ALL_GRAPHICS, or VK_SHADER_STAGE_ALL

• pName must be the name of an OpEntryPoint in module with an execution model that matches stage

• If the identified entry point includes any variable in its interface that is declared with the ClipDistance BuiltIndecoration, that variable must not have an array size greater than VkPhysicalDeviceLimits::maxClipDistances

• If the identified entry point includes any variable in its interface that is declared with the CullDistance BuiltIndecoration, that variable must not have an array size greater than VkPhysicalDeviceLimits::maxCullDistances

• If the identified entry point includes any variables in its interface that are declared with the ClipDistance or CullDistance BuiltIn decoration, those variables must not have array sizes which sum to more thanVkPhysicalDeviceLimits::maxCombinedClipAndCullDistances

• If the identified entry point includes any variable in its interface that is declared with the SampleMask BuiltIndecoration, that variable must not have an array size greater than VkPhysicalDeviceLimits::maxSampleMaskWords

• If stage is VK_SHADER_STAGE_VERTEX_BIT, the identified entry point must not include any input variable in its interface that is decorated with CullDistance

• If stage is VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT or VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT, and the identified entry point has an OpExecutionMode instruction that specifies a patch size with OutputVertices, the patch size must be greater than 0 and less than or equal toVkPhysicalDeviceLimits::maxTessellationPatchSize

• If stage is VK_SHADER_STAGE_GEOMETRY_BIT, the identified entry point must have an OpExecutionMode instruction that specifies a maximum output vertex count that is greater than 0 and less than or equal toVkPhysicalDeviceLimits::maxGeometryOutputVertices

• If stage is VK_SHADER_STAGE_GEOMETRY_BIT, the identified entry point must have an OpExecutionMode instruction that specifies an invocation count that is greater than 0 and less than or equal toVkPhysicalDeviceLimits::maxGeometryShaderInvocations

• If stage is VK_SHADER_STAGE_GEOMETRY_BIT, and the identified entry point writes to Layer for any primitive, it mustwrite the same value to Layer for all vertices of a given primitive

• If stage is VK_SHADER_STAGE_GEOMETRY_BIT, and the identified entry point writes to ViewportIndex for any primitive, it must write the same value to ViewportIndex for all vertices of a given primitive

• If stage is VK_SHADER_STAGE_FRAGMENT_BIT, the identified entry point must not include any output variables in its interface decorated with CullDistance

• If stage is VK_SHADER_STAGE_FRAGMENT_BIT, and the identified entry point writes to FragDepth in any execution path, it must write to FragDepth in all execution paths

Valid Usage (Implicit)

• sType must be VK_STRUCTURE_TYPE_PIPELINE_SHADER_STAGE_CREATE_INFO

• pNext must be NULL

• flags must be 0

• stage must be a valid VkShaderStageFlagBits value

• module must be a valid VkShaderModule handle

• pName must be a null-terminated string

• If pSpecializationInfo is not NULL, pSpecializationInfo must be a pointer to a valid VkSpecializationInfostructure