Vulkan Specification(Vulkan规范)：第十四章 14.6 内置变量

14.6. 内置变量

带有BuiltIn 修饰符修饰的变量是内置变量，可以在着色器内被访问。

每个 BuiltIn 修饰的含义有如下几种： 此节的剩余部分，内置变量的名称与术语带有内置修饰符的变量等同。 内置变量中整数类型的可以被声明为有符号或者无符号整数。

ClipDistance

Decorating a variable with the ClipDistance built-in decoration will make that variable contain the mechanism for controlling user clipping. ClipDistance is an array such that the ith element of the array specifies the clip distance for plane i. A clip distance of 0 means the vertex is on the plane, a positive distance means the vertex is inside the clip half-space, and a negative distance means the point is outside the clip half-space.

ClipDistance 修饰符只能在顶点、片元、细分控制、细分求值、几何着色器内使用。

在顶点着色器内，ClipDistance 修饰的任何变量必须使用 Output 存储类别来声明。

在片元着色器内，ClipDistance 修饰的变量必须使用Input 存储类别来声明。

在细分控制、细分求值、几何着色器内，ClipDistance 修饰的任何变量只能是Input 或者 Output类别。

ClipDistance 修饰的任何变量必须位声明位32位浮点型的数组。

注意 ClipDistance修饰的数组变量，会自动被着色器填充大小。

注意 在顶点处理阶段，这些值在图元之间被线性插值，部分插值距离小于0的图元 将被认为是超出剪裁空间。 若 ClipDistance 被片元着色器使用， ClipDistance将包含这些线性插值的值。

CullDistance

Decorating a variable with the CullDistance built-in decoration will make that variable contain the mechanism for controlling user culling. If any member of this array is assigned a negative value for all vertices belonging to a primitive, then the primitive is discarded before rasterization.

CullDistance 修饰符只能在顶点、片元、细分控制、细分求值、几何着色器中使用。

在顶点着色器中，CullDistance 修饰的任何变量必须使用 Output 存储类别来声明。

在片元着色器中，CullDistance 修饰的任何变量必须使用 Input 存储类别来声明。

在细分控制、细分求值、或几何着色器中，CullDistance 修饰的任何变量必须使用 input 或 output 类别。

CullDistance 修饰的任何变量必须被声明位32位浮点型的三元素数组。

注意 在片元着色器中，CullDistance 数组的值在每个图元之间被线性差值。

注意 若CullDistance 修饰一个 input variable，该变量将包含对应的值，从 上一个着色器阶段的 CullDistance 修饰的输出变量获得。

FragCoord

使用 FragCoord built-in 修饰符来修饰一个变量将造成该变量 包含片元着色器处理生成的帧缓冲区坐标 \((x,y,z,\frac{1}{w})\) 。 (x,y) 坐标 (0,0) 是帧缓冲区左上角像素的左上角。

当开启了采样着色时， FragCoord 的 x 和 y 成员反映了该着色器调用对应的采样位置。

当没有开启采样着色时，FragCoord 的x 和 y 成员反映了像素的中心 (0.5,0.5) 的位置 。

FragCoord的 z 成员是图元的插值深度值。

w 成员是插值的 \(\frac{1}{w}\).

FragCoord 修饰符只能在片元着色器中使用。

FragCoord 修饰的变量必须使用Input 存储类别来声明。

Centroid 差值修饰副被忽略，但是在FragCoord上是允许的。

FragCoord 修饰的变量必须被声明位32位浮点型的四元素数组。

FragDepth

Decorating a variable with the FragDepth built-in decoration will make that variable contain the new depth value for all samples covered by the fragment. This value will be used for depth testing and, if the depth test passes, any subsequent write to the depth/stencil attachment.

To write to FragDepth, a shader must declare the DepthReplacing execution mode. If a shader declares the DepthReplacing execution mode and there is an execution path through the shader that does not set FragDepth, then the fragment’s depth value is undefined for executions of the shader that take that path.

FragDepth 修饰符只能在片元着色器中使用。

FragDepth 修饰的变量必须使用Output 存储类别来声明。

FragDepth 修饰的变量必须被声明位32位浮点型标量。

FrontFacing

