= Vulkan^(R)^ API Documentation Project

This repository contains formal documentation of the Vulkan API. This
includes the Specification of the Vulkan API, including extensions; the
reference ("`man`") pages; the XML API Registry; header files; and related
tools and scripts.

The authoritative public repository is located at
https://github.com/KhronosGroup/Vulkan-Docs/ . Issues, proposed fixes for
issues, and other suggested changes should be created using Github.


== Branch Structure

With the release of Vulkan 1.1, the current Specification is now maintained
in the `master` branch of the repository. It is possible to generate both
Vulkan 1.1 and Vulkan 1.0 Specifications from this branch.


=== `1.0` Branch Is Obsolete

The `1.0` branch in which the 1.0 Specification was previously maintained is
now obsolete. The `1.0` branch will not be updated going forward, and all
outstanding pull requests or merge requests against the `1.0` branch must be
rebased on, and retargeted to `master`.


== Directory Structure

```
README.adoc             This file
ChangeLog.txt           Change log summary for each public spec update
doc/specs/              Main documentation tree
    vulkan/             Vulkan specification
        appendices/     Appendices - one file each
        chapters/       Chapters - one file each
        config/         asciidoc configuration
        images/         Images (figures, diagrams, icons)
        man/            Reference (manual) pages for API, mostly extracted from the spec source
src/spec/               XML API Registry (vk.xml) and related scripts
src/vulkan/             Vulkan headers, generated from the Registry
src/ext_loader/         Extension loader library
```


== 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 `doc/specs/vulkan/README.adoc` for more information on installing the
toolchain and building the Specification.


== Generating Headers and Related Files

The header files (`src/vulkan/vulkan*.h`) and many parts of the
specification and reference page documents are generated from descriptions
in the XML API Registry (`src/spec/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 to `src/spec` and
running:

    $ make clean install

The other generated files are built as required via dependencies in
`doc/specs/vulkan/Makefile` .