Vulkan规范：第九章 9.1

最新推荐文章于 2025-11-14 00:30:46 发布

翻译最新推荐文章于 2025-11-14 00:30:46 发布 · 719 阅读

文章标签：

#Vulkan #api #文档 #翻译 #英语

Vulkan专栏同时被 2 个专栏收录

99 篇文章

订阅专栏

图形

81 篇文章

订阅专栏

本文介绍如何使用 Vulkan API 创建计算管线，包括必要的 VkComputePipelineCreateInfo 和 VkPipelineShaderStageCreateInfo 结构体配置，以及创建过程中的注意事项。

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