Decorating a variable with the FrontFacing built-in decoration will make that variable contain whether a primitive is front or back facing. This variable is non-zero if the current fragment is considered to be part of a front-facing primitive and is zero if the fragment is considered to be part of a back-facing primitive.

FrontFacing 修饰符只能在片元着色器中使用。

FrontFacing 修饰的变量必须使用 Input 存储类别来声明。

FrontFacing 修饰的变量必须被声明位boolean 类型。

GlobalInvocationId

Decorating a variable with the GlobalInvocationId built-in decoration will make that variable contain the location of the current invocation within the global workgroup. Each component is equal to the index of the local workgroup multiplied by the size of the local workgroup plus LocalInvocationId.

GlobalInvocationId 修饰符只能在计算着色器中使用。

GlobalInvocationId 修饰的变量必须使用 Input 存储类别来声明。

GlobalInvocationId 修饰的变量必须被声明为32位整型的三元素数组。

HelperInvocation

Decorating a variable with the HelperInvocation built-in decoration will make that variable contain whether the current invocation is a helper invocation. This variable is non-zero if the current fragment being shaded is a helper invocation and zero otherwise. A helper invocation is an invocation of the shader that is produced to satisfy internal requirements such as the generation of derivatives.

HelperInvocation 修饰符必须在片元着色器中使用。

HelperInvocation 修饰的变量必须使用 Input 存储类别来声明。

HelperInvocation 修饰的变量必须位声明为boolean类型。

注意 It is very likely that a helper invocation will have a value of SampleMask fragment shader input value that is zero.

InvocationId

Decorating a variable with the InvocationId built-in decoration will make that variable contain the index of the current shader invocation in a geometry shader, or the index of the output patch vertex in a tessellation control shader.

在几何着色器内，当前着色器调用的索引从0 到 着色器内声明的instances 减去1之差。 若几何着色器的实例数量是1或者未指定，那么 InvocationId 将为0.

InvocationId 修饰符只能在细分控制、几何着色器中使用。

InvocationId 修饰的变量必须使用Input 存储类别来声明。

InvocationId 修饰的变量必须被声明为32位整型标量。

InstanceIndex

Decorating a variable with the InstanceIndex built-in decoration will make that variable contain the index of the instance that is being processed by the current vertex shader invocation. InstanceIndex begins at the firstInstance parameter to vkCmdDraw or vkCmdDrawIndexed or at the firstInstance member of a structure consumed by vkCmdDrawIndirect or vkCmdDrawIndexedIndirect.

InstanceIndex 修饰符只能在顶点着色器中使用。

InstanceIndex 修饰的变量必须使用Input 存储类别来声明。

InstanceIndex 修饰的变量必须被声明位一个32位整型标量。

Layer

Decorating a variable with the Layer built-in decoration will make that variable contain the select layer of a multi-layer framebuffer attachment.

In a geometry shader, any variable decorated with Layer can be written with the framebuffer layer index to which the primitive produced by the geometry shader will be directed. If a geometry shader entry point’s interface does not include a variable decorated with Layer, then the first layer is used. If a geometry shader entry point’s interface includes a variable decorated with Layer, it must write the same value to Layer for all output vertices of a given primitive.

In a fragment shader, a variable decorated with Layer contains the layer index of the primitive that the fragment invocation belongs to.

Layer 修饰符只能在几何、片元着色器中使用。

在几何着色器中，Layer 修饰的任何变量必须使用Output 存储类别来声明。

在片元着色器中， Layer 修饰的任何变量必须使用Input 存储类别来声明。

Layer 修饰的任何变量必须被声明位32位整型标量。

LocalInvocationId

Decorating a variable with the LocalInvocationId built-in decoration will make that variable contain the location of the current compute shader invocation within the local workgroup. Each component ranges from zero through to the size of the workgroup in that dimension minus one.

LocalInvocationId 修饰符必须在计算着色器中使用。

LocalInvocationId 修饰的变量必须使用 Input 存储类别来声明。

LocalInvocationId 修饰的变量必须被声明位32位整型的三元素向量。

注意 If the size of the workgroup in a particular dimension is one, then the LocalInvocationId in that dimension will be zero. If the workgroup is effectively two-dimensional, then LocalInvocationId.z will be zero. If the workgroup is effectively one-dimensional, then both LocalInvocationId.y and LocalInvocationId.z will be zero.

