84 lines
3.1 KiB
Plaintext
84 lines
3.1 KiB
Plaintext
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
|
|
* API 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 a public Issue tracker, and outside developers can file proposed
|
|
patches (Pull Requests) against the Specification, subject to approval
|
|
by Khronos.
|
|
|
|
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.
|
|
|
|
|
|
== 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, CSS, and index generator
|
|
images/ Images (figures, diagrams, icons)
|
|
man/ Reference (man) pages for the API; mostly extracted from the spec source
|
|
out/ Default directory for the generated documents
|
|
scripts/ Helper scripts used in specification, header, and reference page generation
|
|
style/ Sources for "styleguide" (Vulkan Documentation and Extensions: Procedures and Conventions)
|
|
xml/ XML API Registry (vk.xml)
|
|
registry.txt Sources for documentation of the vk.xml format
|
|
```
|
|
|
|
|
|
== 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 are not checked into the repository.
|
|
If you change `vk.xml`, you can regenerate the headers by going into
|
|
`xml/` and running:
|
|
|
|
$ make clean install
|
|
|
|
The other generated files are built as required via dependencies in
|
|
the top-level `Makefile`.
|