97 lines
3.5 KiB
Plaintext
97 lines
3.5 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
|
|
* 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`.
|