TGSI¶

TGSI, Tungsten Graphics Shader Infrastructure, is an intermediate language for describing shaders. Since Gallium is inherently shaderful, shaders are an important part of the API. TGSI is the only intermediate representation used by all drivers.

Basics¶

All TGSI instructions, known as opcodes, operate on arbitrary-precision floating-point four-component vectors. An opcode may have up to one destination register, known as dst, and between zero and three source registers, called src0 through src2, or simply src if there is only one.

Some instructions, like I2F, permit re-interpretation of vector components as integers. Other instructions permit using registers as two-component vectors with double precision; see Double ISA.

When an instruction has a scalar result, the result is usually copied into each of the components of dst. When this happens, the result is said to be replicated to dst. RCP is one such instruction.

Source Modifiers¶

TGSI supports 32-bit negate and absolute value modifiers on floating-point inputs, and 32-bit integer negates on some drivers. The negate applies after absolute value if both are present.

The type of an input can be found by tgsi_opcode_infer_src_type(), and TGSI_OPCODE_MOV and the second and third operands of TGSI_OPCODE_UCMP (which return TGSI_TYPE_UNTYPED) are also considered floats for the purpose of source modifiers.

Other Modifiers¶

The saturate modifier clamps 32-bit destination stores to [0.0, 1.0].

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.

Instruction Set¶

Core ISA¶

These opcodes are guaranteed to be available regardless of the driver being used.

ARL (Address Register Load)¶: \[ \begin{align}\begin{aligned}dst.x = (int) \lfloor src.x\rfloor\\dst.y = (int) \lfloor src.y\rfloor\\dst.z = (int) \lfloor src.z\rfloor\\dst.w = (int) \lfloor src.w\rfloor\end{aligned}\end{align} \]

MOV (Move)¶: \[ \begin{align}\begin{aligned}dst.x = src.x\\dst.y = src.y\\dst.z = src.z\\dst.w = src.w\end{aligned}\end{align} \]

