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
|
// Copyright 2014-2021 The Khronos Group Inc.
//
// SPDX-License-Identifier: CC-BY-4.0
= Vulkan^(R)^ API Registry Build Instructions and Notes
Jon Leech
* <<intro,Introduction>>
* <<build,Build Environment>>
* <<files,Files>>
* <<targets,Makefile Targets>>
* <<linux,Linux Software Dependencies>>
* <<windows,Windows Software Dependencies>>
* <<history,Revision History>>
[[intro]]
== Introduction
This is the Vulkan XML API Registry. It is used to generate the canonical
`vulkan_core.h`, the API Asciidoc include files used by the Vulkan
Specification and Reference Pages, and many other types of generated files.
When changes to generated files are needed, follow this workflow.
Normally changes are needed only when defining a new extension or core
version of the API.
* Clone the repository and create a branch to work in locally
* Edit `vk.xml`
* `make install test`
** This generates headers in `../gen/include/vulkan` including
`vulkan_core.h` and a set of platform-dependent headers
`vulkan_<platform>.h`.
* `(cd .. && make generated)`
** This uses `vk.xml` to generate asciidoc includes and other intermediate
files in `../gen` for the specification build.
There are many ways to invoke the Makefile in `..`.
This simple recipe only generates includes for the core Vulkan API
without any extensions.
See `../BUILD.adoc` for more.
* Repeat until the headers and/or includes are correct
* Commit your changes to your local git branch, push to your upstream git
server (your personal repository clone of KhronosGroup/Vulkan-Docs on
Github, for people outside Khronos; the Khronos member gitlab server,
otherwise), and create a pull or merge request against the default
branch (currently `main`) or other appropriate target.
For a detailed description of the schema, go to `..` and `make registry`,
which generates `gen/out/registry.html`.
This document also includes some examples of how to make simple changes in
the API via the XML.
The generator scripts are written in Python 3, using the `etree` package for
processing XML.
See `../scripts/README.adoc` for script descriptions.
[[build]]
== Build Environment
We strongly recommend using the Khronos-provided Docker image, which has all
needed build tools pre-installed.
See `../BUILD.adoc` for details.
It is possible to construct your own build environment on Linux, Windows, or
MacOS by following the recipe in the Dockerfile for the Khronos-provided
Docker image.
[[files]]
== Files
* `vk.xml` - XML API description.
* `registry.rnc` - RelaxNG compact schema for validating XML against the
schema.
* `Makefile` - generates headers from `vk.xml` (see <<targets,Makefile
Targets>> below).
* `../gen/include/vulkan/vulkan_core.h` - Generated Vulkan non-platform
API header.
* `../gen/include/vulkan/vulkan_<platform>.h` - Generated Vulkan platform
API headers.
[[targets]]
== Makefile Targets
* `install` (default target) - regenerate header files in
`../include/vulkan`.
* `test` - make sure `../include/vulkan/vulkan_core.h` compiles.
*Important!* Can also be used to test if platform headers compile by
specifying `make TESTDEFS=-DVK_USE_PLATFORM_<PLATFORM>_<AUTHORID> test`.
* `validate` - validate `vk.xml` against the schema. Requires installing
`jing` (see <<linux,Software Dependencies>> below). Also important!
* `clean_dirt` - remove intermediate files.
* `clean` - remove generated files.
Generated files can be created in a directory other than the default
`../gen/` by setting the Makefile variable `GENERATED` to that directory
path.
If you have trouble running the Makefile on your platform, the following
steps will build `vulkan_core.h` and test that it compiles:
[source,sh]
----
# Regenerate header from XML
python3 ../scripts/genvk.py -o ../include/vulkan vulkan_core.h
# Verify that the resulting header compiles
gcc -Wall -c -I../include testcore.c
g++ -Wall -c -std=c++98 -I../include testcore.c
g++ -Wall -c -std=c++11 -I../include testcore.c
----
[[history]]
== Revision History
* 2020-08-25 -
Update for new default branch (`main`).
* 2019/05/12 -
Bring up to date with changes in file paths and build tools.
* 2019/03/10 -
Update for script reorganization.
* 2018/05/21 -
Don't generate vulkan_ext.[ch] from the `install` target. Add a new
shortcut `extloader` target for people still using this code and needing
to regenerate it.
* 2018/03/13 -
Update for new directory structure.
* 2018/03/06 -
Update for Vulkan 1.1 release and `master` branch.
* 2015/09/18 -
Split platform-specific headers into their own vulkan_<platform>.h
files, move vulkan.h to vulkan_core.h, and add a new (static) vulkan.h
which includes appropriate combinations of the other headers.
* 2015/06/01 -
The header that is generated has been improved relative to the first
version. Function arguments are indented like the hand-generated header,
enumerant BEGIN/END_RANGE enums are named the same, etc. The ordering of
declarations is unlike the hand-generated header, and probably always
will because it results from a type/enum/function dependency analysis.
Some of this can be forced by being more explicit about it, if that is a
big deal.
* 2015/06/02 -
Per WG signoff, converted hex constant values to decimal (for
non-bitmasks) and VK_BIT macros to 'bitpos' attributes in the XML and
hex constants in the header. Updated schema to match. Changed <ptype>
tag to <type>.
* 2015/06/03 -
Moved into new 'vulkan' tree (did not bother preserving history in
previous repo). Added semantic knowledge about structs and unions to
<type> tags instead of just imbedding C struct definitions. Improved
registry.rnc schema a bit.
* 2015/06/07 -
Incorporate feedback from F2F including Python 3 and Windows fixes to
the scripts. Add documentation to readme.pdf. Fold in multiple merge
requests resulting from action items agreed at the F2F, to prepare
for everyone moving to XML instead of directly editing the header.
* 2015/06/20 -
Add vulkan-docs target and instructions for installing python3 and
python-lxml for Windows.
* 2015/08/13 -
Bring documentation up to date with Makefile targets (default is now
../include/vulkan.h).
* 2015/09/02 -
Update README with required (or known working) versions of toolchain
components.
* 2015/09/02 -
Move include/vulkan.h to vulkan/vulkan.h so #include "vulkan/vulkan.h"
is the normal usage (Bug 14576).
* 2016/02/12 -
Update README and remove old files to stage for public release.
* 2016/05/31 -
Remove dependency on lxml.
* 2016/07/27 -
Update documentation for changes to schema and generator scripts.
* 2016/08/26 -
Move README to an asciidoc file and update for the single-branch model.
Use 'clean' target to remove generated files in both spec source and
registry Makefiles.
* 2017/02/20 -
Move registry.txt (schema documentation) to the Vulkan spec source
directory and update the README here.
|
