summaryrefslogtreecommitdiffstats
path: root/doc/specs/vulkan/chapters/interfaces.txt
blob: 90687bc93b686a3c83e1ebfa8dcb067639863a0e (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
1866
1867
1868
1869
1870
1871
1872
1873
1874
1875
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
1902
1903
1904
1905
1906
1907
1908
1909
1910
1911
1912
1913
1914
1915
1916
1917
1918
1919
1920
1921
1922
1923
1924
1925
1926
1927
1928
1929
1930
1931
1932
1933
1934
1935
1936
1937
1938
1939
1940
1941
1942
1943
1944
1945
1946
1947
1948
1949
1950
1951
1952
1953
1954
1955
1956
1957
1958
1959
1960
1961
1962
1963
1964
1965
1966
1967
1968
1969
1970
1971
1972
1973
1974
1975
1976
1977
1978
1979
1980
1981
1982
1983
1984
1985
1986
1987
1988
1989
1990
1991
1992
1993
1994
1995
1996
1997
1998
1999
2000
2001
2002
2003
2004
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
2027
2028
2029
2030
2031
2032
2033
2034
2035
2036
2037
2038
2039
2040
2041
2042
2043
2044
2045
2046
2047
2048
2049
2050
2051
2052
2053
2054
2055
2056
2057
2058
2059
2060
2061
2062
2063
2064
2065
2066
2067
2068
2069
2070
2071
2072
2073
2074
2075
2076
2077
2078
2079
2080
2081
2082
2083
2084
2085
2086
2087
2088
2089
2090
2091
2092
2093
2094
2095
2096
2097
2098
2099
2100
2101
// Copyright (c) 2015-2017 Khronos Group. This work is licensed under a
// Creative Commons Attribution 4.0 International License; see
// http://creativecommons.org/licenses/by/4.0/

[[interfaces]]
= Shader Interfaces

When a pipeline is created, the set of shaders specified in the
corresponding stext:Vk*PipelineCreateInfo structure are implicitly linked at
a number of different interfaces.

  * <<interfaces-iointerfaces,Shader Input and Output Interface>>
  * <<interfaces-vertexinput,Vertex Input Interface>>
  * <<interfaces-fragmentoutput,Fragment Output Interface>>
  * <<interfaces-inputattachment,Fragment Input Attachment Interface>>
  * <<interfaces-resources,Shader Resource Interface>>

Interface definitions make use of the following SPIR-V decorations:

  * code:DescriptorSet and code:Binding
  * code:Location, code:Component, and code:Index
  * code:Flat, code:NoPerspective, code:Centroid, and code:Sample
  * code:Block and code:BufferBlock
  * code:InputAttachmentIndex
  * code:Offset, code:ArrayStride, and code:MatrixStride
  * code:BuiltIn
ifdef::VK_NV_geometry_shader_passthrough[]
  * <<geometry-passthrough-passthrough,code:PassthroughNV>>
endif::VK_NV_geometry_shader_passthrough[]


This specification describes valid uses for Vulkan of these decorations.
Any other use of one of these decorations is invalid.

[[interfaces-iointerfaces]]
== Shader Input and Output Interfaces

When multiple stages are present in a pipeline, the outputs of one stage
form an interface with the inputs of the next stage.
When such an interface involves a shader, shader outputs are matched against
the inputs of the next stage, and shader inputs are matched against the
outputs of the previous stage.

There are two classes of variables that can: be matched between shader
stages, built-in variables and user-defined variables.
Each class has a different set of matching criteria.
Generally, when non-shader stages are between shader stages, the
user-defined variables, and most built-in variables, form an interface
between the shader stages.

The variables forming the input or output _interfaces_ are listed as
operands to the code:OpEntryPoint instruction and are declared with the
code:Input or code:Output storage classes, respectively, in the SPIR-V
module.

code:Output variables of a shader stage have undefined values until the
shader writes to them or uses the code:Initializer operand when declaring
the variable.


[[interfaces-iointerfaces-builtin]]
=== Built-in Interface Block

Shader <<interfaces-builtin-variables,built-in>> variables meeting the
following requirements define the _built-in interface block_.
They must:

  * be explicitly declared (there are no implicit built-ins),
  * be identified with a code:BuiltIn decoration,
  * form object types as described in the
    <<interfaces-builtin-variables,Built-in Variables>> section, and
  * be declared in a block whose top-level members are the built-ins.

Built-ins only participate in interface matching if they are declared in
such a block.
They must: not have any code:Location or code:Component decorations.

There must: be no more than one built-in interface block per shader per
interface.


[[interfaces-iointerfaces-user]]
=== User-defined Variable Interface

The remaining variables listed by code:OpEntryPoint with the code:Input or
code:Output storage class form the _user-defined variable interface_.
ifdef::VK_KHR_16bit_storage[]
By default such variables have a type with a width of 32 or 64.
If an implementation supports
<<features-features-storageInputOutput16,storageInputOutput16>>,
user-defined variables in the code:Input and code:Output storage classes
can: also have types with a width of 16.
endif::VK_KHR_16bit_storage[]
These variables must: be identified with a code:Location decoration and can:
also be identified with a code:Component decoration.


[[interfaces-iointerfaces-matching]]
=== Interface Matching

A user-defined output variable is considered to match an input variable in
the subsequent stage if the two variables are declared with the same
code:Location and code:Component decoration and match in type and
decoration, except that <<shaders-interpolation-decorations,interpolation
decorations>> are not required: to match.
For the purposes of interface matching, variables declared without a
code:Component decoration are considered to have a code:Component decoration
of zero.

ifdef::VK_NV_geometry_shader_passthrough[]
[NOTE]
.Note
====
Matching rules for _passthrough geometry shaders_ are slightly different and
are described in the <<geometry-passthrough-interface,Passthrough Interface
Matching>> section.
====

endif::VK_NV_geometry_shader_passthrough[]
Variables or block members declared as structures are considered to match in
type if and only if the structure members match in type, decoration, number,
and declaration order.
Variables or block members declared as arrays are considered to match in
type only if both declarations specify the same element type and size.

Tessellation control shader per-vertex output variables and blocks, and
tessellation control, tessellation evaluation, and geometry shader
per-vertex input variables and blocks are required to be declared as arrays,
with each element representing input or output values for a single vertex of
a multi-vertex primitive.
For the purposes of interface matching, the outermost array dimension of
such variables and blocks is ignored.

At an interface between two non-fragment shader stages, the built-in
interface block must: match exactly, as described above.
At an interface involving the fragment shader inputs, the presence or
absence of any built-in output does not affect the interface matching.

At an interface between two shader stages, the user-defined variable
interface must: match exactly, as described above.

Any input value to a shader stage is well-defined as long as the preceding
stages writes to a matching output, as described above.

Additionally, scalar and vector inputs are well-defined if there is a
corresponding output satisfying all of the following conditions:

  * the input and output match exactly in decoration,
  * the output is a vector with the same basic type and has at least as many
    components as the input, and
  * the common component type of the input and output is
ifdef::VK_KHR_16bit_storage[]
    16-bit integer or floating-point, or
endif::VK_KHR_16bit_storage[]
    32-bit integer or floating-point (64-bit component types are excluded).

In this case, the components of the input will be taken from the first
components of the output, and any extra components of the output will be
ignored.


[[interfaces-iointerfaces-locations]]
=== Location Assignment

This section describes how many locations are consumed by a given type.
As mentioned above, geometry shader inputs, tessellation control shader
inputs and outputs, and tessellation evaluation inputs all have an
additional level of arrayness relative to other shader inputs and outputs.
This outer array level is removed from the type before considering how many
locations the type consumes.

The code:Location value specifies an interface slot comprised of a 32-bit
four-component vector conveyed between stages.
The code:Component specifies
<<interfaces-iointerfaces-components,components>> within these vector
locations.
Only types with widths of
ifdef::VK_KHR_16bit_storage[]
16,
endif::VK_KHR_16bit_storage[]
32 or 64 are supported in shader interfaces.

Inputs and outputs of the following types consume a single interface
location:

ifdef::VK_KHR_16bit_storage[]
  * 16-bit scalar and vector types, and
endif::VK_KHR_16bit_storage[]
  * 32-bit scalar and vector types, and
  * 64-bit scalar and 2-component vector types.

64-bit three- and four-component vectors consume two consecutive locations.

If a declared input or output is an array of size _n_ and each element takes
_m_ locations, it will be assigned _m_ {times} _n_ consecutive locations
starting with the location specified.

If the declared input or output is an _n_ {times} _m_
ifdef::VK_KHR_16bit_storage[]
16-,
endif::VK_KHR_16bit_storage[]
32- or 64-bit matrix, it will be assigned multiple locations starting with
the location specified.
The number of locations assigned for each matrix will be the same as for an
_n_-element array of _m_-component vectors.

The layout of a structure type used as an code:Input or code:Output depends
on whether it is also a code:Block (i.e. has a code:Block decoration).

If it is a not a code:Block, then the structure type must: have a
code:Location decoration.
Its members are assigned consecutive locations in their declaration order,
with the first member assigned to the location specified for the structure
type.
The members, and their nested types, must: not themselves have code:Location
decorations.

If the structure type is a code:Block but without a code:Location, then each
of its members must: have a code:Location decoration.
If it is a code:Block with a code:Location decoration, then its members are
assigned consecutive locations in declaration order, starting from the first
member which is initially assigned the location specified for the
code:Block.
Any member with its own code:Location decoration is assigned that location.
Each remaining member is assigned the location after the immediately
preceding member in declaration order.

The locations consumed by block and structure members are determined by
applying the rules above in a depth-first traversal of the instantiated
members as though the structure or block member were declared as an input or
output variable of the same type.

Any two inputs listed as operands on the same code:OpEntryPoint must: not be
assigned the same location, either explicitly or implicitly.
Any two outputs listed as operands on the same code:OpEntryPoint must: not
be assigned the same location, either explicitly or implicitly.

The number of input and output locations available for a shader input or
output interface are limited, and dependent on the shader stage as described
in <<interfaces-iointerfaces-limits>>.


[[interfaces-iointerfaces-limits]]
.Shader Input and Output Locations
[width="90%",cols="<6,<13",options="header"]
|====
| Shader Interface              | Locations Available
| vertex input                  | pname:maxVertexInputAttributes
| vertex output                 | pname:maxVertexOutputComponents / 4
| tessellation control input    | pname:maxTessellationControlPerVertexInputComponents / 4
| tessellation control output   | pname:maxTessellationControlPerVertexOutputComponents / 4
| tessellation evaluation input | pname:maxTessellationEvaluationInputComponents / 4
| tessellation evaluation output| pname:maxTessellationEvaluationOutputComponents / 4
| geometry input                | pname:maxGeometryInputComponents / 4
| geometry output               | pname:maxGeometryOutputComponents / 4
| fragment input                | pname:maxFragmentInputComponents / 4
| fragment output               | pname:maxFragmentOutputAttachments
|====


[[interfaces-iointerfaces-components]]
=== Component Assignment

The code:Component decoration allows the code:Location to be more finely
specified for scalars and vectors, down to the individual components within
a location that are consumed.
The components within a location are 0, 1, 2, and 3.
A variable or block member starting at component N will consume components
N, N+1, N+2, ...
up through its size.
ifdef::VK_KHR_16bit_storage[]
For 16-, and 32-bit types,
endif::VK_KHR_16bit_storage[]
ifndef::VK_KHR_16bit_storage[]
For single precision types,
endif::VK_KHR_16bit_storage[]
it is invalid if this sequence of components gets larger than 3.
A scalar 64-bit type will consume two of these components in sequence, and a
two-component 64-bit vector type will consume all four components available
within a location.
A three- or four-component 64-bit vector type must: not specify a
code:Component decoration.
A three-component 64-bit vector type will consume all four components of the
first location and components 0 and 1 of the second location.
This leaves components 2 and 3 available for other component-qualified
declarations.

A scalar or two-component 64-bit data type must: not specify a
code:Component decoration of 1 or 3.
A code:Component decoration must: not be specified for any type that is not
a scalar or vector.


[[interfaces-vertexinput]]
== Vertex Input Interface

When the vertex stage is present in a pipeline, the vertex shader input
variables form an interface with the vertex input attributes.
The vertex shader input variables are matched by the code:Location and
code:Component decorations to the vertex input attributes specified in the
pname:pVertexInputState member of the slink:VkGraphicsPipelineCreateInfo
structure.

The vertex shader input variables listed by code:OpEntryPoint with the
code:Input storage class form the _vertex input interface_.
These variables must: be identified with a code:Location decoration and can:
also be identified with a code:Component decoration.

For the purposes of interface matching: variables declared without a
code:Component decoration are considered to have a code:Component decoration
of zero.
The number of available vertex input locations is given by the
pname:maxVertexInputAttributes member of the sname:VkPhysicalDeviceLimits
structure.

See <<fxvertex-attrib-location>> for details.

All vertex shader inputs declared as above must: have a corresponding
attribute and binding in the pipeline.


[[interfaces-fragmentoutput]]
== Fragment Output Interface

When the fragment stage is present in a pipeline, the fragment shader
outputs form an interface with the output attachments of the current
subpass.
The fragment shader output variables are matched by the code:Location and
code:Component decorations to the color attachments specified in the
pname:pColorAttachments array of the slink:VkSubpassDescription structure
that describes the subpass that the fragment shader is executed in.

The fragment shader output variables listed by code:OpEntryPoint with the
code:Output storage class form the _fragment output interface_.
These variables must: be identified with a code:Location decoration.
They can: also be identified with a code:Component decoration and/or an
code:Index decoration.
For the purposes of interface matching: variables declared without a
code:Component decoration are considered to have a code:Component decoration
of zero, and variables declared without an code:Index decoration are
considered to have an code:Index decoration of zero.

A fragment shader output variable identified with a code:Location decoration
of _i_ is directed to the color attachment indicated by
pname:pColorAttachments[_i_], after passing through the blending unit as
described in <<framebuffer-blending>>, if enabled.
Locations are consumed as described in
<<interfaces-iointerfaces-locations,Location Assignment>>.
The number of available fragment output locations is given by the
pname:maxFragmentOutputAttachments member of the
sname:VkPhysicalDeviceLimits structure.

Components of the output variables are assigned as described in
<<interfaces-iointerfaces-components,Component Assignment>>.
Output components identified as 0, 1, 2, and 3 will be directed to the R, G,
B, and A inputs to the blending unit, respectively, or to the output
attachment if blending is disabled.
If two variables are placed within the same location, they must: have the
same underlying type (floating-point or integer).
The input to blending or color attachment writes is undefined for components
which do not correspond to a fragment shader output.

Fragment outputs identified with an code:Index of zero are directed to the
first input of the blending unit associated with the corresponding
code:Location.
Outputs identified with an code:Index of one are directed to the second
input of the corresponding blending unit.

No _component aliasing_ of output variables is allowed, that is there must:
not be two output variables which have the same location, component, and
index, either explicitly declared or implied.

Output values written by a fragment shader must: be declared with either
code:OpTypeFloat or code:OpTypeInt, and a Width of 32.
ifdef::VK_KHR_16bit_storage[]
If pname:storageInputOutput16 is supported, output values written by a
fragment shader can: be also declared with either code:OpTypeFloat or
code:OpTypeInt and a Width of 16.
endif::VK_KHR_16bit_storage[]
Composites of these types are also permitted.
If the color attachment has a signed or unsigned normalized fixed-point
format, color values are assumed to be floating-point and are converted to
fixed-point as described in <<fundamentals-fpfixedfpconv>>; If the color
attachment has an integer format, color values are assumed to be integers
and converted to the bit-depth of the target.
Any value that cannot be represented in the attachment's format is
undefined.
For any other attachment format no conversion is performed.
If the type of the values written by the fragment shader do not match the
format of the corresponding color attachment, the result is undefined for
those components.


[[interfaces-inputattachment]]
== Fragment Input Attachment Interface

When a fragment stage is present in a pipeline, the fragment shader subpass
inputs form an interface with the input attachments of the current subpass.
The fragment shader subpass input variables are matched by
code:InputAttachmentIndex decorations to the input attachments specified in
the pname:pInputAttachments array of the slink:VkSubpassDescription
structure that describes the subpass that the fragment shader is executed
in.

The fragment shader subpass input variables with the code:UniformConstant
storage class and a decoration of code:InputAttachmentIndex that are
statically used by code:OpEntryPoint form the _fragment input attachment
interface_.
These variables must: be declared with a type of code:OpTypeImage, a
code:Dim operand of code:SubpassData, and a code:Sampled operand of 2.

A subpass input variable identified with an code:InputAttachmentIndex
decoration of _i_ reads from the input attachment indicated by
pname:pInputAttachments[_i_] member of sname:VkSubpassDescription.
If the subpass input variable is declared as an array of size N, it consumes
N consecutive input attachments, starting with the index specified.
There must: not be more than one input variable with the same
code:InputAttachmentIndex whether explicitly declared or implied by an array
declaration.
The number of available input attachment indices is given by the
pname:maxPerStageDescriptorInputAttachments member of the
sname:VkPhysicalDeviceLimits structure.

Variables identified with the code:InputAttachmentIndex must: only be used
by a fragment stage.
The basic data type (floating-point, integer, unsigned integer) of the
subpass input must: match the basic format of the corresponding input
attachment, or the values of subpass loads from these variables are
undefined.

See <<descriptorsets-inputattachment>> for more details.


[[interfaces-resources]]
== Shader Resource Interface

When a shader stage accesses buffer or image resources, as described in the
<<descriptorsets,Resource Descriptors>> section, the shader resource
variables must: be matched with the <<descriptorsets-pipelinelayout,pipeline
layout>> that is provided at pipeline creation time.

The set of shader resources that form the _shader resource interface_ for a
stage are the variables statically used by code:OpEntryPoint with the
storage class of code:Uniform, code:UniformConstant, or code:PushConstant.
For the fragment shader, this includes the <<interfaces-inputattachment,
fragment input attachment interface>>.

The shader resource interface consists of two sub-interfaces: the push
constant interface and the descriptor set interface.


[[interfaces-resources-pushconst]]
=== Push Constant Interface

The shader variables defined with a storage class of code:PushConstant that
are statically used by the shader entry points for the pipeline define the
_push constant interface_.
They must: be:

  * typed as code:OpTypeStruct,
  * identified with a code:Block decoration, and
  * laid out explicitly using the code:Offset, code:ArrayStride, and
    code:MatrixStride decorations as specified in
    <<interfaces-resources-layout,Offset and Stride Assignment>>.

There must: be no more than one push constant block statically used per
shader entry point.

Each variable in a push constant block must: be placed at an code:Offset
such that the entire constant value is entirely contained within the
slink:VkPushConstantRange for each code:OpEntryPoint that uses it, and the
pname:stageFlags for that range must: specify the appropriate
elink:VkShaderStageFlagBits for that stage.
The code:Offset decoration for any variable in a push constant block must:
not cause the space required for that variable to extend outside the range
[eq]#[0, pname:maxPushConstantsSize)#.

Any variable in a push constant block that is declared as an array must:
only be accessed with _dynamically uniform_ indices.


[[interfaces-resources-descset]]
=== Descriptor Set Interface

The _descriptor set interface_ is comprised of the shader variables with the
storage class of code:Uniform or code:UniformConstant (including the
variables in the <<interfaces-inputattachment,fragment input attachment
interface>>) that are statically used by the shader entry points for the
pipeline.

These variables must: have code:DescriptorSet and code:Binding decorations
specified, which are assigned and matched with the
sname:VkDescriptorSetLayout objects in the pipeline layout as described in
<<interfaces-resources-setandbinding,DescriptorSet and Binding Assignment>>.

Variables identified with the code:UniformConstant storage class are used
only as handles to refer to opaque resources.
Such variables must: be typed as code:OpTypeImage, code:OpTypeSampler,
code:OpTypeSampledImage, or arrays of only these types.
Variables of type code:OpTypeImage must: have a code:Sampled operand of 1
(sampled image) or 2 (storage image).

Any array of these types must: only be indexed with constant integral
expressions, except under the following conditions:

  * For arrays of code:OpTypeImage variables with code:Sampled operand of 2,
    if the pname:shaderStorageImageArrayDynamicIndexing feature is enabled
    and the shader module declares the code:StorageImageArrayDynamicIndexing
    capability, the array must: only be indexed by dynamically uniform
    expressions.
  * For arrays of code:OpTypeSampler, code:OpTypeSampledImage variables, or
    code:OpTypeImage variables with code:Sampled operand of 1, if the
    pname:shaderSampledImageArrayDynamicIndexing feature is enabled and the
    shader module declares the code:SampledImageArrayDynamicIndexing
    capability, the array must: only be indexed by dynamically uniform
    expressions.
ifdef::VK_KHR_sampler_ycbcr_conversion[]
  * If sampler Y'C~B~C~R~ conversion is enabled, the combined image sampler
    must: be indexed only by constant integral expressions when aggregated
    into arrays in shader code, irrespective of the
    pname:shaderSampledImageArrayDynamicIndexing feature.
endif::VK_KHR_sampler_ycbcr_conversion[]

The code:Sampled code:Type of an code:OpTypeImage declaration must: match
the same basic data type as the corresponding resource, or the values
obtained by reading or sampling from this image are undefined.

The code:Image code:Format of an code:OpTypeImage declaration must: not be
*Unknown*, for variables which are used for code:OpImageRead or
code:OpImageWrite operations, except under the following conditions:

  * For code:OpImageWrite, if the pname:shaderStorageImageWriteWithoutFormat
    feature is enabled and the shader module declares the
    code:StorageImageWriteWithoutFormat capability.
  * For code:OpImageRead, if the pname:shaderStorageImageReadWithoutFormat
    feature is enabled and the shader module declares the
    code:StorageImageReadWithoutFormat capability.

Variables identified with the code:Uniform storage class are used to access
transparent buffer backed resources.
Such variables must: be:

  * typed as code:OpTypeStruct, or arrays of only this type,
  * identified with a code:Block or code:BufferBlock decoration, and
  * laid out explicitly using the code:Offset, code:ArrayStride, and
    code:MatrixStride decorations as specified in
    <<interfaces-resources-layout,Offset and Stride Assignment>>.

ifdef::VK_KHR_storage_buffer_storage_class[]
Variables identified with the code:StorageBuffer storage class are used to
access transparent buffer backed resources.
Such variables must: be:

  * typed as code:OpTypeStruct, or arrays of only this type,
  * identified with a code:Block decoration, and
  * laid out explicitly using the code:Offset, code:ArrayStride, and
    code:MatrixStride decorations as specified in
    <<interfaces-resources-layout,Offset and Stride Assignment>>.
endif::VK_KHR_storage_buffer_storage_class[]

Any array of these types must: only be indexed with constant integral
expressions, except under the following conditions.

  * For arrays of code:Block variables in the code:Uniform storage class, if
    the pname:shaderUniformBufferArrayDynamicIndexing feature is enabled and
    the shader module declares the code:UniformBufferArrayDynamicIndexing
    capability, the array must: only be indexed by dynamically uniform
    expressions.
  * For arrays of code:BufferBlock variables in the code:Uniform storage
    class
ifdef::VK_KHR_storage_buffer_storage_class[]
    or arrays of code:Block variables in the code:StorageBuffer storage
    class
endif::VK_KHR_storage_buffer_storage_class[]
    , if the pname:shaderStorageBufferArrayDynamicIndexing feature is
    enabled and the shader module declares the
    code:StorageBufferArrayDynamicIndexing capability, the array must: only
    be indexed by dynamically uniform expressions.

ifndef::VK_KHR_storage_buffer_storage_class[]
The code:Offset decoration for any variable in a code:Block must: not cause
the space required for that variable to extend outside the range [eq]#[0,
pname:maxUniformBufferRange)#.
The code:Offset decoration for any variable in a code:BufferBlock must: not
cause the space required for that variable to extend outside the range
[eq]#[0, pname:maxStorageBufferRange)#.
endif::VK_KHR_storage_buffer_storage_class[]