LIT (Light Coefficients)¶: \[ \begin{align}\begin{aligned}dst.x = 1\\dst.y = max(src.x, 0)\\\begin{split}dst.z = \left\{ \begin{array}{ c l } max(src.y, 0)^{clamp(src.w, -128, 128)} & \quad \textrm{if } src.x \gt 0 \\ 0 & \quad \textrm{otherwise} \end{array} \right.\end{split}\\dst.w = 1\end{aligned}\end{align} \]

RCP (Reciprocal)¶: This instruction replicates its result.

\[dst = \frac{1}{src.x}\]

RSQ (Reciprocal Square Root)¶: This instruction replicates its result. The results are undefined for src <= 0.

\[dst = \frac{1}{\sqrt{src.x}}\]

SQRT (Square Root)¶: This instruction replicates its result. The results are undefined for src < 0.

\[dst = {\sqrt{src.x}}\]

EXP (Approximate Exponential Base 2)¶: \[\begin{split}dst.x &= 2^{\lfloor src.x\rfloor} \\ dst.y &= src.x - \lfloor src.x\rfloor \\ dst.z &= 2^{src.x} \\ dst.w &= 1\end{split}\]

LOG (Approximate Logarithm Base 2)¶: \[\begin{split}dst.x &= \lfloor\log_2{|src.x|}\rfloor \\ dst.y &= \frac{|src.x|}{2^{\lfloor\log_2{|src.x|}\rfloor}} \\ dst.z &= \log_2{|src.x|} \\ dst.w &= 1\end{split}\]

MUL (Multiply)¶: \[ \begin{align}\begin{aligned}dst.x = src0.x \times src1.x\\dst.y = src0.y \times src1.y\\dst.z = src0.z \times src1.z\\dst.w = src0.w \times src1.w\end{aligned}\end{align} \]

ADD (Add)¶: \[ \begin{align}\begin{aligned}dst.x = src0.x + src1.x\\dst.y = src0.y + src1.y\\dst.z = src0.z + src1.z\\dst.w = src0.w + src1.w\end{aligned}\end{align} \]

DP3 (3-component Dot Product)¶: This instruction replicates its result.

\[\begin{split}\begin{aligned} dst = & src0.x \times src1.x +\\ & src0.y \times src1.y +\\ & src0.z \times src1.z \end{aligned}\end{split}\]

DP4 (4-component Dot Product)¶: This instruction replicates its result.

\[\begin{split}\begin{aligned} dst = & src0.x \times src1.x +\\ & src0.y \times src1.y +\\ & src0.z \times src1.z +\\ & src0.w \times src1.w \end{aligned}\end{split}\]

DST (Distance Vector)¶: \[\begin{split}dst.x &= 1\\ dst.y &= src0.y \times src1.y\\ dst.z &= src0.z\\ dst.w &= src1.w\end{split}\]

MIN (Minimum)¶: \[ \begin{align}\begin{aligned}dst.x = min(src0.x, src1.x)\\dst.y = min(src0.y, src1.y)\\dst.z = min(src0.z, src1.z)\\dst.w = min(src0.w, src1.w)\end{aligned}\end{align} \]

MAX (Maximum)¶: \[ \begin{align}\begin{aligned}dst.x = max(src0.x, src1.x)\\dst.y = max(src0.y, src1.y)\\dst.z = max(src0.z, src1.z)\\dst.w = max(src0.w, src1.w)\end{aligned}\end{align} \]

SLT (Set On Less Than)¶: \[ \begin{align}\begin{aligned}dst.x = (src0.x < src1.x) ? 1.0F : 0.0F\\dst.y = (src0.y < src1.y) ? 1.0F : 0.0F\\dst.z = (src0.z < src1.z) ? 1.0F : 0.0F\\dst.w = (src0.w < src1.w) ? 1.0F : 0.0F\end{aligned}\end{align} \]

SGE (Set On Greater Equal Than)¶: \[ \begin{align}\begin{aligned}dst.x = (src0.x >= src1.x) ? 1.0F : 0.0F\\dst.y = (src0.y >= src1.y) ? 1.0F : 0.0F\\dst.z = (src0.z >= src1.z) ? 1.0F : 0.0F\\dst.w = (src0.w >= src1.w) ? 1.0F : 0.0F\end{aligned}\end{align} \]

MAD (Multiply And Add)¶: Perform a * b + c. The implementation is free to decide whether there is an intermediate rounding step or not.

\[ \begin{align}\begin{aligned}dst.x = src0.x \times src1.x + src2.x\\dst.y = src0.y \times src1.y + src2.y\\dst.z = src0.z \times src1.z + src2.z\\dst.w = src0.w \times src1.w + src2.w\end{aligned}\end{align} \]

LRP (Linear Interpolate)¶: \[ \begin{align}\begin{aligned}dst.x = src0.x \times src1.x + (1 - src0.x) \times src2.x\\dst.y = src0.y \times src1.y + (1 - src0.y) \times src2.y\\dst.z = src0.z \times src1.z + (1 - src0.z) \times src2.z\\dst.w = src0.w \times src1.w + (1 - src0.w) \times src2.w\end{aligned}\end{align} \]

FMA (Fused Multiply-Add)¶: Perform a * b + c with no intermediate rounding step.

\[ \begin{align}\begin{aligned}dst.x = src0.x \times src1.x + src2.x\\dst.y = src0.y \times src1.y + src2.y\\dst.z = src0.z \times src1.z + src2.z\\dst.w = src0.w \times src1.w + src2.w\end{aligned}\end{align} \]

FRC (Fraction)¶: \[ \begin{align}\begin{aligned}dst.x = src.x - \lfloor src.x\rfloor\\dst.y = src.y - \lfloor src.y\rfloor\\dst.z = src.z - \lfloor src.z\rfloor\\dst.w = src.w - \lfloor src.w\rfloor\end{aligned}\end{align} \]

FLR (Floor)¶: \[ \begin{align}\begin{aligned}dst.x = \lfloor src.x\rfloor\\dst.y = \lfloor src.y\rfloor\\dst.z = \lfloor src.z\rfloor\\dst.w = \lfloor src.w\rfloor\end{aligned}\end{align} \]

ROUND (Round)¶: \[ \begin{align}\begin{aligned}dst.x = round(src.x)\\dst.y = round(src.y)\\dst.z = round(src.z)\\dst.w = round(src.w)\end{aligned}\end{align} \]

EX2 (Exponential Base 2)¶: This instruction replicates its result.

\[dst = 2^{src.x}\]

LG2 (Logarithm Base 2)¶: This instruction replicates its result.

\[dst = \log_2{src.x}\]

POW (Power)¶: This instruction replicates its result.

\[dst = src0.x^{src1.x}\]

LDEXP (Multiply Number by Integral Power of 2)¶: src1 is an integer.

\[ \begin{align}\begin{aligned}dst.x = src0.x * 2^{src1.x}\\dst.y = src0.y * 2^{src1.y}\\dst.z = src0.z * 2^{src1.z}\\dst.w = src0.w * 2^{src1.w}\end{aligned}\end{align} \]

COS (Cosine)¶: This instruction replicates its result.

\[dst = \cos{src.x}\]

DDX, DDX_FINE (Derivative Relative To X)¶: The fine variant is only used when PIPE_CAP_FS_FINE_DERIVATIVE is advertised. When it is, the fine version guarantees one derivative per row while DDX is allowed to be the same for the entire 2x2 quad.

\[ \begin{align}\begin{aligned}dst.x = partialx(src.x)\\dst.y = partialx(src.y)\\dst.z = partialx(src.z)\\dst.w = partialx(src.w)\end{aligned}\end{align} \]

DDY, DDY_FINE (Derivative Relative To Y)¶: The fine variant is only used when PIPE_CAP_FS_FINE_DERIVATIVE is advertised. When it is, the fine version guarantees one derivative per column while DDY is allowed to be the same for the entire 2x2 quad.

\[ \begin{align}\begin{aligned}dst.x = partialy(src.x)\\dst.y = partialy(src.y)\\dst.z = partialy(src.z)\\dst.w = partialy(src.w)\end{aligned}\end{align} \]

PK2H (Pack Two 16-bit Floats)¶: This instruction replicates its result.

\[\begin{split}\begin{aligned} dst = & f32\_to\_f16(src.x) | \\ ( & f32\_to\_f16(src.y) \ll 16) \end{aligned}\end{split}\]

PK2US (Pack Two Unsigned 16-bit Scalars)¶: This instruction replicates its result.

\[\begin{split}\begin{aligned} dst = & f32\_to\_unorm16(src.x) | \\ ( & f32\_to\_unorm16(src.y) \ll 16) \end{aligned}\end{split}\]

PK4B (Pack Four Signed 8-bit Scalars)¶: This instruction replicates its result.

\[\begin{split}\begin{aligned} dst = & f32\_to\_snorm8(src.x) | \\ ( & f32\_to\_snorm8(src.y) \ll 8) | \\ ( & f32\_to\_snorm8(src.z) \ll 16) | \\ ( & f32\_to\_snorm8(src.w) \ll 24) \end{aligned}\end{split}\]

PK4UB (Pack Four Unsigned 8-bit Scalars)¶: This instruction replicates its result.

\[\begin{split}\begin{aligned} dst = & f32\_to\_unorm8(src.x) | \\ ( & f32\_to\_unorm8(src.y) \ll 8) | \\ ( & f32\_to\_unorm8(src.z) \ll 16) | \\ ( & f32\_to\_unorm8(src.w) \ll 24) \end{aligned}\end{split}\]

SEQ (Set On Equal)¶: \[ \begin{align}\begin{aligned}dst.x = (src0.x == src1.x) ? 1.0F : 0.0F\\dst.y = (src0.y == src1.y) ? 1.0F : 0.0F\\dst.z = (src0.z == src1.z) ? 1.0F : 0.0F\\dst.w = (src0.w == src1.w) ? 1.0F : 0.0F\end{aligned}\end{align} \]

SGT (Set On Greater Than)¶: \[ \begin{align}\begin{aligned}dst.x = (src0.x > src1.x) ? 1.0F : 0.0F\\dst.y = (src0.y > src1.y) ? 1.0F : 0.0F\\dst.z = (src0.z > src1.z) ? 1.0F : 0.0F\\dst.w = (src0.w > src1.w) ? 1.0F : 0.0F\end{aligned}\end{align} \]

SIN (Sine)¶: This instruction replicates its result.

\[dst = \sin{src.x}\]

SLE (Set On Less Equal Than)¶: \[ \begin{align}\begin{aligned}dst.x = (src0.x <= src1.x) ? 1.0F : 0.0F\\dst.y = (src0.y <= src1.y) ? 1.0F : 0.0F\\dst.z = (src0.z <= src1.z) ? 1.0F : 0.0F\\dst.w = (src0.w <= src1.w) ? 1.0F : 0.0F\end{aligned}\end{align} \]

SNE (Set On Not Equal)¶: \[ \begin{align}\begin{aligned}dst.x = (src0.x != src1.x) ? 1.0F : 0.0F\\dst.y = (src0.y != src1.y) ? 1.0F : 0.0F\\dst.z = (src0.z != src1.z) ? 1.0F : 0.0F\\dst.w = (src0.w != src1.w) ? 1.0F : 0.0F\end{aligned}\end{align} \]

TEX (Texture Lookup)¶

for array textures src0.y contains the slice for 1D, and src0.z contain the slice for 2D.

for shadow textures with no arrays (and not cube map), src0.z contains the reference value.

for shadow textures with arrays, src0.z contains the reference value for 1D arrays, and src0.w contains the reference value for 2D arrays and cube maps.

for cube map array shadow textures, the reference value cannot be passed in src0.w, and TEX2 must be used instead.

\[ \begin{align}\begin{aligned}coord = src0\\shadow\_ref = src0.z \textrm{ or } src0.w \textrm{ (optional)}\\unit = src1\\dst = texture\_sample(unit, coord, shadow\_ref)\end{aligned}\end{align} \]

TEX2 (Texture Lookup (for shadow cube map arrays only))¶: this is the same as TEX, but uses another reg to encode the reference value.

\[ \begin{align}\begin{aligned}coord = src0\\shadow\_ref = src1.x\\unit = src2\\dst = texture\_sample(unit, coord, shadow\_ref)\end{aligned}\end{align} \]

TXD (Texture Lookup with Derivatives)¶: \[ \begin{align}\begin{aligned}coord = src0\\ddx = src1\\ddy = src2\\unit = src3\\dst = texture\_sample\_deriv(unit, coord, ddx, ddy)\end{aligned}\end{align} \]

TXP (Projective Texture Lookup)¶: \[ \begin{align}\begin{aligned}coord.x = src0.x / src0.w\\coord.y = src0.y / src0.w\\coord.z = src0.z / src0.w\\coord.w = src0.w\\unit = src1\\dst = texture\_sample(unit, coord)\end{aligned}\end{align} \]

UP2H (Unpack Two 16-Bit Floats)¶: \[ \begin{align}\begin{aligned}dst.x = f16\_to\_f32(src0.x \& 0xffff)\\dst.y = f16\_to\_f32(src0.x \gg 16)\\dst.z = f16\_to\_f32(src0.x \& 0xffff)\\dst.w = f16\_to\_f32(src0.x \gg 16)\end{aligned}\end{align} \]

Note
Considered for removal.

UP2US (Unpack Two Unsigned 16-Bit Scalars)¶: TBD

Note
Considered for removal.

UP4B (Unpack Four Signed 8-Bit Values)¶: TBD

Note
Considered for removal.

UP4UB (Unpack Four Unsigned 8-Bit Scalars)¶: TBD

Note
Considered for removal.

ARR (Address Register Load With Round)¶: \[ \begin{align}\begin{aligned}dst.x = (int) round(src.x)\\dst.y = (int) round(src.y)\\dst.z = (int) round(src.z)\\dst.w = (int) round(src.w)\end{aligned}\end{align} \]

SSG (Set Sign)¶: \[ \begin{align}\begin{aligned}dst.x = (src.x > 0) ? 1 : (src.x < 0) ? -1 : 0\\dst.y = (src.y > 0) ? 1 : (src.y < 0) ? -1 : 0\\dst.z = (src.z > 0) ? 1 : (src.z < 0) ? -1 : 0\\dst.w = (src.w > 0) ? 1 : (src.w < 0) ? -1 : 0\end{aligned}\end{align} \]

CMP (Compare)¶: \[ \begin{align}\begin{aligned}dst.x = (src0.x < 0) ? src1.x : src2.x\\dst.y = (src0.y < 0) ? src1.y : src2.y\\dst.z = (src0.z < 0) ? src1.z : src2.z\\dst.w = (src0.w < 0) ? src1.w : src2.w\end{aligned}\end{align} \]

KILL_IF (Conditional Discard)¶

Conditional discard. Allowed in fragment shaders only.

Pseudocode:

if (src.x < 0 || src.y < 0 || src.z < 0 || src.w < 0)
   discard
endif

KILL (Discard)¶: Unconditional discard. Allowed in fragment shaders only.

DEMOTE (Demote Invocation to a Helper)¶

This demotes the current invocation to a helper, but continues execution (while KILL may or may not terminate the invocation). After this runs, all the usual helper invocation rules apply about discarding buffer and render target writes. This is useful for having accurate derivatives in the other invocations which have not been demoted.

Allowed in fragment shaders only.

READ_HELPER (Reads Invocation Helper Status)¶

This is identical to TGSI_SEMANTIC_HELPER_INVOCATION, except this will read the current value, which might change as a result of a DEMOTE instruction.

Allowed in fragment shaders only.

TXB (Texture Lookup With Bias)¶

for cube map array textures and shadow cube maps, the bias value cannot be passed in src0.w, and TXB2 must be used instead.

if the target is a shadow texture, the reference value is always in src.z (this prevents shadow 3d and shadow 2d arrays from using this instruction, but this is not needed).

\[ \begin{align}\begin{aligned}coord.x = src0.x\\coord.y = src0.y\\coord.z = src0.z\\coord.w = none\\bias = src0.w\\unit = src1\\dst = texture\_sample(unit, coord, bias)\end{aligned}\end{align} \]

TXB2 (Texture Lookup With Bias (some cube maps only))¶

this is the same as TXB, but uses another reg to encode the LOD bias value for cube map arrays and shadow cube maps. Presumably shadow 2d arrays and shadow 3d targets could use this encoding too, but this is not legal.

if the target is a shadow cube map array, the reference value is in src1.y.

\[ \begin{align}\begin{aligned}coord = src0\\bias = src1.x\\unit = src2\\dst = texture\_sample(unit, coord, bias)\end{aligned}\end{align} \]

DIV (Divide)¶: \[ \begin{align}\begin{aligned}dst.x = \frac{src0.x}{src1.x}\\dst.y = \frac{src0.y}{src1.y}\\dst.z = \frac{src0.z}{src1.z}\\dst.w = \frac{src0.w}{src1.w}\end{aligned}\end{align} \]

DP2 (2-component Dot Product)¶: This instruction replicates its result.

\[\begin{split}\begin{aligned} dst = & src0.x \times src1.x + \\ & src0.y \times src1.y \end{aligned}\end{split}\]

TEX_LZ (Texture Lookup With LOD = 0)¶: This is the same as TXL with LOD = 0. Like every texture opcode, it obeys pipe_sampler_view::u.tex.first_level and pipe_sampler_state::min_lod. There is no way to override those two in shaders.

\[ \begin{align}\begin{aligned}coord.x = src0.x\\coord.y = src0.y\\coord.z = src0.z\\coord.w = none\\lod = 0\\unit = src1\\dst = texture\_sample(unit, coord, lod)\end{aligned}\end{align} \]

TXL (Texture Lookup With explicit LOD)¶

for cube map array textures, the explicit LOD value cannot be passed in src0.w, and TXL2 must be used instead.

if the target is a shadow texture, the reference value is always in src.z (this prevents shadow 3d / 2d array / cube targets from using this instruction, but this is not needed).

\[ \begin{align}\begin{aligned}coord.x = src0.x\\coord.y = src0.y\\coord.z = src0.z\\coord.w = none\\lod = src0.w\\unit = src1\\dst = texture\_sample(unit, coord, lod)\end{aligned}\end{align} \]

TXL2 (Texture Lookup With explicit LOD (for cube map arrays only))¶

this is the same as TXL, but uses another reg to encode the explicit LOD value. Presumably shadow 3d / 2d array / cube targets could use this encoding too, but this is not legal.

if the target is a shadow cube map array, the reference value is in src1.y.

\[ \begin{align}\begin{aligned}coord = src0\\lod = src1.x\\unit = src2\\dst = texture\_sample(unit, coord, lod)\end{aligned}\end{align} \]

Compute ISA¶

These opcodes are primarily provided for special-use computational shaders. Support for these opcodes indicated by a special pipe capability bit (TBD).

XXX doesn’t look like most of the opcodes really belong here.

CEIL (Ceiling)¶: \[ \begin{align}\begin{aligned}dst.x = \lceil src.x\rceil\\dst.y = \lceil src.y\rceil\\dst.z = \lceil src.z\rceil\\dst.w = \lceil src.w\rceil\end{aligned}\end{align} \]

TRUNC (Truncate)¶: \[ \begin{align}\begin{aligned}dst.x = trunc(src.x)\\dst.y = trunc(src.y)\\dst.z = trunc(src.z)\\dst.w = trunc(src.w)\end{aligned}\end{align} \]

MOD (Modulus)¶: \[ \begin{align}\begin{aligned}dst.x = src0.x \bmod src1.x\\dst.y = src0.y \bmod src1.y\\dst.z = src0.z \bmod src1.z\\dst.w = src0.w \bmod src1.w\end{aligned}\end{align} \]

UARL (Integer Address Register Load)¶: Moves the contents of the source register, assumed to be an integer, into the destination register, which is assumed to be an address (ADDR) register.

TXF (Texel Fetch)¶

As per GL_NV_gpu_program4, extract a single texel from a specified texture image or PIPE_BUFFER resource. The source sampler may not be a CUBE or SHADOW. src0 is a four-component signed integer vector used to identify the single texel 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).