NumWorkgroups

Decorating a variable with the NumWorkgroups built-in decoration will make that variable contain the number of local workgroups that are part of the dispatch that the invocation belongs to. Each component is equal to the values of the parameters passed into vkCmdDispatch or read from the VkDispatchIndirectCommand structure read through a call to vkCmdDispatchIndirect.

NumWorkgroups 修饰符只能在计算着色器中使用。

NumWorkgroups 修饰的变量必须使用Input 存储类别来声明。

NumWorkgroups 修饰的变量必须被声明位32位整型的三元素数组。

PatchVertices

Decorating a variable with the PatchVertices built-in decoration will make that variable contain the number of vertices in the input patch being processed by the shader. A single tessellation control or tessellation evaluation shader can read patches of differing sizes, so the value of the PatchVertices variable may differ between patches.

PatchVertices 修饰符只能在细分控制、细分求值着色器中使用。

PatchVertices 修饰的变量必须使用Input 存储类别来声明。

PatchVertices 修饰的变量必须被声明位32位整型标量。

PointCoord

Decorating a variable with the PointCoord built-in decoration will make that variable contain the coordinate of the current fragment within the point being rasterized, normalized to the size of the point with origin in the upper left corner of the point, as described in Basic Point Rasterization. If the primitive the fragment shader invocation belongs to is not a point, then the variable decorated with PointCoord contains an undefined value.

PointCoord 修饰符只能在片元着色器中使用。

PointCoord 修饰的变量必须使用Input 存储类别来声明。

PointCoord 修饰的变量必须被声明位32位浮点型二元素数组。

注意 取决于单点是如何被渲染的， PointCoord 可能永远不会达到 (0,0) 或 (1,1).

PointSize

给一个变量加上PointSize built-in 修饰符将导致该变量包含顶点图元的大小。 管线内最后的顶点处理阶段写入到PointSize修饰的该变量被用于 栅格化产生的帧缓冲区空间的点的大小。

PointSize 修饰符只能在顶点、细分控制、细分求值、几何着色器中使用。shaders.

在顶点着色器中，PointSize 修饰的任何变量必须使用Output 存储类别来声明。

在细分控制、细分求值、几何着色器中，PointSize 修饰的任何变量必须使用 Input 或者 Output 存储类别来声明。

PointSize 修饰的任何变量必须被声明位一个32位浮点型标量。

注意 When PointSize decorates a variable in the Input storage class, it contains the data written to the output variable decorated with PointSize from the previous shader stage.

Position

Decorating a variable with the Position built-in decoration will make that variable contain the position of the current vertex. In the last vertex processing stage, the value of the variable decorated with Position is used in subsequent primitive assembly, clipping, and rasterization operations.

Position 修饰符只能在顶点、细分控制、细分求值、几何着色器中使用。

在顶点着色器中，Position 修饰的任何变量必须使用 Output 存储类别来声明。

在细分控制、细分求值或几何着色器中， Position 修饰的任何变量只能使用 input 或者 output存储类别来声明。

Position 修饰的任何变量必须被声明为32位浮点型的四元素数组。

注意 When Position decorates a variable in the Input storage class, it contains the data written to the output variable decorated with Position from the previous shader stage.

PrimitiveId

使用 PrimitiveId built-in修饰符修饰的变量将让该变量包含当前图元的索引。

在细分控制和细分求值着色器中，它将包含 对应着色器调用的当前渲染图元内的patch的索引。

在几何着色器内，它将包含从当前渲染图元的集合开始之后 作为着色器输入的图元的个数。

在片元着色器中，它将包含几何着色器（若有的话）写入的图元索引，或者该值会当作 几何着色器（若有的话）的输入。

If a geometry shader is present and the fragment shader reads from an input variable decorated with PrimitiveId, then the geometry shader must write to an output variable decorated with PrimitiveId in all execution paths.

PrimitiveId 修饰符只能在片元、细分控制、细分求值、几何着色器中使用。

In a tessellation control or tessellation evaluation shader, any variable decorated with PrimitiveId must be declared using the Output storage class.

In a geometry shader, any variable decorated with PrimitiveId must be declared using either the Input or Output storage class.

In a fragment shader, any variable decorated with PrimitiveId must be declared using the Input storage class, and either the Geometry or Tessellation capability must also be declared.