ifdef::VK_KHR_storage_buffer_storage_class[]
The code:Offset decoration for any member of a code:Block-decorated variable
in the code:Uniform storage class must: not cause the space required for
that variable to extend outside the range [eq]#[0,
pname:maxUniformBufferRange)#.
The code:Offset decoration for any member of a code:Block-decorated variable
in the code:StorageBuffer storage class must: not cause the space required
for that variable to extend outside the range [eq]#[0,
pname:maxStorageBufferRange)#.
endif::VK_KHR_storage_buffer_storage_class[]

Variables identified with a storage class of code:UniformConstant and a
decoration of code:InputAttachmentIndex must: be declared as described in
<<interfaces-inputattachment,Fragment Input Attachment Interface>>.

Each shader variable in the descriptor set interface must: be of a type that
corresponds to the pname:descriptorType in the descriptor set layout binding
that the variable is assigned to, as described in
<<interfaces-resources-setandbinding, DescriptorSet and Binding
Assignment>>.
See <<interfaces-resources-correspondence,Shader Resource and Descriptor
Type Correspondence>> for the relationship between shader types and
descriptor types.

[[interfaces-resources-correspondence]]
.Shader Resource and Descriptor Type Correspondence
[width="90%",cols="<1,<2",options="header"]
|====
| Resource type          | Descriptor Type
| sampler                | ename:VK_DESCRIPTOR_TYPE_SAMPLER or
                           ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER
| sampled image          | ename:VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE or
                           ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER
| storage image          | ename:VK_DESCRIPTOR_TYPE_STORAGE_IMAGE
| combined image sampler | ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER
| uniform texel buffer   | ename:VK_DESCRIPTOR_TYPE_UNIFORM_TEXEL_BUFFER
| storage texel buffer   | ename:VK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFER
| uniform buffer         | ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER or
                           ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC
| storage buffer         | ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER or
                           ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC
| input attachment       | ename:VK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT
|====

.Shader Resource and Storage Class Correspondence
[width="100%",cols="<21%,<22%,<27%,<30%",options="header"]
|====
| Resource type   | Storage Class | Type | Decoration(s)^1^
| sampler
        | code:UniformConstant | code:OpTypeSampler |
| sampled image
        | code:UniformConstant | code:OpTypeImage (code:Sampled=1)|
| storage image
        | code:UniformConstant | code:OpTypeImage (code:Sampled=2) |
| combined image sampler
        | code:UniformConstant | code:OpTypeSampledImage |
| uniform texel buffer
        | code:UniformConstant | code:OpTypeImage (code:Dim=code:Buffer, code:Sampled=1) |
| storage texel buffer
        | code:UniformConstant | code:OpTypeImage (code:Dim=code:Buffer, code:Sampled=2) |
| uniform buffer
        | code:Uniform         | code:OpTypeStruct
        | code:Block, code:Offset, (code:ArrayStride), (code:MatrixStride)
ifndef::VK_KHR_storage_buffer_storage_class[]
| storage buffer
        | code:Uniform         | code:OpTypeStruct
        | code:BufferBlock, code:Offset, (code:ArrayStride), (code:MatrixStride)
endif::VK_KHR_storage_buffer_storage_class[]
ifdef::VK_KHR_storage_buffer_storage_class[]
.2+<.^| storage buffer
        | code:Uniform         .2+<.^| code:OpTypeStruct
        | code:BufferBlock, code:Offset, (code:ArrayStride), (code:MatrixStride)
        | code:StorageBuffer | code:Block, code:Offset, (code:ArrayStride), (code:MatrixStride)
endif::VK_KHR_storage_buffer_storage_class[]
| input attachment
        | code:UniformConstant | code:OpTypeImage (code:Dim=code:SubpassData, code:Sampled=2)
        | code:InputAttachmentIndex
|====
1:: in addition to code:DescriptorSet and code:Binding


[[interfaces-resources-setandbinding]]
=== DescriptorSet and Binding Assignment

A variable decorated with a code:DescriptorSet decoration of [eq]#s# and a
code:Binding decoration of [eq]#b# indicates that this variable is
associated with the slink:VkDescriptorSetLayoutBinding that has a
pname:binding equal to [eq]#b# in pname:pSetLayouts[_s_] that was specified
in slink:VkPipelineLayoutCreateInfo.

code:DescriptorSet decoration values must: be between zero and
pname:maxBoundDescriptorSets minus one, inclusive.
code:Binding decoration values can: be any 32-bit unsigned integer value, as
described in <<descriptorsets-setlayout>>.
Each descriptor set has its own binding name space.

If the code:Binding decoration is used with an array, the entire array is
assigned that binding value.
The size of the array declaration must: be no larger than the
pname:descriptorCount of that sname:VkDescriptorSetLayoutBinding.
The index of each element of the array is referred to as the _arrayElement_.
For the purposes of interface matching and descriptor set
<<descriptorsets-updates,operations>>, if a resource variable is not an
array, it is treated as if it has an arrayElement of zero.

There is a limit on the number of resources of each type that can: be
accessed by a pipeline stage as shown in
<<interfaces-resources-limits,Shader Resource Limits>>.
The "`Resources Per Stage`" column gives the limit on the number each type
of resource that can: be statically used for an entry point in any given
stage in a pipeline.
The "`Resource Types`" column lists which resource types are counted against
the limit.
Some resource types count against multiple limits.

Not all descriptor sets and bindings specified in a pipeline layout need to
be used in a particular shader stage or pipeline.
If a variable assigned to a given code:DescriptorSet and code:Binding pair
is statically used in the entry point being compiled, the pipeline layout
must: contain a descriptor set layout binding in that descriptor set layout
and for that binding number, and that binding's pname:stageFlags must:
include the appropriate elink:VkShaderStageFlagBits for that stage.
The descriptor set layout binding must: be of a corresponding descriptor
type, as defined in <<interfaces-resources-correspondence,Shader Resource
and Descriptor Type Correspondence>>.