TXQ (Texture Size Query)¶

As per GL_NV_gpu_program4, retrieve the dimensions of the texture depending on the target. For 1D (width), 2D/RECT/CUBE (width, height), 3D (width, height, depth), 1D array (width, layers), 2D array (width, height, layers). Also return the number of accessible levels (last_level - first_level + 1) in W.

For components which don’t return a resource dimension, their value is undefined.

\[ \begin{align}\begin{aligned}lod = src0.x\\dst.x = texture\_width(unit, lod)\\dst.y = texture\_height(unit, lod)\\dst.z = texture\_depth(unit, lod)\\dst.w = texture\_levels(unit)\end{aligned}\end{align} \]

TXQS (Texture Samples Query)¶: This retrieves the number of samples in the texture, and stores it 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).

\[dst.x = texture\_samples(unit)\]

TG4 (Texture Gather)¶

As per GL_ARB_texture_gather, gathers the four texels to be used in a bi-linear filtering operation and packs them into a single register. Only works with 2D, 2D array, cubemaps, and cubemaps arrays. For 2D textures, only the addressing modes of the sampler and the top level of any mip pyramid are used. Set W to zero. It behaves like the TEX instruction, but a filtered sample is not generated. The four samples that contribute to filtering are placed into XYZW in clockwise order, starting with the (u,v) texture coordinate delta at the following locations (-, +), (+, +), (+, -), (-, -), where the magnitude of the deltas are half a texel.

PIPE_CAP_TEXTURE_SM5 enhances this instruction to support shadow per-sample depth compares, single component selection, and a non-constant offset. It doesn’t allow support for the GL independent offset to get i0,j0. This would require another CAP is HW can do it natively. For now we lower that before TGSI.

PIPE_CAP_TGSI_TG4_COMPONENT_IN_SWIZZLE changes the encoding so that component is stored in the sampler source swizzle x.

(without TGSI_TG4_COMPONENT_IN_SWIZZLE)

\[ \begin{align}\begin{aligned}coord = src0\\component = src1\\dst = texture\_gather4 (unit, coord, component)\end{aligned}\end{align} \]

(with TGSI_TG4_COMPONENT_IN_SWIZZLE)

\[ \begin{align}\begin{aligned}coord = src0\\dst = texture\_gather4 (unit, coord)\\\text{component is encoded in sampler swizzle.}\end{aligned}\end{align} \]

(with SM5 - cube array shadow)

\[ \begin{align}\begin{aligned}coord = src0\\compare = src1\\dst = texture\_gather (uint, coord, compare)\end{aligned}\end{align} \]

LODQ (level of detail query)¶: Compute the LOD information that the texture pipe would use to access the texture. The Y component contains the computed LOD lambda_prime. The X component contains the LOD that will be accessed, based on min/max LODs and mipmap filters.

\[ \begin{align}\begin{aligned}coord = src0\\dst.xy = lodq(uint, coord);\end{aligned}\end{align} \]

CLOCK (retrieve the current shader time)¶: Invoking this instruction multiple times in the same shader should cause monotonically increasing values to be returned. The values are implicitly 64-bit, so if fewer than 64 bits of precision are available, to provide expected wraparound semantics, the value should be shifted up so that the most significant bit of the time is the most significant bit of the 64-bit value.

\[dst.xy = clock()\]

Integer ISA¶

These opcodes are used for integer operations. Support for these opcodes indicated by PIPE_SHADER_CAP_INTEGERS (all of them?)

I2F (Signed Integer To Float)¶: Rounding is unspecified (round to nearest even suggested).

\[ \begin{align}\begin{aligned}dst.x = (float) src.x\\dst.y = (float) src.y\\dst.z = (float) src.z\\dst.w = (float) src.w\end{aligned}\end{align} \]

U2F (Unsigned Integer To Float)¶: Rounding is unspecified (round to nearest even suggested).

\[ \begin{align}\begin{aligned}dst.x = (float) src.x\\dst.y = (float) src.y\\dst.z = (float) src.z\\dst.w = (float) src.w\end{aligned}\end{align} \]

F2I (Float to Signed Integer)¶: Rounding is towards zero (truncate). Values outside signed range (including NaNs) produce undefined results.

\[ \begin{align}\begin{aligned}dst.x = (int) src.x\\dst.y = (int) src.y\\dst.z = (int) src.z\\dst.w = (int) src.w\end{aligned}\end{align} \]

