forked from KhronosGroup/Vulkan-Docs
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathregistry.txt
2979 lines (2439 loc) · 115 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 2013-2022 The Khronos Group Inc.
//
// SPDX-License-Identifier: CC-BY-4.0
= The Khronos^®^ Vulkan^®^ API Registry
Jon Leech
:data-uri:
:icons: font
:toc2:
:toclevels: 3
:numbered:
:source-highlighter: rouge
:rouge-style: github
: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::{config}/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 default branch,
currently `main`.
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 into a
separate repository under
https://github.com/KhronosGroup/Vulkan-Headers/
== 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/main/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 default branch (`main`).
* 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.
If you build at the latest repository tag, the resulting headers should be
identical to the latest versions in the
link:https://github.com/KhronosGroup/Vulkan-Headers/[Vulkan-Headers
repository].
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` and scripts `genvk.py`, `reg.py`, and `generator.py`.
The scripts are described below and are all located in the `scripts`
directory under the repository root.
== 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
Specific API versions features and extensions can be tagged as belonging to
to classes of features with the use of _API names_.
This is intended to allow multiple closely-related API specifications in the
same family - such as desktop and mobile specifications - to share the same
XML.
An API name is an arbitrary alphanumeric string, although it should be
chosen to match the corresponding API.
For example, Vulkan and OpenXR use `vulkan` and `openxr` as their API names,
respectively.
The attr:api attribute of the tag:feature tag and the attr:supported
attribute of the tag:extensions tag must be comma-separated lists of one or
more API names, all of which match that feature or extension.
When generating headers and other artifacts from the XML, an API name may be
specified to the processing scripts, causing the selection of only those
features and extensions whose API names match the specified name.
Several other tags for defining types and groups of types also support
attr:api attributes.
If present, the attribute value must be a comma-separated list of one or
more API names.
This allows specializing a definition for different, closely related APIs.
[[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-formats,tag:formats>> - defines properties of image formats.
Only one tag is used, wrapping all the formats.
* <<tag-spirvextensions,tag:spirvextensions>> - defines relationship
between SPIR-V extensions and API interfaces which enable each
extension.
Only one tag is used, wrapping all the SPIR-V extensions.
* <<tag-spirvcapabilities,tag:spirvcapabilities>> - defines relationship
between SPIR-V capabilities and API interfaces which enable each
capability.
Only one tag is used, wrapping all the SPIR-V capabilities.
[[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 comma-separated list of <<schema:apiname, API names>>
for which this definition is specialized, so that different APIs may
have different definitions for the same type.
This definition is only used if the requested API name matches the
attribute.
May be used to address subtle incompatibilities.
* 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 extending structures.
This will generate a validity statement on the top level structure that
validates the entire chain in one go, rather than each extending
structure repeating the list of valid structs.
There is no need to set the attr:noautovalidity attribute on the `pNext`
members of extending structures.
* attr:allowduplicate - only applicable if attr:category is `"struct"`.
If `"true"`, then structures whose `pNext` chains include this structure
may include more than one instance of it.
* attr:objtypeenum - only applicable at present if attr:category is
`"handle"`.
Specifies the name of a `VkObjectType` enumerant which corresponds to
this type.
The enumerant must be defined.
== 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:api - optional <<schema:apiname, API names>> for which this
definition is specialized, so that different APIs may have different
definitions for the same type.
This definition is only used if the requested API name matches the
attribute.
May be used to address subtle incompatibilities.
* 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), or 0 (for other scalar types).
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).
Structure members with name `pNext` must always be specified with
`optional="true"`, since there is no requirement that any member of a
`pNext` chain have a following member in the chain.
+
--
[NOTE]
.Note
====
While the attr:optional attribute can be used for scalar types such as
integers, it does not affect the output generators included with the Vulkan
Specification.
In this case, the attribute serves only as an indicator to human readers of
the XML.
====
--
* attr:selector - optional.
If the member is a union, attr:selector identifies another member of the
struct that is used to select which of that union's members are valid.
* attr:selection - optional.
For a member of a union, attr:selection identifies a value of the
attr:selector that indicates this member is valid.
* 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.
* attr:limittype - only applicable for members of
`VkPhysicalDeviceProperties`, `VkPhysicalDeviceProperties2`,
`VkPhysicalDeviceLimits`, `VkFormatProperties`, `VkFormatProperties2`,
`VkQueueFamilyProperties`, `VkQueueFamilyProperties2`, and structures
extending or members of any of those structures.
Specifies the type of a device limit.
This type describes how a value might be compared with the value of a
member in order to check whether it fits the limit.
Valid values:
** `"min"` and `"max"` denote minimum and maximum limits.
They may also apply to arrays and `VkExtent*D`.
** `"bitmask"` corresponds to bitmasks and `VkBool32`, where set bits
indicate the presence of a capability
** `"range"` specifies a [min, max] range
** `"struct"` means that the member's fields should be compared.
** `"noauto"` limits cannot be trivially compared.
This is the default value, if unspecified.
* attr:objecttype - only applicable for members which are `uint64_t`
values representing a Vulkan obejct handle.
Specifies the name of another member which must be a `VkObjectType` or
`VkDebugReportObjectTypeEXT` value specifying the type of object the
handle refers to.
==== 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).
* tag:bitvalues - contains the name of the enumeration defining flag
values for a `bitmask` type.
Ignored for other types.
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` (built-in C language types; scalar API typedefs, such as the
definition of `VkFlags`; and types defined by external APIs, such as an
underlying OS or window system
* `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 implementors 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).
* attr:bitwidth - optional.
Bit width required for the generated enum value type.
If omitted, a default value of 32 is used.
== 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 is a numeric value in the form of a legal C expression when
evaluated at compile time in the generated header files.
This is usually either a literal integer value or the name of an alias
for a previously defined value, though more complex expressions are
sometimes employed for <<compile-time-constants, compile time
constants>>.
* attr:bitpos is a literal integer bit position in a bitmask.
The bit position must be in the range [0,30] when used as a flag bit in
a `Vk*FlagBits` data type.
Bit positions 31 and up may be used for values that are not flag bits,
or for <<adding-bitflags, flag bits used with 64-bit flag types>>.
Exactly one of attr:value and attr:bitpos must be present in an tag:enum
tag.
* attr:name - required.
Enumerant name, a legal C preprocessor token name.
* attr:api - optional comma-separated list of <<schema:apiname, API
names>> for which this definition is specialized, so that different APIs
may have different values for the same token.
This definition is only used if the requested API name matches the
attribute.
May be used to address subtle incompatibilities.
* attr:type - may be used only when attr:value is specified.
In this case, attr:type is optional except when defining a
<<compile-time-constants, compile time constant>>, in which case it is
required when using some output generator paths.
If present the attribute must be a C scalar type corresponding to the
type of attr:value, although only `uint32_t`, `uint64_t`, and `float`
are currently meaningful.
attr:type is used by some output generators to generate constant
declarations, although the default behavior is to use C `#define` for
compile-time constants.
* 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.
* attr:protect - optional.
An additional preprocessor token used to protect an enum definition.
[NOTE]
.Note
====
In older versions of the schema, attr:type was described as allowing only
the C integer suffix types `u` and `ull`, which is inconsistent with the
current definition.
However, attr:type was not actually used in the registry processing scripts
or `vk.xml` at the time the current definition was introduced, so this is
expected to be a benign change.
====
== 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: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.
Both forms of tag:command support these options:
* attr:api - optional <<schema:apiname, API names>> for which this
definition is specialized, so that different APIs may have different
values for the same token.
This definition is only used if the requested API name matches the
attribute.
May be used to address subtle incompatibilities.
== 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.