It is valid for multiple shader variables to be assigned the same descriptor
set and binding values, as long as all those that are statically used by the
entry point being compiled are compatible with the descriptor type in the
descriptor set layout binding.

[[interfaces-resources-limits]]
.Shader Resource Limits
[width="80%",cols="<35,<23",options="header"]
|====
| Resources per Stage                   | Resource Types
.2+<.^| pname:maxPerStageDescriptorSamplers
            | sampler           | combined image sampler
.3+<.^| pname:maxPerStageDescriptorSampledImages
            | sampled image     | combined image sampler | uniform texel buffer
.2+<.^| pname:maxPerStageDescriptorStorageImages
            | storage image     | storage texel buffer
.2+<.^| pname:maxPerStageDescriptorUniformBuffers
            | uniform buffer    | uniform buffer dynamic
.2+<.^| pname:maxPerStageDescriptorStorageBuffers
            | storage buffer    | storage buffer dynamic
| pname:maxPerStageDescriptorInputAttachments
            | input attachment^1^
|====

1::
    Input attachments can: only be used in the fragment shader stage


[[interfaces-resources-layout]]
=== Offset and Stride Assignment

All variables with a storage class of code:PushConstant or code:Uniform
must: be explicitly laid out using the code:Offset, code:ArrayStride, and
code:MatrixStride decorations.
There are two different layouts requirements depending on the specific
resources.

[[interfaces-resources-layout-std140]]
*Standard Uniform Buffer Layout*

The 'base alignment' of the type of an code:OpTypeStruct member of is
defined recursively as follows:

  * A scalar of size [eq]#N# has a base alignment of [eq]#N#.
  * A two-component vector, with components of size [eq]#N#, has a base
    alignment of [eq]#2 N#.
  * A three- or four-component vector, with components of size [eq]#N#, has
    a base alignment of [eq]#4 N#.
  * An array has a base alignment equal to the base alignment of its element
    type, rounded up to a multiple of [eq]#16#.
  * A structure has a base alignment equal to the largest base alignment of
    any of its members, rounded up to a multiple of [eq]#16#.
  * A row-major matrix of [eq]#C# columns has a base alignment equal to the
    base alignment of a vector of [eq]#C# matrix components.
  * A column-major matrix has a base alignment equal to the base alignment
    of the matrix column type.

ifdef::VK_KHR_relaxed_block_layout[]

A member is defined to 'improperly straddle' if either of the following are
true:

  * It is a vector with total size less than or equal to 16 bytes, and has
    code:Offset decorations placing its first byte at [eq]#F# and its last
    byte at [eq]#L#, where [eq]#floor(F / 16) != floor(L / 16)#.
  * It is a vector with total size greater than 16 bytes and has its
    code:Offset decorations placing its first byte at a non-integer multiple
    of 16.

endif::VK_KHR_relaxed_block_layout[]

Every member of an code:OpTypeStruct with storage class of code:Uniform and
a decoration of code:Block (uniform buffers) must: be laid out according to
the following rules:

ifndef::VK_KHR_relaxed_block_layout[]

  * The code:Offset decoration must: be a multiple of its base alignment.

endif::VK_KHR_relaxed_block_layout[]

ifdef::VK_KHR_relaxed_block_layout[]

  * The code:Offset decoration of a scalar, an array, a structure, or a
    matrix must: be a multiple of its base alignment.
  * The code:Offset decoration of a vector must: be an integer multiple of
    the base alignment of its scalar component type, and must: not
    improperly straddle, as defined above.

endif::VK_KHR_relaxed_block_layout[]

  * Any code:ArrayStride or code:MatrixStride decoration must: be an integer
    multiple of the base alignment of the array or matrix from above.
  * The code:Offset decoration of a member must: not place it between the
    end of a structure or an array and the next multiple of the base
    alignment of that structure or array.
  * The numeric order of code:Offset decorations need not follow member
    declaration order.

[NOTE]
.Note
====
The *std140 layout* in GLSL satisfies these rules.
====

[[interfaces-resources-layout-std430]]
*Standard Storage Buffer Layout*

Member variables of an code:OpTypeStruct with a storage class of
code:PushConstant (push constants), or a storage class of code:Uniform with
a decoration of code:BufferBlock (storage buffers)
ifdef::VK_KHR_storage_buffer_storage_class[]
, or a storage class of code:StorageBuffer with a decoration of code:Block
endif::VK_KHR_storage_buffer_storage_class[]
must: be laid out as <<interfaces-resources-layout-std140,above>>, except
for array and structure base alignment which do not need to be rounded up to
a multiple of [eq]#16#.

[NOTE]
.Note
====
The *std430 layout* in GLSL satisfies these rules.
====


[[interfaces-builtin-variables]]
== Built-In Variables

Built-in variables are accessed in shaders by declaring a variable decorated
with a code:BuiltIn decoration.
The meaning of each code:BuiltIn decoration is as follows.
In the remainder of this section, the name of a built-in is used
interchangeably with a term equivalent to a variable decorated with that
particular built-in.
Built-ins that represent integer values can: be declared as either signed or
unsigned 32-bit integers.

ifdef::VK_AMD_shader_explicit_vertex_parameter[]
code:BaryCoordNoPerspAMD::

The code:BaryCoordNoPerspAMD decoration can: be used to decorate a fragment
shader input variable.
This variable will contain the (I,J) pair of the barycentric coordinates
corresponding to the fragment evaluated using linear interpolation at the
pixel's center.
The K coordinate of the barycentric coordinates can: be derived given the
identity I + J + K = 1.0.

code:BaryCoordNoPerspCentroidAMD::

The code:BaryCoordNoPerspCentroidAMD decoration can: be used to decorate a
fragment shader input variable.
This variable will contain the (I,J) pair of the barycentric coordinates
corresponding to the fragment evaluated using linear interpolation at the
centroid.
The K coordinate of the barycentric coordinates can: be derived given the
identity I + J + K = 1.0.

code:BaryCoordNoPerspSampleAMD::

The code:BaryCoordNoPerspCentroidAMD decoration can: be used to decorate a
fragment shader input variable.
This variable will contain the (I,J) pair of the barycentric coordinates
corresponding to the fragment evaluated using linear interpolation at each
covered sample.
The K coordinate of the barycentric coordinates can: be derived given the
identity I + J + K = 1.0.

code:BaryCoordPullModelAMD::

The code:BaryCoordPullModelAMD decoration can: be used to decorate a
fragment shader input variable.
This variable will contain (1/W, 1/I, 1/J) evaluated at the pixel center and
can: be used to calculate gradients and then interpolate I, J, and W at any
desired sample location.

code:BaryCoordSmoothAMD::

The code:BaryCoordSmoothAMD decoration can: be used to decorate a fragment
shader input variable.
This variable will contain the (I,J) pair of the barycentric coordinates
corresponding to the fragment evaluated using perspective interpolation at
the pixel's center.
The K coordinate of the barycentric coordinates can: be derived given the
identity I + J + K = 1.0.

code:BaryCoordSmoothCentroidAMD::

The code:BaryCoordSmoothCentroidAMD decoration can: be used to decorate a
fragment shader input variable.
This variable will contain the (I,J) pair of the barycentric coordinates
corresponding to the fragment evaluated using perspective interpolation at
the centroid.
The K coordinate of the barycentric coordinates can: be derived given the
identity I + J + K = 1.0.

code:BaryCoordSmoothSampleAMD::

The code:BaryCoordSmoothCentroidAMD decoration can: be used to decorate a
fragment shader input variable.
This variable will contain the (I,J) pair of the barycentric coordinates
corresponding to the fragment evaluated using perspective interpolation at
each covered sample.
The K coordinate of the barycentric coordinates can: be derived given the
identity I + J + K = 1.0.

endif::VK_AMD_shader_explicit_vertex_parameter[]

ifdef::VK_KHR_shader_draw_parameters[]

[[interfaces-builtin-variables-baseinstance]]
code:BaseInstance::

Decorating a variable with the code:BaseInstance built-in will make that
variable contain the integer value corresponding to the first instance that
was passed to the command that invoked the current vertex shader invocation.
code:BaseInstance is the pname:firstInstance parameter to a _direct drawing
command_ or the pname:firstInstance member of a structure consumed by an
_indirect drawing command_.
+
The code:BaseInstance decoration must: be used only within vertex shaders.
+
The variable decorated with BaseInstance must: be declared using the input
storage class.
+
The variable decorated with BaseInstance must: be declared as a scalar
32-bit integer.

[[interfaces-builtin-variables-basevertex]]
code:BaseVertex::

Decorating a variable with the code:BaseVertex built-in will make that
variable contain the integer value corresponding to the first vertex or
vertex offset that was passed to the command that invoked the current vertex
shader invocation.
For _non-indexed drawing commands_, this variable is the pname:firstVertex
parameter to a _direct drawing command_ or the pname:firstVertex member of
the structure consumed by an _indirect drawing command_.
For _indexed drawing commands_, this variable is the pname:vertexOffset
parameter to a _direct drawing command_ or the pname:vertexOffset member of
the structure consumed by an _indirect drawing command_.
+
The code:BaseVertex decoration must: be used only within vertex shaders.
+
The variable decorated with code:BaseVertex must: be declared using the
input storage class.
+
The variable decorated with codeBaseVertex must: be declared as a scalar
32-bit integer.

endif::VK_KHR_shader_draw_parameters[]

code:ClipDistance::

Decorating a variable with the code:ClipDistance built-in decoration will
make that variable contain the mechanism for controlling user clipping.
code:ClipDistance is an array such that the i^th^ element of the array
specifies the clip distance for plane i.
A clip distance of 0 means the vertex is on the plane, a positive distance
means the vertex is inside the clip half-space, and a negative distance
means the point is outside the clip half-space.
+
The code:ClipDistance decoration must: be used only within vertex, fragment,
tessellation control, tessellation evaluation, and geometry shaders.
+
In vertex shaders, any variable decorated with code:ClipDistance must: be
declared using the code:Output storage class.
+
In fragment shaders, any variable decorated with code:ClipDistance must: be
declared using the code:Input storage class.
+
In tessellation control, tessellation evaluation, or geometry shaders, any
variable decorated with code:ClipDistance must: not be in a storage class
other than code:Input or code:Output.
+
Any variable decorated with code:ClipDistance must: be declared as an array
of 32-bit floating-point values.