F2U (Float to Unsigned Integer)¶: Rounding is towards zero (truncate). Values outside unsigned range (including NaNs) produce undefined results.

\[ \begin{align}\begin{aligned}dst.x = (unsigned) src.x\\dst.y = (unsigned) src.y\\dst.z = (unsigned) src.z\\dst.w = (unsigned) src.w\end{aligned}\end{align} \]

UADD (Integer Add)¶: This instruction works the same for signed and unsigned integers. The low 32bit of the result is returned.

\[ \begin{align}\begin{aligned}dst.x = src0.x + src1.x\\dst.y = src0.y + src1.y\\dst.z = src0.z + src1.z\\dst.w = src0.w + src1.w\end{aligned}\end{align} \]

UMAD (Integer Multiply And Add)¶: This instruction works the same for signed and unsigned integers. The multiplication returns the low 32bit (as does the result itself).

\[ \begin{align}\begin{aligned}dst.x = src0.x \times src1.x + src2.x\\dst.y = src0.y \times src1.y + src2.y\\dst.z = src0.z \times src1.z + src2.z\\dst.w = src0.w \times src1.w + src2.w\end{aligned}\end{align} \]

UMUL (Integer Multiply)¶: This instruction works the same for signed and unsigned integers. The low 32bit of the result is returned.

\[ \begin{align}\begin{aligned}dst.x = src0.x \times src1.x\\dst.y = src0.y \times src1.y\\dst.z = src0.z \times src1.z\\dst.w = src0.w \times src1.w\end{aligned}\end{align} \]

IMUL_HI (Signed Integer Multiply High Bits)¶: The high 32bits of the multiplication of 2 signed integers are returned.

\[ \begin{align}\begin{aligned}dst.x = (src0.x \times src1.x) \gg 32\\dst.y = (src0.y \times src1.y) \gg 32\\dst.z = (src0.z \times src1.z) \gg 32\\dst.w = (src0.w \times src1.w) \gg 32\end{aligned}\end{align} \]

UMUL_HI (Unsigned Integer Multiply High Bits)¶: The high 32bits of the multiplication of 2 unsigned integers are returned.

\[ \begin{align}\begin{aligned}dst.x = (src0.x \times src1.x) \gg 32\\dst.y = (src0.y \times src1.y) \gg 32\\dst.z = (src0.z \times src1.z) \gg 32\\dst.w = (src0.w \times src1.w) \gg 32\end{aligned}\end{align} \]

IDIV (Signed Integer Division)¶: TBD: behavior for division by zero.

\[ \begin{align}\begin{aligned}dst.x = \frac{src0.x}{src1.x}\\dst.y = \frac{src0.y}{src1.y}\\dst.z = \frac{src0.z}{src1.z}\\dst.w = \frac{src0.w}{src1.w}\end{aligned}\end{align} \]

UDIV (Unsigned Integer Division)¶: For division by zero, 0xffffffff is returned.

\[ \begin{align}\begin{aligned}dst.x = \frac{src0.x}{src1.x}\\dst.y = \frac{src0.y}{src1.y}\\dst.z = \frac{src0.z}{src1.z}\\dst.w = \frac{src0.w}{src1.w}\end{aligned}\end{align} \]

UMOD (Unsigned Integer Remainder)¶: If src1 is zero, 0xffffffff is returned.

\[ \begin{align}\begin{aligned}dst.x = src0.x \bmod src1.x\\dst.y = src0.y \bmod src1.y\\dst.z = src0.z \bmod src1.z\\dst.w = src0.w \bmod src1.w\end{aligned}\end{align} \]

NOT (Bitwise Not)¶: \[ \begin{align}\begin{aligned}dst.x = \sim src.x\\dst.y = \sim src.y\\dst.z = \sim src.z\\dst.w = \sim src.w\end{aligned}\end{align} \]

AND (Bitwise And)¶: \[ \begin{align}\begin{aligned}dst.x = src0.x \& src1.x\\dst.y = src0.y \& src1.y\\dst.z = src0.z \& src1.z\\dst.w = src0.w \& src1.w\end{aligned}\end{align} \]

OR (Bitwise Or)¶: \[ \begin{align}\begin{aligned}dst.x = src0.x | src1.x\\dst.y = src0.y | src1.y\\dst.z = src0.z | src1.z\\dst.w = src0.w | src1.w\end{aligned}\end{align} \]

XOR (Bitwise Xor)¶: \[ \begin{align}\begin{aligned}dst.x = src0.x \oplus src1.x\\dst.y = src0.y \oplus src1.y\\dst.z = src0.z \oplus src1.z\\dst.w = src0.w \oplus src1.w\end{aligned}\end{align} \]

IMAX (Maximum of Signed Integers)¶: \[ \begin{align}\begin{aligned}dst.x = max(src0.x, src1.x)\\dst.y = max(src0.y, src1.y)\\dst.z = max(src0.z, src1.z)\\dst.w = max(src0.w, src1.w)\end{aligned}\end{align} \]

UMAX (Maximum of Unsigned Integers)¶: \[ \begin{align}\begin{aligned}dst.x = max(src0.x, src1.x)\\dst.y = max(src0.y, src1.y)\\dst.z = max(src0.z, src1.z)\\dst.w = max(src0.w, src1.w)\end{aligned}\end{align} \]

IMIN (Minimum of Signed Integers)¶: \[ \begin{align}\begin{aligned}dst.x = min(src0.x, src1.x)\\dst.y = min(src0.y, src1.y)\\dst.z = min(src0.z, src1.z)\\dst.w = min(src0.w, src1.w)\end{aligned}\end{align} \]

UMIN (Minimum of Unsigned Integers)¶: \[ \begin{align}\begin{aligned}dst.x = min(src0.x, src1.x)\\dst.y = min(src0.y, src1.y)\\dst.z = min(src0.z, src1.z)\\dst.w = min(src0.w, src1.w)\end{aligned}\end{align} \]

SHL (Shift Left)¶: The shift count is masked with 0x1f before the shift is applied.

\[ \begin{align}\begin{aligned}dst.x = src0.x \ll (0x1f \& src1.x)\\dst.y = src0.y \ll (0x1f \& src1.y)\\dst.z = src0.z \ll (0x1f \& src1.z)\\dst.w = src0.w \ll (0x1f \& src1.w)\end{aligned}\end{align} \]

ISHR (Arithmetic Shift Right (of Signed Integer))¶: The shift count is masked with 0x1f before the shift is applied.

\[ \begin{align}\begin{aligned}dst.x = src0.x \gg (0x1f \& src1.x)\\dst.y = src0.y \gg (0x1f \& src1.y)\\dst.z = src0.z \gg (0x1f \& src1.z)\\dst.w = src0.w \gg (0x1f \& src1.w)\end{aligned}\end{align} \]

USHR (Logical Shift Right)¶: The shift count is masked with 0x1f before the shift is applied.

\[ \begin{align}\begin{aligned}dst.x = src0.x \gg (unsigned) (0x1f \& src1.x)\\dst.y = src0.y \gg (unsigned) (0x1f \& src1.y)\\dst.z = src0.z \gg (unsigned) (0x1f \& src1.z)\\dst.w = src0.w \gg (unsigned) (0x1f \& src1.w)\end{aligned}\end{align} \]

UCMP (Integer Conditional Move)¶: \[ \begin{align}\begin{aligned}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\end{aligned}\end{align} \]

ISSG (Integer Set Sign)¶: \[ \begin{align}\begin{aligned}dst.x = (src0.x < 0) ? -1 : (src0.x > 0) ? 1 : 0\\dst.y = (src0.y < 0) ? -1 : (src0.y > 0) ? 1 : 0\\dst.z = (src0.z < 0) ? -1 : (src0.z > 0) ? 1 : 0\\dst.w = (src0.w < 0) ? -1 : (src0.w > 0) ? 1 : 0\end{aligned}\end{align} \]

FSLT (Float Set On Less Than (ordered))¶: Same comparison as SLT but returns integer instead of 1.0/0.0 float

\[ \begin{align}\begin{aligned}dst.x = (src0.x < src1.x) ? \sim 0 : 0\\dst.y = (src0.y < src1.y) ? \sim 0 : 0\\dst.z = (src0.z < src1.z) ? \sim 0 : 0\\dst.w = (src0.w < src1.w) ? \sim 0 : 0\end{aligned}\end{align} \]

ISLT (Signed Integer Set On Less Than)¶: \[ \begin{align}\begin{aligned}dst.x = (src0.x < src1.x) ? \sim 0 : 0\\dst.y = (src0.y < src1.y) ? \sim 0 : 0\\dst.z = (src0.z < src1.z) ? \sim 0 : 0\\dst.w = (src0.w < src1.w) ? \sim 0 : 0\end{aligned}\end{align} \]

