• Home
Name Date Size #Lines LOC

..--

LICENSES/03-May-2024-646492

api/03-May-2024-6,6846,012

appendices/03-May-2024-32,55126,161

chapters/03-May-2024-110,54495,522

config/03-May-2024-7,6514,727

gen/include/03-May-2024-17,16914,374

hostsynctable/03-May-2024-171165

images/03-May-2024-35,09634,885

include/03-May-2024-9,9708,092

katex/03-May-2024-44,54535,915

man/03-May-2024-1913

out/03-May-2024-10,1727,799

proposals/03-May-2024-792548

scripts/03-May-2024-22,26815,220

src/ext_loader/03-May-2024-3524

style/03-May-2024-4,5773,754

tests/03-May-2024-18694

validity/03-May-2024-5,3954,542

xml/03-May-2024-50,83241,503

BUILD.adocD03-May-202417.9 KiB460361

CODE_OF_CONDUCT.adocD03-May-2024383 118

CONTRIBUTING.adocD03-May-20241.4 KiB3927

COPYING.adocD03-May-20244.2 KiB9271

COPYING.mdD03-May-20242.3 KiB4037

ChangeLog.txtD03-May-2024444.2 KiB9,6928,074

LICENSE.adocD03-May-20241.2 KiB3525

MakefileD03-May-202423.2 KiB615319

README.adocD03-May-20244.4 KiB11283

checkLinks.pyD03-May-202412.3 KiB316180

copyright-ccby.txtD03-May-2024171 53

copyright-spec.txtD03-May-20244.8 KiB8473

fixupRef.pyD03-May-20247.2 KiB213130

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

genRef.pyD03-May-202419.6 KiB587362

genReleaseD03-May-20245.5 KiB15198

genspec.pyD03-May-20245.9 KiB16785

installReleaseD03-May-20241.1 KiB4523

makeAllExtsD03-May-2024236 111

makeExtD03-May-2024410 173

makeKHRD03-May-2024315 141

makeSpecD03-May-20244.9 KiB13281

package-lock.jsonD03-May-2024872 2524

package.jsonD03-May-2024128 98

promote.pyD03-May-20246.9 KiB184117

refDesc.pyD03-May-202430.5 KiB367337

refPageNotes.mdD03-May-20244.7 KiB8475

reflib.pyD03-May-202420.2 KiB562338

reflow.pyD03-May-202427.9 KiB680329

reflow_count.pyD03-May-202493 31

registry.txtD03-May-2024100.4 KiB2,5762,128

sandboxCopyD03-May-2024613 2412

styleguide.txtD03-May-202417.6 KiB382336

update_valid_usage_ids.shD03-May-2024349 121

vkspec.txtD03-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