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位浮点型的数组。
注意
|
注意 在顶点处理阶段,这些值在图元之间被线性插值,部分插值距离小于0的图元 将被认为是超出剪裁空间。 若 |
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位浮点型的三元素数组。
注意 在片元着色器中, |
注意 若 |
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 |
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 |
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位浮点型二元素数组。
注意 取决于单点是如何被渲染的, |
PointSize
给一个变量加上PointSize
built-in 修饰符将导致该变量包含顶点图元的大小。 管线内最后的顶点处理阶段写入到PointSize
修饰的该变量被用于 栅格化产生的帧缓冲区空间的点的大小。
PointSize
修饰符只能在顶点、细分控制、细分求值、几何着色器中使用。shaders.
在顶点着色器中,PointSize
修饰的任何变量必须使用Output
存储类别来声明。
在细分控制、细分求值、几何着色器中,PointSize
修饰的任何变量必须使用 Input
或者 Output
存储类别来声明。
PointSize
修饰的任何变量必须被声明位一个32位浮点型标量。
注意 When |
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 |
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位整型标量。
注意 当 |
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位的标量整型。
注意
|
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位整型的三元素数组。