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
|
// Copyright 2017-2021 The Khronos Group Inc.
// SPDX-License-Identifier: CC-BY-4.0
ifdef::env-github[]
:note-caption: :information_source:
endif::[]
= Vulkan^(R)^ API Documentation Project
This repository contains sources for the formal documentation of the Vulkan
API. This includes:
[options="compact"]
* The Vulkan API Specification
* Specification of Vulkan extensions
* API reference ("`man`") pages
* The XML API Registry (also mirrored at
link:https://github.com/KhronosGroup/Vulkan-Headers[Vulkan-Headers])
* Vulkan header files (also mirrored at
link:https://github.com/KhronosGroup/Vulkan-Headers[Vulkan-Headers])
* Related tools and scripts.
The authoritative public repository is located at
link:https://github.com/KhronosGroup/Vulkan-Docs/[Vulkan-Docs].
It hosts a public Issue tracker, and outside developers can file proposed
changes (Pull Requests) against the Specification, subject to approval by
Khronos.
If in doubt where to submit your Issue, consult the
link:https://github.com/KhronosGroup/Vulkan-Web-Registry/blob/main/Vulkan-Projects.adoc[Vulkan-Projects] list on the link:https://github.com/KhronosGroup/Vulkan-Web-Registry[Vulkan-Web-Registry]
repository.
== External Contributions
Khronos welcomes feedback in Github Issues, and proposed changes in Github
Pull Requests (PRs), but will not necessarily accept all such changes.
Please keep your issues and pull requests focused on solving a single
problem. Broader feedback that tries to solve multiple problems, or touches
many parts of the Specification at once, is difficult for the Vulkan Working
Group to review in a timely fashion.
== Branch Structure
The current Specification is maintained in the default branch (currently
`main`) of the repository.
From this branch it is possible to generate Specifications for any published
version of Vulkan (1.2, 1.1, and 1.0), and incorporating any desired set of
extensions.
Each published update is tagged in the form `1.2.*release*` where *release*
is a constantly incrementing release number and `1.2` is the latest
published version of the API.
The last public spec update prior to Vulkan 1.2 is tagged `v1.1.130`.
The last state of the default branch in Khronos' internal gitlab server,
before 1.2 content was merged into it, is tagged `1.1-archive` (this tag is
not in github).
== Directory Structure
The directory structure is as follows:
```
README.adoc This file
BUILD.adoc Documents how to build the specifications and reference pages
CONTRIBUTING.adoc Requirements for external contributions to the repository
COPYING.adoc Copyright and licensing information
CODE_OF_CONDUCT.adoc Code of Conduct
LICENSE.adoc Summary of licenses used by files in the repository
ChangeLog.txt Change log summary for each public spec update
Makefile, make* Makefile and helper build scripts (see BUILD.adoc)
appendices/ Specification appendices
chapters/ Specification chapters
proposals/ Design documents for extensions
config/ Asciidoctor configuration, CSS, and index generator
images/ Images (figures, diagrams, icons)
gen/out/ Default directory for the generated documents
scripts/ Helper scripts used in specification, header, and reference page generation
style/ Sources for "styleguide" (Vulkan Documentation and Extensions: Procedures and Conventions)
xml/ XML API Registry (vk.xml)
registry.txt Sources for documentation of the vk.xml format
```
== Building the Specification and Reference Pages
The document sources are marked up in Asciidoctor format, and we use
`asciidoctor` and related toolchain components to generate output documents.
See link:BUILD.adoc[BUILD.adoc] for more information on installing the
toolchain and building the Specification.
== Generating Headers and Related Files
See link:xml/README.adoc[xml/README.adoc].
The header files (`include/vulkan/vulkan*.h`) and many parts of the
specification and reference page documents are generated from descriptions
in the XML API Registry (link:xml/vk.xml[`xml/vk.xml`]).
The generated files are not checked into the repository.
If you change `vk.xml`, you can regenerate the headers by going into
`xml/` and running:
$ make clean install
The other generated files are built as required via dependencies in
the top-level `Makefile`.
|