[NOTE]
.Note
====
The array variable decorated with code:ClipDistance is explicitly sized by
the shader.
====

[NOTE]
.Note
====
In the last vertex processing stage, these values will be linearly
interpolated across the primitive and the portion of the primitive with
interpolated distances less than 0 will be considered outside the clip
volume.
If code:ClipDistance is then used by a fragment shader, code:ClipDistance
contains these linearly interpolated values.
====

code:CullDistance::

Decorating a variable with the code:CullDistance built-in decoration will
make that variable contain the mechanism for controlling user culling.
If any member of this array is assigned a negative value for all vertices
belonging to a primitive, then the primitive is discarded before
rasterization.
+
The code:CullDistance decoration must: be used only within vertex, fragment,
tessellation control, tessellation evaluation, and geometry shaders.
+
In vertex shaders, any variable decorated with code:CullDistance must: be
declared using the code:Output storage class.
+
In fragment shaders, any variable decorated with code:CullDistance must: be
declared using the code:Input storage class.
+
In tessellation control, tessellation evaluation, or geometry shaders, any
variable decorated with code:CullDistance must: not be declared in a storage
class other than input or output.
+
Any variable decorated with code:CullDistance must: be declared as an array
of 32-bit floating-point values.

[NOTE]
.Note
====
In fragment shaders, the values of the code:CullDistance array are linearly
interpolated across each primitive.
====

[NOTE]
.Note
====
If code:CullDistance decorates an input variable, that variable will contain
the corresponding value from the code:CullDistance decorated output variable
from the previous shader stage.
====

ifdef::VK_KHX_device_group[]

[[interfaces-builtin-variables-deviceindex]]
code:DeviceIndex::

The code:DeviceIndex decoration can: be applied to a shader input which will
be filled with the device index of the physical device that is executing the
current shader invocation.
This value will be in the range latexmath:[[0,max(1,physicalDeviceCount))],
where physicalDeviceCount is the pname:physicalDeviceCount member of
slink:VkDeviceGroupDeviceCreateInfoKHX.
+
The code:DeviceIndex decoration can: be used in any shader.
+
The variable decorated with code:DeviceIndex must: be declared using the
code:Input storage class.
+
The variable decorated with code:DeviceIndex must: be declared as a scalar
32-bit integer.

endif::VK_KHX_device_group[]

ifdef::VK_KHR_shader_draw_parameters[]

[[interfaces-builtin-variables-drawindex]]
code:DrawIndex::

Decorating a variable with the code:DrawIndex built-in will make that
variable contain the integer value corresponding to the zero-based index of
the drawing command that invoked the current vertex shader invocation.
For _indirect drawing commands_, code:DrawIndex begins at zero and
increments by one for each draw command executed.
The number of draw commands is given by the pname:drawCount parameter.
For _direct drawing commands_, code:DrawIndex is always zero.
code:DrawIndex is dynamically uniform.
+
The code:DrawIndex decoration must: be used only within vertex shaders.
+
The variable decorated with code:DrawIndex must: be declared using the input
storage class.
+
The variable decorated with code:DrawIndex must: be declared as a scalar
32-bit integer.

endif::VK_KHR_shader_draw_parameters[]

code:FragCoord::

Decorating a variable with the code:FragCoord built-in decoration will make
that variable contain the framebuffer coordinate
latexmath:[(x,y,z,\frac{1}{w})] of the fragment being processed.
The [eq]#(x,y)# coordinate [eq]#(0,0)# is the upper left corner of the upper
left pixel in the framebuffer.
+
When sample shading is enabled, the [eq]#x# and [eq]#y# components of
code:FragCoord reflect the location of the sample corresponding to the
shader invocation.
+
When sample shading is not enabled, the x and y components of code:FragCoord
reflect the location of the center of the pixel, [eq]#(0.5,0.5)#.
+
The [eq]#z# component of code:FragCoord is the interpolated depth value of
the primitive.
+
The [eq]#w# component is the interpolated latexmath:[\frac{1}{w}].
+
The code:FragCoord decoration must: be used only within fragment shaders.
+
The variable decorated with code:FragCoord must: be declared using the
code:Input storage class.
+
The code:Centroid interpolation decoration is ignored, but allowed, on
code:FragCoord.
+
The variable decorated with code:FragCoord must: be declared as a
four-component vector of 32-bit floating-point values.

code:FragDepth::

Decorating a variable with the code:FragDepth built-in decoration will make
that variable contain the new depth value for all samples covered by the
fragment.
This value will be used for depth testing and, if the depth test passes, any
subsequent write to the depth/stencil attachment.
+
To write to code:FragDepth, a shader must: declare the code:DepthReplacing
execution mode.
If a shader declares the code:DepthReplacing execution mode and there is an
execution path through the shader that does not set code:FragDepth, then the
fragment's depth value is undefined for executions of the shader that take
that path.
+
The code:FragDepth decoration must: be used only within fragment shaders.
+
The variable decorated with code:FragDepth must: be declared using the
code:Output storage class.
+
The variable decorated with code:FragDepth must: be declared as a scalar
32-bit floating-point value.

ifdef::VK_EXT_shader_stencil_export[]

code:FragStencilRefEXT::

Decorating a variable with the code:FragStencilRefEXT built-in decoration
will make that variable contain the stencil reference value for all samples
covered by the fragment.
This value will be used as the stencil reference value used in stencil
testing.
+
To write to code:FragStencilRefEXT, a shader must: declare the
code:StencilRefReplacingEXT execution mode.
If a shader declares the code:StencilRefReplacingEXT execution mode and
there is an execution path through the shader that does not set
code:FragStencilRefEXT, then the fragment's stencil reference value is
undefined for executions of the shader that take that path.
+
The code:FragStencilRefEXT decoration must: be used only within fragment
shaders.
+
The variable decorated with code:FragStencilRefEXT must: be declared using
the code:Output storage class.
+
The variable decorated with code:FragStencilRefEXT must: be declared as a
scalar integer value.
Only the least significant *s* bits of the integer value of the variable
decorated with code:FragStencilRefEXT are considered for stencil testing,
where *s* is the number of bits in the stencil framebuffer attachment,
and higher order bits are discarded.

endif::VK_EXT_shader_stencil_export[]

code:FrontFacing::

Decorating a variable with the code:FrontFacing built-in decoration will
make that variable contain whether the fragment is front or back facing.
This variable is non-zero if the current fragment is considered to be part
of a <<primsrast-polygons-basic,front-facing>> polygon primitive or of a
non-polygon primitive and is zero if the fragment is considered to be part
of a back-facing polygon primitive.
+
The code:FrontFacing decoration must: be used only within fragment shaders.
+
The variable decorated with code:FrontFacing must: be declared using the
code:Input storage class.
+
The variable decorated with code:FrontFacing must: be declared as a boolean.

code:GlobalInvocationId::

Decorating a variable with the code:GlobalInvocationId built-in decoration
will make that variable contain the location of the current invocation
within the global workgroup.
Each component is equal to the index of the local workgroup multiplied by
the size of the local workgroup plus code:LocalInvocationId.
+
The code:GlobalInvocationId decoration must: be used only within compute
shaders.
+
The variable decorated with code:GlobalInvocationId must: be declared using
the code:Input storage class.
+
The variable decorated with code:GlobalInvocationId must: be declared as a
three-component vector of 32-bit integers.

code:HelperInvocation::

Decorating a variable with the code:HelperInvocation built-in decoration
will make that variable contain whether the current invocation is a helper
invocation.
This variable is non-zero if the current fragment being shaded is a helper
invocation and zero otherwise.
A helper invocation is an invocation of the shader that is produced to
satisfy internal requirements such as the generation of derivatives.
+
The code:HelperInvocation decoration must: be used only within fragment
shaders.
+
The variable decorated with code:HelperInvocation must: be declared using
the code:Input storage class.
+
The variable decorated with code:HelperInvocation must: be declared as a
boolean.

[NOTE]
.Note
====
It is very likely that a helper invocation will have a value of
code:SampleMask fragment shader input value that is zero.
====

code:InvocationId::

Decorating a variable with the code:InvocationId built-in decoration will
make that variable contain the index of the current shader invocation in a
geometry shader, or the index of the output patch vertex in a tessellation
control shader.
+
In a geometry shader, the index of the current shader invocation ranges from
zero to the number of <<geometry-invocations,instances>> declared in the
shader minus one.
If the instance count of the geometry shader is one or is not specified,
then code:InvocationId will be zero.
+
The code:InvocationId decoration must: be used only within tessellation
control and geometry shaders.
+
The variable decorated with code:InvocationId must: be declared using the
code:Input storage class.
+
The variable decorated with code:InvocationId must: be declared as a scalar
32-bit integer.

code:InstanceIndex::

Decorating a variable with the code:InstanceIndex built-in decoration will
make that variable contain the index of the instance that is being processed
by the current vertex shader invocation.
code:InstanceIndex begins at the pname:firstInstance parameter to
flink:vkCmdDraw or flink:vkCmdDrawIndexed or at the pname:firstInstance
member of a structure consumed by flink:vkCmdDrawIndirect or
flink:vkCmdDrawIndexedIndirect.
+
The code:InstanceIndex decoration must: be used only within vertex shaders.
+
The variable decorated with code:InstanceIndex must: be declared using the
code:Input storage class.
+
The variable decorated with code:InstanceIndex must: be declared as a scalar
32-bit integer.

[[interfaces-builtin-variables-layer]]
code:Layer::

