Vulkan^® API Documentation Project

This repository contains sources for the formal documentation of the Vulkan API. This includes:

• the Vulkan API Specification

• specification of Vulkan Extensions

• the reference (“man”) pages

• the XML API Registry (also mirrored at https://github.com/KhronosGroup/Vulkan-Headers)

• Vulkan header files (also mirrored at https://github.com/KhronosGroup/Vulkan-Headers)

• related tools and scripts.

The authoritative public repository is located at https://github.com/KhronosGroup/Vulkan-Docs/. It hosts public Issue tracker, and accepts patches (Pull Requests) from the general public.

If in doubt where to submit your Issue consult the https://github.com/KhronosGroup/Vulkan-Ecosystem repo.

Branch Structure

Everything is now maintained in the master branch of the repository. From this branch it is possible to generate both Vulkan 1.1 and Vulkan 1.0 Specifications, as well as specifications for any set of Extensions.

ℹ️	Old revisions of the repository maintained the Vulkan 1.0 Specification in the 1.0 branch, and extensions in the 1.0-VK_EXTENSION_NAME. These branches are now obsolete, and contain only very old versions of the Specification (and extensions).

Directory Structure

The directory structure is as follows:

README.adoc           This file
BUILD.adoc            Documents how to build the specifications, and man pages
COPYING.md            Copyright and licensing information
CODE_OF_CONDUCT.md    Code of Conduct
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
config/               Asciidoctor configuration
images/               Images (figures, diagrams, icons)
include/vulkan/       Vulkan headers, generated from the Registry
man/                  Reference (man) pages for the API; mostly extracted from the spec source
out/                  Default directory for the generated documents
scripts/              Related scripts (but many scripts are still in the root or xml/ directory)
src/ext_loader/       Extension loader library (deprecated)
style/                Sources for "styleguide" (Vulkan Documentation and Extensions: Procedures and Conventions)
xml/                  XML API Registry (vk.xml) and related scripts
registry.txt          Sources for documentation of the vk.xml format

This structure was adopted following 1.1.70 spec update. There may be additional cleanup and simplification in the future.

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 BUILD.adoc for more information on installing the toolchain and building the Specification.

Generating Headers and Related Files

See 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 (xml/vk.xml). The generated files (with the exception of header files) are not checked into the repository. If you change vk.xml, you can regenerate the header by going into xml/ and running:

$ make clean install

The other generated files are built as required via dependencies in the top-level Makefile.