PrimitiveId 修饰的任何变量必须被声明为32位整型标量。

注意 当PrimitiveId 修饰符被应用到几何着色器的一个输出变量上，生成的值在片元着色器中可以通过PrimitiveId修饰的输入变量看到。

SampleId

Decorating a variable with the SampleId built-in decoration will make that variable contain the zero-based index of the sample the invocation corresponds to. SampleId ranges from zero to the number of samples in the framebuffer minus one. If a fragment shader entry point’s interface includes an input variable decorated with SampleId, per-sample shading is enabled for draws that use that fragment shader.

SampleId 修饰符只能在片元着色器中使用。

SampleId 修饰的变量只能使用Input 存储类别修饰。

SampleId修饰的变量必须被声明为32位的标量整型。

SampleMask

Decorating a variable with the SampleMask built-in decoration will make any variable contain the sample coverage mask for the current fragment shader invocation.

A variable in the Input storage class decorated with SampleMask will contain a bitmask of the set of samples covered by the primitive generating the fragment during rasterization. It has a sample bit set if and only if the sample is considered covered for this fragment shader invocation. SampleMask[] is an array of integers. Bits are mapped to samples in a manner where bit B of mask M (SampleMask[M]) corresponds to sample 32 × M + B.

When state specifies multiple fragment shader invocations for a given fragment, the sample mask for any single fragment shader invocation specifies the subset of the covered samples for the fragment that correspond to the invocation. In this case, the bit corresponding to each covered sample will be set in exactly one fragment shader invocation.

A variable in the Output storage class decorated with SampleMask is an array of integers forming a bit array in a manner similar an input variable decorated with SampleMask, but where each bit represents coverage as computed by the shader. Modifying the sample mask by writing zero to a bit of SampleMask causes the sample to be considered uncovered. However, setting sample mask bits to one will never enable samples not covered by the original primitive. If the fragment shader is being evaluated at any frequency other than per-fragment, bits of the sample mask not corresponding to the current fragment shader invocation are ignored. This array must be sized in the fragment shader either implicitly or explicitly, to be no larger than the implementation-dependent maximum sample-mask (as an array of 32-bit elements), determined by the maximum number of samples. If a fragment shader entry point’s interface includes an output variable decorated with SampleMask, the sample mask will be undefined for any array elements of any fragment shader invocations that fail to assign a value. If a fragment shader entry point’s interface does not include an output variable decorated with SampleMask, the sample mask has no effect on the processing of a fragment.

SampleMask 修饰符只能在片元着色器内使用。

SampleMask 修饰的任何变量必须使用 Input 或 Output 存储类型来声明。

SampleMask修饰的任何变量必须被声明为32位整型的数组。

SamplePosition

Decorating a variable with the SamplePosition built-in decoration will make that variable contain the sub-pixel position of the sample being shaded. The top left of the pixel is considered to be at coordinate (0,0) and the bottom right of the pixel is considered to be at coordinate (1,1). If a fragment shader entry point’s interface includes an input variable decorated with SamplePosition, per-sample shading is enabled for draws that use that fragment shader.

SamplePosition 修饰符必须只在片元着色器中使用。

SamplePosition修饰的变量必须使用Input 存储类别来声明。

The variable decorated with SamplePosition must be declared as a two-component vector of 32-bit floating-point values.

TessCoord

Decorating a variable with the TessCoord built-in decoration will make that variable contain the three-dimensional (u,v,w) barycentric coordinate of the tessellated vertex within the patch. u, v, and w are in the range [0,1] and vary linearly across the primitive being subdivided. For the tessellation modes of Quads or IsoLines, the third component is always zero.

TessCoord 修饰符只能在细分求值着色器中使用。

TessCoord修饰的变量必须使用Input 存储类别来声明。

TessCoord 修饰的变量必须被声明为 32位浮点类型的三元素数组。

TessLevelOuter

Decorating a variable with the TessLevelOuter built-in decoration will make that variable contain the outer tessellation levels for the current patch.

In tessellation control shaders, the variable decorated with TessLevelOuter can be written to which controls the tessellation factors for the resulting patch. These values are used by the tessellator to control primitive tessellation and can be read by tessellation evaluation shaders.