Decorating a variable with the code:Layer built-in decoration will make that
variable contain the select layer of a multi-layer framebuffer attachment.
+
In a
ifdef::VK_NV_viewport_array2,VK_EXT_shader_viewport_index_layer[]
vertex, tessellation evaluation, or
endif::VK_NV_viewport_array2,VK_EXT_shader_viewport_index_layer[]
geometry shader, any variable decorated with code:Layer can be written with
the framebuffer layer index to which the primitive produced by that shader
will be directed.
ifdef::VK_NV_viewport_array2,VK_EXT_shader_viewport_index_layer[]
+
The last active _vertex processing stage_ (in pipeline order) controls the
code:Layer that is used.
Outputs in previous shader stages are not used, even if the last stage fails
to write the code:Layer.
endif::VK_NV_viewport_array2,VK_EXT_shader_viewport_index_layer[]
+
If the last active vertex processing stage shader entry point's interface
does not include a variable decorated with code:Layer, then the first layer
is used.
If a vertex processing stage shader entry point's interface includes a
variable decorated with code:Layer, it must: write the same value to
code:Layer for all output vertices of a given primitive.
If the code:Layer value is less than 0 or greater than or equal to the
number of layers in the framebuffer, then primitives may: still be
rasterized, fragment shaders may: be executed, and the framebuffer values
for all layers are undefined.
+
The code:Layer decoration must: be used only within
ifdef::VK_NV_viewport_array2,VK_EXT_shader_viewport_index_layer[]
vertex, tessellation evaluation,
endif::VK_NV_viewport_array2,VK_EXT_shader_viewport_index_layer[]
geometry, and fragment shaders.
+
In a
ifdef::VK_NV_viewport_array2,VK_EXT_shader_viewport_index_layer[]
vertex, tessellation evaluation, or
endif::VK_NV_viewport_array2,VK_EXT_shader_viewport_index_layer[]
geometry shader, any variable decorated with code:Layer must: be declared
using the code:Output storage class.
ifdef::VK_NV_viewport_array2[]
If such a variable is also decorated with code:ViewportRelativeNV, then the
code:ViewportIndex is added to the layer that is used for rendering and that
is made available in the fragment shader.
If the shader writes to a variable decorated code:ViewportMaskNV, then the
layer selected has a different value for each viewport a primitive is
rendered to.
endif::VK_NV_viewport_array2[]
+
In a fragment shader, a variable decorated with code:Layer contains the
layer index of the primitive that the fragment invocation belongs to.
+
In a fragment shader, any variable decorated with code:Layer must: be
declared using the code:Input storage class.
+
Any variable decorated with code:Layer must: be declared as a scalar 32-bit
integer.

code:LocalInvocationId::

Decorating a variable with the code:LocalInvocationId built-in decoration
will make that variable contain the location of the current compute shader
invocation within the local workgroup.
Each component ranges from zero through to the size of the workgroup in that
dimension minus one.
+
The code:LocalInvocationId decoration must: be used only within compute
shaders.
+
The variable decorated with code:LocalInvocationId must: be declared using
the code:Input storage class.
+
The variable decorated with code:LocalInvocationId must: be declared as a
three-component vector of 32-bit integers.

[NOTE]
.Note
====
If the size of the workgroup in a particular dimension is one, then the
code:LocalInvocationId in that dimension will be zero.
If the workgroup is effectively two-dimensional, then
code:LocalInvocationId.z will be zero.
If the workgroup is effectively one-dimensional, then both
code:LocalInvocationId.y and code:LocalInvocationId.z will be zero.
====

code:NumWorkgroups::

Decorating a variable with the code:NumWorkgroups built-in decoration will
make that variable contain the number of local workgroups that are part of
the dispatch that the invocation belongs to.
Each component is equal to the values of the workgroup count parameters
passed into the dispatch commands.
+
The code:NumWorkgroups decoration must: be used only within compute shaders.
+
The variable decorated with code:NumWorkgroups must: be declared using the
code:Input storage class.
+
The variable decorated with code:NumWorkgroups must: be declared as a
three-component vector of 32-bit integers.

code:PatchVertices::

Decorating a variable with the code:PatchVertices built-in decoration will
make that variable contain the number of vertices in the input patch being
processed by the shader.
A single tessellation control or tessellation evaluation shader can: read
patches of differing sizes, so the value of the code:PatchVertices variable
may: differ between patches.
+
The code:PatchVertices decoration must: be used only within tessellation
control and tessellation evaluation shaders.
+
The variable decorated with code:PatchVertices must: be declared using the
code:Input storage class.
+
The variable decorated with code:PatchVertices must: be declared as a scalar
32-bit integer.

code:PointCoord::

Decorating a variable with the code:PointCoord built-in decoration will make
that variable contain the coordinate of the current fragment within the
point being rasterized, normalized to the size of the point with origin in
the upper left corner of the point, as described in
<<primsrast-points-basic,Basic Point Rasterization>>.
If the primitive the fragment shader invocation belongs to is not a point,
then the variable decorated with code:PointCoord contains an undefined
value.
+
The code:PointCoord decoration must: be used only within fragment shaders.
+
The variable decorated with code:PointCoord must: be declared using the
code:Input storage class.
+
The variable decorated with code:PointCoord must: be declared as
two-component vector of 32-bit floating-point values.

[NOTE]
.Note
====
Depending on how the point is rasterized, code:PointCoord may: never reach
[eq]#(0,0)# or [eq]#(1,1)#.
====

code:PointSize::

Decorating a variable with the code:PointSize built-in decoration will make
that variable contain the size of point primitives.
The value written to the variable decorated with code:PointSize by the last
vertex processing stage in the pipeline is used as the framebuffer-space
size of points produced by rasterization.
+
The code:PointSize decoration must: be used only within vertex, tessellation
control, tessellation evaluation, and geometry shaders.
+
In a vertex shader, any variable decorated with code:PointSize must: be
declared using the code:Output storage class.
+
In a tessellation control, tessellation evaluation, or geometry shader, any
variable decorated with code:PointSize must: be declared using either the
code:Input or code:Output storage class.
+
Any variable decorated with code:PointSize must: be declared as a scalar
32-bit floating-point value.

[NOTE]
.Note
====
When code:PointSize decorates a variable in the code:Input storage class, it
contains the data written to the output variable decorated with
code:PointSize from the previous shader stage.
====

code:Position::

Decorating a variable with the code:Position built-in decoration will make
that variable contain the position of the current vertex.
In the last vertex processing stage, the value of the variable decorated
with code:Position is used in subsequent primitive assembly, clipping, and
rasterization operations.
+
The code:Position decoration must: be used only within vertex, tessellation
control, tessellation evaluation, and geometry shaders.
+
In a vertex shader, any variable decorated with code:Position must: be
declared using the code:Output storage class.
+
In a tessellation control, tessellation evaluation, or geometry shader, any
variable decorated with code:Position must: not be declared in a storage
class other than code:Input or code:Output.
+
Any variable decorated with code:Position must: be declared as a
four-component vector of 32-bit floating-point values.

[NOTE]
.Note
====
When code:Position decorates a variable in the code:Input storage class, it
contains the data written to the output variable decorated with
code:Position from the previous shader stage.
====

ifdef::VK_NVX_multiview_per_view_attributes[]
[[interfaces-builtin-variables-positionperview]]
code:PositionPerViewNV::

Decorating a variable with the code:PositionPerViewNV built-in decoration
will make that variable contain the position of the current vertex, for each
view.
+
The code:PositionPerViewNV decoration must: be used only within vertex,
tessellation control, tessellation evaluation, and geometry shaders.
+
In a vertex shader, any variable decorated with code:PositionPerViewNV must:
be declared using the code:Output storage class.
+
In a tessellation control, tessellation evaluation, or geometry shader, any
variable decorated with code:PositionPerViewNV must: not be declared in a
storage class other than input or output.
+
Any variable decorated with code:PositionPerViewNV must: be declared as an
array of four-component vector of 32-bit floating-point values with at least
as many elements as the maximum view in the subpass's view mask plus one.
The array must: be indexed by a constant or specialization constant.
+
Elements of the array correspond to views in a multiview subpass, and those
elements corresponding to views in the view mask of the subpass the shader
is compiled against will be used as the position value for those views.
For the final vertex processing stage in the pipeline, values written to an
output variable decorated with code:PositionPerViewNV are used in subsequent
primitive assembly, clipping, and rasterization operations, as with
code:Position.
code:PositionPerViewNV output in an earlier vertex processing stage is
available as an input in the subsequent vertex processing stage.
+
If a shader is compiled against a subpass that has the
ename:VK_SUBPASS_DESCRIPTION_PER_VIEW_POSITION_X_ONLY_BIT_NVX bit set, then
the position values for each view must: not differ in any component other
than the X component.
If the values do differ, one will be chosen in an implementation-dependent
manner.
endif::VK_NVX_multiview_per_view_attributes[]

code:PrimitiveId::

Decorating a variable with the code:PrimitiveId built-in decoration will
make that variable contain the index of the current primitive.
+
In tessellation control and tessellation evaluation shaders, it will contain
the index of the patch within the current set of rendering primitives that
correspond to the shader invocation.
+
In a geometry shader, it will contain the number of primitives presented as
input to the shader since the current set of rendering primitives was
started.
+
In a fragment shader, it will contain the primitive index written by the
geometry shader if a geometry shader is present, or with the value that
would have been presented as input to the geometry shader had it been
present.
+
If a geometry shader is present and the fragment shader reads from an input
variable decorated with code:PrimitiveId, then the geometry shader must:
write to an output variable decorated with code:PrimitiveId in all execution
paths.
+
The code:PrimitiveId decoration must: be used only within fragment,
tessellation control, tessellation evaluation, and geometry shaders.
+
In a tessellation control or tessellation evaluation shader, any variable
decorated with code:PrimitiveId must: be declared using the code:Output
storage class.
+
In a geometry shader, any variable decorated with code:PrimitiveId must: be
declared using either the code:Input or code:Output storage class.
+
In a fragment shader, any variable decorated with code:PrimitiveId must: be
declared using the code:Input storage class, and either the code:Geometry or
code:Tessellation capability must: also be declared.
+
Any variable decorated with code:PrimitiveId must: be declared as a scalar
32-bit integer.

[NOTE]
.Note
====
When the code:PrimitiveId decoration is applied to an output variable in the
geometry shader, the resulting value is seen through the code:PrimitiveId
decorated input variable in the fragment shader.
====

code:SampleId::

