• Home
Name Date Size #Lines LOC

..--

LICENSES/12-May-2024-646492

appendices/12-May-2024-28,14522,446

chapters/12-May-2024-109,77494,855

config/12-May-2024-7,4674,604

images/12-May-2024-34,64834,440

include/12-May-2024-17,11514,340

katex/12-May-2024-44,54435,915

proposals/12-May-2024-792548

scripts/12-May-2024-22,18815,134

src/ext_loader/12-May-2024-3524

style/12-May-2024-4,6033,775

tests/12-May-2024-18694

xml/12-May-2024-20,92420,679

.gitignoreD12-May-20241.1 KiB9068

BUILD.adocD12-May-202417.9 KiB459360

CODE_OF_CONDUCT.adocD12-May-2024383 118

CONTRIBUTING.adocD12-May-20241.4 KiB3927

COPYING.adocD12-May-20244.2 KiB9271

ChangeLog.txtD12-May-2024450.9 KiB9,8428,198

LICENSE.adocD12-May-20241.2 KiB3525

MakefileD12-May-202423.3 KiB616323

README.adocD12-May-20244.4 KiB11283

copyright-spec.txtD12-May-20244.8 KiB8473

gen-script-docs.shD12-May-20241.8 KiB6738

installReleaseD12-May-20241.1 KiB4523

makeAllExtsD12-May-2024236 111

makeExtD12-May-2024410 173

makeKHRD12-May-2024315 141

makeSpecD12-May-20245.3 KiB14083

package-lock.jsonD12-May-2024872 2524

package.jsonD12-May-2024128 98

registry.txtD12-May-2024113.7 KiB2,9542,413

sandboxCopyD12-May-2024614 2412

styleguide.txtD12-May-202417.9 KiB387341

update_valid_usage_ids.shD12-May-2024349 121

vkspec.txtD12-May-20244.8 KiB213140

README.adoc

1// Copyright 2017-2021 The Khronos Group Inc.
2// SPDX-License-Identifier: CC-BY-4.0
3
4ifdef::env-github[]
5:note-caption: :information_source:
6endif::[]
7
8= Vulkan^(R)^ API Documentation Project
9
10This repository contains sources for the formal documentation of the Vulkan
11API. This includes:
12
13[options="compact"]
14 * The Vulkan API Specification
15 * Specification of Vulkan extensions
16 * API reference ("`man`") pages
17 * The XML API Registry (also mirrored at
18   link:https://github.com/KhronosGroup/Vulkan-Headers[Vulkan-Headers])
19 * Vulkan header files (also mirrored at
20   link:https://github.com/KhronosGroup/Vulkan-Headers[Vulkan-Headers])
21 * Related tools and scripts.
22
23The authoritative public repository is located at
24link:https://github.com/KhronosGroup/Vulkan-Docs/[Vulkan-Docs].
25It hosts a public Issue tracker, and outside developers can file proposed
26changes (Pull Requests) against the Specification, subject to approval by
27Khronos.
28
29If in doubt where to submit your Issue, consult the
30link: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]
31repository.
32
33
34== External Contributions
35
36Khronos welcomes feedback in Github Issues, and proposed changes in Github
37Pull Requests (PRs), but will not necessarily accept all such changes.
38
39Please keep your issues and pull requests focused on solving a single
40problem. Broader feedback that tries to solve multiple problems, or touches
41many parts of the Specification at once, is difficult for the Vulkan Working
42Group to review in a timely fashion.
43
44
45== Branch Structure
46
47The current Specification is maintained in the default branch (currently
48`main`) of the repository.
49From this branch it is possible to generate Specifications for any published
50version of Vulkan (1.2, 1.1, and 1.0), and incorporating any desired set of
51extensions.
52Each published update is tagged in the form `1.2.*release*` where *release*
53is a constantly incrementing release number and `1.2` is the latest
54published version of the API.
55The last public spec update prior to Vulkan 1.2 is tagged `v1.1.130`.
56
57The last state of the default branch in Khronos' internal gitlab server,
58before 1.2 content was merged into it, is tagged `1.1-archive` (this tag is
59not in github).
60
61
62== Directory Structure
63
64The directory structure is as follows:
65
66```
67README.adoc           This file
68BUILD.adoc            Documents how to build the specifications and reference pages
69CONTRIBUTING.adoc     Requirements for external contributions to the repository
70COPYING.adoc          Copyright and licensing information
71CODE_OF_CONDUCT.adoc  Code of Conduct
72LICENSE.adoc          Summary of licenses used by files in the repository
73ChangeLog.txt         Change log summary for each public spec update
74Makefile, make*       Makefile and helper build scripts (see BUILD.adoc)
75appendices/           Specification appendices
76chapters/             Specification chapters
77proposals/            Design documents for extensions
78config/               Asciidoctor configuration, CSS, and index generator
79images/               Images (figures, diagrams, icons)
80gen/out/              Default directory for the generated documents
81scripts/              Helper scripts used in specification, header, and reference page generation
82style/                Sources for "styleguide" (Vulkan Documentation and Extensions: Procedures and Conventions)
83xml/                  XML API Registry (vk.xml)
84registry.txt          Sources for documentation of the vk.xml format
85```
86
87
88== Building the Specification and Reference Pages
89
90The document sources are marked up in Asciidoctor format, and we use
91`asciidoctor` and related toolchain components to generate output documents.
92See link:BUILD.adoc[BUILD.adoc] for more information on installing the
93toolchain and building the Specification.
94
95
96== Generating Headers and Related Files
97
98See link:xml/README.adoc[xml/README.adoc].
99
100The header files (`include/vulkan/vulkan*.h`) and many parts of the
101specification and reference page documents are generated from descriptions
102in the XML API Registry (link:xml/vk.xml[`xml/vk.xml`]).
103The generated files are not checked into the repository.
104If you change `vk.xml`, you can regenerate the headers by going into
105`xml/` and running:
106
107    $ make clean install
108
109The other generated files are built as required via dependencies in
110the top-level `Makefile`.
111
112