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
 * 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.

[NOTE]
====
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 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 (`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`.