USLT (Unsigned Integer Set On Less Than)¶: \[ \begin{align}\begin{aligned}dst.x = (src0.x < src1.x) ? \sim 0 : 0\\dst.y = (src0.y < src1.y) ? \sim 0 : 0\\dst.z = (src0.z < src1.z) ? \sim 0 : 0\\dst.w = (src0.w < src1.w) ? \sim 0 : 0\end{aligned}\end{align} \]

FSGE (Float Set On Greater Equal Than (ordered))¶: Same comparison as SGE but returns integer instead of 1.0/0.0 float

\[ \begin{align}\begin{aligned}dst.x = (src0.x >= src1.x) ? \sim 0 : 0\\dst.y = (src0.y >= src1.y) ? \sim 0 : 0\\dst.z = (src0.z >= src1.z) ? \sim 0 : 0\\dst.w = (src0.w >= src1.w) ? \sim 0 : 0\end{aligned}\end{align} \]

ISGE (Signed Integer Set On Greater Equal Than)¶: \[ \begin{align}\begin{aligned}dst.x = (src0.x >= src1.x) ? \sim 0 : 0\\dst.y = (src0.y >= src1.y) ? \sim 0 : 0\\dst.z = (src0.z >= src1.z) ? \sim 0 : 0\\dst.w = (src0.w >= src1.w) ? \sim 0 : 0\end{aligned}\end{align} \]

USGE (Unsigned Integer Set On Greater Equal Than)¶: \[ \begin{align}\begin{aligned}dst.x = (src0.x >= src1.x) ? \sim 0 : 0\\dst.y = (src0.y >= src1.y) ? \sim 0 : 0\\dst.z = (src0.z >= src1.z) ? \sim 0 : 0\\dst.w = (src0.w >= src1.w) ? \sim 0 : 0\end{aligned}\end{align} \]

FSEQ (Float Set On Equal (ordered))¶: Same comparison as SEQ but returns integer instead of 1.0/0.0 float

\[ \begin{align}\begin{aligned}dst.x = (src0.x == src1.x) ? \sim 0 : 0\\dst.y = (src0.y == src1.y) ? \sim 0 : 0\\dst.z = (src0.z == src1.z) ? \sim 0 : 0\\dst.w = (src0.w == src1.w) ? \sim 0 : 0\end{aligned}\end{align} \]

USEQ (Integer Set On Equal)¶: \[ \begin{align}\begin{aligned}dst.x = (src0.x == src1.x) ? \sim 0 : 0\\dst.y = (src0.y == src1.y) ? \sim 0 : 0\\dst.z = (src0.z == src1.z) ? \sim 0 : 0\\dst.w = (src0.w == src1.w) ? \sim 0 : 0\end{aligned}\end{align} \]

FSNE (Float Set On Not Equal (unordered))¶: Same comparison as SNE but returns integer instead of 1.0/0.0 float

\[ \begin{align}\begin{aligned}dst.x = (src0.x != src1.x) ? \sim 0 : 0\\dst.y = (src0.y != src1.y) ? \sim 0 : 0\\dst.z = (src0.z != src1.z) ? \sim 0 : 0\\dst.w = (src0.w != src1.w) ? \sim 0 : 0\end{aligned}\end{align} \]

USNE (Integer Set On Not Equal)¶: \[ \begin{align}\begin{aligned}dst.x = (src0.x != src1.x) ? \sim 0 : 0\\dst.y = (src0.y != src1.y) ? \sim 0 : 0\\dst.z = (src0.z != src1.z) ? \sim 0 : 0\\dst.w = (src0.w != src1.w) ? \sim 0 : 0\end{aligned}\end{align} \]

INEG (Integer Negate)¶: Two’s complement.

\[ \begin{align}\begin{aligned}dst.x = -src.x\\dst.y = -src.y\\dst.z = -src.z\\dst.w = -src.w\end{aligned}\end{align} \]

IABS (Integer Absolute Value)¶: \[ \begin{align}\begin{aligned}dst.x = |src.x|\\dst.y = |src.y|\\dst.z = |src.z|\\dst.w = |src.w|\end{aligned}\end{align} \]

Bitwise ISA¶

These opcodes are used for bit-level manipulation of integers.

IBFE (Signed Bitfield Extract)¶

Like GLSL bitfieldExtract. Extracts a set of bits from the input, and sign-extends them if the high bit of the extracted window is set.

Pseudocode:

def ibfe(value, offset, bits):
   if offset < 0 or bits < 0 or offset + bits > 32:
      return undefined
   if bits == 0: return 0
   # Note: >> sign-extends
   return (value << (32 - offset - bits)) >> (32 - bits)

UBFE (Unsigned Bitfield Extract)¶

Like GLSL bitfieldExtract. Extracts a set of bits from the input, without any sign-extension.

Pseudocode:

def ubfe(value, offset, bits):
   if offset < 0 or bits < 0 or offset + bits > 32:
      return undefined
   if bits == 0: return 0
   # Note: >> does not sign-extend
   return (value << (32 - offset - bits)) >> (32 - bits)

BFI (Bitfield Insert)¶

Like GLSL bitfieldInsert. Replaces a bit region of ‘base’ with the low bits of ‘insert’.

Pseudocode:

def bfi(base, insert, offset, bits):
   if offset < 0 or bits < 0 or offset + bits > 32:
      return undefined
   # << defined such that mask == ~0 when bits == 32, offset == 0
   mask = ((1 << bits) - 1) << offset
   return ((insert << offset) & mask) | (base & ~mask)

BREV (Bitfield Reverse)¶: See SM5 instruction BFREV. Reverses the bits of the argument.

POPC (Population Count)¶: See SM5 instruction COUNTBITS. Counts the number of set bits in the argument.

LSB (Index of lowest set bit)¶: See SM5 instruction FIRSTBIT_LO. Computes the 0-based index of the first set bit of the argument. Returns -1 if none are set.

IMSB (Index of highest non-sign bit)¶: See SM5 instruction FIRSTBIT_SHI. Computes the 0-based index of the highest non-sign bit of the argument (i.e. highest 0 bit for negative numbers, highest 1 bit for positive numbers). Returns -1 if all bits are the same (i.e. for inputs 0 and -1).

UMSB (Index of highest set bit)¶: See SM5 instruction FIRSTBIT_HI. Computes the 0-based index of the highest set bit of the argument. Returns -1 if none are set.

Geometry ISA¶

These opcodes are only supported in geometry shaders; they have no meaning in any other type of shader.

EMIT (Emit)¶: Generate a new vertex for the current primitive into the specified vertex stream using the values in the output registers.

ENDPRIM (End Primitive)¶: Complete the current primitive in the specified vertex stream (consisting of the emitted vertices), and start a new one.

GLSL ISA¶

These opcodes are part of GLSL’s opcode set. Support for these opcodes is determined by a special capability bit, GLSL. Some require glsl version 1.30 (UIF/SWITCH/CASE/DEFAULT/ENDSWITCH).

CAL (Subroutine Call)¶

Pseudocode:

push(pc)
pc = target

RET (Subroutine Call Return)¶

Pseudocode:

pc = pop()

CONT (Continue)¶: Unconditionally moves the point of execution to the instruction after the last BGNLOOP. The instruction must appear within a BGNLOOP/ENDLOOP.

Note

Support for CONT is determined by a special capability bit, TGSI_CONT_SUPPORTED. See Screen for more information.

BGNLOOP (Begin a Loop)¶: Start a loop. Must have a matching ENDLOOP.

BGNSUB (Begin Subroutine)¶: Starts definition of a subroutine. Must have a matching ENDSUB.

ENDLOOP (End a Loop)¶: End a loop started with BGNLOOP.

ENDSUB (End Subroutine)¶: Ends definition of a subroutine.

NOP (No Operation)¶: Do nothing.

BRK (Break)¶: Unconditionally moves the point of execution to the instruction after the next ENDLOOP or ENDSWITCH. The instruction must appear within a BGNLOOP/ENDLOOP or SWITCH/ENDSWITCH.

IF (Float If)¶

Start an IF … ELSE .. ENDIF block. Condition evaluates to true if

src0.x != 0.0

where src0.x is interpreted as a floating point register.

UIF (Bitwise If)¶

Start an UIF … ELSE .. ENDIF block. Condition evaluates to true if

src0.x != 0

where src0.x is interpreted as an integer register.

ELSE (Else)¶: Starts an else block, after an IF or UIF statement.

ENDIF (End If)¶: Ends an IF or UIF block.

SWITCH (Switch)¶

Starts a C-style switch expression. The switch consists of one or multiple CASE statements, and at most one DEFAULT statement. Execution of a statement ends when a BRK is hit, but just like in C falling through to other cases without a break is allowed. Similarly, DEFAULT label is allowed anywhere not just as last statement, and fallthrough is allowed into/from it. CASE src arguments are evaluated at bit level against the SWITCH src argument.