Decorating a variable with the code:SampleId built-in decoration will make
that variable contain the zero-based index of the sample the invocation
corresponds to.
code:SampleId ranges from zero to the number of samples in the framebuffer
minus one.
If a fragment shader entry point's interface includes an input variable
decorated with code:SampleId, per-sample shading is enabled for draws that
use that fragment shader.
+
The code:SampleId decoration must: be used only within fragment shaders.
+
The variable decorated with code:SampleId must: be declared using the
code:Input storage class.
+
The variable decorated with code:SampleId must: be declared as a scalar
32-bit integer.

[[interfaces-builtin-variables-samplemask]]
code:SampleMask::

Decorating a variable with the code:SampleMask built-in decoration will make
any variable contain the sample coverage mask for the current fragment
shader invocation.
+
A variable in the code:Input storage class decorated with code:SampleMask
will contain a bitmask of the set of samples covered by the primitive
generating the fragment during rasterization.
It has a sample bit set if and only if the sample is considered covered for
this fragment shader invocation.
code:SampleMask[] is an array of integers.
Bits are mapped to samples in a manner where bit B of mask M
(`SampleMask[M]`) corresponds to sample [eq]#32 {times} M {plus} B#.
+
When state specifies multiple fragment shader invocations for a given
fragment, the sample mask for any single fragment shader invocation
specifies the subset of the covered samples for the fragment that correspond
to the invocation.
In this case, the bit corresponding to each covered sample will be set in
exactly one fragment shader invocation.

ifdef::VK_EXT_post_depth_coverage[]
+
If the
<<shaders-fragment-earlytest-postdepthcoverage,code:PostDepthCoverage>>
execution mode is specified, the sample is considered covered if and only if
the sample is covered by the primitive and the sample passes the
<<fragops-early,early per-fragment tests>>.
Otherwise the sample is considered covered if the sample is covered by the
primitive, regardless of the result of the fragment tests.
endif::VK_EXT_post_depth_coverage[]
+
A variable in the code:Output storage class decorated with code:SampleMask
is an array of integers forming a bit array in a manner similar an input
variable decorated with code:SampleMask, but where each bit represents
coverage as computed by the shader.
Modifying the sample mask by writing zero to a bit of code:SampleMask causes
the sample to be considered uncovered.
ifndef::VK_NV_sample_mask_override_coverage[]
However, setting sample mask bits to one will never enable samples not
covered by the original primitive.
endif::VK_NV_sample_mask_override_coverage[]
ifdef::VK_NV_sample_mask_override_coverage[]
If this variable is also decorated with code:OverrideCoverageNV, the
fragment coverage is replaced with the sample mask bits set in the shader
otherwise the fragment coverage is code:ANDed with the bits of the sample
mask.
endif::VK_NV_sample_mask_override_coverage[]
If the fragment shader is being evaluated at any frequency other than
per-fragment, bits of the sample mask not corresponding to the current
fragment shader invocation are ignored.
This array must: be sized in the fragment shader either implicitly or
explicitly, to be no larger than the implementation-dependent maximum
sample-mask (as an array of 32-bit elements), determined by the maximum
number of samples.
If a fragment shader entry point's interface includes an output variable
decorated with code:SampleMask, the sample mask will be undefined for any
array elements of any fragment shader invocations that fail to assign a
value.
If a fragment shader entry point's interface does not include an output
variable decorated with code:SampleMask, the sample mask has no effect on
the processing of a fragment.
+
The code:SampleMask decoration must: be used only within fragment shaders.
+
Any variable decorated with code:SampleMask must: be declared using either
the code:Input or code:Output storage class.
+
Any variable decorated with code:SampleMask must: be declared as an array of
32-bit integers.

code:SamplePosition::

Decorating a variable with the code:SamplePosition built-in decoration will
make that variable contain the sub-pixel position of the sample being
shaded.
The top left of the pixel is considered to be at coordinate [eq]#(0,0)# and
the bottom right of the pixel is considered to be at coordinate [eq]#(1,1)#.
If a fragment shader entry point's interface includes an input variable
decorated with code:SamplePosition, per-sample shading is enabled for draws
that use that fragment shader.
+
The code:SamplePosition decoration must: be used only within fragment
shaders.
+
The variable decorated with code:SamplePosition must: be declared using the
code:Input storage class.
ifdef::VK_EXT_sample_locations[]
If the current pipeline uses <<primrast-samplelocations, custom sample
locations>> the value of any variable decorated with the code:SamplePosition
built-in decoration is undefined.
endif::VK_EXT_sample_locations[]
+
The variable decorated with code:SamplePosition must: be declared as a
two-component vector of 32-bit floating-point values.

ifdef::VK_EXT_shader_subgroup_ballot[]

[[interfaces-builtin-variables-sgeq]]
code:SubgroupEqMaskKHR::
+
Decorating a variable with the code:SubgroupEqMaskKHR builtin decoration
will make that variable contain the _subgroup mask_ of the current subgroup
invocation.
The bit corresponding to the code:SubgroupLocalInvocationId is set in the
variable decorated with code:SubgroupEqMaskKHR.
All other bits are set to zero.
+
The variable decorated with code:SubgroupEqMaskKHR must: be declared using
the code:Input storage class.
+
The variable decorated with code:SubgroupEqMaskKHR must: be declared as a
four-component vector of 32-bit integer values.

[[interfaces-builtin-variables-sgge]]
code:SubgroupGeMaskKHR::
+
Decorating a variable with the code:SubgroupGeMaskKHR builtin decoration
will make that variable contain the _subgroup mask_ of the invocations
greater than or equal to the current subgroup invocation.
The bits corresponding to the invocations greather than or equal to
code:SubgroupLocalInvocationId through code:SubgroupSize-1 are set in the
variable decorated with code:SubgroupGeMaskKHR.
All other bits are set to zero.
+
The variable decorated with code:SubgroupGeMaskKHR must: be declared using
the code:Input storage class.
+
The variable decorated with code:SubgroupGeMaskKHR must: be declared as a
four-component vector of 32-bit integer values.

[[interfaces-builtin-variables-sggt]]
code:SubgroupGtMaskKHR::
+
Decorating a variable with the code:SubgroupGtMaskKHR builtin decoration
will make that variable contain the _subgroup mask_ of the invocations
greater than the current subgroup invocation.
The bits corresponding to the invocations greater than
code:SubgroupLocalInvocationId through code:SubgroupSize-1 are set in the
variable decorated with code:SubgroupGtMaskKHR.
All other bits are set to zero.
+
The variable decorated with code:SubgroupGtMaskKHR must: be declared using
the code:Input storage class.
+
The variable decorated with code:SubgroupGtMaskKHR must: be declared as a
four-component vector of 32-bit integer values.

[[interfaces-builtin-variables-sgle]]
code:SubgroupLeMaskKHR::
+
Decorating a variable with the code:SubgroupLeMaskKHR builtin decoration
will make that variable contain the _subgroup mask_ of the invocations less
than or equal to the current subgroup invocation.
The bits corresponding to the invocations less than or equal to
code:SubgroupLocalInvocationId are set in the variable decorated with
code:SubgroupLeMaskKHR.
All other bits are set to zero.
+
The variable decorated with code:SubgroupLeMaskKHR must: be declared using
the code:Input storage class.
+
The variable decorated with code:SubgroupLeMaskKHR must: be declared as a
four-component vector of 32-bit integer values.

[[interfaces-builtin-variables-sglt]]
code:SubgroupLtMaskKHR::
+
Decorating a variable with the code:SubgroupLtMaskKHR builtin decoration
will make that variable contain the _subgroup mask_ of the invocations less
than the current subgroup invocation.
The bits corresponding to the invocations less than
code:SubgroupLocalInvocationId are set in the variable decorated with
code:SubgroupLtMaskKHR.
All other bits are set to zero.
+
The variable decorated with code:SubgroupLtMaskKHR must: be declared using
the code:Input storage class.
+
The variable decorated with code:SubgroupLtMaskKHR must: be declared as a
four-component vector of 32-bit integer values.

[[interfaces-builtin-variables-sgli]]
code:SubgroupLocalInvocationId::
+
Decorating a variable with the code:SubgroupLocalInvocationId builtin
decoration will make that variable contain the index of the invocation
within the subgroup.
This variable is in range [0,code:SubgroupSize-1].
+
The variable decorated with code:SubgroupLocalInvocationId must: be declared
using the code:Input storage class.
+
The variable decorated with code:SubgroupLocalInvocationId must: be declared
as a scalar 32-bit integer.

[[interfaces-builtin-variables-sgs]]
code:SubgroupSize::
+
Decorating a variable with the code:SubgroupSize builtin decoration will
make that variable contain the implementation-dependent maximum number of
invocations in a subgroup.
The maximum number of invocations that an implementation can support per
subgroup is 128.
+
The variable decorated with code:SubgroupSize must: be declared using the
code:Input storage class.
+
The variable decorated with code:SubgroupSize must: be declared as a scalar
32-bit integer.

endif::VK_EXT_shader_subgroup_ballot[]

code:TessCoord::

Decorating a variable with the code:TessCoord built-in decoration will make
that variable contain the three-dimensional [eq]#(u,v,w)# barycentric
coordinate of the tessellated vertex within the patch.
[eq]#u#, [eq]#v#, and [eq]#w# are in the range [eq]#[0,1]# and vary linearly
across the primitive being subdivided.
For the tessellation modes of code:Quads or code:IsoLines, the third
component is always zero.
+
The code:TessCoord decoration must: be used only within tessellation
evaluation shaders.
+
The variable decorated with code:TessCoord must: be declared using the
code:Input storage class.
+
The variable decorated with code:TessCoord must: be declared as
three-component vector of 32-bit floating-point values.

code:TessLevelOuter::

