4 TGSI, Tungsten Graphics Shader Infrastructure, is an intermediate language
5 for describing shaders. Since Gallium is inherently shaderful, shaders are
6 an important part of the API. TGSI is the only intermediate representation
12 All TGSI instructions, known as *opcodes*, operate on arbitrary-precision
13 floating-point four-component vectors. An opcode may have up to one
14 destination register, known as *dst*, and between zero and three source
15 registers, called *src0* through *src2*, or simply *src* if there is only
18 Some instructions, like :opcode:`I2F`, permit re-interpretation of vector
19 components as integers. Other instructions permit using registers as
20 two-component vectors with double precision; see :ref:`Double Opcodes`.
22 When an instruction has a scalar result, the result is usually copied into
23 each of the components of *dst*. When this happens, the result is said to be
24 *replicated* to *dst*. :opcode:`RCP` is one such instruction.
29 TGSI supports modifiers on inputs (as well as saturate modifier on instructions).
31 For inputs which have a floating point type, both absolute value and negation
32 modifiers are supported (with absolute value being applied first).
33 TGSI_OPCODE_MOV is considered to have float input type for applying modifiers.
35 For inputs which have signed or unsigned type only the negate modifier is
42 ^^^^^^^^^^^^^^^^^^^^^^^^^
44 These opcodes are guaranteed to be available regardless of the driver being
47 .. opcode:: ARL - Address Register Load
51 dst.x = \lfloor src.x\rfloor
53 dst.y = \lfloor src.y\rfloor
55 dst.z = \lfloor src.z\rfloor
57 dst.w = \lfloor src.w\rfloor
60 .. opcode:: MOV - Move
73 .. opcode:: LIT - Light Coefficients
81 dst.z = (src.x > 0) ? max(src.y, 0)^{clamp(src.w, -128, 128))} : 0
86 .. opcode:: RCP - Reciprocal
88 This instruction replicates its result.
95 .. opcode:: RSQ - Reciprocal Square Root
97 This instruction replicates its result.
101 dst = \frac{1}{\sqrt{|src.x|}}
104 .. opcode:: SQRT - Square Root
106 This instruction replicates its result.
113 .. opcode:: EXP - Approximate Exponential Base 2
117 dst.x = 2^{\lfloor src.x\rfloor}
119 dst.y = src.x - \lfloor src.x\rfloor
126 .. opcode:: LOG - Approximate Logarithm Base 2
130 dst.x = \lfloor\log_2{|src.x|}\rfloor
132 dst.y = \frac{|src.x|}{2^{\lfloor\log_2{|src.x|}\rfloor}}
134 dst.z = \log_2{|src.x|}
139 .. opcode:: MUL - Multiply
143 dst.x = src0.x \times src1.x
145 dst.y = src0.y \times src1.y
147 dst.z = src0.z \times src1.z
149 dst.w = src0.w \times src1.w
152 .. opcode:: ADD - Add
156 dst.x = src0.x + src1.x
158 dst.y = src0.y + src1.y
160 dst.z = src0.z + src1.z
162 dst.w = src0.w + src1.w
165 .. opcode:: DP3 - 3-component Dot Product
167 This instruction replicates its result.
171 dst = src0.x \times src1.x + src0.y \times src1.y + src0.z \times src1.z
174 .. opcode:: DP4 - 4-component Dot Product
176 This instruction replicates its result.
180 dst = src0.x \times src1.x + src0.y \times src1.y + src0.z \times src1.z + src0.w \times src1.w
183 .. opcode:: DST - Distance Vector
189 dst.y = src0.y \times src1.y
196 .. opcode:: MIN - Minimum
200 dst.x = min(src0.x, src1.x)
202 dst.y = min(src0.y, src1.y)
204 dst.z = min(src0.z, src1.z)
206 dst.w = min(src0.w, src1.w)
209 .. opcode:: MAX - Maximum
213 dst.x = max(src0.x, src1.x)
215 dst.y = max(src0.y, src1.y)
217 dst.z = max(src0.z, src1.z)
219 dst.w = max(src0.w, src1.w)
222 .. opcode:: SLT - Set On Less Than
226 dst.x = (src0.x < src1.x) ? 1 : 0
228 dst.y = (src0.y < src1.y) ? 1 : 0
230 dst.z = (src0.z < src1.z) ? 1 : 0
232 dst.w = (src0.w < src1.w) ? 1 : 0
235 .. opcode:: SGE - Set On Greater Equal Than
239 dst.x = (src0.x >= src1.x) ? 1 : 0
241 dst.y = (src0.y >= src1.y) ? 1 : 0
243 dst.z = (src0.z >= src1.z) ? 1 : 0
245 dst.w = (src0.w >= src1.w) ? 1 : 0
248 .. opcode:: MAD - Multiply And Add
252 dst.x = src0.x \times src1.x + src2.x
254 dst.y = src0.y \times src1.y + src2.y
256 dst.z = src0.z \times src1.z + src2.z
258 dst.w = src0.w \times src1.w + src2.w
261 .. opcode:: SUB - Subtract
265 dst.x = src0.x - src1.x
267 dst.y = src0.y - src1.y
269 dst.z = src0.z - src1.z
271 dst.w = src0.w - src1.w
274 .. opcode:: LRP - Linear Interpolate
278 dst.x = src0.x \times src1.x + (1 - src0.x) \times src2.x
280 dst.y = src0.y \times src1.y + (1 - src0.y) \times src2.y
282 dst.z = src0.z \times src1.z + (1 - src0.z) \times src2.z
284 dst.w = src0.w \times src1.w + (1 - src0.w) \times src2.w
287 .. opcode:: CND - Condition
291 dst.x = (src2.x > 0.5) ? src0.x : src1.x
293 dst.y = (src2.y > 0.5) ? src0.y : src1.y
295 dst.z = (src2.z > 0.5) ? src0.z : src1.z
297 dst.w = (src2.w > 0.5) ? src0.w : src1.w
300 .. opcode:: DP2A - 2-component Dot Product And Add
304 dst.x = src0.x \times src1.x + src0.y \times src1.y + src2.x
306 dst.y = src0.x \times src1.x + src0.y \times src1.y + src2.x
308 dst.z = src0.x \times src1.x + src0.y \times src1.y + src2.x
310 dst.w = src0.x \times src1.x + src0.y \times src1.y + src2.x
313 .. opcode:: FRC - Fraction
317 dst.x = src.x - \lfloor src.x\rfloor
319 dst.y = src.y - \lfloor src.y\rfloor
321 dst.z = src.z - \lfloor src.z\rfloor
323 dst.w = src.w - \lfloor src.w\rfloor
326 .. opcode:: CLAMP - Clamp
330 dst.x = clamp(src0.x, src1.x, src2.x)
332 dst.y = clamp(src0.y, src1.y, src2.y)
334 dst.z = clamp(src0.z, src1.z, src2.z)
336 dst.w = clamp(src0.w, src1.w, src2.w)
339 .. opcode:: FLR - Floor
341 This is identical to :opcode:`ARL`.
345 dst.x = \lfloor src.x\rfloor
347 dst.y = \lfloor src.y\rfloor
349 dst.z = \lfloor src.z\rfloor
351 dst.w = \lfloor src.w\rfloor
354 .. opcode:: ROUND - Round
367 .. opcode:: EX2 - Exponential Base 2
369 This instruction replicates its result.
376 .. opcode:: LG2 - Logarithm Base 2
378 This instruction replicates its result.
385 .. opcode:: POW - Power
387 This instruction replicates its result.
391 dst = src0.x^{src1.x}
393 .. opcode:: XPD - Cross Product
397 dst.x = src0.y \times src1.z - src1.y \times src0.z
399 dst.y = src0.z \times src1.x - src1.z \times src0.x
401 dst.z = src0.x \times src1.y - src1.x \times src0.y
406 .. opcode:: ABS - Absolute
419 .. opcode:: RCC - Reciprocal Clamped
421 This instruction replicates its result.
423 XXX cleanup on aisle three
427 dst = (1 / src.x) > 0 ? clamp(1 / src.x, 5.42101e-020, 1.884467e+019) : clamp(1 / src.x, -1.884467e+019, -5.42101e-020)
430 .. opcode:: DPH - Homogeneous Dot Product
432 This instruction replicates its result.
436 dst = src0.x \times src1.x + src0.y \times src1.y + src0.z \times src1.z + src1.w
439 .. opcode:: COS - Cosine
441 This instruction replicates its result.
448 .. opcode:: DDX - Derivative Relative To X
452 dst.x = partialx(src.x)
454 dst.y = partialx(src.y)
456 dst.z = partialx(src.z)
458 dst.w = partialx(src.w)
461 .. opcode:: DDY - Derivative Relative To Y
465 dst.x = partialy(src.x)
467 dst.y = partialy(src.y)
469 dst.z = partialy(src.z)
471 dst.w = partialy(src.w)
474 .. opcode:: KILP - Predicated Discard
479 .. opcode:: PK2H - Pack Two 16-bit Floats
484 .. opcode:: PK2US - Pack Two Unsigned 16-bit Scalars
489 .. opcode:: PK4B - Pack Four Signed 8-bit Scalars
494 .. opcode:: PK4UB - Pack Four Unsigned 8-bit Scalars
499 .. opcode:: RFL - Reflection Vector
503 dst.x = 2 \times (src0.x \times src1.x + src0.y \times src1.y + src0.z \times src1.z) / (src0.x \times src0.x + src0.y \times src0.y + src0.z \times src0.z) \times src0.x - src1.x
505 dst.y = 2 \times (src0.x \times src1.x + src0.y \times src1.y + src0.z \times src1.z) / (src0.x \times src0.x + src0.y \times src0.y + src0.z \times src0.z) \times src0.y - src1.y
507 dst.z = 2 \times (src0.x \times src1.x + src0.y \times src1.y + src0.z \times src1.z) / (src0.x \times src0.x + src0.y \times src0.y + src0.z \times src0.z) \times src0.z - src1.z
513 Considered for removal.
516 .. opcode:: SEQ - Set On Equal
520 dst.x = (src0.x == src1.x) ? 1 : 0
522 dst.y = (src0.y == src1.y) ? 1 : 0
524 dst.z = (src0.z == src1.z) ? 1 : 0
526 dst.w = (src0.w == src1.w) ? 1 : 0
529 .. opcode:: SFL - Set On False
531 This instruction replicates its result.
539 Considered for removal.
542 .. opcode:: SGT - Set On Greater Than
546 dst.x = (src0.x > src1.x) ? 1 : 0
548 dst.y = (src0.y > src1.y) ? 1 : 0
550 dst.z = (src0.z > src1.z) ? 1 : 0
552 dst.w = (src0.w > src1.w) ? 1 : 0
555 .. opcode:: SIN - Sine
557 This instruction replicates its result.
564 .. opcode:: SLE - Set On Less Equal Than
568 dst.x = (src0.x <= src1.x) ? 1 : 0
570 dst.y = (src0.y <= src1.y) ? 1 : 0
572 dst.z = (src0.z <= src1.z) ? 1 : 0
574 dst.w = (src0.w <= src1.w) ? 1 : 0
577 .. opcode:: SNE - Set On Not Equal
581 dst.x = (src0.x != src1.x) ? 1 : 0
583 dst.y = (src0.y != src1.y) ? 1 : 0
585 dst.z = (src0.z != src1.z) ? 1 : 0
587 dst.w = (src0.w != src1.w) ? 1 : 0
590 .. opcode:: STR - Set On True
592 This instruction replicates its result.
599 .. opcode:: TEX - Texture Lookup
607 dst = texture_sample(unit, coord, bias)
609 for array textures src0.y contains the slice for 1D,
610 and src0.z contain the slice for 2D.
611 for shadow textures with no arrays, src0.z contains
613 for shadow textures with arrays, src0.z contains
614 the reference value for 1D arrays, and src0.w contains
615 the reference value for 2D arrays.
616 There is no way to pass a bias in the .w value for
617 shadow arrays, and GLSL doesn't allow this.
618 GLSL does allow cube shadows maps to take a bias value,
619 and we have to determine how this will look in TGSI.
621 .. opcode:: TXD - Texture Lookup with Derivatives
633 dst = texture_sample_deriv(unit, coord, bias, ddx, ddy)
636 .. opcode:: TXP - Projective Texture Lookup
640 coord.x = src0.x / src.w
642 coord.y = src0.y / src.w
644 coord.z = src0.z / src.w
650 dst = texture_sample(unit, coord, bias)
653 .. opcode:: UP2H - Unpack Two 16-Bit Floats
659 Considered for removal.
661 .. opcode:: UP2US - Unpack Two Unsigned 16-Bit Scalars
667 Considered for removal.
669 .. opcode:: UP4B - Unpack Four Signed 8-Bit Values
675 Considered for removal.
677 .. opcode:: UP4UB - Unpack Four Unsigned 8-Bit Scalars
683 Considered for removal.
685 .. opcode:: X2D - 2D Coordinate Transformation
689 dst.x = src0.x + src1.x \times src2.x + src1.y \times src2.y
691 dst.y = src0.y + src1.x \times src2.z + src1.y \times src2.w
693 dst.z = src0.x + src1.x \times src2.x + src1.y \times src2.y
695 dst.w = src0.y + src1.x \times src2.z + src1.y \times src2.w
699 Considered for removal.
702 .. opcode:: ARA - Address Register Add
708 Considered for removal.
710 .. opcode:: ARR - Address Register Load With Round
723 .. opcode:: BRA - Branch
729 Considered for removal.
731 .. opcode:: CAL - Subroutine Call
737 .. opcode:: RET - Subroutine Call Return
742 .. opcode:: SSG - Set Sign
746 dst.x = (src.x > 0) ? 1 : (src.x < 0) ? -1 : 0
748 dst.y = (src.y > 0) ? 1 : (src.y < 0) ? -1 : 0
750 dst.z = (src.z > 0) ? 1 : (src.z < 0) ? -1 : 0
752 dst.w = (src.w > 0) ? 1 : (src.w < 0) ? -1 : 0
755 .. opcode:: CMP - Compare
759 dst.x = (src0.x < 0) ? src1.x : src2.x
761 dst.y = (src0.y < 0) ? src1.y : src2.y
763 dst.z = (src0.z < 0) ? src1.z : src2.z
765 dst.w = (src0.w < 0) ? src1.w : src2.w
768 .. opcode:: KIL - Conditional Discard
772 if (src.x < 0 || src.y < 0 || src.z < 0 || src.w < 0)
777 .. opcode:: SCS - Sine Cosine
790 .. opcode:: TXB - Texture Lookup With Bias
804 dst = texture_sample(unit, coord, bias)
807 .. opcode:: NRM - 3-component Vector Normalise
811 dst.x = src.x / (src.x \times src.x + src.y \times src.y + src.z \times src.z)
813 dst.y = src.y / (src.x \times src.x + src.y \times src.y + src.z \times src.z)
815 dst.z = src.z / (src.x \times src.x + src.y \times src.y + src.z \times src.z)
820 .. opcode:: DIV - Divide
824 dst.x = \frac{src0.x}{src1.x}
826 dst.y = \frac{src0.y}{src1.y}
828 dst.z = \frac{src0.z}{src1.z}
830 dst.w = \frac{src0.w}{src1.w}
833 .. opcode:: DP2 - 2-component Dot Product
835 This instruction replicates its result.
839 dst = src0.x \times src1.x + src0.y \times src1.y
842 .. opcode:: TXL - Texture Lookup With explicit LOD
856 dst = texture_sample(unit, coord, lod)
859 .. opcode:: BRK - Break
861 Unconditionally moves the point of execution to the instruction after the
862 next endloop or endswitch. The instruction must appear within a loop/endloop
866 .. opcode:: BREAKC - Break Conditional
868 Conditionally moves the point of execution to the instruction after the
869 next endloop or endswitch. The instruction must appear within a loop/endloop
871 Condition evaluates to true if src0.x != 0 where src0.x is interpreted
872 as an integer register.
875 .. opcode:: IF - Float If
877 Start an IF ... ELSE .. ENDIF block. Condition evaluates to true if
881 where src0.x is interpreted as a floating point register.
884 .. opcode:: UIF - Bitwise If
886 Start an UIF ... ELSE .. ENDIF block. Condition evaluates to true if
890 where src0.x is interpreted as an integer register.
893 .. opcode:: ELSE - Else
895 Starts an else block, after an IF or UIF statement.
898 .. opcode:: ENDIF - End If
900 Ends an IF or UIF block.
903 .. opcode:: SWITCH - Switch
905 Starts a C-style switch expression. The switch consists of one or multiple
906 CASE statements, and at most one DEFAULT statement. Execution of a statement
907 ends when a BRK is hit, but just like in C falling through to other cases
908 without a break is allowed. Similarly, DEFAULT label is allowed anywhere not
909 just as last statement, and fallthrough is allowed into/from it.
910 CASE src arguments are evaluated at bit level against the SWITCH src argument.
915 (some instructions here)
918 (some instructions here)
921 (some instructions here)
926 .. opcode:: CASE - Switch case
928 This represents a switch case label. The src arg must be an integer immediate.
931 .. opcode:: DEFAULT - Switch default
933 This represents the default case in the switch, which is taken if no other
937 .. opcode:: ENDSWITCH - End of switch
939 Ends a switch expression.
942 .. opcode:: PUSHA - Push Address Register On Stack
951 Considered for cleanup.
955 Considered for removal.
957 .. opcode:: POPA - Pop Address Register From Stack
966 Considered for cleanup.
970 Considered for removal.
974 ^^^^^^^^^^^^^^^^^^^^^^^^
976 These opcodes are primarily provided for special-use computational shaders.
977 Support for these opcodes indicated by a special pipe capability bit (TBD).
979 XXX so let's discuss it, yeah?
981 .. opcode:: CEIL - Ceiling
985 dst.x = \lceil src.x\rceil
987 dst.y = \lceil src.y\rceil
989 dst.z = \lceil src.z\rceil
991 dst.w = \lceil src.w\rceil
994 .. opcode:: I2F - Integer To Float
998 dst.x = (float) src.x
1000 dst.y = (float) src.y
1002 dst.z = (float) src.z
1004 dst.w = (float) src.w
1007 .. opcode:: NOT - Bitwise Not
1020 .. opcode:: TRUNC - Truncate
1024 dst.x = trunc(src.x)
1026 dst.y = trunc(src.y)
1028 dst.z = trunc(src.z)
1030 dst.w = trunc(src.w)
1033 .. opcode:: SHL - Shift Left
1037 dst.x = src0.x << src1.x
1039 dst.y = src0.y << src1.x
1041 dst.z = src0.z << src1.x
1043 dst.w = src0.w << src1.x
1046 .. opcode:: SHR - Shift Right
1050 dst.x = src0.x >> src1.x
1052 dst.y = src0.y >> src1.x
1054 dst.z = src0.z >> src1.x
1056 dst.w = src0.w >> src1.x
1059 .. opcode:: AND - Bitwise And
1063 dst.x = src0.x & src1.x
1065 dst.y = src0.y & src1.y
1067 dst.z = src0.z & src1.z
1069 dst.w = src0.w & src1.w
1072 .. opcode:: OR - Bitwise Or
1076 dst.x = src0.x | src1.x
1078 dst.y = src0.y | src1.y
1080 dst.z = src0.z | src1.z
1082 dst.w = src0.w | src1.w
1085 .. opcode:: MOD - Modulus
1089 dst.x = src0.x \bmod src1.x
1091 dst.y = src0.y \bmod src1.y
1093 dst.z = src0.z \bmod src1.z
1095 dst.w = src0.w \bmod src1.w
1098 .. opcode:: XOR - Bitwise Xor
1102 dst.x = src0.x \oplus src1.x
1104 dst.y = src0.y \oplus src1.y
1106 dst.z = src0.z \oplus src1.z
1108 dst.w = src0.w \oplus src1.w
1111 .. opcode:: UCMP - Integer Conditional Move
1115 dst.x = src0.x ? src1.x : src2.x
1117 dst.y = src0.y ? src1.y : src2.y
1119 dst.z = src0.z ? src1.z : src2.z
1121 dst.w = src0.w ? src1.w : src2.w
1124 .. opcode:: UARL - Integer Address Register Load
1126 Moves the contents of the source register, assumed to be an integer, into the
1127 destination register, which is assumed to be an address (ADDR) register.
1130 .. opcode:: IABS - Integer Absolute Value
1143 .. opcode:: SAD - Sum Of Absolute Differences
1147 dst.x = |src0.x - src1.x| + src2.x
1149 dst.y = |src0.y - src1.y| + src2.y
1151 dst.z = |src0.z - src1.z| + src2.z
1153 dst.w = |src0.w - src1.w| + src2.w
1156 .. opcode:: TXF - Texel Fetch (as per NV_gpu_shader4), extract a single texel
1157 from a specified texture image. The source sampler may
1158 not be a CUBE or SHADOW.
1159 src 0 is a four-component signed integer vector used to
1160 identify the single texel accessed. 3 components + level.
1161 src 1 is a 3 component constant signed integer vector,
1162 with each component only have a range of
1163 -8..+8 (hw only seems to deal with this range, interface
1164 allows for up to unsigned int).
1165 TXF(uint_vec coord, int_vec offset).
1168 .. opcode:: TXQ - Texture Size Query (as per NV_gpu_program4)
1169 retrieve the dimensions of the texture
1170 depending on the target. For 1D (width), 2D/RECT/CUBE
1171 (width, height), 3D (width, height, depth),
1172 1D array (width, layers), 2D array (width, height, layers)
1178 dst.x = texture_width(unit, lod)
1180 dst.y = texture_height(unit, lod)
1182 dst.z = texture_depth(unit, lod)
1185 .. opcode:: CONT - Continue
1191 Support for CONT is determined by a special capability bit,
1192 ``TGSI_CONT_SUPPORTED``. See :ref:`Screen` for more information.
1196 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1198 These opcodes are only supported in geometry shaders; they have no meaning
1199 in any other type of shader.
1201 .. opcode:: EMIT - Emit
1206 .. opcode:: ENDPRIM - End Primitive
1214 These opcodes are part of :term:`GLSL`'s opcode set. Support for these
1215 opcodes is determined by a special capability bit, ``GLSL``.
1217 .. opcode:: BGNLOOP - Begin a Loop
1222 .. opcode:: BGNSUB - Begin Subroutine
1227 .. opcode:: ENDLOOP - End a Loop
1232 .. opcode:: ENDSUB - End Subroutine
1237 .. opcode:: NOP - No Operation
1242 .. opcode:: NRM4 - 4-component Vector Normalise
1244 This instruction replicates its result.
1248 dst = \frac{src.x}{src.x \times src.x + src.y \times src.y + src.z \times src.z + src.w \times src.w}
1256 .. opcode:: CALLNZ - Subroutine Call If Not Zero
1265 The double-precision opcodes reinterpret four-component vectors into
1266 two-component vectors with doubled precision in each component.
1268 Support for these opcodes is XXX undecided. :T
1270 .. opcode:: DADD - Add
1274 dst.xy = src0.xy + src1.xy
1276 dst.zw = src0.zw + src1.zw
1279 .. opcode:: DDIV - Divide
1283 dst.xy = src0.xy / src1.xy
1285 dst.zw = src0.zw / src1.zw
1287 .. opcode:: DSEQ - Set on Equal
1291 dst.xy = src0.xy == src1.xy ? 1.0F : 0.0F
1293 dst.zw = src0.zw == src1.zw ? 1.0F : 0.0F
1295 .. opcode:: DSLT - Set on Less than
1299 dst.xy = src0.xy < src1.xy ? 1.0F : 0.0F
1301 dst.zw = src0.zw < src1.zw ? 1.0F : 0.0F
1303 .. opcode:: DFRAC - Fraction
1307 dst.xy = src.xy - \lfloor src.xy\rfloor
1309 dst.zw = src.zw - \lfloor src.zw\rfloor
1312 .. opcode:: DFRACEXP - Convert Number to Fractional and Integral Components
1314 Like the ``frexp()`` routine in many math libraries, this opcode stores the
1315 exponent of its source to ``dst0``, and the significand to ``dst1``, such that
1316 :math:`dst1 \times 2^{dst0} = src` .
1320 dst0.xy = exp(src.xy)
1322 dst1.xy = frac(src.xy)
1324 dst0.zw = exp(src.zw)
1326 dst1.zw = frac(src.zw)
1328 .. opcode:: DLDEXP - Multiply Number by Integral Power of 2
1330 This opcode is the inverse of :opcode:`DFRACEXP`.
1334 dst.xy = src0.xy \times 2^{src1.xy}
1336 dst.zw = src0.zw \times 2^{src1.zw}
1338 .. opcode:: DMIN - Minimum
1342 dst.xy = min(src0.xy, src1.xy)
1344 dst.zw = min(src0.zw, src1.zw)
1346 .. opcode:: DMAX - Maximum
1350 dst.xy = max(src0.xy, src1.xy)
1352 dst.zw = max(src0.zw, src1.zw)
1354 .. opcode:: DMUL - Multiply
1358 dst.xy = src0.xy \times src1.xy
1360 dst.zw = src0.zw \times src1.zw
1363 .. opcode:: DMAD - Multiply And Add
1367 dst.xy = src0.xy \times src1.xy + src2.xy
1369 dst.zw = src0.zw \times src1.zw + src2.zw
1372 .. opcode:: DRCP - Reciprocal
1376 dst.xy = \frac{1}{src.xy}
1378 dst.zw = \frac{1}{src.zw}
1380 .. opcode:: DSQRT - Square Root
1384 dst.xy = \sqrt{src.xy}
1386 dst.zw = \sqrt{src.zw}
1389 .. _samplingopcodes:
1391 Resource Sampling Opcodes
1392 ^^^^^^^^^^^^^^^^^^^^^^^^^
1394 Those opcodes follow very closely semantics of the respective Direct3D
1395 instructions. If in doubt double check Direct3D documentation.
1397 .. opcode:: SAMPLE - Using provided address, sample data from the
1398 specified texture using the filtering mode identified
1399 by the gven sampler. The source data may come from
1400 any resource type other than buffers.
1401 SAMPLE dst, address, sampler_view, sampler
1403 SAMPLE TEMP[0], TEMP[1], SVIEW[0], SAMP[0]
1405 .. opcode:: SAMPLE_I - Simplified alternative to the SAMPLE instruction.
1406 Using the provided integer address, SAMPLE_I fetches data
1407 from the specified sampler view without any filtering.
1408 The source data may come from any resource type other
1410 SAMPLE_I dst, address, sampler_view
1412 SAMPLE_I TEMP[0], TEMP[1], SVIEW[0]
1413 The 'address' is specified as unsigned integers. If the
1414 'address' is out of range [0...(# texels - 1)] the
1415 result of the fetch is always 0 in all components.
1416 As such the instruction doesn't honor address wrap
1417 modes, in cases where that behavior is desirable
1418 'SAMPLE' instruction should be used.
1419 address.w always provides an unsigned integer mipmap
1420 level. If the value is out of the range then the
1421 instruction always returns 0 in all components.
1422 address.yz are ignored for buffers and 1d textures.
1423 address.z is ignored for 1d texture arrays and 2d
1425 For 1D texture arrays address.y provides the array
1426 index (also as unsigned integer). If the value is
1427 out of the range of available array indices
1428 [0... (array size - 1)] then the opcode always returns
1429 0 in all components.
1430 For 2D texture arrays address.z provides the array
1431 index, otherwise it exhibits the same behavior as in
1432 the case for 1D texture arrays.
1433 The exact semantics of the source address are presented
1435 resource type X Y Z W
1436 ------------- ------------------------
1437 PIPE_BUFFER x ignored
1438 PIPE_TEXTURE_1D x mpl
1439 PIPE_TEXTURE_2D x y mpl
1440 PIPE_TEXTURE_3D x y z mpl
1441 PIPE_TEXTURE_RECT x y mpl
1442 PIPE_TEXTURE_CUBE not allowed as source
1443 PIPE_TEXTURE_1D_ARRAY x idx mpl
1444 PIPE_TEXTURE_2D_ARRAY x y idx mpl
1446 Where 'mpl' is a mipmap level and 'idx' is the
1449 .. opcode:: SAMPLE_I_MS - Just like SAMPLE_I but allows fetch data from
1450 multi-sampled surfaces.
1451 SAMPLE_I_MS dst, address, sampler_view, sample
1453 .. opcode:: SAMPLE_B - Just like the SAMPLE instruction with the
1454 exception that an additional bias is applied to the
1455 level of detail computed as part of the instruction
1457 SAMPLE_B dst, address, sampler_view, sampler, lod_bias
1459 SAMPLE_B TEMP[0], TEMP[1], SVIEW[0], SAMP[0], TEMP[2].x
1461 .. opcode:: SAMPLE_C - Similar to the SAMPLE instruction but it
1462 performs a comparison filter. The operands to SAMPLE_C
1463 are identical to SAMPLE, except that there is an additional
1464 float32 operand, reference value, which must be a register
1465 with single-component, or a scalar literal.
1466 SAMPLE_C makes the hardware use the current samplers
1467 compare_func (in pipe_sampler_state) to compare
1468 reference value against the red component value for the
1469 surce resource at each texel that the currently configured
1470 texture filter covers based on the provided coordinates.
1471 SAMPLE_C dst, address, sampler_view.r, sampler, ref_value
1473 SAMPLE_C TEMP[0], TEMP[1], SVIEW[0].r, SAMP[0], TEMP[2].x
1475 .. opcode:: SAMPLE_C_LZ - Same as SAMPLE_C, but LOD is 0 and derivatives
1476 are ignored. The LZ stands for level-zero.
1477 SAMPLE_C_LZ dst, address, sampler_view.r, sampler, ref_value
1479 SAMPLE_C_LZ TEMP[0], TEMP[1], SVIEW[0].r, SAMP[0], TEMP[2].x
1482 .. opcode:: SAMPLE_D - SAMPLE_D is identical to the SAMPLE opcode except
1483 that the derivatives for the source address in the x
1484 direction and the y direction are provided by extra
1486 SAMPLE_D dst, address, sampler_view, sampler, der_x, der_y
1488 SAMPLE_D TEMP[0], TEMP[1], SVIEW[0], SAMP[0], TEMP[2], TEMP[3]
1490 .. opcode:: SAMPLE_L - SAMPLE_L is identical to the SAMPLE opcode except
1491 that the LOD is provided directly as a scalar value,
1492 representing no anisotropy.
1493 SAMPLE_L dst, address, sampler_view, sampler, explicit_lod
1495 SAMPLE_L TEMP[0], TEMP[1], SVIEW[0], SAMP[0], TEMP[2].x
1497 .. opcode:: GATHER4 - Gathers the four texels to be used in a bi-linear
1498 filtering operation and packs them into a single register.
1499 Only works with 2D, 2D array, cubemaps, and cubemaps arrays.
1500 For 2D textures, only the addressing modes of the sampler and
1501 the top level of any mip pyramid are used. Set W to zero.
1502 It behaves like the SAMPLE instruction, but a filtered
1503 sample is not generated. The four samples that contribute
1504 to filtering are placed into xyzw in counter-clockwise order,
1505 starting with the (u,v) texture coordinate delta at the
1506 following locations (-, +), (+, +), (+, -), (-, -), where
1507 the magnitude of the deltas are half a texel.
1510 .. opcode:: SVIEWINFO - query the dimensions of a given sampler view.
1511 dst receives width, height, depth or array size and
1512 number of mipmap levels as int4. The dst can have a writemask
1513 which will specify what info is the caller interested
1515 SVIEWINFO dst, src_mip_level, sampler_view
1517 SVIEWINFO TEMP[0], TEMP[1].x, SVIEW[0]
1518 src_mip_level is an unsigned integer scalar. If it's
1519 out of range then returns 0 for width, height and
1520 depth/array size but the total number of mipmap is
1521 still returned correctly for the given sampler view.
1522 The returned width, height and depth values are for
1523 the mipmap level selected by the src_mip_level and
1524 are in the number of texels.
1525 For 1d texture array width is in dst.x, array size
1526 is in dst.y and dst.zw are always 0.
1528 .. opcode:: SAMPLE_POS - query the position of a given sample.
1529 dst receives float4 (x, y, 0, 0) indicated where the
1530 sample is located. If the resource is not a multi-sample
1531 resource and not a render target, the result is 0.
1533 .. opcode:: SAMPLE_INFO - dst receives number of samples in x.
1534 If the resource is not a multi-sample resource and
1535 not a render target, the result is 0.
1538 .. _resourceopcodes:
1540 Resource Access Opcodes
1541 ^^^^^^^^^^^^^^^^^^^^^^^
1543 .. opcode:: LOAD - Fetch data from a shader resource
1545 Syntax: ``LOAD dst, resource, address``
1547 Example: ``LOAD TEMP[0], RES[0], TEMP[1]``
1549 Using the provided integer address, LOAD fetches data
1550 from the specified buffer or texture without any
1553 The 'address' is specified as a vector of unsigned
1554 integers. If the 'address' is out of range the result
1557 Only the first mipmap level of a resource can be read
1558 from using this instruction.
1560 For 1D or 2D texture arrays, the array index is
1561 provided as an unsigned integer in address.y or
1562 address.z, respectively. address.yz are ignored for
1563 buffers and 1D textures. address.z is ignored for 1D
1564 texture arrays and 2D textures. address.w is always
1567 .. opcode:: STORE - Write data to a shader resource
1569 Syntax: ``STORE resource, address, src``
1571 Example: ``STORE RES[0], TEMP[0], TEMP[1]``
1573 Using the provided integer address, STORE writes data
1574 to the specified buffer or texture.
1576 The 'address' is specified as a vector of unsigned
1577 integers. If the 'address' is out of range the result
1580 Only the first mipmap level of a resource can be
1581 written to using this instruction.
1583 For 1D or 2D texture arrays, the array index is
1584 provided as an unsigned integer in address.y or
1585 address.z, respectively. address.yz are ignored for
1586 buffers and 1D textures. address.z is ignored for 1D
1587 texture arrays and 2D textures. address.w is always
1591 .. _threadsyncopcodes:
1593 Inter-thread synchronization opcodes
1594 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1596 These opcodes are intended for communication between threads running
1597 within the same compute grid. For now they're only valid in compute
1600 .. opcode:: MFENCE - Memory fence
1602 Syntax: ``MFENCE resource``
1604 Example: ``MFENCE RES[0]``
1606 This opcode forces strong ordering between any memory access
1607 operations that affect the specified resource. This means that
1608 previous loads and stores (and only those) will be performed and
1609 visible to other threads before the program execution continues.
1612 .. opcode:: LFENCE - Load memory fence
1614 Syntax: ``LFENCE resource``
1616 Example: ``LFENCE RES[0]``
1618 Similar to MFENCE, but it only affects the ordering of memory loads.
1621 .. opcode:: SFENCE - Store memory fence
1623 Syntax: ``SFENCE resource``
1625 Example: ``SFENCE RES[0]``
1627 Similar to MFENCE, but it only affects the ordering of memory stores.
1630 .. opcode:: BARRIER - Thread group barrier
1634 This opcode suspends the execution of the current thread until all
1635 the remaining threads in the working group reach the same point of
1636 the program. Results are unspecified if any of the remaining
1637 threads terminates or never reaches an executed BARRIER instruction.
1645 These opcodes provide atomic variants of some common arithmetic and
1646 logical operations. In this context atomicity means that another
1647 concurrent memory access operation that affects the same memory
1648 location is guaranteed to be performed strictly before or after the
1649 entire execution of the atomic operation.
1651 For the moment they're only valid in compute programs.
1653 .. opcode:: ATOMUADD - Atomic integer addition
1655 Syntax: ``ATOMUADD dst, resource, offset, src``
1657 Example: ``ATOMUADD TEMP[0], RES[0], TEMP[1], TEMP[2]``
1659 The following operation is performed atomically on each component:
1663 dst_i = resource[offset]_i
1665 resource[offset]_i = dst_i + src_i
1668 .. opcode:: ATOMXCHG - Atomic exchange
1670 Syntax: ``ATOMXCHG dst, resource, offset, src``
1672 Example: ``ATOMXCHG TEMP[0], RES[0], TEMP[1], TEMP[2]``
1674 The following operation is performed atomically on each component:
1678 dst_i = resource[offset]_i
1680 resource[offset]_i = src_i
1683 .. opcode:: ATOMCAS - Atomic compare-and-exchange
1685 Syntax: ``ATOMCAS dst, resource, offset, cmp, src``
1687 Example: ``ATOMCAS TEMP[0], RES[0], TEMP[1], TEMP[2], TEMP[3]``
1689 The following operation is performed atomically on each component:
1693 dst_i = resource[offset]_i
1695 resource[offset]_i = (dst_i == cmp_i ? src_i : dst_i)
1698 .. opcode:: ATOMAND - Atomic bitwise And
1700 Syntax: ``ATOMAND dst, resource, offset, src``
1702 Example: ``ATOMAND TEMP[0], RES[0], TEMP[1], TEMP[2]``
1704 The following operation is performed atomically on each component:
1708 dst_i = resource[offset]_i
1710 resource[offset]_i = dst_i \& src_i
1713 .. opcode:: ATOMOR - Atomic bitwise Or
1715 Syntax: ``ATOMOR dst, resource, offset, src``
1717 Example: ``ATOMOR TEMP[0], RES[0], TEMP[1], TEMP[2]``
1719 The following operation is performed atomically on each component:
1723 dst_i = resource[offset]_i
1725 resource[offset]_i = dst_i | src_i
1728 .. opcode:: ATOMXOR - Atomic bitwise Xor
1730 Syntax: ``ATOMXOR dst, resource, offset, src``
1732 Example: ``ATOMXOR TEMP[0], RES[0], TEMP[1], TEMP[2]``
1734 The following operation is performed atomically on each component:
1738 dst_i = resource[offset]_i
1740 resource[offset]_i = dst_i \oplus src_i
1743 .. opcode:: ATOMUMIN - Atomic unsigned minimum
1745 Syntax: ``ATOMUMIN dst, resource, offset, src``
1747 Example: ``ATOMUMIN TEMP[0], RES[0], TEMP[1], TEMP[2]``
1749 The following operation is performed atomically on each component:
1753 dst_i = resource[offset]_i
1755 resource[offset]_i = (dst_i < src_i ? dst_i : src_i)
1758 .. opcode:: ATOMUMAX - Atomic unsigned maximum
1760 Syntax: ``ATOMUMAX dst, resource, offset, src``
1762 Example: ``ATOMUMAX TEMP[0], RES[0], TEMP[1], TEMP[2]``
1764 The following operation is performed atomically on each component:
1768 dst_i = resource[offset]_i
1770 resource[offset]_i = (dst_i > src_i ? dst_i : src_i)
1773 .. opcode:: ATOMIMIN - Atomic signed minimum
1775 Syntax: ``ATOMIMIN dst, resource, offset, src``
1777 Example: ``ATOMIMIN TEMP[0], RES[0], TEMP[1], TEMP[2]``
1779 The following operation is performed atomically on each component:
1783 dst_i = resource[offset]_i
1785 resource[offset]_i = (dst_i < src_i ? dst_i : src_i)
1788 .. opcode:: ATOMIMAX - Atomic signed maximum
1790 Syntax: ``ATOMIMAX dst, resource, offset, src``
1792 Example: ``ATOMIMAX TEMP[0], RES[0], TEMP[1], TEMP[2]``
1794 The following operation is performed atomically on each component:
1798 dst_i = resource[offset]_i
1800 resource[offset]_i = (dst_i > src_i ? dst_i : src_i)
1804 Explanation of symbols used
1805 ------------------------------
1812 :math:`|x|` Absolute value of `x`.
1814 :math:`\lceil x \rceil` Ceiling of `x`.
1816 clamp(x,y,z) Clamp x between y and z.
1817 (x < y) ? y : (x > z) ? z : x
1819 :math:`\lfloor x\rfloor` Floor of `x`.
1821 :math:`\log_2{x}` Logarithm of `x`, base 2.
1823 max(x,y) Maximum of x and y.
1826 min(x,y) Minimum of x and y.
1829 partialx(x) Derivative of x relative to fragment's X.
1831 partialy(x) Derivative of x relative to fragment's Y.
1833 pop() Pop from stack.
1835 :math:`x^y` `x` to the power `y`.
1837 push(x) Push x on stack.
1841 trunc(x) Truncate x, i.e. drop the fraction bits.
1848 discard Discard fragment.
1852 target Label of target instruction.
1863 Declares a register that is will be referenced as an operand in Instruction
1866 File field contains register file that is being declared and is one
1869 UsageMask field specifies which of the register components can be accessed
1870 and is one of TGSI_WRITEMASK.
1872 The Local flag specifies that a given value isn't intended for
1873 subroutine parameter passing and, as a result, the implementation
1874 isn't required to give any guarantees of it being preserved across
1875 subroutine boundaries. As it's merely a compiler hint, the
1876 implementation is free to ignore it.
1878 If Dimension flag is set to 1, a Declaration Dimension token follows.
1880 If Semantic flag is set to 1, a Declaration Semantic token follows.
1882 If Interpolate flag is set to 1, a Declaration Interpolate token follows.
1884 If file is TGSI_FILE_RESOURCE, a Declaration Resource token follows.
1886 If Array flag is set to 1, a Declaration Array token follows.
1889 ^^^^^^^^^^^^^^^^^^^^^^^^
1891 Declarations can optional have an ArrayID attribute which can be referred by
1892 indirect addressing operands. An ArrayID of zero is reserved and treaded as
1893 if no ArrayID is specified.
1895 If an indirect addressing operand refers to a specific declaration by using
1896 an ArrayID only the registers in this declaration are guaranteed to be
1897 accessed, accessing any register outside this declaration results in undefined
1898 behavior. Note that for compatibility the effective index is zero-based and
1899 not relative to the specified declaration
1901 If no ArrayID is specified with an indirect addressing operand the whole
1902 register file might be accessed by this operand. This is strongly discouraged
1903 and will prevent packing of scalar/vec2 arrays and effective alias analysis.
1905 Declaration Semantic
1906 ^^^^^^^^^^^^^^^^^^^^^^^^
1908 Vertex and fragment shader input and output registers may be labeled
1909 with semantic information consisting of a name and index.
1911 Follows Declaration token if Semantic bit is set.
1913 Since its purpose is to link a shader with other stages of the pipeline,
1914 it is valid to follow only those Declaration tokens that declare a register
1915 either in INPUT or OUTPUT file.
1917 SemanticName field contains the semantic name of the register being declared.
1918 There is no default value.
1920 SemanticIndex is an optional subscript that can be used to distinguish
1921 different register declarations with the same semantic name. The default value
1924 The meanings of the individual semantic names are explained in the following
1927 TGSI_SEMANTIC_POSITION
1928 """"""""""""""""""""""
1930 For vertex shaders, TGSI_SEMANTIC_POSITION indicates the vertex shader
1931 output register which contains the homogeneous vertex position in the clip
1932 space coordinate system. After clipping, the X, Y and Z components of the
1933 vertex will be divided by the W value to get normalized device coordinates.
1935 For fragment shaders, TGSI_SEMANTIC_POSITION is used to indicate that
1936 fragment shader input contains the fragment's window position. The X
1937 component starts at zero and always increases from left to right.
1938 The Y component starts at zero and always increases but Y=0 may either
1939 indicate the top of the window or the bottom depending on the fragment
1940 coordinate origin convention (see TGSI_PROPERTY_FS_COORD_ORIGIN).
1941 The Z coordinate ranges from 0 to 1 to represent depth from the front
1942 to the back of the Z buffer. The W component contains the reciprocol
1943 of the interpolated vertex position W component.
1945 Fragment shaders may also declare an output register with
1946 TGSI_SEMANTIC_POSITION. Only the Z component is writable. This allows
1947 the fragment shader to change the fragment's Z position.
1954 For vertex shader outputs or fragment shader inputs/outputs, this
1955 label indicates that the resister contains an R,G,B,A color.
1957 Several shader inputs/outputs may contain colors so the semantic index
1958 is used to distinguish them. For example, color[0] may be the diffuse
1959 color while color[1] may be the specular color.
1961 This label is needed so that the flat/smooth shading can be applied
1962 to the right interpolants during rasterization.
1966 TGSI_SEMANTIC_BCOLOR
1967 """"""""""""""""""""
1969 Back-facing colors are only used for back-facing polygons, and are only valid
1970 in vertex shader outputs. After rasterization, all polygons are front-facing
1971 and COLOR and BCOLOR end up occupying the same slots in the fragment shader,
1972 so all BCOLORs effectively become regular COLORs in the fragment shader.
1978 Vertex shader inputs and outputs and fragment shader inputs may be
1979 labeled with TGSI_SEMANTIC_FOG to indicate that the register contains
1980 a fog coordinate in the form (F, 0, 0, 1). Typically, the fragment
1981 shader will use the fog coordinate to compute a fog blend factor which
1982 is used to blend the normal fragment color with a constant fog color.
1984 Only the first component matters when writing from the vertex shader;
1985 the driver will ensure that the coordinate is in this format when used
1986 as a fragment shader input.
1992 Vertex shader input and output registers may be labeled with
1993 TGIS_SEMANTIC_PSIZE to indicate that the register contains a point size
1994 in the form (S, 0, 0, 1). The point size controls the width or diameter
1995 of points for rasterization. This label cannot be used in fragment
1998 When using this semantic, be sure to set the appropriate state in the
1999 :ref:`rasterizer` first.
2002 TGSI_SEMANTIC_TEXCOORD
2003 """"""""""""""""""""""
2005 Only available if PIPE_CAP_TGSI_TEXCOORD is exposed !
2007 Vertex shader outputs and fragment shader inputs may be labeled with
2008 this semantic to make them replaceable by sprite coordinates via the
2009 sprite_coord_enable state in the :ref:`rasterizer`.
2010 The semantic index permitted with this semantic is limited to <= 7.
2012 If the driver does not support TEXCOORD, sprite coordinate replacement
2013 applies to inputs with the GENERIC semantic instead.
2015 The intended use case for this semantic is gl_TexCoord.
2018 TGSI_SEMANTIC_PCOORD
2019 """"""""""""""""""""
2021 Only available if PIPE_CAP_TGSI_TEXCOORD is exposed !
2023 Fragment shader inputs may be labeled with TGSI_SEMANTIC_PCOORD to indicate
2024 that the register contains sprite coordinates in the form (x, y, 0, 1), if
2025 the current primitive is a point and point sprites are enabled. Otherwise,
2026 the contents of the register are undefined.
2028 The intended use case for this semantic is gl_PointCoord.
2031 TGSI_SEMANTIC_GENERIC
2032 """""""""""""""""""""
2034 All vertex/fragment shader inputs/outputs not labeled with any other
2035 semantic label can be considered to be generic attributes. Typical
2036 uses of generic inputs/outputs are texcoords and user-defined values.
2039 TGSI_SEMANTIC_NORMAL
2040 """"""""""""""""""""
2042 Indicates that a vertex shader input is a normal vector. This is
2043 typically only used for legacy graphics APIs.
2049 This label applies to fragment shader inputs only and indicates that
2050 the register contains front/back-face information of the form (F, 0,
2051 0, 1). The first component will be positive when the fragment belongs
2052 to a front-facing polygon, and negative when the fragment belongs to a
2053 back-facing polygon.
2056 TGSI_SEMANTIC_EDGEFLAG
2057 """"""""""""""""""""""
2059 For vertex shaders, this sematic label indicates that an input or
2060 output is a boolean edge flag. The register layout is [F, x, x, x]
2061 where F is 0.0 or 1.0 and x = don't care. Normally, the vertex shader
2062 simply copies the edge flag input to the edgeflag output.
2064 Edge flags are used to control which lines or points are actually
2065 drawn when the polygon mode converts triangles/quads/polygons into
2068 TGSI_SEMANTIC_STENCIL
2069 """"""""""""""""""""""
2071 For fragment shaders, this semantic label indicates than an output
2072 is a writable stencil reference value. Only the Y component is writable.
2073 This allows the fragment shader to change the fragments stencilref value.
2076 Declaration Interpolate
2077 ^^^^^^^^^^^^^^^^^^^^^^^
2079 This token is only valid for fragment shader INPUT declarations.
2081 The Interpolate field specifes the way input is being interpolated by
2082 the rasteriser and is one of TGSI_INTERPOLATE_*.
2084 The CylindricalWrap bitfield specifies which register components
2085 should be subject to cylindrical wrapping when interpolating by the
2086 rasteriser. If TGSI_CYLINDRICAL_WRAP_X is set to 1, the X component
2087 should be interpolated according to cylindrical wrapping rules.
2090 Declaration Sampler View
2091 ^^^^^^^^^^^^^^^^^^^^^^^^
2093 Follows Declaration token if file is TGSI_FILE_SAMPLER_VIEW.
2095 DCL SVIEW[#], resource, type(s)
2097 Declares a shader input sampler view and assigns it to a SVIEW[#]
2100 resource can be one of BUFFER, 1D, 2D, 3D, 1DArray and 2DArray.
2102 type must be 1 or 4 entries (if specifying on a per-component
2103 level) out of UNORM, SNORM, SINT, UINT and FLOAT.
2106 Declaration Resource
2107 ^^^^^^^^^^^^^^^^^^^^
2109 Follows Declaration token if file is TGSI_FILE_RESOURCE.
2111 DCL RES[#], resource [, WR] [, RAW]
2113 Declares a shader input resource and assigns it to a RES[#]
2116 resource can be one of BUFFER, 1D, 2D, 3D, CUBE, 1DArray and
2119 If the RAW keyword is not specified, the texture data will be
2120 subject to conversion, swizzling and scaling as required to yield
2121 the specified data type from the physical data format of the bound
2124 If the RAW keyword is specified, no channel conversion will be
2125 performed: the values read for each of the channels (X,Y,Z,W) will
2126 correspond to consecutive words in the same order and format
2127 they're found in memory. No element-to-address conversion will be
2128 performed either: the value of the provided X coordinate will be
2129 interpreted in byte units instead of texel units. The result of
2130 accessing a misaligned address is undefined.
2132 Usage of the STORE opcode is only allowed if the WR (writable) flag
2137 ^^^^^^^^^^^^^^^^^^^^^^^^
2140 Properties are general directives that apply to the whole TGSI program.
2145 Specifies the fragment shader TGSI_SEMANTIC_POSITION coordinate origin.
2146 The default value is UPPER_LEFT.
2148 If UPPER_LEFT, the position will be (0,0) at the upper left corner and
2149 increase downward and rightward.
2150 If LOWER_LEFT, the position will be (0,0) at the lower left corner and
2151 increase upward and rightward.
2153 OpenGL defaults to LOWER_LEFT, and is configurable with the
2154 GL_ARB_fragment_coord_conventions extension.
2156 DirectX 9/10 use UPPER_LEFT.
2158 FS_COORD_PIXEL_CENTER
2159 """""""""""""""""""""
2161 Specifies the fragment shader TGSI_SEMANTIC_POSITION pixel center convention.
2162 The default value is HALF_INTEGER.
2164 If HALF_INTEGER, the fractionary part of the position will be 0.5
2165 If INTEGER, the fractionary part of the position will be 0.0
2167 Note that this does not affect the set of fragments generated by
2168 rasterization, which is instead controlled by half_pixel_center in the
2171 OpenGL defaults to HALF_INTEGER, and is configurable with the
2172 GL_ARB_fragment_coord_conventions extension.
2174 DirectX 9 uses INTEGER.
2175 DirectX 10 uses HALF_INTEGER.
2177 FS_COLOR0_WRITES_ALL_CBUFS
2178 """"""""""""""""""""""""""
2179 Specifies that writes to the fragment shader color 0 are replicated to all
2180 bound cbufs. This facilitates OpenGL's fragColor output vs fragData[0] where
2181 fragData is directed to a single color buffer, but fragColor is broadcast.
2184 """"""""""""""""""""""""""
2185 If this property is set on the program bound to the shader stage before the
2186 fragment shader, user clip planes should have no effect (be disabled) even if
2187 that shader does not write to any clip distance outputs and the rasterizer's
2188 clip_plane_enable is non-zero.
2189 This property is only supported by drivers that also support shader clip
2191 This is useful for APIs that don't have UCPs and where clip distances written
2192 by a shader cannot be disabled.
2195 Texture Sampling and Texture Formats
2196 ------------------------------------
2198 This table shows how texture image components are returned as (x,y,z,w) tuples
2199 by TGSI texture instructions, such as :opcode:`TEX`, :opcode:`TXD`, and
2200 :opcode:`TXP`. For reference, OpenGL and Direct3D conventions are shown as
2203 +--------------------+--------------+--------------------+--------------+
2204 | Texture Components | Gallium | OpenGL | Direct3D 9 |
2205 +====================+==============+====================+==============+
2206 | R | (r, 0, 0, 1) | (r, 0, 0, 1) | (r, 1, 1, 1) |
2207 +--------------------+--------------+--------------------+--------------+
2208 | RG | (r, g, 0, 1) | (r, g, 0, 1) | (r, g, 1, 1) |
2209 +--------------------+--------------+--------------------+--------------+
2210 | RGB | (r, g, b, 1) | (r, g, b, 1) | (r, g, b, 1) |
2211 +--------------------+--------------+--------------------+--------------+
2212 | RGBA | (r, g, b, a) | (r, g, b, a) | (r, g, b, a) |
2213 +--------------------+--------------+--------------------+--------------+
2214 | A | (0, 0, 0, a) | (0, 0, 0, a) | (0, 0, 0, a) |
2215 +--------------------+--------------+--------------------+--------------+
2216 | L | (l, l, l, 1) | (l, l, l, 1) | (l, l, l, 1) |
2217 +--------------------+--------------+--------------------+--------------+
2218 | LA | (l, l, l, a) | (l, l, l, a) | (l, l, l, a) |
2219 +--------------------+--------------+--------------------+--------------+
2220 | I | (i, i, i, i) | (i, i, i, i) | N/A |
2221 +--------------------+--------------+--------------------+--------------+
2222 | UV | XXX TBD | (0, 0, 0, 1) | (u, v, 1, 1) |
2223 | | | [#envmap-bumpmap]_ | |
2224 +--------------------+--------------+--------------------+--------------+
2225 | Z | XXX TBD | (z, z, z, 1) | (0, z, 0, 1) |
2226 | | | [#depth-tex-mode]_ | |
2227 +--------------------+--------------+--------------------+--------------+
2228 | S | (s, s, s, s) | unknown | unknown |
2229 +--------------------+--------------+--------------------+--------------+
2231 .. [#envmap-bumpmap] http://www.opengl.org/registry/specs/ATI/envmap_bumpmap.txt
2232 .. [#depth-tex-mode] the default is (z, z, z, 1) but may also be (0, 0, 0, z)
2233 or (z, z, z, z) depending on the value of GL_DEPTH_TEXTURE_MODE.