Example:

SWITCH src[0].x
CASE src[0].x
(some instructions here)
(optional BRK here)
DEFAULT
(some instructions here)
(optional BRK here)
CASE src[0].x
(some instructions here)
(optional BRK here)
ENDSWITCH

CASE (Switch case)¶: This represents a switch case label. The src arg must be an integer immediate.

DEFAULT (Switch default)¶: This represents the default case in the switch, which is taken if no other case matches.

ENDSWITCH (End of switch)¶: Ends a switch expression.

Interpolation ISA¶

The interpolation instructions allow an input to be interpolated in a different way than its declaration. This corresponds to the GLSL 4.00 interpolateAt* functions. The first argument of each of these must come from TGSI_FILE_INPUT.

INTERP_CENTROID (Interpolate at the centroid)¶: Interpolates the varying specified by src0 at the centroid

INTERP_SAMPLE (Interpolate at the specified sample)¶: Interpolates the varying specified by src0 at the sample id specified by src1.x (interpreted as an integer)

INTERP_OFFSET (Interpolate at the specified offset)¶: Interpolates the varying specified by src0 at the offset src1.xy from the pixel center (interpreted as floats)

Double ISA¶

The double-precision opcodes reinterpret four-component vectors into two-component vectors with doubled precision in each component.

DABS (Absolute)¶: \[ \begin{align}\begin{aligned}dst.xy = |src0.xy|\\dst.zw = |src0.zw|\end{aligned}\end{align} \]

DADD (Add)¶: \[ \begin{align}\begin{aligned}dst.xy = src0.xy + src1.xy\\dst.zw = src0.zw + src1.zw\end{aligned}\end{align} \]

DSEQ (Set on Equal)¶: \[ \begin{align}\begin{aligned}dst.x = src0.xy == src1.xy ? \sim 0 : 0\\dst.z = src0.zw == src1.zw ? \sim 0 : 0\end{aligned}\end{align} \]

DSNE (Set on Not Equal)¶: \[ \begin{align}\begin{aligned}dst.x = src0.xy != src1.xy ? \sim 0 : 0\\dst.z = src0.zw != src1.zw ? \sim 0 : 0\end{aligned}\end{align} \]

DSLT (Set on Less than)¶: \[ \begin{align}\begin{aligned}dst.x = src0.xy < src1.xy ? \sim 0 : 0\\dst.z = src0.zw < src1.zw ? \sim 0 : 0\end{aligned}\end{align} \]

DSGE (Set on Greater equal)¶: \[ \begin{align}\begin{aligned}dst.x = src0.xy >= src1.xy ? \sim 0 : 0\\dst.z = src0.zw >= src1.zw ? \sim 0 : 0\end{aligned}\end{align} \]

DFRAC (Fraction)¶: \[ \begin{align}\begin{aligned}dst.xy = src.xy - \lfloor src.xy\rfloor\\dst.zw = src.zw - \lfloor src.zw\rfloor\end{aligned}\end{align} \]

DTRUNC (Truncate)¶: \[ \begin{align}\begin{aligned}dst.xy = trunc(src.xy)\\dst.zw = trunc(src.zw)\end{aligned}\end{align} \]

DCEIL (Ceiling)¶: \[ \begin{align}\begin{aligned}dst.xy = \lceil src.xy\rceil\\dst.zw = \lceil src.zw\rceil\end{aligned}\end{align} \]

DFLR (Floor)¶: \[ \begin{align}\begin{aligned}dst.xy = \lfloor src.xy\rfloor\\dst.zw = \lfloor src.zw\rfloor\end{aligned}\end{align} \]

DROUND (Fraction)¶: \[ \begin{align}\begin{aligned}dst.xy = round(src.xy)\\dst.zw = round(src.zw)\end{aligned}\end{align} \]

DSSG (Set Sign)¶: \[ \begin{align}\begin{aligned}dst.xy = (src.xy > 0) ? 1.0 : (src.xy < 0) ? -1.0 : 0.0\\dst.zw = (src.zw > 0) ? 1.0 : (src.zw < 0) ? -1.0 : 0.0\end{aligned}\end{align} \]

DLDEXP (Multiply Number by Integral Power of 2)¶: This opcode is the inverse of frexp. The second source is an integer.

\[ \begin{align}\begin{aligned}dst.xy = src0.xy \times 2^{src1.x}\\dst.zw = src0.zw \times 2^{src1.z}\end{aligned}\end{align} \]

DMIN (Minimum)¶: \[ \begin{align}\begin{aligned}dst.xy = min(src0.xy, src1.xy)\\dst.zw = min(src0.zw, src1.zw)\end{aligned}\end{align} \]

DMAX (Maximum)¶: \[ \begin{align}\begin{aligned}dst.xy = max(src0.xy, src1.xy)\\dst.zw = max(src0.zw, src1.zw)\end{aligned}\end{align} \]

DMUL (Multiply)¶: \[ \begin{align}\begin{aligned}dst.xy = src0.xy \times src1.xy\\dst.zw = src0.zw \times src1.zw\end{aligned}\end{align} \]

DMAD (Multiply And Add)¶: \[ \begin{align}\begin{aligned}dst.xy = src0.xy \times src1.xy + src2.xy\\dst.zw = src0.zw \times src1.zw + src2.zw\end{aligned}\end{align} \]

DFMA (Fused Multiply-Add)¶: Perform a * b + c with no intermediate rounding step.

\[ \begin{align}\begin{aligned}dst.xy = src0.xy \times src1.xy + src2.xy\\dst.zw = src0.zw \times src1.zw + src2.zw\end{aligned}\end{align} \]

DDIV (Divide)¶: \[ \begin{align}\begin{aligned}dst.xy = \frac{src0.xy}{src1.xy}\\dst.zw = \frac{src0.zw}{src1.zw}\end{aligned}\end{align} \]

DRCP (Reciprocal)¶: \[ \begin{align}\begin{aligned}dst.xy = \frac{1}{src.xy}\\dst.zw = \frac{1}{src.zw}\end{aligned}\end{align} \]

DSQRT (Square Root)¶: \[ \begin{align}\begin{aligned}dst.xy = \sqrt{src.xy}\\dst.zw = \sqrt{src.zw}\end{aligned}\end{align} \]

DRSQ (Reciprocal Square Root)¶: \[ \begin{align}\begin{aligned}dst.xy = \frac{1}{\sqrt{src.xy}}\\dst.zw = \frac{1}{\sqrt{src.zw}}\end{aligned}\end{align} \]

F2D (Float to Double)¶: \[ \begin{align}\begin{aligned}dst.xy = double(src0.x)\\dst.zw = double(src0.y)\end{aligned}\end{align} \]

D2F (Double to Float)¶: \[ \begin{align}\begin{aligned}dst.x = float(src0.xy)\\dst.y = float(src0.zw)\end{aligned}\end{align} \]

I2D (Int to Double)¶: \[ \begin{align}\begin{aligned}dst.xy = double(src0.x)\\dst.zw = double(src0.y)\end{aligned}\end{align} \]

D2I (Double to Int)¶: \[ \begin{align}\begin{aligned}dst.x = int(src0.xy)\\dst.y = int(src0.zw)\end{aligned}\end{align} \]

U2D (Unsigned Int to Double)¶: \[ \begin{align}\begin{aligned}dst.xy = double(src0.x)\\dst.zw = double(src0.y)\end{aligned}\end{align} \]

D2U (Double to Unsigned Int)¶: \[ \begin{align}\begin{aligned}dst.x = unsigned(src0.xy)\\dst.y = unsigned(src0.zw)\end{aligned}\end{align} \]

64-bit Integer ISA¶

The 64-bit integer opcodes reinterpret four-component vectors into two-component vectors with 64-bits in each component.

I64ABS (64-bit Integer Absolute Value)¶: \[ \begin{align}\begin{aligned}dst.xy = |src0.xy|\\dst.zw = |src0.zw|\end{aligned}\end{align} \]

I64NEG (64-bit Integer Negate)¶: Two’s complement.

\[ \begin{align}\begin{aligned}dst.xy = -src.xy\\dst.zw = -src.zw\end{aligned}\end{align} \]

I64SSG (64-bit Integer Set Sign)¶: \[ \begin{align}\begin{aligned}dst.xy = (src0.xy < 0) ? -1 : (src0.xy > 0) ? 1 : 0\\dst.zw = (src0.zw < 0) ? -1 : (src0.zw > 0) ? 1 : 0\end{aligned}\end{align} \]

U64ADD (64-bit Integer Add)¶: \[ \begin{align}\begin{aligned}dst.xy = src0.xy + src1.xy\\dst.zw = src0.zw + src1.zw\end{aligned}\end{align} \]

U64MUL (64-bit Integer Multiply)¶: \[ \begin{align}\begin{aligned}dst.xy = src0.xy * src1.xy\\dst.zw = src0.zw * src1.zw\end{aligned}\end{align} \]