在细分求值着色器内，TessLevelOuter修饰的变量可以读取 细分控制着色器写入的值。

TessLevelOuter 修饰符只能在细分控制着色器、细分求值着色器中使用。

在细分控制着色器内，TessLevelOuter修饰的任何变量必须使用 Output 存储类别来声明。

在细分求值着色器内，TessLevelOuter修饰的任何变量必须使用 Input 存储类别来声明。

TessLevelOuter修饰的任何变量必须被声明为32位浮点型的四元素数组。

TessLevelInner

Decorating a variable with the TessLevelInner built-in decoration will make that variable contain the inner tessellation levels for the current patch.

In tessellation control shaders, the variable decorated with TessLevelInner can be written to, which controls the tessellation factors for the resulting patch. These values are used by the tessellator to control primitive tessellation and can be read by tessellation evaluation shaders.

In tessellation evaluation shaders, the variable decorated with TessLevelInner can read the values written by the tessellation control shader.

TessLevelInner 修饰符只能在细分控制着色器、细分求值着色器内使用。

In a tessellation control shader, any variable decorated with TessLevelInner must be declared using the Output storage class.

In a tessellation evaluation shader, any variable decorated with TessLevelInner must be declared using the Input storage class.

Any variable decorated with TessLevelInner must be declared as an array of size two, containing 32-bit floating-point values.

VertexIndex

使用built-in 修饰符 VertexIndex 来修饰变量，将导致当前顶点着色器调用正在处理的该变量包含顶点的索引。 对于非索引化绘制，此变量从 firstVertex 参数开始 到 vkCmdDraw 或者 vkCmdDrawIndirect使用的数据结构的firstVertex 成员，且在绘制过程中对于每个顶点增长一个。 对于索引化绘制，它的值就是 顶点的索引缓冲区的内容加上 vkCmdDrawIndexed 命令的vertexOffset参数或者 vkCmdDrawIndexedIndirect使用的 vertexOffset成员。

VertexIndex 修饰符只能在顶点着色器内使用。

VertexIndex修饰的变量必须使用Input 存储类别来声明。

VertexIndex 修饰的变量必须被声明位32位的标量整型。

注意 VertexIndex 对于每个实例都从相同的值开始。

ViewportIndex

Decorating a variable with the ViewportIndex built-in decoration will make that variable contain the index of the viewport.

In a geometry shader, the variable decorated with ViewportIndex can be written to with the viewport index to which the primitive produced by the geometry shader will be directed. The selected viewport index is used to select the viewport transform and scissor rectangle. If a geometry shader entry point’s interface does not include a variable decorated with ViewportIndex, then the first viewport is used. If a geometry shader entry point’s interface includes a variable decorated with ViewportIndex, it must write the same value to ViewportIndex for all output vertices of a given primitive.

In a fragment shader, the variable decorated with ViewportIndex contains the viewport index of the primitive that the fragment invocation belongs to.

ViewportIndex 修饰符只能在几何着色器、片元着色器中使用。

在几何着色器内部，ViewportIndex 修饰的任何变量必须使用 Output 存储类别来声明。

在片元着色器内，ViewportIndex 修饰的任何变量必须使用 Input 存储类别来声明。

ViewportIndex修饰的任何变量必须被声明为32位整型标量。

WorkgroupId

Decorating a variable with the WorkgroupId built-in decoration will make that variable contain the global workgroup that the current invocation is a member of. Each component ranges from zero to the values of the parameters passed into vkCmdDispatch or read from the VkDispatchIndirectCommand structure read through a call to vkCmdDispatchIndirect.

WorkgroupId 修饰符只能在计算着色器内使用。

WorkgroupId 修饰的变量必须使用Input 存储类别来声明。

WorkgroupId 修饰的变量必须被声明位32位整型的三元素数组。

WorkgroupSize

Decorating a variable with the WorkgroupSize built-in decoration will make that variable contain the dimensions of a local workgroup. If an object is decorated with the WorkgroupSize decoration, this must take precedence over any execution mode set for LocalSize.

WorkgroupSize 修饰符只能在计算着色器内使用。

WorkgroupSize 修饰的对象必须是一个特化常量或者是一个常量。

WorkgroupSize 修饰的对象必须被声明为32位整型的三元素数组。