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 From GL_NV_vertex_program
13 ^^^^^^^^^^^^^^^^^^^^^^^^^
16 .. opcode:: ARL - Address Register Load
20 dst.x = \lfloor src.x\rfloor
22 dst.y = \lfloor src.y\rfloor
24 dst.z = \lfloor src.z\rfloor
26 dst.w = \lfloor src.w\rfloor
29 .. opcode:: MOV - Move
42 .. opcode:: LIT - Light Coefficients
50 dst.z = (src.x > 0) ? max(src.y, 0)^{clamp(src.w, -128, 128))} : 0
55 .. opcode:: RCP - Reciprocal
59 dst.x = \frac{1}{src.x}
61 dst.y = \frac{1}{src.x}
63 dst.z = \frac{1}{src.x}
65 dst.w = \frac{1}{src.x}
68 .. opcode:: RSQ - Reciprocal Square Root
72 dst.x = \frac{1}{\sqrt{|src.x|}}
74 dst.y = \frac{1}{\sqrt{|src.x|}}
76 dst.z = \frac{1}{\sqrt{|src.x|}}
78 dst.w = \frac{1}{\sqrt{|src.x|}}
81 .. opcode:: EXP - Approximate Exponential Base 2
85 dst.x = 2^{\lfloor src.x\rfloor}
87 dst.y = src.x - \lfloor src.x\rfloor
94 .. opcode:: LOG - Approximate Logarithm Base 2
98 dst.x = \lfloor\log_2{|src.x|}\rfloor
100 dst.y = \frac{|src.x|}{2^{\lfloor\log_2{|src.x|}\rfloor}}
102 dst.z = \log_2{|src.x|}
107 .. opcode:: MUL - Multiply
111 dst.x = src0.x \times src1.x
113 dst.y = src0.y \times src1.y
115 dst.z = src0.z \times src1.z
117 dst.w = src0.w \times src1.w
120 .. opcode:: ADD - Add
124 dst.x = src0.x + src1.x
126 dst.y = src0.y + src1.y
128 dst.z = src0.z + src1.z
130 dst.w = src0.w + src1.w
133 .. opcode:: DP3 - 3-component Dot Product
137 dst.x = src0.x \times src1.x + src0.y \times src1.y + src0.z \times src1.z
139 dst.y = src0.x \times src1.x + src0.y \times src1.y + src0.z \times src1.z
141 dst.z = src0.x \times src1.x + src0.y \times src1.y + src0.z \times src1.z
143 dst.w = src0.x \times src1.x + src0.y \times src1.y + src0.z \times src1.z
146 .. opcode:: DP4 - 4-component Dot Product
150 dst.x = src0.x \times src1.x + src0.y \times src1.y + src0.z \times src1.z + src0.w \times src1.w
152 dst.y = src0.x \times src1.x + src0.y \times src1.y + src0.z \times src1.z + src0.w \times src1.w
154 dst.z = src0.x \times src1.x + src0.y \times src1.y + src0.z \times src1.z + src0.w \times src1.w
156 dst.w = src0.x \times src1.x + src0.y \times src1.y + src0.z \times src1.z + src0.w \times src1.w
159 .. opcode:: DST - Distance Vector
165 dst.y = src0.y \times src1.y
172 .. opcode:: MIN - Minimum
176 dst.x = min(src0.x, src1.x)
178 dst.y = min(src0.y, src1.y)
180 dst.z = min(src0.z, src1.z)
182 dst.w = min(src0.w, src1.w)
185 .. opcode:: MAX - Maximum
189 dst.x = max(src0.x, src1.x)
191 dst.y = max(src0.y, src1.y)
193 dst.z = max(src0.z, src1.z)
195 dst.w = max(src0.w, src1.w)
198 .. opcode:: SLT - Set On Less Than
202 dst.x = (src0.x < src1.x) ? 1 : 0
204 dst.y = (src0.y < src1.y) ? 1 : 0
206 dst.z = (src0.z < src1.z) ? 1 : 0
208 dst.w = (src0.w < src1.w) ? 1 : 0
211 .. opcode:: SGE - Set On Greater Equal Than
215 dst.x = (src0.x >= src1.x) ? 1 : 0
217 dst.y = (src0.y >= src1.y) ? 1 : 0
219 dst.z = (src0.z >= src1.z) ? 1 : 0
221 dst.w = (src0.w >= src1.w) ? 1 : 0
224 .. opcode:: MAD - Multiply And Add
228 dst.x = src0.x \times src1.x + src2.x
230 dst.y = src0.y \times src1.y + src2.y
232 dst.z = src0.z \times src1.z + src2.z
234 dst.w = src0.w \times src1.w + src2.w
237 .. opcode:: SUB - Subtract
241 dst.x = src0.x - src1.x
243 dst.y = src0.y - src1.y
245 dst.z = src0.z - src1.z
247 dst.w = src0.w - src1.w
250 .. opcode:: LRP - Linear Interpolate
254 dst.x = src0.x \times src1.x + (1 - src0.x) \times src2.x
256 dst.y = src0.y \times src1.y + (1 - src0.y) \times src2.y
258 dst.z = src0.z \times src1.z + (1 - src0.z) \times src2.z
260 dst.w = src0.w \times src1.w + (1 - src0.w) \times src2.w
263 .. opcode:: CND - Condition
267 dst.x = (src2.x > 0.5) ? src0.x : src1.x
269 dst.y = (src2.y > 0.5) ? src0.y : src1.y
271 dst.z = (src2.z > 0.5) ? src0.z : src1.z
273 dst.w = (src2.w > 0.5) ? src0.w : src1.w
276 .. opcode:: DP2A - 2-component Dot Product And Add
280 dst.x = src0.x \times src1.x + src0.y \times src1.y + src2.x
282 dst.y = src0.x \times src1.x + src0.y \times src1.y + src2.x
284 dst.z = src0.x \times src1.x + src0.y \times src1.y + src2.x
286 dst.w = src0.x \times src1.x + src0.y \times src1.y + src2.x
289 .. opcode:: FRAC - Fraction
293 dst.x = src.x - \lfloor src.x\rfloor
295 dst.y = src.y - \lfloor src.y\rfloor
297 dst.z = src.z - \lfloor src.z\rfloor
299 dst.w = src.w - \lfloor src.w\rfloor
302 .. opcode:: CLAMP - Clamp
306 dst.x = clamp(src0.x, src1.x, src2.x)
308 dst.y = clamp(src0.y, src1.y, src2.y)
310 dst.z = clamp(src0.z, src1.z, src2.z)
312 dst.w = clamp(src0.w, src1.w, src2.w)
315 .. opcode:: FLR - Floor
317 This is identical to ARL.
321 dst.x = \lfloor src.x\rfloor
323 dst.y = \lfloor src.y\rfloor
325 dst.z = \lfloor src.z\rfloor
327 dst.w = \lfloor src.w\rfloor
330 .. opcode:: ROUND - Round
343 .. opcode:: EX2 - Exponential Base 2
356 .. opcode:: LG2 - Logarithm Base 2
360 dst.x = \log_2{src.x}
362 dst.y = \log_2{src.x}
364 dst.z = \log_2{src.x}
366 dst.w = \log_2{src.x}
369 .. opcode:: POW - Power
373 dst.x = src0.x^{src1.x}
375 dst.y = src0.x^{src1.x}
377 dst.z = src0.x^{src1.x}
379 dst.w = src0.x^{src1.x}
381 .. opcode:: XPD - Cross Product
385 dst.x = src0.y \times src1.z - src1.y \times src0.z
387 dst.y = src0.z \times src1.x - src1.z \times src0.x
389 dst.z = src0.x \times src1.y - src1.x \times src0.y
394 .. opcode:: ABS - Absolute
407 .. opcode:: RCC - Reciprocal Clamped
409 XXX cleanup on aisle three
413 dst.x = (1 / src.x) > 0 ? clamp(1 / src.x, 5.42101e-020, 1.884467e+019) : clamp(1 / src.x, -1.884467e+019, -5.42101e-020)
415 dst.y = (1 / src.x) > 0 ? clamp(1 / src.x, 5.42101e-020, 1.884467e+019) : clamp(1 / src.x, -1.884467e+019, -5.42101e-020)
417 dst.z = (1 / src.x) > 0 ? clamp(1 / src.x, 5.42101e-020, 1.884467e+019) : clamp(1 / src.x, -1.884467e+019, -5.42101e-020)
419 dst.w = (1 / src.x) > 0 ? clamp(1 / src.x, 5.42101e-020, 1.884467e+019) : clamp(1 / src.x, -1.884467e+019, -5.42101e-020)
422 .. opcode:: DPH - Homogeneous Dot Product
426 dst.x = src0.x \times src1.x + src0.y \times src1.y + src0.z \times src1.z + src1.w
428 dst.y = src0.x \times src1.x + src0.y \times src1.y + src0.z \times src1.z + src1.w
430 dst.z = src0.x \times src1.x + src0.y \times src1.y + src0.z \times src1.z + src1.w
432 dst.w = src0.x \times src1.x + src0.y \times src1.y + src0.z \times src1.z + src1.w
435 .. opcode:: COS - Cosine
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
511 Considered for removal.
514 .. opcode:: SEQ - Set On Equal
518 dst.x = (src0.x == src1.x) ? 1 : 0
520 dst.y = (src0.y == src1.y) ? 1 : 0
522 dst.z = (src0.z == src1.z) ? 1 : 0
524 dst.w = (src0.w == src1.w) ? 1 : 0
527 .. opcode:: SFL - Set On False
539 Considered for removal.
541 .. opcode:: SGT - Set On Greater Than
545 dst.x = (src0.x > src1.x) ? 1 : 0
547 dst.y = (src0.y > src1.y) ? 1 : 0
549 dst.z = (src0.z > src1.z) ? 1 : 0
551 dst.w = (src0.w > src1.w) ? 1 : 0
554 .. opcode:: SIN - Sine
567 .. opcode:: SLE - Set On Less Equal Than
571 dst.x = (src0.x <= src1.x) ? 1 : 0
573 dst.y = (src0.y <= src1.y) ? 1 : 0
575 dst.z = (src0.z <= src1.z) ? 1 : 0
577 dst.w = (src0.w <= src1.w) ? 1 : 0
580 .. opcode:: SNE - Set On Not Equal
584 dst.x = (src0.x != src1.x) ? 1 : 0
586 dst.y = (src0.y != src1.y) ? 1 : 0
588 dst.z = (src0.z != src1.z) ? 1 : 0
590 dst.w = (src0.w != src1.w) ? 1 : 0
593 .. opcode:: STR - Set On True
606 .. opcode:: TEX - Texture Lookup
611 .. opcode:: TXD - Texture Lookup with Derivatives
616 .. opcode:: TXP - Projective Texture Lookup
621 .. opcode:: UP2H - Unpack Two 16-Bit Floats
625 Considered for removal.
627 .. opcode:: UP2US - Unpack Two Unsigned 16-Bit Scalars
631 Considered for removal.
633 .. opcode:: UP4B - Unpack Four Signed 8-Bit Values
637 Considered for removal.
639 .. opcode:: UP4UB - Unpack Four Unsigned 8-Bit Scalars
643 Considered for removal.
645 .. opcode:: X2D - 2D Coordinate Transformation
649 dst.x = src0.x + src1.x \times src2.x + src1.y \times src2.y
651 dst.y = src0.y + src1.x \times src2.z + src1.y \times src2.w
653 dst.z = src0.x + src1.x \times src2.x + src1.y \times src2.y
655 dst.w = src0.y + src1.x \times src2.z + src1.y \times src2.w
657 Considered for removal.
660 From GL_NV_vertex_program2
661 ^^^^^^^^^^^^^^^^^^^^^^^^^^
664 .. opcode:: ARA - Address Register Add
668 Considered for removal.
670 .. opcode:: ARR - Address Register Load With Round
683 .. opcode:: BRA - Branch
687 Considered for removal.
689 .. opcode:: CAL - Subroutine Call
695 .. opcode:: RET - Subroutine Call Return
699 Potential restrictions:
700 * Only occurs at end of function.
702 .. opcode:: SSG - Set Sign
706 dst.x = (src.x > 0) ? 1 : (src.x < 0) ? -1 : 0
708 dst.y = (src.y > 0) ? 1 : (src.y < 0) ? -1 : 0
710 dst.z = (src.z > 0) ? 1 : (src.z < 0) ? -1 : 0
712 dst.w = (src.w > 0) ? 1 : (src.w < 0) ? -1 : 0
715 .. opcode:: CMP - Compare
719 dst.x = (src0.x < 0) ? src1.x : src2.x
721 dst.y = (src0.y < 0) ? src1.y : src2.y
723 dst.z = (src0.z < 0) ? src1.z : src2.z
725 dst.w = (src0.w < 0) ? src1.w : src2.w
728 .. opcode:: KIL - Conditional Discard
732 if (src.x < 0 || src.y < 0 || src.z < 0 || src.w < 0)
737 .. opcode:: SCS - Sine Cosine
750 .. opcode:: TXB - Texture Lookup With Bias
755 .. opcode:: NRM - 3-component Vector Normalise
759 dst.x = src.x / (src.x \times src.x + src.y \times src.y + src.z \times src.z)
761 dst.y = src.y / (src.x \times src.x + src.y \times src.y + src.z \times src.z)
763 dst.z = src.z / (src.x \times src.x + src.y \times src.y + src.z \times src.z)
768 .. opcode:: DIV - Divide
772 dst.x = \frac{src0.x}{src1.x}
774 dst.y = \frac{src0.y}{src1.y}
776 dst.z = \frac{src0.z}{src1.z}
778 dst.w = \frac{src0.w}{src1.w}
781 .. opcode:: DP2 - 2-component Dot Product
785 dst.x = src0.x \times src1.x + src0.y \times src1.y
787 dst.y = src0.x \times src1.x + src0.y \times src1.y
789 dst.z = src0.x \times src1.x + src0.y \times src1.y
791 dst.w = src0.x \times src1.x + src0.y \times src1.y
794 .. opcode:: TXL - Texture Lookup With LOD
799 .. opcode:: BRK - Break
809 .. opcode:: BGNFOR - Begin a For-Loop
816 pc = [matching ENDFOR] + 1
819 Note: The destination must be a loop register.
820 The source must be a constant register.
822 Considered for cleanup / removal.
825 .. opcode:: REP - Repeat
830 .. opcode:: ELSE - Else
835 .. opcode:: ENDIF - End If
840 .. opcode:: ENDFOR - End a For-Loop
842 dst.x = dst.x + dst.z
846 pc = [matching BGNFOR instruction] + 1
849 Note: The destination must be a loop register.
851 Considered for cleanup / removal.
853 .. opcode:: ENDREP - End Repeat
858 .. opcode:: PUSHA - Push Address Register On Stack
865 Considered for cleanup / removal.
867 .. opcode:: POPA - Pop Address Register From Stack
874 Considered for cleanup / removal.
877 From GL_NV_gpu_program4
878 ^^^^^^^^^^^^^^^^^^^^^^^^
880 Support for these opcodes indicated by a special pipe capability bit (TBD).
882 .. opcode:: CEIL - Ceiling
886 dst.x = \lceil src.x\rceil
888 dst.y = \lceil src.y\rceil
890 dst.z = \lceil src.z\rceil
892 dst.w = \lceil src.w\rceil
895 .. opcode:: I2F - Integer To Float
899 dst.x = (float) src.x
901 dst.y = (float) src.y
903 dst.z = (float) src.z
905 dst.w = (float) src.w
908 .. opcode:: NOT - Bitwise Not
921 .. opcode:: TRUNC - Truncate
934 .. opcode:: SHL - Shift Left
938 dst.x = src0.x << src1.x
940 dst.y = src0.y << src1.x
942 dst.z = src0.z << src1.x
944 dst.w = src0.w << src1.x
947 .. opcode:: SHR - Shift Right
951 dst.x = src0.x >> src1.x
953 dst.y = src0.y >> src1.x
955 dst.z = src0.z >> src1.x
957 dst.w = src0.w >> src1.x
960 .. opcode:: AND - Bitwise And
964 dst.x = src0.x & src1.x
966 dst.y = src0.y & src1.y
968 dst.z = src0.z & src1.z
970 dst.w = src0.w & src1.w
973 .. opcode:: OR - Bitwise Or
977 dst.x = src0.x | src1.x
979 dst.y = src0.y | src1.y
981 dst.z = src0.z | src1.z
983 dst.w = src0.w | src1.w
986 .. opcode:: MOD - Modulus
990 dst.x = src0.x \bmod src1.x
992 dst.y = src0.y \bmod src1.y
994 dst.z = src0.z \bmod src1.z
996 dst.w = src0.w \bmod src1.w
999 .. opcode:: XOR - Bitwise Xor
1003 dst.x = src0.x \oplus src1.x
1005 dst.y = src0.y \oplus src1.y
1007 dst.z = src0.z \oplus src1.z
1009 dst.w = src0.w \oplus src1.w
1012 .. opcode:: SAD - Sum Of Absolute Differences
1016 dst.x = |src0.x - src1.x| + src2.x
1018 dst.y = |src0.y - src1.y| + src2.y
1020 dst.z = |src0.z - src1.z| + src2.z
1022 dst.w = |src0.w - src1.w| + src2.w
1025 .. opcode:: TXF - Texel Fetch
1030 .. opcode:: TXQ - Texture Size Query
1035 .. opcode:: CONT - Continue
1040 From GL_NV_geometry_program4
1041 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1044 .. opcode:: EMIT - Emit
1049 .. opcode:: ENDPRIM - End Primitive
1058 .. opcode:: BGNLOOP - Begin a Loop
1063 .. opcode:: BGNSUB - Begin Subroutine
1068 .. opcode:: ENDLOOP - End a Loop
1073 .. opcode:: ENDSUB - End Subroutine
1078 .. opcode:: NOP - No Operation
1083 .. opcode:: NRM4 - 4-component Vector Normalise
1087 dst.x = \frac{src.x}{src.x \times src.x + src.y \times src.y + src.z \times src.z + src.w \times src.w}
1089 dst.y = \frac{src.y}{src.x \times src.x + src.y \times src.y + src.z \times src.z + src.w \times src.w}
1091 dst.z = \frac{src.z}{src.x \times src.x + src.y \times src.y + src.z \times src.z + src.w \times src.w}
1093 dst.w = \frac{src.w}{src.x \times src.x + src.y \times src.y + src.z \times src.z + src.w \times src.w}
1100 .. opcode:: CALLNZ - Subroutine Call If Not Zero
1105 .. opcode:: IFC - If
1110 .. opcode:: BREAKC - Break Conditional
1117 .. opcode:: DADD - Add Double
1121 dst.xy = src0.xy + src1.xy
1123 dst.zw = src0.zw + src1.zw
1126 .. opcode:: DDIV - Divide Double
1130 dst.xy = src0.xy / src1.xy
1132 dst.zw = src0.zw / src1.zw
1134 .. opcode:: DSEQ - Set Double on Equal
1138 dst.xy = src0.xy == src1.xy ? 1.0F : 0.0F
1140 dst.zw = src0.zw == src1.zw ? 1.0F : 0.0F
1142 .. opcode:: DSLT - Set Double on Less than
1146 dst.xy = src0.xy < src1.xy ? 1.0F : 0.0F
1148 dst.zw = src0.zw < src1.zw ? 1.0F : 0.0F
1150 .. opcode:: DFRAC - Double Fraction
1154 dst.xy = src.xy - \lfloor src.xy\rfloor
1156 dst.zw = src.zw - \lfloor src.zw\rfloor
1159 .. opcode:: DFRACEXP - Convert Double Number to Fractional and Integral Components
1163 dst0.xy = frexp(src.xy, dst1.xy)
1165 dst0.zw = frexp(src.zw, dst1.zw)
1167 .. opcode:: DLDEXP - Multiple Double Number by Integral Power of 2
1171 dst.xy = ldexp(src0.xy, src1.xy)
1173 dst.zw = ldexp(src0.zw, src1.zw)
1175 .. opcode:: DMIN - Minimum Double
1179 dst.xy = min(src0.xy, src1.xy)
1181 dst.zw = min(src0.zw, src1.zw)
1183 .. opcode:: DMAX - Maximum Double
1187 dst.xy = max(src0.xy, src1.xy)
1189 dst.zw = max(src0.zw, src1.zw)
1191 .. opcode:: DMUL - Multiply Double
1195 dst.xy = src0.xy \times src1.xy
1197 dst.zw = src0.zw \times src1.zw
1200 .. opcode:: DMAD - Multiply And Add Doubles
1204 dst.xy = src0.xy \times src1.xy + src2.xy
1206 dst.zw = src0.zw \times src1.zw + src2.zw
1209 .. opcode:: DRCP - Reciprocal Double
1213 dst.xy = \frac{1}{src.xy}
1215 dst.zw = \frac{1}{src.zw}
1217 .. opcode:: DSQRT - Square root double
1221 dst.xy = \sqrt{src.xy}
1223 dst.zw = \sqrt{src.zw}
1226 Explanation of symbols used
1227 ------------------------------
1234 :math:`|x|` Absolute value of `x`.
1236 :math:`\lceil x \rceil` Ceiling of `x`.
1238 clamp(x,y,z) Clamp x between y and z.
1239 (x < y) ? y : (x > z) ? z : x
1241 :math:`\lfloor x\rfloor` Floor of `x`.
1243 :math:`\log_2{x}` Logarithm of `x`, base 2.
1245 max(x,y) Maximum of x and y.
1248 min(x,y) Minimum of x and y.
1251 partialx(x) Derivative of x relative to fragment's X.
1253 partialy(x) Derivative of x relative to fragment's Y.
1255 pop() Pop from stack.
1257 :math:`x^y` `x` to the power `y`.
1259 push(x) Push x on stack.
1263 trunc(x) Truncate x, i.e. drop the fraction bits.
1270 discard Discard fragment.
1272 dst First destination register.
1274 dst0 First destination register.
1278 src First source register.
1280 src0 First source register.
1282 src1 Second source register.
1284 src2 Third source register.
1286 target Label of target instruction.
1293 Declaration Semantic
1294 ^^^^^^^^^^^^^^^^^^^^^^^^
1297 Follows Declaration token if Semantic bit is set.
1299 Since its purpose is to link a shader with other stages of the pipeline,
1300 it is valid to follow only those Declaration tokens that declare a register
1301 either in INPUT or OUTPUT file.
1303 SemanticName field contains the semantic name of the register being declared.
1304 There is no default value.
1306 SemanticIndex is an optional subscript that can be used to distinguish
1307 different register declarations with the same semantic name. The default value
1310 The meanings of the individual semantic names are explained in the following
1313 TGSI_SEMANTIC_POSITION
1314 """"""""""""""""""""""
1316 Position, sometimes known as HPOS or WPOS for historical reasons, is the
1317 location of the vertex in space, in ``(x, y, z, w)`` format. ``x``, ``y``, and ``z``
1318 are the Cartesian coordinates, and ``w`` is the homogenous coordinate and used
1319 for the perspective divide, if enabled.
1321 As a vertex shader output, position should be scaled to the viewport. When
1322 used in fragment shaders, position will be in window coordinates. The convention
1323 used depends on the FS_COORD_ORIGIN and FS_COORD_PIXEL_CENTER properties.
1325 XXX additionally, is there a way to configure the perspective divide? it's
1326 accelerated on most chipsets AFAIK...
1328 Position, if not specified, usually defaults to ``(0, 0, 0, 1)``, and can
1329 be partially specified as ``(x, y, 0, 1)`` or ``(x, y, z, 1)``.
1331 XXX usually? can we solidify that?
1336 Colors are used to, well, color the primitives. Colors are always in
1337 ``(r, g, b, a)`` format.
1339 If alpha is not specified, it defaults to 1.
1341 TGSI_SEMANTIC_BCOLOR
1342 """"""""""""""""""""
1344 Back-facing colors are only used for back-facing polygons, and are only valid
1345 in vertex shader outputs. After rasterization, all polygons are front-facing
1346 and COLOR and BCOLOR end up occupying the same slots in the fragment, so
1347 all BCOLORs effectively become regular COLORs in the fragment shader.
1352 The fog coordinate historically has been used to replace the depth coordinate
1353 for generation of fog in dedicated fog blocks. Gallium, however, does not use
1354 dedicated fog acceleration, placing it entirely in the fragment shader
1357 The fog coordinate should be written in ``(f, 0, 0, 1)`` format. Only the first
1358 component matters when writing from the vertex shader; the driver will ensure
1359 that the coordinate is in this format when used as a fragment shader input.
1364 PSIZE, or point size, is used to specify point sizes per-vertex. It should
1365 be in ``(p, n, x, f)`` format, where ``p`` is the point size, ``n`` is the minimum
1366 size, ``x`` is the maximum size, and ``f`` is the fade threshold.
1368 XXX this is arb_vp. is this what we actually do? should double-check...
1370 When using this semantic, be sure to set the appropriate state in the
1371 :ref:`rasterizer` first.
1373 TGSI_SEMANTIC_GENERIC
1374 """""""""""""""""""""
1376 Generic semantics are nearly always used for texture coordinate attributes,
1377 in ``(s, t, r, q)`` format. ``t`` and ``r`` may be unused for certain kinds
1378 of lookups, and ``q`` is the level-of-detail bias for biased sampling.
1380 These attributes are called "generic" because they may be used for anything
1381 else, including parameters, texture generation information, or anything that
1382 can be stored inside a four-component vector.
1384 TGSI_SEMANTIC_NORMAL
1385 """"""""""""""""""""
1387 Vertex normal; could be used to implement per-pixel lighting for legacy APIs
1388 that allow mixing fixed-function and programmable stages.
1393 FACE is the facing bit, to store the facing information for the fragment
1394 shader. ``(f, 0, 0, 1)`` is the format. The first component will be positive
1395 when the fragment is front-facing, and negative when the component is
1398 TGSI_SEMANTIC_EDGEFLAG
1399 """"""""""""""""""""""
1405 ^^^^^^^^^^^^^^^^^^^^^^^^
1408 Properties are general directives that apply to the whole TGSI program.
1413 Specifies the fragment shader TGSI_SEMANTIC_POSITION coordinate origin.
1414 The default value is UPPER_LEFT.
1416 If UPPER_LEFT, the position will be (0,0) at the upper left corner and
1417 increase downward and rightward.
1418 If LOWER_LEFT, the position will be (0,0) at the lower left corner and
1419 increase upward and rightward.
1421 OpenGL defaults to LOWER_LEFT, and is configurable with the
1422 GL_ARB_fragment_coord_conventions extension.
1424 DirectX 9/10 use UPPER_LEFT.
1426 FS_COORD_PIXEL_CENTER
1427 """""""""""""""""""""
1429 Specifies the fragment shader TGSI_SEMANTIC_POSITION pixel center convention.
1430 The default value is HALF_INTEGER.
1432 If HALF_INTEGER, the fractionary part of the position will be 0.5
1433 If INTEGER, the fractionary part of the position will be 0.0
1435 Note that this does not affect the set of fragments generated by
1436 rasterization, which is instead controlled by gl_rasterization_rules in the
1439 OpenGL defaults to HALF_INTEGER, and is configurable with the
1440 GL_ARB_fragment_coord_conventions extension.
1442 DirectX 9 uses INTEGER.
1443 DirectX 10 uses HALF_INTEGER.
1447 Texture Sampling and Texture Formats
1448 ------------------------------------
1450 This table shows how texture image components are returned as (x,y,z,w)
1451 tuples by TGSI texture instructions, such as TEX, TXD, and TXP.
1452 For reference, OpenGL and Direct3D conventions are shown as well.
1454 +--------------------+--------------+--------------------+--------------+
1455 | Texture Components | Gallium | OpenGL | Direct3D 9 |
1456 +====================+==============+====================+==============+
1457 | R | XXX TBD | (r, 0, 0, 1) | (r, 1, 1, 1) |
1458 +--------------------+--------------+--------------------+--------------+
1459 | RG | XXX TBD | (r, g, 0, 1) | (r, g, 1, 1) |
1460 +--------------------+--------------+--------------------+--------------+
1461 | RGB | (r, g, b, 1) | (r, g, b, 1) | (r, g, b, 1) |
1462 +--------------------+--------------+--------------------+--------------+
1463 | RGBA | (r, g, b, a) | (r, g, b, a) | (r, g, b, a) |
1464 +--------------------+--------------+--------------------+--------------+
1465 | A | (0, 0, 0, a) | (0, 0, 0, a) | (0, 0, 0, a) |
1466 +--------------------+--------------+--------------------+--------------+
1467 | L | (l, l, l, 1) | (l, l, l, 1) | (l, l, l, 1) |
1468 +--------------------+--------------+--------------------+--------------+
1469 | LA | (l, l, l, a) | (l, l, l, a) | (l, l, l, a) |
1470 +--------------------+--------------+--------------------+--------------+
1471 | I | (i, i, i, i) | (i, i, i, i) | N/A |
1472 +--------------------+--------------+--------------------+--------------+
1473 | UV | XXX TBD | (0, 0, 0, 1) | (u, v, 1, 1) |
1474 | | | [#envmap-bumpmap]_ | |
1475 +--------------------+--------------+--------------------+--------------+
1476 | Z | XXX TBD | (z, z, z, 1) | (0, z, 0, 1) |
1477 | | | [#depth-tex-mode]_ | |
1478 +--------------------+--------------+--------------------+--------------+
1480 .. [#envmap-bumpmap] http://www.opengl.org/registry/specs/ATI/envmap_bumpmap.txt
1481 .. [#depth-tex-mode] the default is (z, z, z, 1) but may also be (0, 0, 0, z)
1482 or (z, z, z, z) depending on the value of GL_DEPTH_TEXTURE_MODE.