U64SEQ (64-bit Integer Set on Equal)¶: \[ \begin{align}\begin{aligned}dst.x = src0.xy == src1.xy ? \sim 0 : 0\\dst.z = src0.zw == src1.zw ? \sim 0 : 0\end{aligned}\end{align} \]

U64SNE (64-bit Integer Set on Not Equal)¶: \[ \begin{align}\begin{aligned}dst.x = src0.xy != src1.xy ? \sim 0 : 0\\dst.z = src0.zw != src1.zw ? \sim 0 : 0\end{aligned}\end{align} \]

U64SLT (64-bit Unsigned Integer Set on Less Than)¶: \[ \begin{align}\begin{aligned}dst.x = src0.xy < src1.xy ? \sim 0 : 0\\dst.z = src0.zw < src1.zw ? \sim 0 : 0\end{aligned}\end{align} \]

U64SGE (64-bit Unsigned Integer Set on Greater Equal)¶: \[ \begin{align}\begin{aligned}dst.x = src0.xy >= src1.xy ? \sim 0 : 0\\dst.z = src0.zw >= src1.zw ? \sim 0 : 0\end{aligned}\end{align} \]

I64SLT (64-bit Signed Integer Set on Less Than)¶: \[ \begin{align}\begin{aligned}dst.x = src0.xy < src1.xy ? \sim 0 : 0\\dst.z = src0.zw < src1.zw ? \sim 0 : 0\end{aligned}\end{align} \]

I64SGE (64-bit Signed Integer Set on Greater Equal)¶: \[ \begin{align}\begin{aligned}dst.x = src0.xy >= src1.xy ? \sim 0 : 0\\dst.z = src0.zw >= src1.zw ? \sim 0 : 0\end{aligned}\end{align} \]

I64MIN (Minimum of 64-bit Signed Integers)¶: \[ \begin{align}\begin{aligned}dst.xy = min(src0.xy, src1.xy)\\dst.zw = min(src0.zw, src1.zw)\end{aligned}\end{align} \]

U64MIN (Minimum of 64-bit Unsigned Integers)¶: \[ \begin{align}\begin{aligned}dst.xy = min(src0.xy, src1.xy)\\dst.zw = min(src0.zw, src1.zw)\end{aligned}\end{align} \]

I64MAX (Maximum of 64-bit Signed Integers)¶: \[ \begin{align}\begin{aligned}dst.xy = max(src0.xy, src1.xy)\\dst.zw = max(src0.zw, src1.zw)\end{aligned}\end{align} \]

U64MAX (Maximum of 64-bit Unsigned Integers)¶: \[ \begin{align}\begin{aligned}dst.xy = max(src0.xy, src1.xy)\\dst.zw = max(src0.zw, src1.zw)\end{aligned}\end{align} \]

U64SHL (Shift Left 64-bit Unsigned Integer)¶: The shift count is masked with 0x3f before the shift is applied.

\[ \begin{align}\begin{aligned}dst.xy = src0.xy \ll (0x3f \& src1.x)\\dst.zw = src0.zw \ll (0x3f \& src1.y)\end{aligned}\end{align} \]

I64SHR (Arithmetic Shift Right (of 64-bit Signed Integer))¶: The shift count is masked with 0x3f before the shift is applied.

\[ \begin{align}\begin{aligned}dst.xy = src0.xy \gg (0x3f \& src1.x)\\dst.zw = src0.zw \gg (0x3f \& src1.y)\end{aligned}\end{align} \]

U64SHR (Logical Shift Right (of 64-bit Unsigned Integer))¶: The shift count is masked with 0x3f before the shift is applied.

\[ \begin{align}\begin{aligned}dst.xy = src0.xy \gg (unsigned) (0x3f \& src1.x)\\dst.zw = src0.zw \gg (unsigned) (0x3f \& src1.y)\end{aligned}\end{align} \]

I64DIV (64-bit Signed Integer Division)¶: \[ \begin{align}\begin{aligned}dst.xy = \frac{src0.xy}{src1.xy}\\dst.zw = \frac{src0.zw}{src1.zw}\end{aligned}\end{align} \]

U64DIV (64-bit Unsigned Integer Division)¶: \[ \begin{align}\begin{aligned}dst.xy = \frac{src0.xy}{src1.xy}\\dst.zw = \frac{src0.zw}{src1.zw}\end{aligned}\end{align} \]

U64MOD (64-bit Unsigned Integer Remainder)¶: \[ \begin{align}\begin{aligned}dst.xy = src0.xy \bmod src1.xy\\dst.zw = src0.zw \bmod src1.zw\end{aligned}\end{align} \]

I64MOD (64-bit Signed Integer Remainder)¶: \[ \begin{align}\begin{aligned}dst.xy = src0.xy \bmod src1.xy\\dst.zw = src0.zw \bmod src1.zw\end{aligned}\end{align} \]

F2U64 (Float to 64-bit Unsigned Int)¶: \[ \begin{align}\begin{aligned}dst.xy = (uint64_t) src0.x\\dst.zw = (uint64_t) src0.y\end{aligned}\end{align} \]

F2I64 (Float to 64-bit Int)¶: \[ \begin{align}\begin{aligned}dst.xy = (int64_t) src0.x\\dst.zw = (int64_t) src0.y\end{aligned}\end{align} \]

U2I64 (Unsigned Integer to 64-bit Integer)¶: This is a zero extension.

\[ \begin{align}\begin{aligned}dst.xy = (int64_t) src0.x\\dst.zw = (int64_t) src0.y\end{aligned}\end{align} \]

I2I64 (Signed Integer to 64-bit Integer)¶: This is a sign extension.

\[ \begin{align}\begin{aligned}dst.xy = (int64_t) src0.x\\dst.zw = (int64_t) src0.y\end{aligned}\end{align} \]

D2U64 (Double to 64-bit Unsigned Int)¶: \[ \begin{align}\begin{aligned}dst.xy = (uint64_t) src0.xy\\dst.zw = (uint64_t) src0.zw\end{aligned}\end{align} \]

D2I64 (Double to 64-bit Int)¶: \[ \begin{align}\begin{aligned}dst.xy = (int64_t) src0.xy\\dst.zw = (int64_t) src0.zw\end{aligned}\end{align} \]

U642F (64-bit unsigned integer to float)¶: \[ \begin{align}\begin{aligned}dst.x = (float) src0.xy\\dst.y = (float) src0.zw\end{aligned}\end{align} \]

I642F (64-bit Int to Float)¶: \[ \begin{align}\begin{aligned}dst.x = (float) src0.xy\\dst.y = (float) src0.zw\end{aligned}\end{align} \]

U642D (64-bit unsigned integer to double)¶: \[ \begin{align}\begin{aligned}dst.xy = (double) src0.xy\\dst.zw = (double) src0.zw\end{aligned}\end{align} \]

I642D (64-bit Int to double)¶: \[ \begin{align}\begin{aligned}dst.xy = (double) src0.xy\\dst.zw = (double) src0.zw\end{aligned}\end{align} \]

Resource Sampling Opcodes¶

Those opcodes follow very closely semantics of the respective Direct3D instructions. If in doubt double check Direct3D documentation. Note that the swizzle on SVIEW (src1) determines texel swizzling after lookup.

SAMPLE

Using provided address, sample data from the specified texture using the filtering mode identified by the given sampler. The source data may come from any resource type other than buffers.

Syntax: SAMPLE dst, address, sampler_view, sampler

Example: SAMPLE TEMP[0], TEMP[1], SVIEW[0], SAMP[0]

SAMPLE_I

Simplified alternative to the SAMPLE instruction. Using the provided integer address, SAMPLE_I fetches data from the specified sampler view without any filtering. The source data may come from any resource type other than CUBE.

Syntax: SAMPLE_I dst, address, sampler_view

Example: SAMPLE_I TEMP[0], TEMP[1], SVIEW[0]

