gallium: create TGSI_PROPERTY to disable viewport and clipping
[mesa.git] / src / gallium / docs / source / tgsi.rst
1 TGSI
2 ====
3
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
7 used by all drivers.
8
9 Basics
10 ------
11
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
16 one.
17
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:`doubleopcodes`.
21
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.
25
26 Modifiers
27 ^^^^^^^^^^^^^^^
28
29 TGSI supports modifiers on inputs (as well as saturate modifier on instructions).
30
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.
34
35 For inputs which have signed or unsigned type only the negate modifier is
36 supported.
37
38 Instruction Set
39 ---------------
40
41 Core ISA
42 ^^^^^^^^^^^^^^^^^^^^^^^^^
43
44 These opcodes are guaranteed to be available regardless of the driver being
45 used.
46
47 .. opcode:: ARL - Address Register Load
48
49 .. math::
50
51 dst.x = \lfloor src.x\rfloor
52
53 dst.y = \lfloor src.y\rfloor
54
55 dst.z = \lfloor src.z\rfloor
56
57 dst.w = \lfloor src.w\rfloor
58
59
60 .. opcode:: MOV - Move
61
62 .. math::
63
64 dst.x = src.x
65
66 dst.y = src.y
67
68 dst.z = src.z
69
70 dst.w = src.w
71
72
73 .. opcode:: LIT - Light Coefficients
74
75 .. math::
76
77 dst.x &= 1 \\
78 dst.y &= max(src.x, 0) \\
79 dst.z &= (src.x > 0) ? max(src.y, 0)^{clamp(src.w, -128, 128))} : 0 \\
80 dst.w &= 1
81
82
83 .. opcode:: RCP - Reciprocal
84
85 This instruction replicates its result.
86
87 .. math::
88
89 dst = \frac{1}{src.x}
90
91
92 .. opcode:: RSQ - Reciprocal Square Root
93
94 This instruction replicates its result. The results are undefined for src <= 0.
95
96 .. math::
97
98 dst = \frac{1}{\sqrt{src.x}}
99
100
101 .. opcode:: SQRT - Square Root
102
103 This instruction replicates its result. The results are undefined for src < 0.
104
105 .. math::
106
107 dst = {\sqrt{src.x}}
108
109
110 .. opcode:: EXP - Approximate Exponential Base 2
111
112 .. math::
113
114 dst.x &= 2^{\lfloor src.x\rfloor} \\
115 dst.y &= src.x - \lfloor src.x\rfloor \\
116 dst.z &= 2^{src.x} \\
117 dst.w &= 1
118
119
120 .. opcode:: LOG - Approximate Logarithm Base 2
121
122 .. math::
123
124 dst.x &= \lfloor\log_2{|src.x|}\rfloor \\
125 dst.y &= \frac{|src.x|}{2^{\lfloor\log_2{|src.x|}\rfloor}} \\
126 dst.z &= \log_2{|src.x|} \\
127 dst.w &= 1
128
129
130 .. opcode:: MUL - Multiply
131
132 .. math::
133
134 dst.x = src0.x \times src1.x
135
136 dst.y = src0.y \times src1.y
137
138 dst.z = src0.z \times src1.z
139
140 dst.w = src0.w \times src1.w
141
142
143 .. opcode:: ADD - Add
144
145 .. math::
146
147 dst.x = src0.x + src1.x
148
149 dst.y = src0.y + src1.y
150
151 dst.z = src0.z + src1.z
152
153 dst.w = src0.w + src1.w
154
155
156 .. opcode:: DP3 - 3-component Dot Product
157
158 This instruction replicates its result.
159
160 .. math::
161
162 dst = src0.x \times src1.x + src0.y \times src1.y + src0.z \times src1.z
163
164
165 .. opcode:: DP4 - 4-component Dot Product
166
167 This instruction replicates its result.
168
169 .. math::
170
171 dst = src0.x \times src1.x + src0.y \times src1.y + src0.z \times src1.z + src0.w \times src1.w
172
173
174 .. opcode:: DST - Distance Vector
175
176 .. math::
177
178 dst.x &= 1\\
179 dst.y &= src0.y \times src1.y\\
180 dst.z &= src0.z\\
181 dst.w &= src1.w
182
183
184 .. opcode:: MIN - Minimum
185
186 .. math::
187
188 dst.x = min(src0.x, src1.x)
189
190 dst.y = min(src0.y, src1.y)
191
192 dst.z = min(src0.z, src1.z)
193
194 dst.w = min(src0.w, src1.w)
195
196
197 .. opcode:: MAX - Maximum
198
199 .. math::
200
201 dst.x = max(src0.x, src1.x)
202
203 dst.y = max(src0.y, src1.y)
204
205 dst.z = max(src0.z, src1.z)
206
207 dst.w = max(src0.w, src1.w)
208
209
210 .. opcode:: SLT - Set On Less Than
211
212 .. math::
213
214 dst.x = (src0.x < src1.x) ? 1.0F : 0.0F
215
216 dst.y = (src0.y < src1.y) ? 1.0F : 0.0F
217
218 dst.z = (src0.z < src1.z) ? 1.0F : 0.0F
219
220 dst.w = (src0.w < src1.w) ? 1.0F : 0.0F
221
222
223 .. opcode:: SGE - Set On Greater Equal Than
224
225 .. math::
226
227 dst.x = (src0.x >= src1.x) ? 1.0F : 0.0F
228
229 dst.y = (src0.y >= src1.y) ? 1.0F : 0.0F
230
231 dst.z = (src0.z >= src1.z) ? 1.0F : 0.0F
232
233 dst.w = (src0.w >= src1.w) ? 1.0F : 0.0F
234
235
236 .. opcode:: MAD - Multiply And Add
237
238 .. math::
239
240 dst.x = src0.x \times src1.x + src2.x
241
242 dst.y = src0.y \times src1.y + src2.y
243
244 dst.z = src0.z \times src1.z + src2.z
245
246 dst.w = src0.w \times src1.w + src2.w
247
248
249 .. opcode:: SUB - Subtract
250
251 .. math::
252
253 dst.x = src0.x - src1.x
254
255 dst.y = src0.y - src1.y
256
257 dst.z = src0.z - src1.z
258
259 dst.w = src0.w - src1.w
260
261
262 .. opcode:: LRP - Linear Interpolate
263
264 .. math::
265
266 dst.x = src0.x \times src1.x + (1 - src0.x) \times src2.x
267
268 dst.y = src0.y \times src1.y + (1 - src0.y) \times src2.y
269
270 dst.z = src0.z \times src1.z + (1 - src0.z) \times src2.z
271
272 dst.w = src0.w \times src1.w + (1 - src0.w) \times src2.w
273
274
275 .. opcode:: CND - Condition
276
277 .. math::
278
279 dst.x = (src2.x > 0.5) ? src0.x : src1.x
280
281 dst.y = (src2.y > 0.5) ? src0.y : src1.y
282
283 dst.z = (src2.z > 0.5) ? src0.z : src1.z
284
285 dst.w = (src2.w > 0.5) ? src0.w : src1.w
286
287
288 .. opcode:: DP2A - 2-component Dot Product And Add
289
290 .. math::
291
292 dst.x = src0.x \times src1.x + src0.y \times src1.y + src2.x
293
294 dst.y = src0.x \times src1.x + src0.y \times src1.y + src2.x
295
296 dst.z = src0.x \times src1.x + src0.y \times src1.y + src2.x
297
298 dst.w = src0.x \times src1.x + src0.y \times src1.y + src2.x
299
300
301 .. opcode:: FRC - Fraction
302
303 .. math::
304
305 dst.x = src.x - \lfloor src.x\rfloor
306
307 dst.y = src.y - \lfloor src.y\rfloor
308
309 dst.z = src.z - \lfloor src.z\rfloor
310
311 dst.w = src.w - \lfloor src.w\rfloor
312
313
314 .. opcode:: CLAMP - Clamp
315
316 .. math::
317
318 dst.x = clamp(src0.x, src1.x, src2.x)
319
320 dst.y = clamp(src0.y, src1.y, src2.y)
321
322 dst.z = clamp(src0.z, src1.z, src2.z)
323
324 dst.w = clamp(src0.w, src1.w, src2.w)
325
326
327 .. opcode:: FLR - Floor
328
329 This is identical to :opcode:`ARL`.
330
331 .. math::
332
333 dst.x = \lfloor src.x\rfloor
334
335 dst.y = \lfloor src.y\rfloor
336
337 dst.z = \lfloor src.z\rfloor
338
339 dst.w = \lfloor src.w\rfloor
340
341
342 .. opcode:: ROUND - Round
343
344 .. math::
345
346 dst.x = round(src.x)
347
348 dst.y = round(src.y)
349
350 dst.z = round(src.z)
351
352 dst.w = round(src.w)
353
354
355 .. opcode:: EX2 - Exponential Base 2
356
357 This instruction replicates its result.
358
359 .. math::
360
361 dst = 2^{src.x}
362
363
364 .. opcode:: LG2 - Logarithm Base 2
365
366 This instruction replicates its result.
367
368 .. math::
369
370 dst = \log_2{src.x}
371
372
373 .. opcode:: POW - Power
374
375 This instruction replicates its result.
376
377 .. math::
378
379 dst = src0.x^{src1.x}
380
381 .. opcode:: XPD - Cross Product
382
383 .. math::
384
385 dst.x = src0.y \times src1.z - src1.y \times src0.z
386
387 dst.y = src0.z \times src1.x - src1.z \times src0.x
388
389 dst.z = src0.x \times src1.y - src1.x \times src0.y
390
391 dst.w = 1
392
393
394 .. opcode:: ABS - Absolute
395
396 .. math::
397
398 dst.x = |src.x|
399
400 dst.y = |src.y|
401
402 dst.z = |src.z|
403
404 dst.w = |src.w|
405
406
407 .. opcode:: RCC - Reciprocal Clamped
408
409 This instruction replicates its result.
410
411 XXX cleanup on aisle three
412
413 .. math::
414
415 dst = (1 / src.x) > 0 ? clamp(1 / src.x, 5.42101e-020, 1.84467e+019) : clamp(1 / src.x, -1.84467e+019, -5.42101e-020)
416
417
418 .. opcode:: DPH - Homogeneous Dot Product
419
420 This instruction replicates its result.
421
422 .. math::
423
424 dst = src0.x \times src1.x + src0.y \times src1.y + src0.z \times src1.z + src1.w
425
426
427 .. opcode:: COS - Cosine
428
429 This instruction replicates its result.
430
431 .. math::
432
433 dst = \cos{src.x}
434
435
436 .. opcode:: DDX - Derivative Relative To X
437
438 .. math::
439
440 dst.x = partialx(src.x)
441
442 dst.y = partialx(src.y)
443
444 dst.z = partialx(src.z)
445
446 dst.w = partialx(src.w)
447
448
449 .. opcode:: DDY - Derivative Relative To Y
450
451 .. math::
452
453 dst.x = partialy(src.x)
454
455 dst.y = partialy(src.y)
456
457 dst.z = partialy(src.z)
458
459 dst.w = partialy(src.w)
460
461
462 .. opcode:: PK2H - Pack Two 16-bit Floats
463
464 TBD
465
466
467 .. opcode:: PK2US - Pack Two Unsigned 16-bit Scalars
468
469 TBD
470
471
472 .. opcode:: PK4B - Pack Four Signed 8-bit Scalars
473
474 TBD
475
476
477 .. opcode:: PK4UB - Pack Four Unsigned 8-bit Scalars
478
479 TBD
480
481
482 .. opcode:: RFL - Reflection Vector
483
484 .. math::
485
486 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
487
488 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
489
490 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
491
492 dst.w = 1
493
494 .. note::
495
496 Considered for removal.
497
498
499 .. opcode:: SEQ - Set On Equal
500
501 .. math::
502
503 dst.x = (src0.x == src1.x) ? 1.0F : 0.0F
504
505 dst.y = (src0.y == src1.y) ? 1.0F : 0.0F
506
507 dst.z = (src0.z == src1.z) ? 1.0F : 0.0F
508
509 dst.w = (src0.w == src1.w) ? 1.0F : 0.0F
510
511
512 .. opcode:: SFL - Set On False
513
514 This instruction replicates its result.
515
516 .. math::
517
518 dst = 0.0F
519
520 .. note::
521
522 Considered for removal.
523
524
525 .. opcode:: SGT - Set On Greater Than
526
527 .. math::
528
529 dst.x = (src0.x > src1.x) ? 1.0F : 0.0F
530
531 dst.y = (src0.y > src1.y) ? 1.0F : 0.0F
532
533 dst.z = (src0.z > src1.z) ? 1.0F : 0.0F
534
535 dst.w = (src0.w > src1.w) ? 1.0F : 0.0F
536
537
538 .. opcode:: SIN - Sine
539
540 This instruction replicates its result.
541
542 .. math::
543
544 dst = \sin{src.x}
545
546
547 .. opcode:: SLE - Set On Less Equal Than
548
549 .. math::
550
551 dst.x = (src0.x <= src1.x) ? 1.0F : 0.0F
552
553 dst.y = (src0.y <= src1.y) ? 1.0F : 0.0F
554
555 dst.z = (src0.z <= src1.z) ? 1.0F : 0.0F
556
557 dst.w = (src0.w <= src1.w) ? 1.0F : 0.0F
558
559
560 .. opcode:: SNE - Set On Not Equal
561
562 .. math::
563
564 dst.x = (src0.x != src1.x) ? 1.0F : 0.0F
565
566 dst.y = (src0.y != src1.y) ? 1.0F : 0.0F
567
568 dst.z = (src0.z != src1.z) ? 1.0F : 0.0F
569
570 dst.w = (src0.w != src1.w) ? 1.0F : 0.0F
571
572
573 .. opcode:: STR - Set On True
574
575 This instruction replicates its result.
576
577 .. math::
578
579 dst = 1.0F
580
581
582 .. opcode:: TEX - Texture Lookup
583
584 for array textures src0.y contains the slice for 1D,
585 and src0.z contain the slice for 2D.
586
587 for shadow textures with no arrays, src0.z contains
588 the reference value.
589
590 for shadow textures with arrays, src0.z contains
591 the reference value for 1D arrays, and src0.w contains
592 the reference value for 2D arrays.
593
594 There is no way to pass a bias in the .w value for
595 shadow arrays, and GLSL doesn't allow this.
596 GLSL does allow cube shadows maps to take a bias value,
597 and we have to determine how this will look in TGSI.
598
599 .. math::
600
601 coord = src0
602
603 bias = 0.0
604
605 dst = texture\_sample(unit, coord, bias)
606
607 .. opcode:: TXD - Texture Lookup with Derivatives
608
609 .. math::
610
611 coord = src0
612
613 ddx = src1
614
615 ddy = src2
616
617 bias = 0.0
618
619 dst = texture\_sample\_deriv(unit, coord, bias, ddx, ddy)
620
621
622 .. opcode:: TXP - Projective Texture Lookup
623
624 .. math::
625
626 coord.x = src0.x / src.w
627
628 coord.y = src0.y / src.w
629
630 coord.z = src0.z / src.w
631
632 coord.w = src0.w
633
634 bias = 0.0
635
636 dst = texture\_sample(unit, coord, bias)
637
638
639 .. opcode:: UP2H - Unpack Two 16-Bit Floats
640
641 TBD
642
643 .. note::
644
645 Considered for removal.
646
647 .. opcode:: UP2US - Unpack Two Unsigned 16-Bit Scalars
648
649 TBD
650
651 .. note::
652
653 Considered for removal.
654
655 .. opcode:: UP4B - Unpack Four Signed 8-Bit Values
656
657 TBD
658
659 .. note::
660
661 Considered for removal.
662
663 .. opcode:: UP4UB - Unpack Four Unsigned 8-Bit Scalars
664
665 TBD
666
667 .. note::
668
669 Considered for removal.
670
671 .. opcode:: X2D - 2D Coordinate Transformation
672
673 .. math::
674
675 dst.x = src0.x + src1.x \times src2.x + src1.y \times src2.y
676
677 dst.y = src0.y + src1.x \times src2.z + src1.y \times src2.w
678
679 dst.z = src0.x + src1.x \times src2.x + src1.y \times src2.y
680
681 dst.w = src0.y + src1.x \times src2.z + src1.y \times src2.w
682
683 .. note::
684
685 Considered for removal.
686
687
688 .. opcode:: ARA - Address Register Add
689
690 TBD
691
692 .. note::
693
694 Considered for removal.
695
696 .. opcode:: ARR - Address Register Load With Round
697
698 .. math::
699
700 dst.x = round(src.x)
701
702 dst.y = round(src.y)
703
704 dst.z = round(src.z)
705
706 dst.w = round(src.w)
707
708
709 .. opcode:: SSG - Set Sign
710
711 .. math::
712
713 dst.x = (src.x > 0) ? 1 : (src.x < 0) ? -1 : 0
714
715 dst.y = (src.y > 0) ? 1 : (src.y < 0) ? -1 : 0
716
717 dst.z = (src.z > 0) ? 1 : (src.z < 0) ? -1 : 0
718
719 dst.w = (src.w > 0) ? 1 : (src.w < 0) ? -1 : 0
720
721
722 .. opcode:: CMP - Compare
723
724 .. math::
725
726 dst.x = (src0.x < 0) ? src1.x : src2.x
727
728 dst.y = (src0.y < 0) ? src1.y : src2.y
729
730 dst.z = (src0.z < 0) ? src1.z : src2.z
731
732 dst.w = (src0.w < 0) ? src1.w : src2.w
733
734
735 .. opcode:: KILL_IF - Conditional Discard
736
737 Conditional discard. Allowed in fragment shaders only.
738
739 .. math::
740
741 if (src.x < 0 || src.y < 0 || src.z < 0 || src.w < 0)
742 discard
743 endif
744
745
746 .. opcode:: KILL - Discard
747
748 Unconditional discard. Allowed in fragment shaders only.
749
750
751 .. opcode:: SCS - Sine Cosine
752
753 .. math::
754
755 dst.x = \cos{src.x}
756
757 dst.y = \sin{src.x}
758
759 dst.z = 0
760
761 dst.w = 1
762
763
764 .. opcode:: TXB - Texture Lookup With Bias
765
766 .. math::
767
768 coord.x = src.x
769
770 coord.y = src.y
771
772 coord.z = src.z
773
774 coord.w = 1.0
775
776 bias = src.z
777
778 dst = texture\_sample(unit, coord, bias)
779
780
781 .. opcode:: NRM - 3-component Vector Normalise
782
783 .. math::
784
785 dst.x = src.x / (src.x \times src.x + src.y \times src.y + src.z \times src.z)
786
787 dst.y = src.y / (src.x \times src.x + src.y \times src.y + src.z \times src.z)
788
789 dst.z = src.z / (src.x \times src.x + src.y \times src.y + src.z \times src.z)
790
791 dst.w = 1
792
793
794 .. opcode:: DIV - Divide
795
796 .. math::
797
798 dst.x = \frac{src0.x}{src1.x}
799
800 dst.y = \frac{src0.y}{src1.y}
801
802 dst.z = \frac{src0.z}{src1.z}
803
804 dst.w = \frac{src0.w}{src1.w}
805
806
807 .. opcode:: DP2 - 2-component Dot Product
808
809 This instruction replicates its result.
810
811 .. math::
812
813 dst = src0.x \times src1.x + src0.y \times src1.y
814
815
816 .. opcode:: TXL - Texture Lookup With explicit LOD
817
818 .. math::
819
820 coord.x = src0.x
821
822 coord.y = src0.y
823
824 coord.z = src0.z
825
826 coord.w = 1.0
827
828 lod = src0.w
829
830 dst = texture\_sample(unit, coord, lod)
831
832
833 .. opcode:: PUSHA - Push Address Register On Stack
834
835 push(src.x)
836 push(src.y)
837 push(src.z)
838 push(src.w)
839
840 .. note::
841
842 Considered for cleanup.
843
844 .. note::
845
846 Considered for removal.
847
848 .. opcode:: POPA - Pop Address Register From Stack
849
850 dst.w = pop()
851 dst.z = pop()
852 dst.y = pop()
853 dst.x = pop()
854
855 .. note::
856
857 Considered for cleanup.
858
859 .. note::
860
861 Considered for removal.
862
863
864 .. opcode:: BRA - Branch
865
866 pc = target
867
868 .. note::
869
870 Considered for removal.
871
872
873 .. opcode:: CALLNZ - Subroutine Call If Not Zero
874
875 TBD
876
877 .. note::
878
879 Considered for cleanup.
880
881 .. note::
882
883 Considered for removal.
884
885
886 Compute ISA
887 ^^^^^^^^^^^^^^^^^^^^^^^^
888
889 These opcodes are primarily provided for special-use computational shaders.
890 Support for these opcodes indicated by a special pipe capability bit (TBD).
891
892 XXX doesn't look like most of the opcodes really belong here.
893
894 .. opcode:: CEIL - Ceiling
895
896 .. math::
897
898 dst.x = \lceil src.x\rceil
899
900 dst.y = \lceil src.y\rceil
901
902 dst.z = \lceil src.z\rceil
903
904 dst.w = \lceil src.w\rceil
905
906
907 .. opcode:: TRUNC - Truncate
908
909 .. math::
910
911 dst.x = trunc(src.x)
912
913 dst.y = trunc(src.y)
914
915 dst.z = trunc(src.z)
916
917 dst.w = trunc(src.w)
918
919
920 .. opcode:: MOD - Modulus
921
922 .. math::
923
924 dst.x = src0.x \bmod src1.x
925
926 dst.y = src0.y \bmod src1.y
927
928 dst.z = src0.z \bmod src1.z
929
930 dst.w = src0.w \bmod src1.w
931
932
933 .. opcode:: UARL - Integer Address Register Load
934
935 Moves the contents of the source register, assumed to be an integer, into the
936 destination register, which is assumed to be an address (ADDR) register.
937
938
939 .. opcode:: SAD - Sum Of Absolute Differences
940
941 .. math::
942
943 dst.x = |src0.x - src1.x| + src2.x
944
945 dst.y = |src0.y - src1.y| + src2.y
946
947 dst.z = |src0.z - src1.z| + src2.z
948
949 dst.w = |src0.w - src1.w| + src2.w
950
951
952 .. opcode:: TXF - Texel Fetch
953
954 As per NV_gpu_shader4, extract a single texel from a specified texture
955 image. The source sampler may not be a CUBE or SHADOW. src 0 is a
956 four-component signed integer vector used to identify the single texel
957 accessed. 3 components + level. src 1 is a 3 component constant signed
958 integer vector, with each component only have a range of -8..+8 (hw only
959 seems to deal with this range, interface allows for up to unsigned int).
960 TXF(uint_vec coord, int_vec offset).
961
962
963 .. opcode:: TXQ - Texture Size Query
964
965 As per NV_gpu_program4, retrieve the dimensions of the texture depending on
966 the target. For 1D (width), 2D/RECT/CUBE (width, height), 3D (width, height,
967 depth), 1D array (width, layers), 2D array (width, height, layers)
968
969 .. math::
970
971 lod = src0.x
972
973 dst.x = texture\_width(unit, lod)
974
975 dst.y = texture\_height(unit, lod)
976
977 dst.z = texture\_depth(unit, lod)
978
979 .. opcode:: TG4 - Texture Gather
980
981 As per ARB_texture_gather, gathers the four texels to be used in a bi-linear
982 filtering operation and packs them into a single register. Only works with
983 2D, 2D array, cubemaps, and cubemaps arrays. For 2D textures, only the
984 addressing modes of the sampler and the top level of any mip pyramid are
985 used. Set W to zero. It behaves like the TEX instruction, but a filtered
986 sample is not generated. The four samples that contribute to filtering are
987 placed into xyzw in clockwise order, starting with the (u,v) texture
988 coordinate delta at the following locations (-, +), (+, +), (+, -), (-, -),
989 where the magnitude of the deltas are half a texel.
990
991 PIPE_CAP_TEXTURE_SM5 enhances this instruction to support shadow per-sample
992 depth compares, single component selection, and a non-constant offset. It
993 doesn't allow support for the GL independent offset to get i0,j0. This would
994 require another CAP is hw can do it natively. For now we lower that before
995 TGSI.
996
997 .. math::
998
999 coord = src0
1000
1001 component = src1
1002
1003 dst = texture\_gather4 (unit, coord, component)
1004
1005 (with SM5 - cube array shadow)
1006
1007 .. math::
1008
1009 coord = src0
1010
1011 compare = src1
1012
1013 dst = texture\_gather (uint, coord, compare)
1014
1015 .. opcode:: LODQ - level of detail query
1016
1017 Compute the LOD information that the texture pipe would use to access the
1018 texture. The Y component contains the computed LOD lambda_prime. The X
1019 component contains the LOD that will be accessed, based on min/max lod's
1020 and mipmap filters.
1021
1022 .. math::
1023
1024 coord = src0
1025
1026 dst.xy = lodq(uint, coord);
1027
1028 Integer ISA
1029 ^^^^^^^^^^^^^^^^^^^^^^^^
1030 These opcodes are used for integer operations.
1031 Support for these opcodes indicated by PIPE_SHADER_CAP_INTEGERS (all of them?)
1032
1033
1034 .. opcode:: I2F - Signed Integer To Float
1035
1036 Rounding is unspecified (round to nearest even suggested).
1037
1038 .. math::
1039
1040 dst.x = (float) src.x
1041
1042 dst.y = (float) src.y
1043
1044 dst.z = (float) src.z
1045
1046 dst.w = (float) src.w
1047
1048
1049 .. opcode:: U2F - Unsigned Integer To Float
1050
1051 Rounding is unspecified (round to nearest even suggested).
1052
1053 .. math::
1054
1055 dst.x = (float) src.x
1056
1057 dst.y = (float) src.y
1058
1059 dst.z = (float) src.z
1060
1061 dst.w = (float) src.w
1062
1063
1064 .. opcode:: F2I - Float to Signed Integer
1065
1066 Rounding is towards zero (truncate).
1067 Values outside signed range (including NaNs) produce undefined results.
1068
1069 .. math::
1070
1071 dst.x = (int) src.x
1072
1073 dst.y = (int) src.y
1074
1075 dst.z = (int) src.z
1076
1077 dst.w = (int) src.w
1078
1079
1080 .. opcode:: F2U - Float to Unsigned Integer
1081
1082 Rounding is towards zero (truncate).
1083 Values outside unsigned range (including NaNs) produce undefined results.
1084
1085 .. math::
1086
1087 dst.x = (unsigned) src.x
1088
1089 dst.y = (unsigned) src.y
1090
1091 dst.z = (unsigned) src.z
1092
1093 dst.w = (unsigned) src.w
1094
1095
1096 .. opcode:: UADD - Integer Add
1097
1098 This instruction works the same for signed and unsigned integers.
1099 The low 32bit of the result is returned.
1100
1101 .. math::
1102
1103 dst.x = src0.x + src1.x
1104
1105 dst.y = src0.y + src1.y
1106
1107 dst.z = src0.z + src1.z
1108
1109 dst.w = src0.w + src1.w
1110
1111
1112 .. opcode:: UMAD - Integer Multiply And Add
1113
1114 This instruction works the same for signed and unsigned integers.
1115 The multiplication returns the low 32bit (as does the result itself).
1116
1117 .. math::
1118
1119 dst.x = src0.x \times src1.x + src2.x
1120
1121 dst.y = src0.y \times src1.y + src2.y
1122
1123 dst.z = src0.z \times src1.z + src2.z
1124
1125 dst.w = src0.w \times src1.w + src2.w
1126
1127
1128 .. opcode:: UMUL - Integer Multiply
1129
1130 This instruction works the same for signed and unsigned integers.
1131 The low 32bit of the result is returned.
1132
1133 .. math::
1134
1135 dst.x = src0.x \times src1.x
1136
1137 dst.y = src0.y \times src1.y
1138
1139 dst.z = src0.z \times src1.z
1140
1141 dst.w = src0.w \times src1.w
1142
1143
1144 .. opcode:: IMUL_HI - Signed Integer Multiply High Bits
1145
1146 The high 32bits of the multiplication of 2 signed integers are returned.
1147
1148 .. math::
1149
1150 dst.x = (src0.x \times src1.x) >> 32
1151
1152 dst.y = (src0.y \times src1.y) >> 32
1153
1154 dst.z = (src0.z \times src1.z) >> 32
1155
1156 dst.w = (src0.w \times src1.w) >> 32
1157
1158
1159 .. opcode:: UMUL_HI - Unsigned Integer Multiply High Bits
1160
1161 The high 32bits of the multiplication of 2 unsigned integers are returned.
1162
1163 .. math::
1164
1165 dst.x = (src0.x \times src1.x) >> 32
1166
1167 dst.y = (src0.y \times src1.y) >> 32
1168
1169 dst.z = (src0.z \times src1.z) >> 32
1170
1171 dst.w = (src0.w \times src1.w) >> 32
1172
1173
1174 .. opcode:: IDIV - Signed Integer Division
1175
1176 TBD: behavior for division by zero.
1177
1178 .. math::
1179
1180 dst.x = src0.x \ src1.x
1181
1182 dst.y = src0.y \ src1.y
1183
1184 dst.z = src0.z \ src1.z
1185
1186 dst.w = src0.w \ src1.w
1187
1188
1189 .. opcode:: UDIV - Unsigned Integer Division
1190
1191 For division by zero, 0xffffffff is returned.
1192
1193 .. math::
1194
1195 dst.x = src0.x \ src1.x
1196
1197 dst.y = src0.y \ src1.y
1198
1199 dst.z = src0.z \ src1.z
1200
1201 dst.w = src0.w \ src1.w
1202
1203
1204 .. opcode:: UMOD - Unsigned Integer Remainder
1205
1206 If second arg is zero, 0xffffffff is returned.
1207
1208 .. math::
1209
1210 dst.x = src0.x \ src1.x
1211
1212 dst.y = src0.y \ src1.y
1213
1214 dst.z = src0.z \ src1.z
1215
1216 dst.w = src0.w \ src1.w
1217
1218
1219 .. opcode:: NOT - Bitwise Not
1220
1221 .. math::
1222
1223 dst.x = \sim src.x
1224
1225 dst.y = \sim src.y
1226
1227 dst.z = \sim src.z
1228
1229 dst.w = \sim src.w
1230
1231
1232 .. opcode:: AND - Bitwise And
1233
1234 .. math::
1235
1236 dst.x = src0.x \& src1.x
1237
1238 dst.y = src0.y \& src1.y
1239
1240 dst.z = src0.z \& src1.z
1241
1242 dst.w = src0.w \& src1.w
1243
1244
1245 .. opcode:: OR - Bitwise Or
1246
1247 .. math::
1248
1249 dst.x = src0.x | src1.x
1250
1251 dst.y = src0.y | src1.y
1252
1253 dst.z = src0.z | src1.z
1254
1255 dst.w = src0.w | src1.w
1256
1257
1258 .. opcode:: XOR - Bitwise Xor
1259
1260 .. math::
1261
1262 dst.x = src0.x \oplus src1.x
1263
1264 dst.y = src0.y \oplus src1.y
1265
1266 dst.z = src0.z \oplus src1.z
1267
1268 dst.w = src0.w \oplus src1.w
1269
1270
1271 .. opcode:: IMAX - Maximum of Signed Integers
1272
1273 .. math::
1274
1275 dst.x = max(src0.x, src1.x)
1276
1277 dst.y = max(src0.y, src1.y)
1278
1279 dst.z = max(src0.z, src1.z)
1280
1281 dst.w = max(src0.w, src1.w)
1282
1283
1284 .. opcode:: UMAX - Maximum of Unsigned Integers
1285
1286 .. math::
1287
1288 dst.x = max(src0.x, src1.x)
1289
1290 dst.y = max(src0.y, src1.y)
1291
1292 dst.z = max(src0.z, src1.z)
1293
1294 dst.w = max(src0.w, src1.w)
1295
1296
1297 .. opcode:: IMIN - Minimum of Signed Integers
1298
1299 .. math::
1300
1301 dst.x = min(src0.x, src1.x)
1302
1303 dst.y = min(src0.y, src1.y)
1304
1305 dst.z = min(src0.z, src1.z)
1306
1307 dst.w = min(src0.w, src1.w)
1308
1309
1310 .. opcode:: UMIN - Minimum of Unsigned Integers
1311
1312 .. math::
1313
1314 dst.x = min(src0.x, src1.x)
1315
1316 dst.y = min(src0.y, src1.y)
1317
1318 dst.z = min(src0.z, src1.z)
1319
1320 dst.w = min(src0.w, src1.w)
1321
1322
1323 .. opcode:: SHL - Shift Left
1324
1325 The shift count is masked with 0x1f before the shift is applied.
1326
1327 .. math::
1328
1329 dst.x = src0.x << (0x1f \& src1.x)
1330
1331 dst.y = src0.y << (0x1f \& src1.y)
1332
1333 dst.z = src0.z << (0x1f \& src1.z)
1334
1335 dst.w = src0.w << (0x1f \& src1.w)
1336
1337
1338 .. opcode:: ISHR - Arithmetic Shift Right (of Signed Integer)
1339
1340 The shift count is masked with 0x1f before the shift is applied.
1341
1342 .. math::
1343
1344 dst.x = src0.x >> (0x1f \& src1.x)
1345
1346 dst.y = src0.y >> (0x1f \& src1.y)
1347
1348 dst.z = src0.z >> (0x1f \& src1.z)
1349
1350 dst.w = src0.w >> (0x1f \& src1.w)
1351
1352
1353 .. opcode:: USHR - Logical Shift Right
1354
1355 The shift count is masked with 0x1f before the shift is applied.
1356
1357 .. math::
1358
1359 dst.x = src0.x >> (unsigned) (0x1f \& src1.x)
1360
1361 dst.y = src0.y >> (unsigned) (0x1f \& src1.y)
1362
1363 dst.z = src0.z >> (unsigned) (0x1f \& src1.z)
1364
1365 dst.w = src0.w >> (unsigned) (0x1f \& src1.w)
1366
1367
1368 .. opcode:: UCMP - Integer Conditional Move
1369
1370 .. math::
1371
1372 dst.x = src0.x ? src1.x : src2.x
1373
1374 dst.y = src0.y ? src1.y : src2.y
1375
1376 dst.z = src0.z ? src1.z : src2.z
1377
1378 dst.w = src0.w ? src1.w : src2.w
1379
1380
1381
1382 .. opcode:: ISSG - Integer Set Sign
1383
1384 .. math::
1385
1386 dst.x = (src0.x < 0) ? -1 : (src0.x > 0) ? 1 : 0
1387
1388 dst.y = (src0.y < 0) ? -1 : (src0.y > 0) ? 1 : 0
1389
1390 dst.z = (src0.z < 0) ? -1 : (src0.z > 0) ? 1 : 0
1391
1392 dst.w = (src0.w < 0) ? -1 : (src0.w > 0) ? 1 : 0
1393
1394
1395
1396 .. opcode:: FSLT - Float Set On Less Than (ordered)
1397
1398 Same comparison as SLT but returns integer instead of 1.0/0.0 float
1399
1400 .. math::
1401
1402 dst.x = (src0.x < src1.x) ? \sim 0 : 0
1403
1404 dst.y = (src0.y < src1.y) ? \sim 0 : 0
1405
1406 dst.z = (src0.z < src1.z) ? \sim 0 : 0
1407
1408 dst.w = (src0.w < src1.w) ? \sim 0 : 0
1409
1410
1411 .. opcode:: ISLT - Signed Integer Set On Less Than
1412
1413 .. math::
1414
1415 dst.x = (src0.x < src1.x) ? \sim 0 : 0
1416
1417 dst.y = (src0.y < src1.y) ? \sim 0 : 0
1418
1419 dst.z = (src0.z < src1.z) ? \sim 0 : 0
1420
1421 dst.w = (src0.w < src1.w) ? \sim 0 : 0
1422
1423
1424 .. opcode:: USLT - Unsigned Integer Set On Less Than
1425
1426 .. math::
1427
1428 dst.x = (src0.x < src1.x) ? \sim 0 : 0
1429
1430 dst.y = (src0.y < src1.y) ? \sim 0 : 0
1431
1432 dst.z = (src0.z < src1.z) ? \sim 0 : 0
1433
1434 dst.w = (src0.w < src1.w) ? \sim 0 : 0
1435
1436
1437 .. opcode:: FSGE - Float Set On Greater Equal Than (ordered)
1438
1439 Same comparison as SGE but returns integer instead of 1.0/0.0 float
1440
1441 .. math::
1442
1443 dst.x = (src0.x >= src1.x) ? \sim 0 : 0
1444
1445 dst.y = (src0.y >= src1.y) ? \sim 0 : 0
1446
1447 dst.z = (src0.z >= src1.z) ? \sim 0 : 0
1448
1449 dst.w = (src0.w >= src1.w) ? \sim 0 : 0
1450
1451
1452 .. opcode:: ISGE - Signed Integer Set On Greater Equal Than
1453
1454 .. math::
1455
1456 dst.x = (src0.x >= src1.x) ? \sim 0 : 0
1457
1458 dst.y = (src0.y >= src1.y) ? \sim 0 : 0
1459
1460 dst.z = (src0.z >= src1.z) ? \sim 0 : 0
1461
1462 dst.w = (src0.w >= src1.w) ? \sim 0 : 0
1463
1464
1465 .. opcode:: USGE - Unsigned Integer Set On Greater Equal Than
1466
1467 .. math::
1468
1469 dst.x = (src0.x >= src1.x) ? \sim 0 : 0
1470
1471 dst.y = (src0.y >= src1.y) ? \sim 0 : 0
1472
1473 dst.z = (src0.z >= src1.z) ? \sim 0 : 0
1474
1475 dst.w = (src0.w >= src1.w) ? \sim 0 : 0
1476
1477
1478 .. opcode:: FSEQ - Float Set On Equal (ordered)
1479
1480 Same comparison as SEQ but returns integer instead of 1.0/0.0 float
1481
1482 .. math::
1483
1484 dst.x = (src0.x == src1.x) ? \sim 0 : 0
1485
1486 dst.y = (src0.y == src1.y) ? \sim 0 : 0
1487
1488 dst.z = (src0.z == src1.z) ? \sim 0 : 0
1489
1490 dst.w = (src0.w == src1.w) ? \sim 0 : 0
1491
1492
1493 .. opcode:: USEQ - Integer Set On Equal
1494
1495 .. math::
1496
1497 dst.x = (src0.x == src1.x) ? \sim 0 : 0
1498
1499 dst.y = (src0.y == src1.y) ? \sim 0 : 0
1500
1501 dst.z = (src0.z == src1.z) ? \sim 0 : 0
1502
1503 dst.w = (src0.w == src1.w) ? \sim 0 : 0
1504
1505
1506 .. opcode:: FSNE - Float Set On Not Equal (unordered)
1507
1508 Same comparison as SNE but returns integer instead of 1.0/0.0 float
1509
1510 .. math::
1511
1512 dst.x = (src0.x != src1.x) ? \sim 0 : 0
1513
1514 dst.y = (src0.y != src1.y) ? \sim 0 : 0
1515
1516 dst.z = (src0.z != src1.z) ? \sim 0 : 0
1517
1518 dst.w = (src0.w != src1.w) ? \sim 0 : 0
1519
1520
1521 .. opcode:: USNE - Integer Set On Not Equal
1522
1523 .. math::
1524
1525 dst.x = (src0.x != src1.x) ? \sim 0 : 0
1526
1527 dst.y = (src0.y != src1.y) ? \sim 0 : 0
1528
1529 dst.z = (src0.z != src1.z) ? \sim 0 : 0
1530
1531 dst.w = (src0.w != src1.w) ? \sim 0 : 0
1532
1533
1534 .. opcode:: INEG - Integer Negate
1535
1536 Two's complement.
1537
1538 .. math::
1539
1540 dst.x = -src.x
1541
1542 dst.y = -src.y
1543
1544 dst.z = -src.z
1545
1546 dst.w = -src.w
1547
1548
1549 .. opcode:: IABS - Integer Absolute Value
1550
1551 .. math::
1552
1553 dst.x = |src.x|
1554
1555 dst.y = |src.y|
1556
1557 dst.z = |src.z|
1558
1559 dst.w = |src.w|
1560
1561 Bitwise ISA
1562 ^^^^^^^^^^^
1563 These opcodes are used for bit-level manipulation of integers.
1564
1565 .. opcode:: IBFE - Signed Bitfield Extract
1566
1567 See SM5 instruction of the same name. Extracts a set of bits from the input,
1568 and sign-extends them if the high bit of the extracted window is set.
1569
1570 Pseudocode::
1571
1572 def ibfe(value, offset, bits):
1573 offset = offset & 0x1f
1574 bits = bits & 0x1f
1575 if bits == 0: return 0
1576 # Note: >> sign-extends
1577 if width + offset < 32:
1578 return (value << (32 - offset - bits)) >> (32 - bits)
1579 else:
1580 return value >> offset
1581
1582 .. opcode:: UBFE - Unsigned Bitfield Extract
1583
1584 See SM5 instruction of the same name. Extracts a set of bits from the input,
1585 without any sign-extension.
1586
1587 Pseudocode::
1588
1589 def ubfe(value, offset, bits):
1590 offset = offset & 0x1f
1591 bits = bits & 0x1f
1592 if bits == 0: return 0
1593 # Note: >> does not sign-extend
1594 if width + offset < 32:
1595 return (value << (32 - offset - bits)) >> (32 - bits)
1596 else:
1597 return value >> offset
1598
1599 .. opcode:: BFI - Bitfield Insert
1600
1601 See SM5 instruction of the same name. Replaces a bit region of 'base' with
1602 the low bits of 'insert'.
1603
1604 Pseudocode::
1605
1606 def bfi(base, insert, offset, bits):
1607 offset = offset & 0x1f
1608 bits = bits & 0x1f
1609 mask = ((1 << bits) - 1) << offset
1610 return ((insert << offset) & mask) | (base & ~mask)
1611
1612 .. opcode:: BREV - Bitfield Reverse
1613
1614 See SM5 instruction BFREV. Reverses the bits of the argument.
1615
1616 .. opcode:: POPC - Population Count
1617
1618 See SM5 instruction COUNTBITS. Counts the number of set bits in the argument.
1619
1620 .. opcode:: LSB - Index of lowest set bit
1621
1622 See SM5 instruction FIRSTBIT_LO. Computes the 0-based index of the first set
1623 bit of the argument. Returns -1 if none are set.
1624
1625 .. opcode:: IMSB - Index of highest non-sign bit
1626
1627 See SM5 instruction FIRSTBIT_SHI. Computes the 0-based index of the highest
1628 non-sign bit of the argument (i.e. highest 0 bit for negative numbers,
1629 highest 1 bit for positive numbers). Returns -1 if all bits are the same
1630 (i.e. for inputs 0 and -1).
1631
1632 .. opcode:: UMSB - Index of highest set bit
1633
1634 See SM5 instruction FIRSTBIT_HI. Computes the 0-based index of the highest
1635 set bit of the argument. Returns -1 if none are set.
1636
1637 Geometry ISA
1638 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1639
1640 These opcodes are only supported in geometry shaders; they have no meaning
1641 in any other type of shader.
1642
1643 .. opcode:: EMIT - Emit
1644
1645 Generate a new vertex for the current primitive using the values in the
1646 output registers.
1647
1648
1649 .. opcode:: ENDPRIM - End Primitive
1650
1651 Complete the current primitive (consisting of the emitted vertices),
1652 and start a new one.
1653
1654
1655 GLSL ISA
1656 ^^^^^^^^^^
1657
1658 These opcodes are part of :term:`GLSL`'s opcode set. Support for these
1659 opcodes is determined by a special capability bit, ``GLSL``.
1660 Some require glsl version 1.30 (UIF/BREAKC/SWITCH/CASE/DEFAULT/ENDSWITCH).
1661
1662 .. opcode:: CAL - Subroutine Call
1663
1664 push(pc)
1665 pc = target
1666
1667
1668 .. opcode:: RET - Subroutine Call Return
1669
1670 pc = pop()
1671
1672
1673 .. opcode:: CONT - Continue
1674
1675 Unconditionally moves the point of execution to the instruction after the
1676 last bgnloop. The instruction must appear within a bgnloop/endloop.
1677
1678 .. note::
1679
1680 Support for CONT is determined by a special capability bit,
1681 ``TGSI_CONT_SUPPORTED``. See :ref:`Screen` for more information.
1682
1683
1684 .. opcode:: BGNLOOP - Begin a Loop
1685
1686 Start a loop. Must have a matching endloop.
1687
1688
1689 .. opcode:: BGNSUB - Begin Subroutine
1690
1691 Starts definition of a subroutine. Must have a matching endsub.
1692
1693
1694 .. opcode:: ENDLOOP - End a Loop
1695
1696 End a loop started with bgnloop.
1697
1698
1699 .. opcode:: ENDSUB - End Subroutine
1700
1701 Ends definition of a subroutine.
1702
1703
1704 .. opcode:: NOP - No Operation
1705
1706 Do nothing.
1707
1708
1709 .. opcode:: BRK - Break
1710
1711 Unconditionally moves the point of execution to the instruction after the
1712 next endloop or endswitch. The instruction must appear within a loop/endloop
1713 or switch/endswitch.
1714
1715
1716 .. opcode:: BREAKC - Break Conditional
1717
1718 Conditionally moves the point of execution to the instruction after the
1719 next endloop or endswitch. The instruction must appear within a loop/endloop
1720 or switch/endswitch.
1721 Condition evaluates to true if src0.x != 0 where src0.x is interpreted
1722 as an integer register.
1723
1724 .. note::
1725
1726 Considered for removal as it's quite inconsistent wrt other opcodes
1727 (could emulate with UIF/BRK/ENDIF).
1728
1729
1730 .. opcode:: IF - Float If
1731
1732 Start an IF ... ELSE .. ENDIF block. Condition evaluates to true if
1733
1734 src0.x != 0.0
1735
1736 where src0.x is interpreted as a floating point register.
1737
1738
1739 .. opcode:: UIF - Bitwise If
1740
1741 Start an UIF ... ELSE .. ENDIF block. Condition evaluates to true if
1742
1743 src0.x != 0
1744
1745 where src0.x is interpreted as an integer register.
1746
1747
1748 .. opcode:: ELSE - Else
1749
1750 Starts an else block, after an IF or UIF statement.
1751
1752
1753 .. opcode:: ENDIF - End If
1754
1755 Ends an IF or UIF block.
1756
1757
1758 .. opcode:: SWITCH - Switch
1759
1760 Starts a C-style switch expression. The switch consists of one or multiple
1761 CASE statements, and at most one DEFAULT statement. Execution of a statement
1762 ends when a BRK is hit, but just like in C falling through to other cases
1763 without a break is allowed. Similarly, DEFAULT label is allowed anywhere not
1764 just as last statement, and fallthrough is allowed into/from it.
1765 CASE src arguments are evaluated at bit level against the SWITCH src argument.
1766
1767 Example::
1768
1769 SWITCH src[0].x
1770 CASE src[0].x
1771 (some instructions here)
1772 (optional BRK here)
1773 DEFAULT
1774 (some instructions here)
1775 (optional BRK here)
1776 CASE src[0].x
1777 (some instructions here)
1778 (optional BRK here)
1779 ENDSWITCH
1780
1781
1782 .. opcode:: CASE - Switch case
1783
1784 This represents a switch case label. The src arg must be an integer immediate.
1785
1786
1787 .. opcode:: DEFAULT - Switch default
1788
1789 This represents the default case in the switch, which is taken if no other
1790 case matches.
1791
1792
1793 .. opcode:: ENDSWITCH - End of switch
1794
1795 Ends a switch expression.
1796
1797
1798 .. opcode:: NRM4 - 4-component Vector Normalise
1799
1800 This instruction replicates its result.
1801
1802 .. math::
1803
1804 dst = \frac{src.x}{src.x \times src.x + src.y \times src.y + src.z \times src.z + src.w \times src.w}
1805
1806
1807 .. _doubleopcodes:
1808
1809 Double ISA
1810 ^^^^^^^^^^^^^^^
1811
1812 The double-precision opcodes reinterpret four-component vectors into
1813 two-component vectors with doubled precision in each component.
1814
1815 Support for these opcodes is XXX undecided. :T
1816
1817 .. opcode:: DADD - Add
1818
1819 .. math::
1820
1821 dst.xy = src0.xy + src1.xy
1822
1823 dst.zw = src0.zw + src1.zw
1824
1825
1826 .. opcode:: DDIV - Divide
1827
1828 .. math::
1829
1830 dst.xy = src0.xy / src1.xy
1831
1832 dst.zw = src0.zw / src1.zw
1833
1834 .. opcode:: DSEQ - Set on Equal
1835
1836 .. math::
1837
1838 dst.xy = src0.xy == src1.xy ? 1.0F : 0.0F
1839
1840 dst.zw = src0.zw == src1.zw ? 1.0F : 0.0F
1841
1842 .. opcode:: DSLT - Set on Less than
1843
1844 .. math::
1845
1846 dst.xy = src0.xy < src1.xy ? 1.0F : 0.0F
1847
1848 dst.zw = src0.zw < src1.zw ? 1.0F : 0.0F
1849
1850 .. opcode:: DFRAC - Fraction
1851
1852 .. math::
1853
1854 dst.xy = src.xy - \lfloor src.xy\rfloor
1855
1856 dst.zw = src.zw - \lfloor src.zw\rfloor
1857
1858
1859 .. opcode:: DFRACEXP - Convert Number to Fractional and Integral Components
1860
1861 Like the ``frexp()`` routine in many math libraries, this opcode stores the
1862 exponent of its source to ``dst0``, and the significand to ``dst1``, such that
1863 :math:`dst1 \times 2^{dst0} = src` .
1864
1865 .. math::
1866
1867 dst0.xy = exp(src.xy)
1868
1869 dst1.xy = frac(src.xy)
1870
1871 dst0.zw = exp(src.zw)
1872
1873 dst1.zw = frac(src.zw)
1874
1875 .. opcode:: DLDEXP - Multiply Number by Integral Power of 2
1876
1877 This opcode is the inverse of :opcode:`DFRACEXP`.
1878
1879 .. math::
1880
1881 dst.xy = src0.xy \times 2^{src1.xy}
1882
1883 dst.zw = src0.zw \times 2^{src1.zw}
1884
1885 .. opcode:: DMIN - Minimum
1886
1887 .. math::
1888
1889 dst.xy = min(src0.xy, src1.xy)
1890
1891 dst.zw = min(src0.zw, src1.zw)
1892
1893 .. opcode:: DMAX - Maximum
1894
1895 .. math::
1896
1897 dst.xy = max(src0.xy, src1.xy)
1898
1899 dst.zw = max(src0.zw, src1.zw)
1900
1901 .. opcode:: DMUL - Multiply
1902
1903 .. math::
1904
1905 dst.xy = src0.xy \times src1.xy
1906
1907 dst.zw = src0.zw \times src1.zw
1908
1909
1910 .. opcode:: DMAD - Multiply And Add
1911
1912 .. math::
1913
1914 dst.xy = src0.xy \times src1.xy + src2.xy
1915
1916 dst.zw = src0.zw \times src1.zw + src2.zw
1917
1918
1919 .. opcode:: DRCP - Reciprocal
1920
1921 .. math::
1922
1923 dst.xy = \frac{1}{src.xy}
1924
1925 dst.zw = \frac{1}{src.zw}
1926
1927 .. opcode:: DSQRT - Square Root
1928
1929 .. math::
1930
1931 dst.xy = \sqrt{src.xy}
1932
1933 dst.zw = \sqrt{src.zw}
1934
1935
1936 .. _samplingopcodes:
1937
1938 Resource Sampling Opcodes
1939 ^^^^^^^^^^^^^^^^^^^^^^^^^
1940
1941 Those opcodes follow very closely semantics of the respective Direct3D
1942 instructions. If in doubt double check Direct3D documentation.
1943 Note that the swizzle on SVIEW (src1) determines texel swizzling
1944 after lookup.
1945
1946 .. opcode:: SAMPLE
1947
1948 Using provided address, sample data from the specified texture using the
1949 filtering mode identified by the gven sampler. The source data may come from
1950 any resource type other than buffers.
1951
1952 Syntax: ``SAMPLE dst, address, sampler_view, sampler``
1953
1954 Example: ``SAMPLE TEMP[0], TEMP[1], SVIEW[0], SAMP[0]``
1955
1956 .. opcode:: SAMPLE_I
1957
1958 Simplified alternative to the SAMPLE instruction. Using the provided
1959 integer address, SAMPLE_I fetches data from the specified sampler view
1960 without any filtering. The source data may come from any resource type
1961 other than CUBE.
1962
1963 Syntax: ``SAMPLE_I dst, address, sampler_view``
1964
1965 Example: ``SAMPLE_I TEMP[0], TEMP[1], SVIEW[0]``
1966
1967 The 'address' is specified as unsigned integers. If the 'address' is out of
1968 range [0...(# texels - 1)] the result of the fetch is always 0 in all
1969 components. As such the instruction doesn't honor address wrap modes, in
1970 cases where that behavior is desirable 'SAMPLE' instruction should be used.
1971 address.w always provides an unsigned integer mipmap level. If the value is
1972 out of the range then the instruction always returns 0 in all components.
1973 address.yz are ignored for buffers and 1d textures. address.z is ignored
1974 for 1d texture arrays and 2d textures.
1975
1976 For 1D texture arrays address.y provides the array index (also as unsigned
1977 integer). If the value is out of the range of available array indices
1978 [0... (array size - 1)] then the opcode always returns 0 in all components.
1979 For 2D texture arrays address.z provides the array index, otherwise it
1980 exhibits the same behavior as in the case for 1D texture arrays. The exact
1981 semantics of the source address are presented in the table below:
1982
1983 +---------------------------+----+-----+-----+---------+
1984 | resource type | X | Y | Z | W |
1985 +===========================+====+=====+=====+=========+
1986 | ``PIPE_BUFFER`` | x | | | ignored |
1987 +---------------------------+----+-----+-----+---------+
1988 | ``PIPE_TEXTURE_1D`` | x | | | mpl |
1989 +---------------------------+----+-----+-----+---------+
1990 | ``PIPE_TEXTURE_2D`` | x | y | | mpl |
1991 +---------------------------+----+-----+-----+---------+
1992 | ``PIPE_TEXTURE_3D`` | x | y | z | mpl |
1993 +---------------------------+----+-----+-----+---------+
1994 | ``PIPE_TEXTURE_RECT`` | x | y | | mpl |
1995 +---------------------------+----+-----+-----+---------+
1996 | ``PIPE_TEXTURE_CUBE`` | not allowed as source |
1997 +---------------------------+----+-----+-----+---------+
1998 | ``PIPE_TEXTURE_1D_ARRAY`` | x | idx | | mpl |
1999 +---------------------------+----+-----+-----+---------+
2000 | ``PIPE_TEXTURE_2D_ARRAY`` | x | y | idx | mpl |
2001 +---------------------------+----+-----+-----+---------+
2002
2003 Where 'mpl' is a mipmap level and 'idx' is the array index.
2004
2005 .. opcode:: SAMPLE_I_MS
2006
2007 Just like SAMPLE_I but allows fetch data from multi-sampled surfaces.
2008
2009 Syntax: ``SAMPLE_I_MS dst, address, sampler_view, sample``
2010
2011 .. opcode:: SAMPLE_B
2012
2013 Just like the SAMPLE instruction with the exception that an additional bias
2014 is applied to the level of detail computed as part of the instruction
2015 execution.
2016
2017 Syntax: ``SAMPLE_B dst, address, sampler_view, sampler, lod_bias``
2018
2019 Example: ``SAMPLE_B TEMP[0], TEMP[1], SVIEW[0], SAMP[0], TEMP[2].x``
2020
2021 .. opcode:: SAMPLE_C
2022
2023 Similar to the SAMPLE instruction but it performs a comparison filter. The
2024 operands to SAMPLE_C are identical to SAMPLE, except that there is an
2025 additional float32 operand, reference value, which must be a register with
2026 single-component, or a scalar literal. SAMPLE_C makes the hardware use the
2027 current samplers compare_func (in pipe_sampler_state) to compare reference
2028 value against the red component value for the surce resource at each texel
2029 that the currently configured texture filter covers based on the provided
2030 coordinates.
2031
2032 Syntax: ``SAMPLE_C dst, address, sampler_view.r, sampler, ref_value``
2033
2034 Example: ``SAMPLE_C TEMP[0], TEMP[1], SVIEW[0].r, SAMP[0], TEMP[2].x``
2035
2036 .. opcode:: SAMPLE_C_LZ
2037
2038 Same as SAMPLE_C, but LOD is 0 and derivatives are ignored. The LZ stands
2039 for level-zero.
2040
2041 Syntax: ``SAMPLE_C_LZ dst, address, sampler_view.r, sampler, ref_value``
2042
2043 Example: ``SAMPLE_C_LZ TEMP[0], TEMP[1], SVIEW[0].r, SAMP[0], TEMP[2].x``
2044
2045
2046 .. opcode:: SAMPLE_D
2047
2048 SAMPLE_D is identical to the SAMPLE opcode except that the derivatives for
2049 the source address in the x direction and the y direction are provided by
2050 extra parameters.
2051
2052 Syntax: ``SAMPLE_D dst, address, sampler_view, sampler, der_x, der_y``
2053
2054 Example: ``SAMPLE_D TEMP[0], TEMP[1], SVIEW[0], SAMP[0], TEMP[2], TEMP[3]``
2055
2056 .. opcode:: SAMPLE_L
2057
2058 SAMPLE_L is identical to the SAMPLE opcode except that the LOD is provided
2059 directly as a scalar value, representing no anisotropy.
2060
2061 Syntax: ``SAMPLE_L dst, address, sampler_view, sampler, explicit_lod``
2062
2063 Example: ``SAMPLE_L TEMP[0], TEMP[1], SVIEW[0], SAMP[0], TEMP[2].x``
2064
2065 .. opcode:: GATHER4
2066
2067 Gathers the four texels to be used in a bi-linear filtering operation and
2068 packs them into a single register. Only works with 2D, 2D array, cubemaps,
2069 and cubemaps arrays. For 2D textures, only the addressing modes of the
2070 sampler and the top level of any mip pyramid are used. Set W to zero. It
2071 behaves like the SAMPLE instruction, but a filtered sample is not
2072 generated. The four samples that contribute to filtering are placed into
2073 xyzw in counter-clockwise order, starting with the (u,v) texture coordinate
2074 delta at the following locations (-, +), (+, +), (+, -), (-, -), where the
2075 magnitude of the deltas are half a texel.
2076
2077
2078 .. opcode:: SVIEWINFO
2079
2080 Query the dimensions of a given sampler view. dst receives width, height,
2081 depth or array size and number of mipmap levels as int4. The dst can have a
2082 writemask which will specify what info is the caller interested in.
2083
2084 Syntax: ``SVIEWINFO dst, src_mip_level, sampler_view``
2085
2086 Example: ``SVIEWINFO TEMP[0], TEMP[1].x, SVIEW[0]``
2087
2088 src_mip_level is an unsigned integer scalar. If it's out of range then
2089 returns 0 for width, height and depth/array size but the total number of
2090 mipmap is still returned correctly for the given sampler view. The returned
2091 width, height and depth values are for the mipmap level selected by the
2092 src_mip_level and are in the number of texels. For 1d texture array width
2093 is in dst.x, array size is in dst.y and dst.z is 0. The number of mipmaps is
2094 still in dst.w. In contrast to d3d10 resinfo, there's no way in the tgsi
2095 instruction encoding to specify the return type (float/rcpfloat/uint), hence
2096 always using uint. Also, unlike the SAMPLE instructions, the swizzle on src1
2097 resinfo allowing swizzling dst values is ignored (due to the interaction
2098 with rcpfloat modifier which requires some swizzle handling in the state
2099 tracker anyway).
2100
2101 .. opcode:: SAMPLE_POS
2102
2103 Query the position of a given sample. dst receives float4 (x, y, 0, 0)
2104 indicated where the sample is located. If the resource is not a multi-sample
2105 resource and not a render target, the result is 0.
2106
2107 .. opcode:: SAMPLE_INFO
2108
2109 dst receives number of samples in x. If the resource is not a multi-sample
2110 resource and not a render target, the result is 0.
2111
2112
2113 .. _resourceopcodes:
2114
2115 Resource Access Opcodes
2116 ^^^^^^^^^^^^^^^^^^^^^^^
2117
2118 .. opcode:: LOAD - Fetch data from a shader resource
2119
2120 Syntax: ``LOAD dst, resource, address``
2121
2122 Example: ``LOAD TEMP[0], RES[0], TEMP[1]``
2123
2124 Using the provided integer address, LOAD fetches data
2125 from the specified buffer or texture without any
2126 filtering.
2127
2128 The 'address' is specified as a vector of unsigned
2129 integers. If the 'address' is out of range the result
2130 is unspecified.
2131
2132 Only the first mipmap level of a resource can be read
2133 from using this instruction.
2134
2135 For 1D or 2D texture arrays, the array index is
2136 provided as an unsigned integer in address.y or
2137 address.z, respectively. address.yz are ignored for
2138 buffers and 1D textures. address.z is ignored for 1D
2139 texture arrays and 2D textures. address.w is always
2140 ignored.
2141
2142 .. opcode:: STORE - Write data to a shader resource
2143
2144 Syntax: ``STORE resource, address, src``
2145
2146 Example: ``STORE RES[0], TEMP[0], TEMP[1]``
2147
2148 Using the provided integer address, STORE writes data
2149 to the specified buffer or texture.
2150
2151 The 'address' is specified as a vector of unsigned
2152 integers. If the 'address' is out of range the result
2153 is unspecified.
2154
2155 Only the first mipmap level of a resource can be
2156 written to using this instruction.
2157
2158 For 1D or 2D texture arrays, the array index is
2159 provided as an unsigned integer in address.y or
2160 address.z, respectively. address.yz are ignored for
2161 buffers and 1D textures. address.z is ignored for 1D
2162 texture arrays and 2D textures. address.w is always
2163 ignored.
2164
2165
2166 .. _threadsyncopcodes:
2167
2168 Inter-thread synchronization opcodes
2169 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
2170
2171 These opcodes are intended for communication between threads running
2172 within the same compute grid. For now they're only valid in compute
2173 programs.
2174
2175 .. opcode:: MFENCE - Memory fence
2176
2177 Syntax: ``MFENCE resource``
2178
2179 Example: ``MFENCE RES[0]``
2180
2181 This opcode forces strong ordering between any memory access
2182 operations that affect the specified resource. This means that
2183 previous loads and stores (and only those) will be performed and
2184 visible to other threads before the program execution continues.
2185
2186
2187 .. opcode:: LFENCE - Load memory fence
2188
2189 Syntax: ``LFENCE resource``
2190
2191 Example: ``LFENCE RES[0]``
2192
2193 Similar to MFENCE, but it only affects the ordering of memory loads.
2194
2195
2196 .. opcode:: SFENCE - Store memory fence
2197
2198 Syntax: ``SFENCE resource``
2199
2200 Example: ``SFENCE RES[0]``
2201
2202 Similar to MFENCE, but it only affects the ordering of memory stores.
2203
2204
2205 .. opcode:: BARRIER - Thread group barrier
2206
2207 ``BARRIER``
2208
2209 This opcode suspends the execution of the current thread until all
2210 the remaining threads in the working group reach the same point of
2211 the program. Results are unspecified if any of the remaining
2212 threads terminates or never reaches an executed BARRIER instruction.
2213
2214
2215 .. _atomopcodes:
2216
2217 Atomic opcodes
2218 ^^^^^^^^^^^^^^
2219
2220 These opcodes provide atomic variants of some common arithmetic and
2221 logical operations. In this context atomicity means that another
2222 concurrent memory access operation that affects the same memory
2223 location is guaranteed to be performed strictly before or after the
2224 entire execution of the atomic operation.
2225
2226 For the moment they're only valid in compute programs.
2227
2228 .. opcode:: ATOMUADD - Atomic integer addition
2229
2230 Syntax: ``ATOMUADD dst, resource, offset, src``
2231
2232 Example: ``ATOMUADD TEMP[0], RES[0], TEMP[1], TEMP[2]``
2233
2234 The following operation is performed atomically on each component:
2235
2236 .. math::
2237
2238 dst_i = resource[offset]_i
2239
2240 resource[offset]_i = dst_i + src_i
2241
2242
2243 .. opcode:: ATOMXCHG - Atomic exchange
2244
2245 Syntax: ``ATOMXCHG dst, resource, offset, src``
2246
2247 Example: ``ATOMXCHG TEMP[0], RES[0], TEMP[1], TEMP[2]``
2248
2249 The following operation is performed atomically on each component:
2250
2251 .. math::
2252
2253 dst_i = resource[offset]_i
2254
2255 resource[offset]_i = src_i
2256
2257
2258 .. opcode:: ATOMCAS - Atomic compare-and-exchange
2259
2260 Syntax: ``ATOMCAS dst, resource, offset, cmp, src``
2261
2262 Example: ``ATOMCAS TEMP[0], RES[0], TEMP[1], TEMP[2], TEMP[3]``
2263
2264 The following operation is performed atomically on each component:
2265
2266 .. math::
2267
2268 dst_i = resource[offset]_i
2269
2270 resource[offset]_i = (dst_i == cmp_i ? src_i : dst_i)
2271
2272
2273 .. opcode:: ATOMAND - Atomic bitwise And
2274
2275 Syntax: ``ATOMAND dst, resource, offset, src``
2276
2277 Example: ``ATOMAND TEMP[0], RES[0], TEMP[1], TEMP[2]``
2278
2279 The following operation is performed atomically on each component:
2280
2281 .. math::
2282
2283 dst_i = resource[offset]_i
2284
2285 resource[offset]_i = dst_i \& src_i
2286
2287
2288 .. opcode:: ATOMOR - Atomic bitwise Or
2289
2290 Syntax: ``ATOMOR dst, resource, offset, src``
2291
2292 Example: ``ATOMOR TEMP[0], RES[0], TEMP[1], TEMP[2]``
2293
2294 The following operation is performed atomically on each component:
2295
2296 .. math::
2297
2298 dst_i = resource[offset]_i
2299
2300 resource[offset]_i = dst_i | src_i
2301
2302
2303 .. opcode:: ATOMXOR - Atomic bitwise Xor
2304
2305 Syntax: ``ATOMXOR dst, resource, offset, src``
2306
2307 Example: ``ATOMXOR TEMP[0], RES[0], TEMP[1], TEMP[2]``
2308
2309 The following operation is performed atomically on each component:
2310
2311 .. math::
2312
2313 dst_i = resource[offset]_i
2314
2315 resource[offset]_i = dst_i \oplus src_i
2316
2317
2318 .. opcode:: ATOMUMIN - Atomic unsigned minimum
2319
2320 Syntax: ``ATOMUMIN dst, resource, offset, src``
2321
2322 Example: ``ATOMUMIN TEMP[0], RES[0], TEMP[1], TEMP[2]``
2323
2324 The following operation is performed atomically on each component:
2325
2326 .. math::
2327
2328 dst_i = resource[offset]_i
2329
2330 resource[offset]_i = (dst_i < src_i ? dst_i : src_i)
2331
2332
2333 .. opcode:: ATOMUMAX - Atomic unsigned maximum
2334
2335 Syntax: ``ATOMUMAX dst, resource, offset, src``
2336
2337 Example: ``ATOMUMAX TEMP[0], RES[0], TEMP[1], TEMP[2]``
2338
2339 The following operation is performed atomically on each component:
2340
2341 .. math::
2342
2343 dst_i = resource[offset]_i
2344
2345 resource[offset]_i = (dst_i > src_i ? dst_i : src_i)
2346
2347
2348 .. opcode:: ATOMIMIN - Atomic signed minimum
2349
2350 Syntax: ``ATOMIMIN dst, resource, offset, src``
2351
2352 Example: ``ATOMIMIN TEMP[0], RES[0], TEMP[1], TEMP[2]``
2353
2354 The following operation is performed atomically on each component:
2355
2356 .. math::
2357
2358 dst_i = resource[offset]_i
2359
2360 resource[offset]_i = (dst_i < src_i ? dst_i : src_i)
2361
2362
2363 .. opcode:: ATOMIMAX - Atomic signed maximum
2364
2365 Syntax: ``ATOMIMAX dst, resource, offset, src``
2366
2367 Example: ``ATOMIMAX TEMP[0], RES[0], TEMP[1], TEMP[2]``
2368
2369 The following operation is performed atomically on each component:
2370
2371 .. math::
2372
2373 dst_i = resource[offset]_i
2374
2375 resource[offset]_i = (dst_i > src_i ? dst_i : src_i)
2376
2377
2378
2379 Explanation of symbols used
2380 ------------------------------
2381
2382
2383 Functions
2384 ^^^^^^^^^^^^^^
2385
2386
2387 :math:`|x|` Absolute value of `x`.
2388
2389 :math:`\lceil x \rceil` Ceiling of `x`.
2390
2391 clamp(x,y,z) Clamp x between y and z.
2392 (x < y) ? y : (x > z) ? z : x
2393
2394 :math:`\lfloor x\rfloor` Floor of `x`.
2395
2396 :math:`\log_2{x}` Logarithm of `x`, base 2.
2397
2398 max(x,y) Maximum of x and y.
2399 (x > y) ? x : y
2400
2401 min(x,y) Minimum of x and y.
2402 (x < y) ? x : y
2403
2404 partialx(x) Derivative of x relative to fragment's X.
2405
2406 partialy(x) Derivative of x relative to fragment's Y.
2407
2408 pop() Pop from stack.
2409
2410 :math:`x^y` `x` to the power `y`.
2411
2412 push(x) Push x on stack.
2413
2414 round(x) Round x.
2415
2416 trunc(x) Truncate x, i.e. drop the fraction bits.
2417
2418
2419 Keywords
2420 ^^^^^^^^^^^^^
2421
2422
2423 discard Discard fragment.
2424
2425 pc Program counter.
2426
2427 target Label of target instruction.
2428
2429
2430 Other tokens
2431 ---------------
2432
2433
2434 Declaration
2435 ^^^^^^^^^^^
2436
2437
2438 Declares a register that is will be referenced as an operand in Instruction
2439 tokens.
2440
2441 File field contains register file that is being declared and is one
2442 of TGSI_FILE.
2443
2444 UsageMask field specifies which of the register components can be accessed
2445 and is one of TGSI_WRITEMASK.
2446
2447 The Local flag specifies that a given value isn't intended for
2448 subroutine parameter passing and, as a result, the implementation
2449 isn't required to give any guarantees of it being preserved across
2450 subroutine boundaries. As it's merely a compiler hint, the
2451 implementation is free to ignore it.
2452
2453 If Dimension flag is set to 1, a Declaration Dimension token follows.
2454
2455 If Semantic flag is set to 1, a Declaration Semantic token follows.
2456
2457 If Interpolate flag is set to 1, a Declaration Interpolate token follows.
2458
2459 If file is TGSI_FILE_RESOURCE, a Declaration Resource token follows.
2460
2461 If Array flag is set to 1, a Declaration Array token follows.
2462
2463 Array Declaration
2464 ^^^^^^^^^^^^^^^^^^^^^^^^
2465
2466 Declarations can optional have an ArrayID attribute which can be referred by
2467 indirect addressing operands. An ArrayID of zero is reserved and treaded as
2468 if no ArrayID is specified.
2469
2470 If an indirect addressing operand refers to a specific declaration by using
2471 an ArrayID only the registers in this declaration are guaranteed to be
2472 accessed, accessing any register outside this declaration results in undefined
2473 behavior. Note that for compatibility the effective index is zero-based and
2474 not relative to the specified declaration
2475
2476 If no ArrayID is specified with an indirect addressing operand the whole
2477 register file might be accessed by this operand. This is strongly discouraged
2478 and will prevent packing of scalar/vec2 arrays and effective alias analysis.
2479
2480 Declaration Semantic
2481 ^^^^^^^^^^^^^^^^^^^^^^^^
2482
2483 Vertex and fragment shader input and output registers may be labeled
2484 with semantic information consisting of a name and index.
2485
2486 Follows Declaration token if Semantic bit is set.
2487
2488 Since its purpose is to link a shader with other stages of the pipeline,
2489 it is valid to follow only those Declaration tokens that declare a register
2490 either in INPUT or OUTPUT file.
2491
2492 SemanticName field contains the semantic name of the register being declared.
2493 There is no default value.
2494
2495 SemanticIndex is an optional subscript that can be used to distinguish
2496 different register declarations with the same semantic name. The default value
2497 is 0.
2498
2499 The meanings of the individual semantic names are explained in the following
2500 sections.
2501
2502 TGSI_SEMANTIC_POSITION
2503 """"""""""""""""""""""
2504
2505 For vertex shaders, TGSI_SEMANTIC_POSITION indicates the vertex shader
2506 output register which contains the homogeneous vertex position in the clip
2507 space coordinate system. After clipping, the X, Y and Z components of the
2508 vertex will be divided by the W value to get normalized device coordinates.
2509
2510 For fragment shaders, TGSI_SEMANTIC_POSITION is used to indicate that
2511 fragment shader input contains the fragment's window position. The X
2512 component starts at zero and always increases from left to right.
2513 The Y component starts at zero and always increases but Y=0 may either
2514 indicate the top of the window or the bottom depending on the fragment
2515 coordinate origin convention (see TGSI_PROPERTY_FS_COORD_ORIGIN).
2516 The Z coordinate ranges from 0 to 1 to represent depth from the front
2517 to the back of the Z buffer. The W component contains the reciprocol
2518 of the interpolated vertex position W component.
2519
2520 Fragment shaders may also declare an output register with
2521 TGSI_SEMANTIC_POSITION. Only the Z component is writable. This allows
2522 the fragment shader to change the fragment's Z position.
2523
2524
2525
2526 TGSI_SEMANTIC_COLOR
2527 """""""""""""""""""
2528
2529 For vertex shader outputs or fragment shader inputs/outputs, this
2530 label indicates that the resister contains an R,G,B,A color.
2531
2532 Several shader inputs/outputs may contain colors so the semantic index
2533 is used to distinguish them. For example, color[0] may be the diffuse
2534 color while color[1] may be the specular color.
2535
2536 This label is needed so that the flat/smooth shading can be applied
2537 to the right interpolants during rasterization.
2538
2539
2540
2541 TGSI_SEMANTIC_BCOLOR
2542 """"""""""""""""""""
2543
2544 Back-facing colors are only used for back-facing polygons, and are only valid
2545 in vertex shader outputs. After rasterization, all polygons are front-facing
2546 and COLOR and BCOLOR end up occupying the same slots in the fragment shader,
2547 so all BCOLORs effectively become regular COLORs in the fragment shader.
2548
2549
2550 TGSI_SEMANTIC_FOG
2551 """""""""""""""""
2552
2553 Vertex shader inputs and outputs and fragment shader inputs may be
2554 labeled with TGSI_SEMANTIC_FOG to indicate that the register contains
2555 a fog coordinate. Typically, the fragment shader will use the fog coordinate
2556 to compute a fog blend factor which is used to blend the normal fragment color
2557 with a constant fog color. But fog coord really is just an ordinary vec4
2558 register like regular semantics.
2559
2560
2561 TGSI_SEMANTIC_PSIZE
2562 """""""""""""""""""
2563
2564 Vertex shader input and output registers may be labeled with
2565 TGIS_SEMANTIC_PSIZE to indicate that the register contains a point size
2566 in the form (S, 0, 0, 1). The point size controls the width or diameter
2567 of points for rasterization. This label cannot be used in fragment
2568 shaders.
2569
2570 When using this semantic, be sure to set the appropriate state in the
2571 :ref:`rasterizer` first.
2572
2573
2574 TGSI_SEMANTIC_TEXCOORD
2575 """"""""""""""""""""""
2576
2577 Only available if PIPE_CAP_TGSI_TEXCOORD is exposed !
2578
2579 Vertex shader outputs and fragment shader inputs may be labeled with
2580 this semantic to make them replaceable by sprite coordinates via the
2581 sprite_coord_enable state in the :ref:`rasterizer`.
2582 The semantic index permitted with this semantic is limited to <= 7.
2583
2584 If the driver does not support TEXCOORD, sprite coordinate replacement
2585 applies to inputs with the GENERIC semantic instead.
2586
2587 The intended use case for this semantic is gl_TexCoord.
2588
2589
2590 TGSI_SEMANTIC_PCOORD
2591 """"""""""""""""""""
2592
2593 Only available if PIPE_CAP_TGSI_TEXCOORD is exposed !
2594
2595 Fragment shader inputs may be labeled with TGSI_SEMANTIC_PCOORD to indicate
2596 that the register contains sprite coordinates in the form (x, y, 0, 1), if
2597 the current primitive is a point and point sprites are enabled. Otherwise,
2598 the contents of the register are undefined.
2599
2600 The intended use case for this semantic is gl_PointCoord.
2601
2602
2603 TGSI_SEMANTIC_GENERIC
2604 """""""""""""""""""""
2605
2606 All vertex/fragment shader inputs/outputs not labeled with any other
2607 semantic label can be considered to be generic attributes. Typical
2608 uses of generic inputs/outputs are texcoords and user-defined values.
2609
2610
2611 TGSI_SEMANTIC_NORMAL
2612 """"""""""""""""""""
2613
2614 Indicates that a vertex shader input is a normal vector. This is
2615 typically only used for legacy graphics APIs.
2616
2617
2618 TGSI_SEMANTIC_FACE
2619 """"""""""""""""""
2620
2621 This label applies to fragment shader inputs only and indicates that
2622 the register contains front/back-face information of the form (F, 0,
2623 0, 1). The first component will be positive when the fragment belongs
2624 to a front-facing polygon, and negative when the fragment belongs to a
2625 back-facing polygon.
2626
2627
2628 TGSI_SEMANTIC_EDGEFLAG
2629 """"""""""""""""""""""
2630
2631 For vertex shaders, this sematic label indicates that an input or
2632 output is a boolean edge flag. The register layout is [F, x, x, x]
2633 where F is 0.0 or 1.0 and x = don't care. Normally, the vertex shader
2634 simply copies the edge flag input to the edgeflag output.
2635
2636 Edge flags are used to control which lines or points are actually
2637 drawn when the polygon mode converts triangles/quads/polygons into
2638 points or lines.
2639
2640
2641 TGSI_SEMANTIC_STENCIL
2642 """""""""""""""""""""
2643
2644 For fragment shaders, this semantic label indicates that an output
2645 is a writable stencil reference value. Only the Y component is writable.
2646 This allows the fragment shader to change the fragments stencilref value.
2647
2648
2649 TGSI_SEMANTIC_VIEWPORT_INDEX
2650 """"""""""""""""""""""""""""
2651
2652 For geometry shaders, this semantic label indicates that an output
2653 contains the index of the viewport (and scissor) to use.
2654 Only the X value is used.
2655
2656
2657 TGSI_SEMANTIC_LAYER
2658 """""""""""""""""""
2659
2660 For geometry shaders, this semantic label indicates that an output
2661 contains the layer value to use for the color and depth/stencil surfaces.
2662 Only the X value is used. (Also known as rendertarget array index.)
2663
2664
2665 TGSI_SEMANTIC_CULLDIST
2666 """"""""""""""""""""""
2667
2668 Used as distance to plane for performing application-defined culling
2669 of individual primitives against a plane. When components of vertex
2670 elements are given this label, these values are assumed to be a
2671 float32 signed distance to a plane. Primitives will be completely
2672 discarded if the plane distance for all of the vertices in the
2673 primitive are < 0. If a vertex has a cull distance of NaN, that
2674 vertex counts as "out" (as if its < 0);
2675 The limits on both clip and cull distances are bound
2676 by the PIPE_MAX_CLIP_OR_CULL_DISTANCE_COUNT define which defines
2677 the maximum number of components that can be used to hold the
2678 distances and by the PIPE_MAX_CLIP_OR_CULL_DISTANCE_ELEMENT_COUNT
2679 which specifies the maximum number of registers which can be
2680 annotated with those semantics.
2681
2682
2683 TGSI_SEMANTIC_CLIPDIST
2684 """"""""""""""""""""""
2685
2686 When components of vertex elements are identified this way, these
2687 values are each assumed to be a float32 signed distance to a plane.
2688 Primitive setup only invokes rasterization on pixels for which
2689 the interpolated plane distances are >= 0. Multiple clip planes
2690 can be implemented simultaneously, by annotating multiple
2691 components of one or more vertex elements with the above specified
2692 semantic. The limits on both clip and cull distances are bound
2693 by the PIPE_MAX_CLIP_OR_CULL_DISTANCE_COUNT define which defines
2694 the maximum number of components that can be used to hold the
2695 distances and by the PIPE_MAX_CLIP_OR_CULL_DISTANCE_ELEMENT_COUNT
2696 which specifies the maximum number of registers which can be
2697 annotated with those semantics.
2698
2699 TGSI_SEMANTIC_SAMPLEID
2700 """"""""""""""""""""""
2701
2702 For fragment shaders, this semantic label indicates that a system value
2703 contains the current sample id (i.e. gl_SampleID). Only the X value is used.
2704
2705 TGSI_SEMANTIC_SAMPLEPOS
2706 """""""""""""""""""""""
2707
2708 For fragment shaders, this semantic label indicates that a system value
2709 contains the current sample's position (i.e. gl_SamplePosition). Only the X
2710 and Y values are used.
2711
2712 TGSI_SEMANTIC_SAMPLEMASK
2713 """"""""""""""""""""""""
2714
2715 For fragment shaders, this semantic label indicates that an output contains
2716 the sample mask used to disable further sample processing
2717 (i.e. gl_SampleMask). Only the X value is used, up to 32x MS.
2718
2719 TGSI_SEMANTIC_INVOCATIONID
2720 """"""""""""""""""""""""""
2721
2722 For geometry shaders, this semantic label indicates that a system value
2723 contains the current invocation id (i.e. gl_InvocationID). Only the X value is
2724 used.
2725
2726 Declaration Interpolate
2727 ^^^^^^^^^^^^^^^^^^^^^^^
2728
2729 This token is only valid for fragment shader INPUT declarations.
2730
2731 The Interpolate field specifes the way input is being interpolated by
2732 the rasteriser and is one of TGSI_INTERPOLATE_*.
2733
2734 The CylindricalWrap bitfield specifies which register components
2735 should be subject to cylindrical wrapping when interpolating by the
2736 rasteriser. If TGSI_CYLINDRICAL_WRAP_X is set to 1, the X component
2737 should be interpolated according to cylindrical wrapping rules.
2738
2739
2740 Declaration Sampler View
2741 ^^^^^^^^^^^^^^^^^^^^^^^^
2742
2743 Follows Declaration token if file is TGSI_FILE_SAMPLER_VIEW.
2744
2745 DCL SVIEW[#], resource, type(s)
2746
2747 Declares a shader input sampler view and assigns it to a SVIEW[#]
2748 register.
2749
2750 resource can be one of BUFFER, 1D, 2D, 3D, 1DArray and 2DArray.
2751
2752 type must be 1 or 4 entries (if specifying on a per-component
2753 level) out of UNORM, SNORM, SINT, UINT and FLOAT.
2754
2755
2756 Declaration Resource
2757 ^^^^^^^^^^^^^^^^^^^^
2758
2759 Follows Declaration token if file is TGSI_FILE_RESOURCE.
2760
2761 DCL RES[#], resource [, WR] [, RAW]
2762
2763 Declares a shader input resource and assigns it to a RES[#]
2764 register.
2765
2766 resource can be one of BUFFER, 1D, 2D, 3D, CUBE, 1DArray and
2767 2DArray.
2768
2769 If the RAW keyword is not specified, the texture data will be
2770 subject to conversion, swizzling and scaling as required to yield
2771 the specified data type from the physical data format of the bound
2772 resource.
2773
2774 If the RAW keyword is specified, no channel conversion will be
2775 performed: the values read for each of the channels (X,Y,Z,W) will
2776 correspond to consecutive words in the same order and format
2777 they're found in memory. No element-to-address conversion will be
2778 performed either: the value of the provided X coordinate will be
2779 interpreted in byte units instead of texel units. The result of
2780 accessing a misaligned address is undefined.
2781
2782 Usage of the STORE opcode is only allowed if the WR (writable) flag
2783 is set.
2784
2785
2786 Properties
2787 ^^^^^^^^^^^^^^^^^^^^^^^^
2788
2789 Properties are general directives that apply to the whole TGSI program.
2790
2791 FS_COORD_ORIGIN
2792 """""""""""""""
2793
2794 Specifies the fragment shader TGSI_SEMANTIC_POSITION coordinate origin.
2795 The default value is UPPER_LEFT.
2796
2797 If UPPER_LEFT, the position will be (0,0) at the upper left corner and
2798 increase downward and rightward.
2799 If LOWER_LEFT, the position will be (0,0) at the lower left corner and
2800 increase upward and rightward.
2801
2802 OpenGL defaults to LOWER_LEFT, and is configurable with the
2803 GL_ARB_fragment_coord_conventions extension.
2804
2805 DirectX 9/10 use UPPER_LEFT.
2806
2807 FS_COORD_PIXEL_CENTER
2808 """""""""""""""""""""
2809
2810 Specifies the fragment shader TGSI_SEMANTIC_POSITION pixel center convention.
2811 The default value is HALF_INTEGER.
2812
2813 If HALF_INTEGER, the fractionary part of the position will be 0.5
2814 If INTEGER, the fractionary part of the position will be 0.0
2815
2816 Note that this does not affect the set of fragments generated by
2817 rasterization, which is instead controlled by half_pixel_center in the
2818 rasterizer.
2819
2820 OpenGL defaults to HALF_INTEGER, and is configurable with the
2821 GL_ARB_fragment_coord_conventions extension.
2822
2823 DirectX 9 uses INTEGER.
2824 DirectX 10 uses HALF_INTEGER.
2825
2826 FS_COLOR0_WRITES_ALL_CBUFS
2827 """"""""""""""""""""""""""
2828 Specifies that writes to the fragment shader color 0 are replicated to all
2829 bound cbufs. This facilitates OpenGL's fragColor output vs fragData[0] where
2830 fragData is directed to a single color buffer, but fragColor is broadcast.
2831
2832 VS_PROHIBIT_UCPS
2833 """"""""""""""""""""""""""
2834 If this property is set on the program bound to the shader stage before the
2835 fragment shader, user clip planes should have no effect (be disabled) even if
2836 that shader does not write to any clip distance outputs and the rasterizer's
2837 clip_plane_enable is non-zero.
2838 This property is only supported by drivers that also support shader clip
2839 distance outputs.
2840 This is useful for APIs that don't have UCPs and where clip distances written
2841 by a shader cannot be disabled.
2842
2843 GS_INVOCATIONS
2844 """"""""""""""
2845
2846 Specifies the number of times a geometry shader should be executed for each
2847 input primitive. Each invocation will have a different
2848 TGSI_SEMANTIC_INVOCATIONID system value set. If not specified, assumed to
2849 be 1.
2850
2851 VS_WINDOW_SPACE_POSITION
2852 """"""""""""""""""""""""""
2853 If this property is set on the vertex shader, the TGSI_SEMANTIC_POSITION output
2854 is assumed to contain window space coordinates.
2855 Division of X,Y,Z by W and the viewport transformation are disabled, and 1/W is
2856 directly taken from the 4-th component of the shader output.
2857 Naturally, clipping is not performed on window coordinates either.
2858 The effect of this property is undefined if a geometry or tessellation shader
2859 are in use.
2860
2861 Texture Sampling and Texture Formats
2862 ------------------------------------
2863
2864 This table shows how texture image components are returned as (x,y,z,w) tuples
2865 by TGSI texture instructions, such as :opcode:`TEX`, :opcode:`TXD`, and
2866 :opcode:`TXP`. For reference, OpenGL and Direct3D conventions are shown as
2867 well.
2868
2869 +--------------------+--------------+--------------------+--------------+
2870 | Texture Components | Gallium | OpenGL | Direct3D 9 |
2871 +====================+==============+====================+==============+
2872 | R | (r, 0, 0, 1) | (r, 0, 0, 1) | (r, 1, 1, 1) |
2873 +--------------------+--------------+--------------------+--------------+
2874 | RG | (r, g, 0, 1) | (r, g, 0, 1) | (r, g, 1, 1) |
2875 +--------------------+--------------+--------------------+--------------+
2876 | RGB | (r, g, b, 1) | (r, g, b, 1) | (r, g, b, 1) |
2877 +--------------------+--------------+--------------------+--------------+
2878 | RGBA | (r, g, b, a) | (r, g, b, a) | (r, g, b, a) |
2879 +--------------------+--------------+--------------------+--------------+
2880 | A | (0, 0, 0, a) | (0, 0, 0, a) | (0, 0, 0, a) |
2881 +--------------------+--------------+--------------------+--------------+
2882 | L | (l, l, l, 1) | (l, l, l, 1) | (l, l, l, 1) |
2883 +--------------------+--------------+--------------------+--------------+
2884 | LA | (l, l, l, a) | (l, l, l, a) | (l, l, l, a) |
2885 +--------------------+--------------+--------------------+--------------+
2886 | I | (i, i, i, i) | (i, i, i, i) | N/A |
2887 +--------------------+--------------+--------------------+--------------+
2888 | UV | XXX TBD | (0, 0, 0, 1) | (u, v, 1, 1) |
2889 | | | [#envmap-bumpmap]_ | |
2890 +--------------------+--------------+--------------------+--------------+
2891 | Z | XXX TBD | (z, z, z, 1) | (0, z, 0, 1) |
2892 | | | [#depth-tex-mode]_ | |
2893 +--------------------+--------------+--------------------+--------------+
2894 | S | (s, s, s, s) | unknown | unknown |
2895 +--------------------+--------------+--------------------+--------------+
2896
2897 .. [#envmap-bumpmap] http://www.opengl.org/registry/specs/ATI/envmap_bumpmap.txt
2898 .. [#depth-tex-mode] the default is (z, z, z, 1) but may also be (0, 0, 0, z)
2899 or (z, z, z, z) depending on the value of GL_DEPTH_TEXTURE_MODE.