README.adoc

Vulkan^® API Documentation Project

This repository contains formal documentation of the Vulkan API. This includes the main API Specification, the reference (man) pages, the XML API Registry, and related tools and scripts.

Single-Branch Model

As of the 1.0.25 release, we have switched to a new "single-branch" model in which all extensions are included in the source of the 1.0 branch of the Specification, and can be configured in or out of the build using Makefile options.

Repository 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
    misc/               Related specifications (GL_KHR_vulkan_glsl)
src/spec/               XML API Registry (vk.xml) and related scripts
src/vulkan/             Vulkan headers, generated from the Registry

Building the Specification and Reference Pages

As of the 1.0.40 release, we have moved from the old asciidoc toolchain to a new one based on asciidoctor. See doc/specs/vulkan/README.adoc for more information on installing the toolchain and building the Specification.

Generating Headers and Related Files

The header file (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 vulkan.h, are not checked into the repository. If you change vk.xml, you can regenerate the header by going to src/spec and running:

$ make clobber install

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