The ‘address’ is specified as unsigned integers. If the ‘address’ is out of range [0…(# texels - 1)] the result of the fetch is always 0 in all components. As such the instruction doesn’t honor address wrap modes, in cases where that behavior is desirable ‘SAMPLE’ instruction should be used. address.w always provides an unsigned integer mipmap level. If the value is out of the range then the instruction always returns 0 in all components. address.yz are ignored for buffers and 1d textures. address.z is ignored for 1d texture arrays and 2d textures.

For 1D texture arrays address.y provides the array index (also as unsigned integer). If the value is out of the range of available array indices [0… (array size - 1)] then the opcode always returns 0 in all components. For 2D texture arrays address.z provides the array index, otherwise it exhibits the same behavior as in the case for 1D texture arrays. The exact semantics of the source address are presented in the table below:

resource type	X	Y	Z	W
`PIPE_BUFFER`	x			ignored
`PIPE_TEXTURE_1D`	x			mpl
`PIPE_TEXTURE_2D`	x	y		mpl
`PIPE_TEXTURE_3D`	x	y	z	mpl
`PIPE_TEXTURE_RECT`	x	y		mpl
`PIPE_TEXTURE_CUBE`	not allowed as source
`PIPE_TEXTURE_1D_ARRAY`	x	idx		mpl
`PIPE_TEXTURE_2D_ARRAY`	x	y	idx	mpl

Where ‘mpl’ is a mipmap level and ‘idx’ is the array index.

SAMPLE_I_MS

Just like SAMPLE_I but allows fetch data from multi-sampled surfaces.

Syntax: SAMPLE_I_MS dst, address, sampler_view, sample

SAMPLE_B

Just like the SAMPLE instruction with the exception that an additional bias is applied to the level of detail computed as part of the instruction execution.

Syntax: SAMPLE_B dst, address, sampler_view, sampler, lod_bias

Example: SAMPLE_B TEMP[0], TEMP[1], SVIEW[0], SAMP[0], TEMP[2].x

SAMPLE_C

Similar to the SAMPLE instruction but it performs a comparison filter. The operands to SAMPLE_C are identical to SAMPLE, except that there is an additional float32 operand, reference value, which must be a register with single-component, or a scalar literal. SAMPLE_C makes the hardware use the current samplers compare_func (in pipe_sampler_state) to compare reference value against the red component value for the source resource at each texel that the currently configured texture filter covers based on the provided coordinates.

Syntax: SAMPLE_C dst, address, sampler_view.r, sampler, ref_value

Example: SAMPLE_C TEMP[0], TEMP[1], SVIEW[0].r, SAMP[0], TEMP[2].x

SAMPLE_C_LZ

Same as SAMPLE_C, but LOD is 0 and derivatives are ignored. The LZ stands for level-zero.

Syntax: SAMPLE_C_LZ dst, address, sampler_view.r, sampler, ref_value

Example: SAMPLE_C_LZ TEMP[0], TEMP[1], SVIEW[0].r, SAMP[0], TEMP[2].x

SAMPLE_D

SAMPLE_D is identical to the SAMPLE opcode except that the derivatives for the source address in the x direction and the y direction are provided by extra parameters.

Syntax: SAMPLE_D dst, address, sampler_view, sampler, der_x, der_y

Example: SAMPLE_D TEMP[0], TEMP[1], SVIEW[0], SAMP[0], TEMP[2], TEMP[3]

SAMPLE_L

SAMPLE_L is identical to the SAMPLE opcode except that the LOD is provided directly as a scalar value, representing no anisotropy.

Syntax: SAMPLE_L dst, address, sampler_view, sampler, explicit_lod

Example: SAMPLE_L TEMP[0], TEMP[1], SVIEW[0], SAMP[0], TEMP[2].x

GATHER4: Gathers the four texels to be used in a bi-linear filtering operation and packs them into a single register. Only works with 2D, 2D array, cubemaps, and cubemaps arrays. For 2D textures, only the addressing modes of the sampler and the top level of any mip pyramid are used. Set W to zero. It behaves like the SAMPLE instruction, but a filtered sample is not generated. The four samples that contribute to filtering are placed into XYZW in counter-clockwise order, starting with the (u,v) texture coordinate delta at the following locations (-, +), (+, +), (+, -), (-, -), where the magnitude of the deltas are half a texel.

SVIEWINFO

Query the dimensions of a given sampler view. dst receives width, height, depth or array size and number of mipmap levels as int4. The dst can have a writemask which will specify what info is the caller interested in.

Syntax: SVIEWINFO dst, src_mip_level, sampler_view

Example: SVIEWINFO TEMP[0], TEMP[1].x, SVIEW[0]

src_mip_level is an unsigned integer scalar. If it’s out of range then returns 0 for width, height and depth/array size but the total number of mipmap is still returned correctly for the given sampler view. The returned width, height and depth values are for the mipmap level selected by the src_mip_level and are in the number of texels. For 1d texture array width is in dst.x, array size is in dst.y and dst.z is 0. The number of mipmaps is still in dst.w. In contrast to d3d10 resinfo, there’s no way in the TGSI instruction encoding to specify the return type (float/rcpfloat/uint), hence always using uint. Also, unlike the SAMPLE instructions, the swizzle on src1 resinfo allowing swizzling dst values is ignored (due to the interaction with rcpfloat modifier which requires some swizzle handling in the state tracker anyway).

SAMPLE_POS

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 gallium frontend emits it). This information is subject to change.

SAMPLE_INFO

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 gallium frontend emits it). This information is subject to change.

LOD (level of detail)¶

Same syntax as the SAMPLE opcode but instead of performing an actual texture lookup/filter, return the computed LOD information that the texture pipe would use to access the texture. The Y component contains the computed LOD lambda_prime. The X component contains the LOD that will be accessed, based on min/max lod’s and mipmap filters. The Z and W components are set to 0.

Syntax: LOD dst, address, sampler_view, sampler

Resource Access Opcodes¶

For these opcodes, the resource can be a BUFFER, IMAGE, or MEMORY.

LOAD (Fetch data from a shader buffer or image)¶

Syntax: LOAD dst, resource, address

Example: LOAD TEMP[0], BUFFER[0], TEMP[1]

Using the provided integer address, LOAD fetches data from the specified buffer or texture without any filtering.

The ‘address’ is specified as a vector of unsigned integers. If the ‘address’ is out of range the result is unspecified.

Only the first mipmap level of a resource can be read from using this instruction.

For 1D or 2D texture arrays, the array index is provided as an unsigned integer in address.y or address.z, respectively. address.yz are ignored for buffers and 1D textures. address.z is ignored for 1D texture arrays and 2D textures. address.w is always ignored.

A swizzle suffix may be added to the resource argument this will cause the resource data to be swizzled accordingly.

STORE (Write data to a shader resource)¶

Syntax: STORE resource, address, src

Example: STORE BUFFER[0], TEMP[0], TEMP[1]

Using the provided integer address, STORE writes data to the specified buffer or texture.

The ‘address’ is specified as a vector of unsigned integers. If the ‘address’ is out of range the result is unspecified.

Only the first mipmap level of a resource can be written to using this instruction.

RESQ (Query information about a resource)¶

Syntax: RESQ dst, resource

Example: RESQ TEMP[0], BUFFER[0]

Returns information about the buffer or image resource. For buffer resources, the size (in bytes) is returned in the x component. For image resources, .xyz will contain the width/height/layers of the image, while .w will contain the number of samples for multi-sampled images.

FBFETCH (Load data from framebuffer)¶

Syntax: FBFETCH dst, output

Example: FBFETCH TEMP[0], OUT[0]

This is only valid on COLOR semantic outputs. Returns the color of the current position in the framebuffer from before this fragment shader invocation. May return the same value from multiple calls for a particular output within a single invocation. Note that result may be undefined if a fragment is drawn multiple times without a blend barrier in between.

Bindless Opcodes¶

These opcodes are for working with bindless sampler or image handles and require PIPE_CAP_BINDLESS_TEXTURE.

IMG2HND (Get a bindless handle for a image)¶

Syntax: IMG2HND dst, image

Example: IMG2HND TEMP[0], IMAGE[0]

Sets ‘dst’ to a bindless handle for ‘image’.

SAMP2HND (Get a bindless handle for a sampler)¶

Syntax: SAMP2HND dst, sampler

Example: SAMP2HND TEMP[0], SAMP[0]

Sets ‘dst’ to a bindless handle for ‘sampler’.

Inter-thread synchronization opcodes¶

These opcodes are intended for communication between threads running within the same compute grid. For now they’re only valid in compute programs.

BARRIER (Thread group barrier)¶

BARRIER

This opcode suspends the execution of the current thread until all the remaining threads in the working group reach the same point of the program. Results are unspecified if any of the remaining threads terminates or never reaches an executed BARRIER instruction.

MEMBAR (Memory barrier)¶

MEMBAR type

This opcode waits for the completion of all memory accesses based on the type passed in. The type is an immediate bitfield with the following meaning:

Bit 0: Shader storage buffers Bit 1: Atomic buffers Bit 2: Images Bit 3: Shared memory Bit 4: Thread group

These may be passed in in any combination. An implementation is free to not distinguish between these as it sees fit. However these map to all the possibilities made available by GLSL.

Atomic opcodes¶

These opcodes provide atomic variants of some common arithmetic and 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, IMAGE, HWATOMIC, or MEMORY. In the case of an image, the offset works the same as for LOAD and STORE, specified above. For atomic counters, the offset is an immediate index to the base HW atomic counter for this operation. These atomic operations may only be used with 32-bit integer image formats.

ATOMUADD (Atomic integer addition)¶

Syntax: ATOMUADD dst, resource, offset, src

Example: ATOMUADD TEMP[0], BUFFER[0], TEMP[1], TEMP[2]