forked from KhronosGroup/Vulkan-Docs
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathregistry.txt
2104 lines (1696 loc) · 84.3 KB
/
registry.txt
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
// Copyright (c) 2013-2019 Khronos Group. This work is licensed under a
// Creative Commons Attribution 4.0 International License; see
// http://creativecommons.org/licenses/by/4.0/
= The Khronos^®^ Vulkan^®^ API Registry
Jon Leech
:data-uri:
:icons: font
:toc2:
:toclevels: 3
:max-width: 100
:numbered:
:doctype: book
:imagewidth: 800
:fullimagewidth: width="800"
:cl: :
// Various special / math symbols. This is easier to edit with than Unicode.
include::config/attribs.txt[]
:leveloffset: 1
<<<<
include::copyright-ccby.txt[]
<<<<
[[introduction]]
= Introduction
This document describes the Khronos Vulkan API Registry schema, and
provides some additional information about using the registry and
scripts to generate a variety of outputs, including C header files as
well as several types of asciidoc include files used in the Vulkan API
specification and reference pages. The underlying XML files and scripts
are located on the Khronos public Github server at URL
https://github.com/KhronosGroup/Vulkan-Docs
The authoritative copy of the Registry is maintained in the `master` branch.
[NOTE]
.Note
====
The older version of the registry in the `1.0` branch is out of date.
====
The registry uses an XML representation of the Vulkan API, together with
a set of Python scripts to manipulate the registry once loaded. The
scripts rely on the Python `etree` package to parse and operate on XML.
An XML schema and validator target are included.
The schema is based on, but not identical to that used for the previously
published OpenGL, OpenGL ES and EGL API registries. It was extended to
represent additional types and concepts not needed for those APIs, such as
structure and enumerant types, as well as additional types
of registered information specific to Vulkan.
The Vulkan C header files generated from the registry are checked in under
`include/vulkan/`.
== Schema Choices
The XML schema is not pure XML all the way down. In particular, command
return types/names and parameters, and structure members, are described in
mixed-mode tag containing C declarations of the appropriate information,
with some XML nodes annotating particular parts of the declaration such as
its base type and name. This choice is based on prior experience with the
SGI `.spec` file format used to describe OpenGL, and greatly eases human
reading and writing the XML, and generating C-oriented output. The cost is
that people writing output generators for other languages will have to
include enough logic to parse the C declarations and extract the relevant
information.
People who do not find the supplied Python scripts to suit their needs
are likely to write their own parsers, interpreters, and/or converters
operating on the registry XML. We hope that we have provided enough
information in this document, the RNC schema (`registry.rnc`), and
comments in the Registry (`vk.xml`) itself to enable such projects. If
not and you need clarifications; if you have other problems using the
registry; or if you have proposed changes and enhancements, then please
file issues on Khronos' public Github project at
https://github.com/KhronosGroup/Vulkan-Docs/issues
Please tag your issues with `[Registry]` in the subject line to help us
categorize them. We have considered separating the registry from the
specification source into a separate repository, but since there is so
much specification valid usage language imbedded in the registry XML,
this is unlikely to happen.
[[starting]]
= Getting Started
See
https://gitlab.khronos.org/vulkan/vulkan/blob/master/xml/README.adoc[`xml/README.adoc`]
in the `Vulkan-Docs` repository for information on required toolchain
components such as Python 3, pass:[g++], and GNU make.
Once you have the right tools installed, perform the following steps:
* Check out the `Vulkan-Docs` repository linked above from Khronos
Github (there are instructions at the link)
* `cd` to the root directory in your checked-out repo
* Switch to the `master` branch.
* Invoke `make clean ; make install ; make test`
This should regenerate `vulkan_core.h` and a variety of platform-specific
headers, install them in `../include/vulkan/`, and verify that the headers build
properly. The result should be identical to the version you just pulled from
Github. They can be compared by, for example:
`git diff ../include/vulkan/`
The `install` target also generates source code for a simple extension
loader library in `../src/ext_loader/`.
Other Makefile targets in `xml/` include:
* `validate` - validate `vk.xml` against the XML schema. Recommended
if you are making nontrivial changes.
* The asciidoc includes used by the Specification and Reference Pages
are built using the 'make generated' target in the parent directory Makefile,
although they use the scripts and XML in this directory. These files
are generated dynamically when building the specs, since their
contents depend on the exact set of extensions the Specification is
being built to include.
If you just want to modify the API, changing `vk.xml` and running `make`
should be all that is needed. See <<examples>> for some examples of
modifying the XML.
If you want to use the registry for reasons other than generating the
header file, extension loader, and asciidoc includes, or to generate
headers for languages other than C, start with the Makefile rules and
the files `vk.xml`, `genvk.py`, `reg.py`, and `generator.py`.
If you are using other platforms, issues or merge requests with additional
documentation on using the tools on those platforms would be very helpful.
== Header Generation Script - `genvk.py`
When generating header files using the `genvk.py` script, an API name
and profile name are required, as shown in the Makefile examples.
Additionally, specific API versions and extensions can be required or
excluded. Based on this information, the generator script extracts the
relevant interfaces and creates a C-language header file for them.
`genvk.py` contains predefined generator options for the current Vulkan
Specification release.
The generator script is intended to be generalizable to other languages by
writing new generator classes. Such generators would have to rewrite the C
types and definitions in the XML to something appropriate to their language.
== Registry Processing Script - `reg.py`
XML processing is done in `reg.py`, which contains several objects and
methods for loading registries and extracting interfaces and extensions for
use in header generation. There is some internal documentation in the form
of comments, although nothing more extensive exists yet.
== Output Generator Script - `generator.py`
Once the registry is loaded, the `COutputGenerator` class defined in
`generator.py` is used to create a header file. The
`DocOutputGenerator` class is used to create the asciidoc include
files. Output generators for other purposes can be added as needed.
There are a variety of output generators included:
* `cgenerator.py` - generate C header file
* `docgenerator.py` - generate asciidoc includes for APIs
* `hostsyncgenerator.py` - generate host sync table includes for APIs
* `validitygenerator.py` - generate validity language includes
* `pygenerator.py` - generate a Python dictionary-based encoding of
portions of the registry, used during spec generation
* `extensionStubSource.py` - generate a simple C extension loader.
[[schema]]
= Vulkan Registry Schema
The format of the Vulkan registry is a top level tag:registry tag
containing tag:types, tag:enums, tag:commands, tag:feature, and
tag:extension tags describing the different elements of an API, as
explained below.
This description corresponds to a formal Relax NG schema file,
`registry.rnc`, against which the XML registry files can be validated.
At present the only registry in this schema is the core Vulkan API registry,
`vk.xml`.
[[schema:profile]]
== Profiles
Types and enumerants can have different definitions depending on the API
profile requested. This capability is not used in the current Vulkan API but
may be in the future. Features and extensions can include some elements
conditionally depending on the API profile requested.
[[schema:apiname]]
== API Names
The schema supports, but does not currently use an attr:api attribute on
several tags. This is an arbitrary string, specified at header generation
time, for labelling properties of a specific API or API profile. The string
can be, but is not necessarily, an actual API name. Names starting with `vk`
are suggested if and when we start defining profiles of Vulkan.
[[schema:root]]
= Registry Root (tag:registry tag)
A tag:registry contains the entire definition of one or more related
APIs.
== Attributes of tag:registry tags
None.
== Contents of tag:registry tags
Zero or more of each of the following tags, normally in this order
(although order should not be important):
* tag:comment - Contains arbitrary text, such as a copyright
statement.
* <<tag-platforms,tag:platforms>> - defines platform names corresponding
to platform-specific <<tag-extension,API extensions>>.
* <<tag-tags,tag:tags>> - defines author IDs used for
extensions and layers.
Author IDs are described in detail in the "`Layers & Extensions`"
section of the "`Vulkan Documentation and Extensions: Procedures and
Conventions`" document.
* <<tag-types,tag:types>> - defines API types. Usually only one
tag is used.
* <<tag-enums,tag:enums>> - defines API token names and values.
Usually multiple tags are used. Related groups may be tagged as an
enumerated type corresponding to a tag:type tag, and resulting in a
C `enum` declaration. This ability is heavily used in the Vulkan
API.
* <<tag-commands,tag:commands>> - defines API commands
(functions). Usually only one tag is used.
* <<tag-feature,tag:feature>> - defines API feature interfaces
(API versions, more or less). One tag per feature set.
* <<tag-extensions,tag:extensions>> - defines API extension
interfaces. Usually only one tag is used, wrapping many extensions.
[[tag-comment]]
=== Comment Tags (tag:comment tag)
A tag:comment tag contains an arbitrary string, and is unused.
Comment tags may appear in multiple places in the schema, as described
below.
Comment tags are removed by output generators if they would otherwise appear
in generated headers, asciidoc include files, etc.
[[tag-platforms]]
= Platform Name Blocks (tag:platforms tag)
A tag:platforms contains descriptions of platform IDs for platforms
supported by window system-specific extensions to Vulkan.
== Attributes of tag:platforms tags
* attr:comment - optional. Arbitrary string (unused).
== Contents of tag:platforms tags
Zero or more tag:platform tags, in arbitrary order (though they are
typically ordered by sorting on the platform name).
[[tag-platform]]
= Platform Names (tag:platform tag)
A tag:platform tag describes a single platform name.
== Attributes of tag:platform tags
* attr:name - required.
The platform name.
This must be a short alphanumeric string corresponding to the platform
name, valid as part of a C99 identifier.
Lower-case is preferred.
In some cases, it may be desirable to distinguish a subset of platform
functionality from the entire platform.
In these cases, the platform name should begin with the entire platform
name, followed by `_` and the subset name.
+
--
[NOTE]
.Note
====
For example,
`name="xlib"`
is used for the X Window System, Xlib client library platform.
`name="xlib_xrandr"`
is used for the XRandR functionality within the `xlib` platform.
====
--
* attr:protect - required.
This must be a C99 preprocessor token beginning with `VK_USE_PLATFORM_`
followed by the platform name, converted to upper case, followed by `_`
and the extension suffix of the corresponding window system-specific
extension supporting the platform.
+
--
[NOTE]
.Note
====
For example,
`protect="VK_USE_PLATFORM_XLIB_XRANDR_EXT"`
is used for the `xlib_xrandr` platform name.
====
--
* attr:comment - optional. Arbitrary string (unused).
== Contents of tag:platform tags
No contents are allowed. All information is contained in the attributes.
[[tag-tags]]
= Author ID Blocks (tag:tags tag)
A tag:tags tag contains tag:authorid tags describing reserved author IDs
used by extension and layer authors.
== Attributes of tag:tags tags
* attr:comment - optional. Arbitrary string (unused).
== Contents of tag:tags tags
Zero or more tag:tag tags, in arbitrary order (though they are typically
ordered by sorting on the author ID).
[[tag-tag]]
= Author IDs (tag:tag tag)
A tag:tag tag contains information defining a single author ID.
== Attributes of tag:tag tags
* attr:name - required. The author ID, as registered with Khronos.
A short, upper-case string, usually an abbreviation of an author,
project or company name.
* attr:author - required.
The author name, such as a full company or project name.
* attr:contact - required.
The contact who registered or is currently responsible for extensions
and layers using the ID, including sufficient contact information to
reach the contact such as individual name together with email address,
Github username, or other contact information.
== Contents of tag:tag tags
No contents are allowed. All information is contained in the attributes.
[[tag-types]]
= API Type Blocks (tag:types tag)
A tag:types tag contains definitions of derived types used in the API.
== Attributes of tag:types tags
* attr:comment - optional. Arbitrary string (unused).
== Contents of tag:types tags
Zero or more tag:type and tag:comment tags, in arbitrary order (though they
are typically ordered by putting dependencies of other types earlier in the
list).
The tag:comment tags are used mostly to indicate grouping of related types.
[[tag-type]]
= API Type (tag:type tag)
A tag:type tag contains information which can be used to generate C code
corresponding to the type. In many cases, this is simply legal C code, with
attributes or embedded tags denoting the type name and other types used in
defining this type. In some cases, additional attribute and embedded type
information is used to generate more complicated C types.
== Attributes of tag:type tags
* attr:requires - optional. Another type name this type requires to
complete its definition.
* attr:name - optional. Name of this type (if not defined in the tag
body).
* attr:alias - optional. Another type name which this type is an alias of.
Must match the name of another tag:type element. This is typically used
when promoting a type defined by an extension to a new core version of
the API. The old extension type is still defined, but as an alias of the
new type.
* attr:api - optional. An API name (see tag:feature below) which
specializes this definition of the named type, so that the same API
types may have different definitions for e.g. GL ES and GL. This is
unlikely to be used in Vulkan, where a single API supports desktop
and mobile devices, but the functionality is retained.
* attr:category - optional. A string which indicates that this type
contains a more complex structured definition. At present the only
accepted categories are `basetype`, `bitmask`, `define`, `enum`,
`funcpointer`, `group`, `handle`, `include`, `struct`, and `union`,
as described below.
* attr:comment - optional. Arbitrary string (unused).
* attr:parent only applicable if category is `handle`. Notes another
type with the `handle` category that acts as a parent object for
this type.
* attr:returnedonly only applicable if category is `struct` or
`union`. Notes that this struct/union is going to be filled in by
the API, rather than an application filling it out and passing it to
the API.
* attr:structextends only applicable if category is `struct` or `union`.
This is a comma-separated list of structures whose `pNext` can include
this type.
This should usually only list the top-level structure that is
extended, for all possible chained structures - the chained structures
themselves should have their `pNext` tagged with attr:noautovalidity.
This will generate a validity statement on the top level structure
that validates the entire chain in one go, rather than each chained
structure repeating the list of valid structs.
== Contents of tag:type tags
The valid contents depend on the attr:category attribute.
=== Enumerated types - attr:category `"enum"`
If the attr:category tag has the value `enum`, the type is a C
enumeration. The body of the tag is ignored in this case. The value of
the attr:name attribute must be provided and must match the attr:name
attribute of a <<tag-enums,tag:enums>> tag. The enumerant values defined
within the tag:enums tag are used to generate a C `enum` type
declaration.
=== Structure types - attr:category `"struct"` or `"union"`
If the attr:category tag has the values `struct` or `union`, the type is a C
structure or union, respectively. In this case, the attr:name attribute must
be provided, and the contents of the tag:type tag are a series of tag:member
tags defining the members of the aggregate type, in order, interleaved with
any number of tag:comment tags.
==== Structure member (tag:member) tags
The tag:member tag defines the type and name of a structure or union
member.
==== Attributes of tag:member tags
* attr:values - only valid on the `sType` member of a struct. This is a
comma-separated list of enumerant values that are valid for the
structure type; usually there is only a single value.
* attr:len - if the member is an array, len may be one or more of the
following things, separated by commas (one for each array
indirection): another member of that struct; `"null-terminated"` for
a string; `"1"` to indicate it is just a pointer (used for nested
pointers); or an equation in math markup for incorporation in the
specification (a LaTeX math expression delimited by `latexmath:[` and
`]`.
The only variables in the equation should be the names of members of the
structure.
* attr:altlen - if the attr:len attribute is specified, and
contains a `latexmath:` equation, this attribute should
be specified with an equivalent equation using only C builtin operators,
C math library function names, and variables as allowed for attr:len.
It must be a valid C99 expression whose result is equal to attr:len for
all possible inputs.
It is a comma separated list that has size equal to only the `latexmath`
item count in attr:len list.
This attribute is intended to support consumers of the XML who need to
generate validation code from the allowed length.
* attr:externsync - denotes that the member should be externally
synchronized when accessed by Vulkan
* attr:optional - optional.
A value of `"true"` or `"false"` determines whether this
member can be omitted by providing `NULL` (for pointers),
`VK_NULL_HANDLE` (for handles), 0 (for bitmasks), or 0 for values
that are the size of an array in the same structure. If the member
is a pointer to one of those types, multiple values may be provided,
separated by commas - one for each pointer indirection.
If not present, the value is assumed to be `"false"` (the member must
not be omitted).
* attr:noautovalidity - prevents automatic validity language being
generated for the tagged item. Only suppresses item-specific
validity - parenting issues etc. are still captured.
It must also be used for structures that have no implicit validity when
such structure has explicit validity.
==== Contents of tag:member tags
The text elements of a tag:member tag, with all other tags removed,
is a legal C declaration of a struct or union member. In addition it may
contain several semantic tags:
* The tag:type tag is optional. It contains text which is a valid type
name found in another tag:type tag, and indicates that this type
must be previously defined for the definition of the command to
succeed. Builtin C types should not be wrapped in tag:type tags.
* The tag:name tag is required, and contains the struct/union member
name being described.
* The tag:enum tag is optional. It contains text which is a valid
enumerant name found in another tag:type tag, and indicates that this
enumerant must be previously defined for the definition of the command
to succeed. Typically this is used to semantically tag static array
lengths.
* The tag:comment tag is optional. It contains an arbitrary string
(unused).
=== All other types
If the attr:category attribute is one of `basetype`, `bitmask`,
`define`, `funcpointer`, `group`, `handle` or
`include`, or is not specified, tag:type contains text which is legal
C code for a type declaration. It may also contain embedded tags:
* tag:type - nested type tags contain other type names which are
required by the definition of this type.
* tag:apientry/ - insert a platform calling convention macro here
during header generation, used mostly for function pointer types.
* tag:name - contains the name of this type (if not defined in the tag
attributes).
There is no restriction on which sorts of definitions may be made in a given
category, although the contents of tags with attr:category `enum`,
`struct` or `union` are interpreted specially as described above.
However, when generating the header, types within each category are grouped
together, and categories are generated in the order given by the following
list. Therefore, types in a category should correspond to the intended
purpose given for that category. If this recommendation is not followed, it
is possible that the resulting header file will not compile due to
out-of-order type dependencies. The intended purpose of each category is:
* `include` (`#include`) directives)
* `define` (macro `#define` directives)
* `basetype` (scalar typedefs, such as the definition of `VkFlags`)
* `handle` (invocations of macros defining scalar types such as
`VkInstance`)
* `enum` (enumeration types and `#define` for constant values)
* `group` (currently unused)
* `bitmask` (enumeration types whose members are bitmasks)
* `funcpointer` (function pointer typedefs)
* `struct` and `union` together (struct and union types)
[[tag-types:example]]
== Example of a tag:types tag
[source,xml]
--------------------------------------
<types>
<type name="stddef">#include <stddef.h></type>
<type requires="stddef">typedef ptrdiff_t <name>VKlongint</name>;</type>
<type name="VkEnum" category="enum"/>
<type category="struct" name="VkStruct">
<member><type>VkEnum</type> <name>srcEnum</name></member>
<member><type>VkEnum</type> <name>dstEnum</name></member>
</type>
</types>
<enums name="VkEnum" type="enum">
<enum value="0" name="VK_ENUM_ZERO"/>
<enum value="42" name="VK_ENUM_FORTY_TWO"/>
</enums>
--------------------------------------
The `VkStruct` type is defined to require the types `VkEnum` and
`VKlongint` as well. If `VkStruct` is in turn required by a command
or another type during header generation, it will result in the following
declarations:
[source,c]
--------------------------------------
#include <stddef.h>
typedef ptrdiff_t VKlongint.
typedef enum {
VK_ENUM_ZERO = 0,
VK_ENUM_FORTY_TWO = 42
} VkEnum;
typedef struct {
VkEnum dstEnum;
VkLongint dstVal;
} VkStruct;
--------------------------------------
Note that the angle brackets around `stddef.h` are represented as XML
entities in the registry. This could also be done using a CDATA block but
unless there are many characters requiring special representation in XML,
using entities is preferred.
[[tag-enums]]
= Enumerant Blocks (tag:enums tag)
The tag:enums tags contain individual tag:enum tags describing each of
the token names used in the API. In some cases these correspond to a C
`enum`, and in some cases they are simply compile time constants (e.g.
`#define`).
[NOTE]
.Note
====
It would make more sense to call these `const` or `define` tags.
This is a historical hangover from the OpenGL XML format which this schema
was based on.
====
== Attributes of tag:enums tags
* attr:name - optional. String naming the C `enum` type whose members are
defined by this enum group. If present, this attribute should match the
attr:name attribute of a corresponding tag:type tag.
* attr:type - optional. String describing the data type of the values of
this group of enums. At present the only accepted categories are `enum`
and `bitmask`, as described below.
* attr:start, attr:end - optional. Integers defining the start and end of
a reserved range of enumerants for a particular vendor or purpose.
attr:start must be less than or equal to attr:end. These fields define
formal enumerant allocations, and are made by the Khronos Registrar on
request from implementers following the enum allocation policy.
* attr:vendor - optional. String describing the vendor or purpose to whom
a reserved range of enumerants is allocated.
* attr:comment - optional. Arbitrary string (unused).
== Contents of tag:enums tags
Each tag:enums block contains zero or more tag:enum, tag:unused, and
tag:comment tags, in arbitrary order (although they are typically ordered by
sorting on enumerant values, to improve human readability).
== Example of tag:enums tags
<<tag-types:example,An example>> showing a tag with attribute
attr:type`="enum"` is given above. The following example is for
non-enumerated tokens.
[source,xml]
--------------------------------------
<enums>
<enum value="256" name="VK_MAX_EXTENSION_NAME"/>
<enum value="MAX_FLOAT" name="VK_LOD_CLAMP_NONE"/>
</enums>
--------------------------------------
When processed into a C header, and assuming all these tokens were
required, this results in
[source,c]
--------------------------------------
#define VK_MAX_EXTENSION_NAME 256
#define VK_LOD_CLAMP_NONE MAX_FLOAT
--------------------------------------
[[tag-enum]]
= Enumerants (tag:enum tag)
Each tag:enum tag defines a single Vulkan (or other API) token.
== Attributes of tag:enum tags
* attr:value or attr:bitpos - exactly one of these is allowed and
required. attr:value is an enumerant value in the form of a legal C
constant (usually a literal decimal or hexadecimal integer, though
arbitrary strings are allowed). attr:bitpos is a literal integer bit
position in a bitmask.
* attr:name - required. Enumerant name, a legal C preprocessor token
name.
* attr:api - optional. An API name which specializes this definition
of the named enum, so that different APIs may have different values
for the same token. May be used to address a subtle
incompatibilities.
* attr:type - optional. Used only when attr:value is specified. C
suffix for the value to force it to a specific type. Currently only
`u` and `ull` are used, for `unsigned` 32- and 64-bit integer
values, respectively. Separated from attr:value since this eases
parsing and sorting of values, and rarely used.
* attr:alias - optional. Name of another enumerant this is an alias
of, used where token names have been changed as a result of profile
changes or for consistency purposes. An enumerant alias is simply a
different attr:name for the exact same attr:value or attr:bitpos.
== Contents of tag:enum tags
tag:enum tags have no allowed contents. All information is contained
in the attributes.
[[tag-unused]]
= Unused Enumerants (tag:unused tag)
Each tag:unused tag defines a range of enumerants which is allocated, but
not yet assigned to specific enums. This just tracks the unused values for
the Registrar's use, and is not used for header generation.
[NOTE]
.Note
====
tag:unused tags could be generated and inserted automatically, which would
be a good way to avoid the attributes becoming out of date. However, they
are rarely used in the Vulkan XML schema, unlike the OpenGL XML schema it
was based on.
====
== Attributes of tag:unused tags
* attr:start - required, attr:end - optional. Integers defining the
start and end of an unused range of enumerants. attr:start must be
{leq} attr:end. If attr:end is not present, then attr:start defines a
single unused enumerant. This range should not exceed the range
reserved by the surrounding tag:enums tag.
* attr:vendor - optional. String describing the vendor or purposes to
whom a reserved range of enumerants is allocated. Usually identical
to the attr:vendor attribute of the surrounding attr:enums block.
* attr:comment - optional. Arbitrary string (unused).
== Contents of tag:unused tags
None.
[[tag-commands]]
= Command Blocks (tag:commands tag)
The tag:commands tag contains definitions of each of the functions
(commands) used in the API.
== Attributes of tag:commands tags
* attr:comment - optional. Arbitrary string (unused).
== Contents of tag:commands tags
Each tag:commands block contains zero or more tag:command tags, in
arbitrary order (although they are typically ordered by sorting on the
command name, to improve human readability).
[[tag-command]]
= Commands (tag:command tag)
The tag:command tag contains a structured definition of a single API
command (function).
== Attributes of tag:command tags
There are two ways to define a command. The first uses a set of attributes
to the tag:command tag defining properties of the command used for
constructing automatic validation rules, and the contents of the tag:command
tag define the name, signature, and parameters of the command. In this case
the allowed attributes include:
* attr:queues - optional. A string identifying the command queues this
command can be placed on. The format of the string is one or more of
the terms `"compute"`, `"transfer"`, and `"graphics"`, with multiple
terms separated by commas (`","`).
* attr:successcodes - optional. A string describing possible
successful return codes from the command, as a comma-separated list
of Vulkan result code names.
* attr:errorcodes - optional. A string describing possible error
return codes from the command, as a comma-separated list of Vulkan
result code names.
* attr:renderpass - optional. A string identifying whether the command
can be issued only inside a render pass (`"inside"`), only outside a
render pass (`"outside"`), or both (`"both"`).
* attr:cmdbufferlevel - optional. A string identifying the command
buffer levels that this command can be called by. The format of the
string is one or more of the terms `"primary"` and `"secondary"`,
with multiple terms separated by commas (`","`).
* attr:pipeline - optional. A string identifying the pipeline type
that this command uses when executed. The format of the string is one of
the terms `"compute"`, `"transfer"`, or `"graphics"`.
* attr:comment - optional. Arbitrary string (unused).
The second way of defining a command is as an alias of another command. For
example when an extension is promoted from extension to core status, the
commands defined by that extensions become aliases of the corresponding new
core commands. In this case, only two attributes are allowed:
* attr:name - required. A string naming the command defined by the tag.
* attr:alias - required. A string naming the command that attr:name is an
alias of. The string must be the same as the attr:name value of another
tag:command defining another command.
== Contents of tag:command tags
* tag:proto is required and must be the first element. It is a tag
defining the C function prototype of a command as described below,
up to the function name and return type but not including function
parameters.
* tag:param elements for each command parameter follow, defining its
name and type, as described below. If a command takes no arguments,
it has no tag:param tags.
Following these elements, the remaining elements in a tag:command
tag are optional and may be in any order:
* tag:alias - optional. Has no attributes and contains a string which
is the name of another command this command is an alias of, used
when promoting a function from vendor to Khronos extension or
Khronos extension to core API status. A command alias describes the case
where there are two function names which implement the same behavior.
* tag:description - optional. Unused text.
* tag:implicitexternsyncparams - optional. Contains a list of tag:param
tags, each containing asciidoc source text describing an object which is
not a parameter of the command but is related to one, and which also
<<tag-command:param:attr,requires external synchronization>>. The text
is intended to be incorporated into the API specification.
[NOTE]
.Note
====
Versions of the registry documentation prior to 1.1.93 asserted that
command aliases "`resolve to the _same_ entry point in the underlying layer
stack.`"
Whilst this may be true on many implementations, it is not required - each
command alias must be queried separately through flink:vkGetInstanceProcAddr
or flink:vkGetDeviceProcAddr.
====
[[tag-command:proto]]
== Command prototype (tag:proto tags)
The tag:proto tag defines the return type and name of a command.
=== Attributes of tag:proto tags
None.
// attr:group - group name, an arbitrary string.
//
// If the group name is defined, it may be interpreted as described in
// <<tag-group:meaning>>.
=== Contents of tag:proto tags
The text elements of a tag:proto tag, with all other tags removed, is
legal C code describing the return type and name of a command. In addition
to text, it may contain two semantic tags:
* The tag:type tag is optional, and contains text which is a valid
type name found in a tag:type tag. It indicates that this type must
be previously defined for the definition of the command to succeed.
Builtin C types, and any derived types which are expected to be
found in other header files, should not be wrapped in tag:type tags.
* The tag:name tag is required, and contains the command name being
described.
[[tag-command:param]]
== Command parameter (tag:param tags)
The tag:param tag defines the type and name of a parameter. Its contents
are very similar to the tag:member tag used to define struct and union
members.
[[tag-command:param:attr]]
=== Attributes of tag:param tags
* attr:len - if the param is an array, len may be one or more of the
following things, separated by commas (one for each array
indirection): another param of that command; `"null-terminated"` for
a string; `"1"` to indicate it is just a pointer (used for nested
pointers); or an equation in math markup for incorporation in the
specification (a LaTeX math expression delimited by `latexmath:[` and
`]`.
The only variables in the equation should be the names of this or other
parameters.
* attr:altlen - if the attr:len attribute is specified, and
contains a `latexmath:` equation, this attribute should
be specified with an equivalent equation using only C builtin operators,
C math library function names, and variables as allowed for attr:len.
It must be a valid C99 expression whose result is equal to attr:len for
all possible inputs.
It is a comma separated list that has size equal to only the `latexmath`
item count in attr:len list.
This attribute is intended to support consumers of the XML who need to
generate validation code from the allowed length.
* attr:optional - optional. A value of `"true"` or `"false"` determines whether this
parameter can be omitted by providing `NULL` (for pointers),
`VK_NULL_HANDLE` (for handles), 0 (for bitmasks), or 0 for values
that are the size of an array in the same command. If the parameter is
a pointer to one of those types, multiple values may be provided,
separated by commas - one for each pointer indirection. If not present,
the value is assumed to be `"false"` (the parameter must not be
omitted).
* attr:noautovalidity - prevents automatic validity language being
generated for the tagged item. Only suppresses item-specific
validity - parenting issues etc. are still captured.
* attr:externsync - optional. A value of `"true"` indicates that this
parameter (e.g. the object a handle refers to, or the contents of an
array a pointer refers to) is modified by the command, and is not
protected against modification in multiple app threads. If only certain
members of an object or elements of an array are modified, multiple
strings may be provided, separated by commas. Each string describes a
member which is modified. For example, the `vkQueueSubmit` command
includes attr:externsync attributes for the `pSubmits` array indicating
that only specific members of each element of the array are modified:
+
--
[source,xml]
--------------------------------------
<param len="submitCount" externsync="pSubmits[].pWaitSemaphores[],pSubmits[].pSignalSemaphores[]">const <type>VkSubmitInfo</type>* <name>pSubmits</name></param>
--------------------------------------
Parameters which do not have an attr:externsync attribute are assumed to not
require external synchronization.
--
=== Contents of tag:param tags
The text elements of a tag:param tag, with all other tags removed, is
legal C code describing the type and name of a function parameter. In
addition it may contain two semantic tags:
* The tag:type tag is optional, and contains text which is a valid
type name found in tag:type tag, and indicates that this type must
be previously defined for the definition of the command to succeed.
Builtin C types, and any derived types which are expected to be
found in other header files, should not be wrapped in tag:type tags.
* The tag:name tag is required, and contains the parameter name being
described.
== Example of a tag:commands tag
[source,xml]
--------------------------------------
<commands>
<command>
<proto><type>VkResult</type> <name>vkCreateInstance</name></proto>
<param>const <type>VkInstanceCreateInfo</type>* <name>pCreateInfo</name></param>
<param><type>VkInstance</type>* <name>pInstance</name></param>
</command>
</commands>
--------------------------------------
When processed into a C header, this results in
[source,c]
--------------------------------------
VkResult vkCreateInstance(
const VkInstanceCreateInfo* pCreateInfo,
VkInstance* pInstance);
--------------------------------------
[[tag-feature]]
= API Features and Versions (tag:feature tag)
API features are described in individual tag:feature tags. A feature is
the set of interfaces (enumerants and commands) defined by a particular API
and version, such as Vulkan 1.0, and includes all profiles of that API and
version.
== Attributes of tag:feature tags
* attr:api - required. <<schema:apiname,API name>> this feature is for,
such as `vk`.
* attr:name - required. Version name, used as the C preprocessor token
under which the version's interfaces are protected against multiple
inclusion. Example: `"VK_VERSION_1_0"`.
* attr:number - required. Feature version number, usually a string
interpreted as `majorNumber.minorNumber`. Example: `4.2`.
* attr:protect - optional. An additional preprocessor token used to
protect a feature definition. Usually another feature or extension
attr:name. Rarely used, for odd circumstances where the definition
of a feature or extension requires another to be defined first.
* attr:comment - optional. Arbitrary string (unused).
[NOTE]
.Note
====
The attr:name attribute used for Vulkan core versions, such as