Modifiers
^^^^^^^^^^^^^^^
-TGSI supports modifiers on inputs (as well as saturate modifier on instructions).
+TGSI supports modifiers on inputs (as well as saturate and precise modifier
+on instructions).
+
+For arithmetic instruction having a precise modifier certain optimizations
+which may alter the result are disallowed. Example: *add(mul(a,b),c)* can't be
+optimized to TGSI_OPCODE_MAD, because some hardware only supports the fused
+MAD instruction.
For inputs which have a floating point type, both absolute value and
negation modifiers are supported (with absolute value being applied
.. opcode:: MAD - Multiply And Add
+Perform a * b + c. The implementation is free to decide whether there is an
+intermediate rounding step or not.
+
.. math::
dst.x = src0.x \times src1.x + src2.x
dst.w = src0.w \times src1.w + src2.w
-.. opcode:: DP2A - 2-component Dot Product And Add
-
-.. math::
-
- dst.x = src0.x \times src1.x + src0.y \times src1.y + src2.x
-
- dst.y = src0.x \times src1.x + src0.y \times src1.y + src2.x
-
- dst.z = src0.x \times src1.x + src0.y \times src1.y + src2.x
-
- dst.w = src0.x \times src1.x + src0.y \times src1.y + src2.x
-
-
.. opcode:: FRC - Fraction
.. math::
dst = src0.x^{src1.x}
-.. opcode:: XPD - Cross Product
-
-.. math::
-
- dst.x = src0.y \times src1.z - src1.y \times src0.z
-
- dst.y = src0.z \times src1.x - src1.z \times src0.x
-
- dst.z = src0.x \times src1.y - src1.x \times src0.y
-
- dst.w = 1
-
-
-.. opcode:: DPH - Homogeneous Dot Product
-
-This instruction replicates its result.
-
-.. math::
-
- dst = src0.x \times src1.x + src0.y \times src1.y + src0.z \times src1.z + src1.w
-
.. opcode:: COS - Cosine
dst = texture\_sample(unit, coord, lod)
-.. opcode:: PUSHA - Push Address Register On Stack
-
- push(src.x)
- push(src.y)
- push(src.z)
- push(src.w)
-
-.. note::
-
- Considered for cleanup.
-
-.. note::
-
- Considered for removal.
-
-.. opcode:: POPA - Pop Address Register From Stack
-
- dst.w = pop()
- dst.z = pop()
- dst.y = pop()
- dst.x = pop()
-
-.. note::
-
- Considered for cleanup.
-
-.. note::
-
- Considered for removal.
-
-
-.. opcode:: CALLNZ - Subroutine Call If Not Zero
-
- TBD
-
-.. note::
-
- Considered for cleanup.
-
-.. note::
-
- Considered for removal.
-
-
Compute ISA
^^^^^^^^^^^^^^^^^^^^^^^^
destination register, which is assumed to be an address (ADDR) register.
-.. opcode:: SAD - Sum Of Absolute Differences
-
-.. math::
-
- dst.x = |src0.x - src1.x| + src2.x
-
- dst.y = |src0.y - src1.y| + src2.y
-
- dst.z = |src0.z - src1.z| + src2.z
-
- dst.w = |src0.w - src1.w| + src2.w
-
-
.. opcode:: TXF - Texel Fetch
As per NV_gpu_shader4, extract a single texel from a specified texture
- image. The source sampler may not be a CUBE or SHADOW. src 0 is a
+ image or PIPE_BUFFER resource. The source sampler may not be a CUBE or
+ SHADOW. src 0 is a
four-component signed integer vector used to identify the single texel
- accessed. 3 components + level. Just like texture instructions, an optional
+ accessed. 3 components + level. If the texture is multisampled, then
+ the fourth component indicates the sample, not the mipmap level.
+ Just like texture instructions, an optional
offset vector is provided, which is subject to various driver restrictions
(regarding range, source of offsets). This instruction ignores the sampler
state.
TXF(uint_vec coord, int_vec offset).
-.. opcode:: TXF_LZ - Texel Fetch
-
- This is the same as TXF with level = 0. Like TXF, it obeys
- pipe_sampler_view::u.tex.first_level.
-
-
.. opcode:: TXQ - Texture Size Query
As per NV_gpu_program4, retrieve the dimensions of the texture depending on
.. opcode:: TXQS - Texture Samples Query
This retrieves the number of samples in the texture, and stores it
- into the x component. The other components are undefined.
+ into the x component as an unsigned integer. The other components are
+ undefined. If the texture is not multisampled, this function returns
+ (1, undef, undef, undef).
.. math::
.. math::
- dst.x = src0.x \ src1.x
+ dst.x = \frac{src0.x}{src1.x}
- dst.y = src0.y \ src1.y
+ dst.y = \frac{src0.y}{src1.y}
- dst.z = src0.z \ src1.z
+ dst.z = \frac{src0.z}{src1.z}
- dst.w = src0.w \ src1.w
+ dst.w = \frac{src0.w}{src1.w}
.. opcode:: UDIV - Unsigned Integer Division
.. math::
- dst.x = src0.x \ src1.x
+ dst.x = \frac{src0.x}{src1.x}
- dst.y = src0.y \ src1.y
+ dst.y = \frac{src0.y}{src1.y}
- dst.z = src0.z \ src1.z
+ dst.z = \frac{src0.z}{src1.z}
- dst.w = src0.w \ src1.w
+ dst.w = \frac{src0.w}{src1.w}
.. opcode:: UMOD - Unsigned Integer Remainder
.. math::
- dst.x = src0.x \ src1.x
+ dst.x = src0.x \bmod src1.x
- dst.y = src0.y \ src1.y
+ dst.y = src0.y \bmod src1.y
- dst.z = src0.z \ src1.z
+ dst.z = src0.z \bmod src1.z
- dst.w = src0.w \ src1.w
+ dst.w = src0.w \bmod src1.w
.. opcode:: NOT - Bitwise Not
These opcodes are part of :term:`GLSL`'s opcode set. Support for these
opcodes is determined by a special capability bit, ``GLSL``.
-Some require glsl version 1.30 (UIF/BREAKC/SWITCH/CASE/DEFAULT/ENDSWITCH).
+Some require glsl version 1.30 (UIF/SWITCH/CASE/DEFAULT/ENDSWITCH).
.. opcode:: CAL - Subroutine Call
or switch/endswitch.
-.. opcode:: BREAKC - Break Conditional
-
- Conditionally moves the point of execution to the instruction after the
- next endloop or endswitch. The instruction must appear within a loop/endloop
- or switch/endswitch.
- Condition evaluates to true if src0.x != 0 where src0.x is interpreted
- as an integer register.
-
-.. note::
-
- Considered for removal as it's quite inconsistent wrt other opcodes
- (could emulate with UIF/BRK/ENDIF).
-
-
.. opcode:: IF - Float If
Start an IF ... ELSE .. ENDIF block. Condition evaluates to true if
.. math::
- dst.xy = src0.xy \ src1.xy
+ dst.xy = \frac{src0.xy}{src1.xy}
- dst.zw = src0.zw \ src1.zw
+ dst.zw = \frac{src0.zw}{src1.zw}
.. opcode:: U64DIV - 64-bit Unsigned Integer Division
.. math::
- dst.xy = src0.xy \ src1.xy
+ dst.xy = \frac{src0.xy}{src1.xy}
- dst.zw = src0.zw \ src1.zw
+ dst.zw = \frac{src0.zw}{src1.zw}
.. opcode:: U64MOD - 64-bit Unsigned Integer Remainder
.. opcode:: SAMPLE_POS
- Query the position of a given sample. dst receives float4 (x, y, 0, 0)
- indicated where the sample is located. If the resource is not a multi-sample
- resource and not a render target, the result is 0.
+ Query the position of a sample in the given resource or render target
+ when per-sample fragment shading is in effect.
+
+ Syntax: ``SAMPLE_POS dst, source, sample_index``
+
+ dst receives float4 (x, y, undef, undef) indicated where the sample is
+ located. Sample locations are in the range [0, 1] where 0.5 is the center
+ of the fragment.
+
+ source is either a sampler view (to indicate a shader resource) or temp
+ register (to indicate the render target). The source register may have
+ an optional swizzle to apply to the returned result
+
+ sample_index is an integer scalar indicating which sample position is to
+ be queried.
+
+ If per-sample shading is not in effect or the source resource or render
+ target is not multisampled, the result is (0.5, 0.5, undef, undef).
+
+ NOTE: no driver has implemented this opcode yet (and no state tracker
+ emits it). This information is subject to change.
.. opcode:: SAMPLE_INFO
- dst receives number of samples in x. If the resource is not a multi-sample
- resource and not a render target, the result is 0.
+ Query the number of samples in a multisampled resource or render target.
+
+ Syntax: ``SAMPLE_INFO dst, source``
+
+ dst receives int4 (n, 0, 0, 0) where n is the number of samples in a
+ resource or the render target.
+
+ source is either a sampler view (to indicate a shader resource) or temp
+ register (to indicate the render target). The source register may have
+ an optional swizzle to apply to the returned result
+ If per-sample shading is not in effect or the source resource or render
+ target is not multisampled, the result is (1, 0, 0, 0).
+
+ NOTE: no driver has implemented this opcode yet (and no state tracker
+ emits it). This information is subject to change.
.. _resourceopcodes:
Resource Access Opcodes
^^^^^^^^^^^^^^^^^^^^^^^
+For these opcodes, the resource can be a BUFFER, IMAGE, or MEMORY.
+
.. opcode:: LOAD - Fetch data from a shader buffer or image
Syntax: ``LOAD dst, resource, address``
within the same compute grid. For now they're only valid in compute
programs.
-.. opcode:: MFENCE - Memory fence
-
- Syntax: ``MFENCE resource``
-
- Example: ``MFENCE RES[0]``
-
- This opcode forces strong ordering between any memory access
- operations that affect the specified resource. This means that
- previous loads and stores (and only those) will be performed and
- visible to other threads before the program execution continues.
-
-
-.. opcode:: LFENCE - Load memory fence
-
- Syntax: ``LFENCE resource``
-
- Example: ``LFENCE RES[0]``
-
- Similar to MFENCE, but it only affects the ordering of memory loads.
-
-
-.. opcode:: SFENCE - Store memory fence
-
- Syntax: ``SFENCE resource``
-
- Example: ``SFENCE RES[0]``
-
- Similar to MFENCE, but it only affects the ordering of memory stores.
-
-
.. opcode:: BARRIER - Thread group barrier
``BARRIER``
logical operations. In this context atomicity means that another
concurrent memory access operation that affects the same memory
location is guaranteed to be performed strictly before or after the
-entire execution of the atomic operation. The resource may be a buffer
-or an image. In the case of an image, the offset works the same as for
+entire execution of the atomic operation. The resource may be a BUFFER,
+IMAGE, or MEMORY. In the case of an image, the offset works the same as for
``LOAD`` and ``STORE``, specified above. These atomic operations may
only be used with 32-bit integer image formats.
contains the index of the viewport (and scissor) to use.
This is an integer value, and only the X component is used.
+If PIPE_CAP_TGSI_VS_LAYER_VIEWPORT or PIPE_CAP_TGSI_TES_LAYER_VIEWPORT is
+supported, then this semantic label can also be used in vertex or
+tessellation evaluation shaders, respectively. Only the value written in the
+last vertex processing stage is used.
+
TGSI_SEMANTIC_LAYER
"""""""""""""""""""
This is an integer value, and only the X component is used.
(Also known as rendertarget array index.)
+If PIPE_CAP_TGSI_VS_LAYER_VIEWPORT or PIPE_CAP_TGSI_TES_LAYER_VIEWPORT is
+supported, then this semantic label can also be used in vertex or
+tessellation evaluation shaders, respectively. Only the value written in the
+last vertex processing stage is used.
+
TGSI_SEMANTIC_CULLDIST
""""""""""""""""""""""
""""""""""""""""""""""
For fragment shaders, this semantic label indicates that a system value
-contains the current sample id (i.e. gl_SampleID).
-This is an integer value, and only the X component is used.
+contains the current sample id (i.e. gl_SampleID) as an unsigned int.
+Only the X component is used. If per-sample shading is not enabled,
+the result is (0, undef, undef, undef).
+
+Note that if the fragment shader uses this system value, the fragment
+shader is automatically executed at per sample frequency.
TGSI_SEMANTIC_SAMPLEPOS
"""""""""""""""""""""""
-For fragment shaders, this semantic label indicates that a system value
-contains the current sample's position (i.e. gl_SamplePosition). Only the X
-and Y values are used.
+For fragment shaders, this semantic label indicates that a system
+value contains the current sample's position as float4(x, y, undef, undef)
+in the render target (i.e. gl_SamplePosition) when per-fragment shading
+is in effect. Position values are in the range [0, 1] where 0.5 is
+the center of the fragment.
+
+Note that if the fragment shader uses this system value, the fragment
+shader is automatically executed at per sample frequency.
TGSI_SEMANTIC_SAMPLEMASK
""""""""""""""""""""""""
-For fragment shaders, this semantic label indicates that an output contains
-the sample mask used to disable further sample processing
-(i.e. gl_SampleMask). Only the X value is used, up to 32x MS.
+For fragment shaders, this semantic label can be applied to either a
+shader system value input or output.
+
+For a system value, the sample mask indicates the set of samples covered by
+the current primitive. If MSAA is not enabled, the value is (1, 0, 0, 0).
+
+For an output, the sample mask is used to disable further sample processing.
+
+For both, the register type is uint[4] but only the X component is used
+(i.e. gl_SampleMask[0]). Each bit corresponds to one sample position (up
+to 32x MSAA is supported).
TGSI_SEMANTIC_INVOCATIONID
""""""""""""""""""""""""""
current thread inside of the block.
+TGSI_SEMANTIC_SUBGROUP_SIZE
+"""""""""""""""""""""""""""
+
+This semantic indicates the subgroup size for the current invocation. This is
+an integer of at most 64, as it indicates the width of lanemasks. It does not
+depend on the number of invocations that are active.
+
+
+TGSI_SEMANTIC_SUBGROUP_INVOCATION
+"""""""""""""""""""""""""""""""""
+
+The index of the current invocation within its subgroup.
+
+
+TGSI_SEMANTIC_SUBGROUP_EQ_MASK
+""""""""""""""""""""""""""""""
+
+A bit mask of ``bit index == TGSI_SEMANTIC_SUBGROUP_INVOCATION``, i.e.
+``1 << subgroup_invocation`` in arbitrary precision arithmetic.
+
+
+TGSI_SEMANTIC_SUBGROUP_GE_MASK
+""""""""""""""""""""""""""""""
+
+A bit mask of ``bit index >= TGSI_SEMANTIC_SUBGROUP_INVOCATION``, i.e.
+``((1 << (subgroup_size - subgroup_invocation)) - 1) << subgroup_invocation``
+in arbitrary precision arithmetic.
+
+
+TGSI_SEMANTIC_SUBGROUP_GT_MASK
+""""""""""""""""""""""""""""""
+
+A bit mask of ``bit index > TGSI_SEMANTIC_SUBGROUP_INVOCATION``, i.e.
+``((1 << (subgroup_size - subgroup_invocation - 1)) - 1) << (subgroup_invocation + 1)``
+in arbitrary precision arithmetic.
+
+
+TGSI_SEMANTIC_SUBGROUP_LE_MASK
+""""""""""""""""""""""""""""""
+
+A bit mask of ``bit index <= TGSI_SEMANTIC_SUBGROUP_INVOCATION``, i.e.
+``(1 << (subgroup_invocation + 1)) - 1`` in arbitrary precision arithmetic.
+
+
+TGSI_SEMANTIC_SUBGROUP_LT_MASK
+""""""""""""""""""""""""""""""
+
+A bit mask of ``bit index > TGSI_SEMANTIC_SUBGROUP_INVOCATION``, i.e.
+``(1 << subgroup_invocation) - 1`` in arbitrary precision arithmetic.
+
+
Declaration Interpolate
^^^^^^^^^^^^^^^^^^^^^^^
should be set the same way for an entire pipeline. Note that this
applies not only to the literal MUL TGSI opcode, but all FP32
multiplications implied by other operations, such as MAD, FMA, DP2,
-DP3, DP4, DPH, DST, LOG, LRP, XPD, and possibly others. If there is a
+DP3, DP4, DST, LOG, LRP, and possibly others. If there is a
mismatch between shaders, then it is unspecified whether this behavior
will be enabled.
+FS_POST_DEPTH_COVERAGE
+""""""""""""""""""""""
+
+When enabled, the input for TGSI_SEMANTIC_SAMPLEMASK will exclude samples
+that have failed the depth/stencil tests. This is only valid when
+FS_EARLY_DEPTH_STENCIL is also specified.
+
Texture Sampling and Texture Formats
------------------------------------