Decorating a variable with the code:TessLevelOuter built-in decoration will
make that variable contain the outer tessellation levels for the current
patch.
+
In tessellation control shaders, the variable decorated with
code:TessLevelOuter can: be written to which controls the tessellation
factors for the resulting patch.
These values are used by the tessellator to control primitive tessellation
and can: be read by tessellation evaluation shaders.
+
In tessellation evaluation shaders, the variable decorated with
code:TessLevelOuter can: read the values written by the tessellation control
shader.
+
The code:TessLevelOuter decoration must: be used only within tessellation
control and tessellation evaluation shaders.
+
In a tessellation control shader, any variable decorated with
code:TessLevelOuter must: be declared using the code:Output storage class.
+
In a tessellation evaluation shader, any variable decorated with
code:TessLevelOuter must: be declared using the code:Input storage class.
+
Any variable decorated with code:TessLevelOuter must: be declared as an
array of size four, containing 32-bit floating-point values.

code:TessLevelInner::

Decorating a variable with the code:TessLevelInner built-in decoration will
make that variable contain the inner tessellation levels for the current
patch.
+
In tessellation control shaders, the variable decorated with
code:TessLevelInner can: be written to, which controls the tessellation
factors for the resulting patch.
These values are used by the tessellator to control primitive tessellation
and can: be read by tessellation evaluation shaders.
+
In tessellation evaluation shaders, the variable decorated with
code:TessLevelInner can: read the values written by the tessellation control
shader.
+
The code:TessLevelInner decoration must: be used only within tessellation
control and tessellation evaluation shaders.
+
In a tessellation control shader, any variable decorated with
code:TessLevelInner must: be declared using the code:Output storage class.
+
In a tessellation evaluation shader, any variable decorated with
code:TessLevelInner must: be declared using the code:Input storage class.
+
Any variable decorated with code:TessLevelInner must: be declared as an
array of size two, containing 32-bit floating-point values.

code:VertexIndex::

Decorating a variable with the code:VertexIndex built-in decoration will
make that variable contain the index of the vertex that is being processed
by the current vertex shader invocation.
For non-indexed draws, this variable begins at the pname:firstVertex
parameter to flink:vkCmdDraw or the pname:firstVertex member of a structure
consumed by flink:vkCmdDrawIndirect and increments by one for each vertex in
the draw.
For indexed draws, its value is the content of the index buffer for the
vertex plus the pname:vertexOffset parameter to flink:vkCmdDrawIndexed or
the pname:vertexOffset member of the structure consumed by
flink:vkCmdDrawIndexedIndirect.
+
The code:VertexIndex decoration must: be used only within vertex shaders.
+
The variable decorated with code:VertexIndex must: be declared using the
code:Input storage class.
+
The variable decorated with code:VertexIndex must: be declared as a scalar
32-bit integer.

[NOTE]
.Note
====
code:VertexIndex starts at the same starting value for each instance.
====

ifdef::VK_KHX_multiview[]

[[interfaces-builtin-variables-viewindex]]
code:ViewIndex::

The code:ViewIndex decoration can: be applied to a shader input which will
be filled with the index of the view that is being processed by the current
shader invocation.
+
If multiview is enabled in the render pass, this value will be one of the
bits set in the view mask of the subpass the pipeline is compiled against.
If multiview is not enabled in the render pass, this value will be zero.
+
The code:ViewIndex decoration must: not be used within compute shaders.
+
The variable decorated with code:ViewIndex must: be declared using the
code:Input storage class.
+
The variable decorated with code:ViewIndex must: be declared as a scalar
32-bit integer.

endif::VK_KHX_multiview[]

[[interfaces-builtin-variables-viewportindex]]
code:ViewportIndex::

Decorating a variable with the code:ViewportIndex built-in decoration will
make that variable contain the index of the viewport.
+
In a
ifdef::VK_NV_viewport_array2,VK_EXT_shader_viewport_index_layer[]
vertex, tessellation evaluation, or
endif::VK_NV_viewport_array2,VK_EXT_shader_viewport_index_layer[]
geometry shader, the variable decorated with code:ViewportIndex can be
written to with the viewport index to which the primitive produced by that
shader will be directed.
+
The selected viewport index is used to select the viewport transform and
scissor rectangle.
ifdef::VK_NV_viewport_array2,VK_EXT_shader_viewport_index_layer[]
+
The last active _vertex processing stage_ (in pipeline order) controls the
code:ViewportIndex that is used.
Outputs in previous shader stages are not used, even if the last stage fails
to write the code:ViewportIndex.
endif::VK_NV_viewport_array2,VK_EXT_shader_viewport_index_layer[]
+
If the last active vertex processing stage shader entry point's interface
does not include a variable decorated with code:ViewportIndex, then the
first viewport is used.
If a vertex processing stage shader entry point's interface includes a
variable decorated with code:ViewportIndex, it must: write the same value to
code:ViewportIndex for all output vertices of a given primitive.
+
The code:ViewportIndex decoration must: be used only within
ifdef::VK_NV_viewport_array2,VK_EXT_shader_viewport_index_layer[]
vertex, tessellation evaluation,
endif::VK_NV_viewport_array2,VK_EXT_shader_viewport_index_layer[]
geometry, and fragment shaders.
+
In a
ifdef::VK_NV_viewport_array2,VK_EXT_shader_viewport_index_layer[]
vertex, tessellation evaluation, or
endif::VK_NV_viewport_array2,VK_EXT_shader_viewport_index_layer[]
geometry shader, any variable decorated with code:ViewportIndex must: be
declared using the code:Output storage class.
+
In a fragment shader, the variable decorated with code:ViewportIndex
contains the viewport index of the primitive that the fragment invocation
belongs to.
+
In a fragment shader, any variable decorated with code:ViewportIndex must:
be declared using the code:Input storage class.
+
Any variable decorated with code:ViewportIndex must: be declared as a scalar
32-bit integer.

ifdef::VK_NV_viewport_array2[]
[[interfaces-builtin-variables-viewportmask]]
code:ViewportMaskNV::

Decorating a variable with the code:ViewportMaskNV built-in decoration will
make that variable contain the viewport mask.
+
In a vertex, tessellation evaluation, or geometry shader, the variable
decorated with code:ViewportMaskNV can be written to with the mask of which
viewports the primitive produced by that shader will directed.
+
The code:ViewportMaskNV variable must: be an array that has
[eq]#{lceil}(sname:VkPhysicalDeviceLimits::pname:maxViewports / 32){rceil}#
elements.
When a shader writes to this variable, bit B of element M controls whether a
primitive is emitted to viewport [eq]#32 {times} M +B#.
The viewports indicated by the mask are used to select the viewport
transform and scissor rectangle that a primitive will be transformed by.
+
The last active _vertex processing stage_ (in pipeline order) controls the
code:ViewportMaskNV that is used.
Outputs in previous shader stages are not used, even if the last stage fails
to write the code:ViewportMaskNV.
When code:ViewportMaskNV is written by the final vertex processing stage,
any variable decorated with code:ViewportIndex in the fragment shader will
have the index of the viewport that was used in generating that fragment.
+
If a vertex processing stage shader entry point's interface includes a
variable decorated with code:ViewportMaskNV, it must: write the same value
to code:ViewportMaskNV for all output vertices of a given primitive.
+
The code:ViewportMaskNV decoration must: be used only within vertex,
tessellation evaluation, and geometry shaders.
+
Any variable decorated with code:ViewportMaskNV must: be declared using the
code:Output storage class.
+
Any variable decorated with code:ViewportMaskNV must: be declared as an
array of 32-bit integers.
endif::VK_NV_viewport_array2[]

ifdef::VK_NVX_multiview_per_view_attributes+VK_NV_viewport_array2[]
[[interfaces-builtin-variables-viewportmaskperview]]
code:ViewportMaskPerViewNV::

Decorating a variable with the code:ViewportMaskPerViewNV built-in
decoration will make that variable contain the mask of viewports primitives
are broadcast to, for each view.
+
The code:ViewportMaskPerViewNV decoration must: be used only within vertex,
tessellation control, tessellation evaluation, and geometry shaders.
+
Any variable decorated with code:ViewportMaskPerViewNV must: be declared
using the code:Output storage class.
+
The value written to an element of code:ViewportMaskPerViewNV in the last
vertex processing stage is a bitmask indicating which viewports the
primitive will be directed to.
The primitive will be broadcast to the viewport corresponding to each
non-zero bit of the bitmask, and that viewport index is used to select the
viewport transform and scissor rectangle, for each view.
The same values must: be written to all vertices in a given primitive, or
else the set of viewports used for that primitive is undefined.
+
Any variable decorated with code:ViewportMaskPerViewNV must: be declared as
an array of scalar 32-bit integers with at least as many elements as the
maximum view in the subpass's view mask plus one.
The array must: be indexed by a constant or specialization constant.
+
Elements of the array correspond to views in a multiview subpass, and those
elements corresponding to views in the view mask of the subpass the shader
is compiled against will be used as the viewport mask value for those views.
code:ViewportMaskPerViewNV output in an earlier vertex processing stage is
not available as an input in the subsequent vertex processing stage.
+
Although code:ViewportMaskNV is an array, code:ViewportMaskPerViewNV is not
a two-dimensional array.
Instead, code:ViewportMaskPerViewNV is limited to 32 viewports.
endif::VK_NVX_multiview_per_view_attributes+VK_NV_viewport_array2[]

code:WorkgroupId::

Decorating a variable with the code:WorkgroupId built-in decoration will
make that variable contain the global workgroup that the current invocation
is a member of.
Each component ranges from a base value to a [eq]#base {plus} count# value,
based on the parameters passed into the dispatch commands.
+
The code:WorkgroupId decoration must: be used only within compute shaders.
+
The variable decorated with code:WorkgroupId must: be declared using the
code:Input storage class.
+
The variable decorated with code:WorkgroupId must: be declared as a
three-component vector of 32-bit integers.

code:WorkgroupSize::

Decorating an object with the code:WorkgroupSize built-in decoration will
make that object contain the dimensions of a local workgroup.
If an object is decorated with the code:WorkgroupSize decoration, this must:
take precedence over any execution mode set for code:LocalSize.
+
The code:WorkgroupSize decoration must: be used only within compute shaders.
+
The object decorated with code:WorkgroupSize must: be a specialization
constant or a constant.
+
The object decorated with code:WorkgroupSize must: be declared as a
three-component vector of 32-bit integers.