| // Copyright 2017-2021 The Khronos Group Inc. |
| // SPDX-License-Identifier: CC-BY-4.0 |
| |
| 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 |
| link:https://github.com/KhronosGroup/Vulkan-Headers[Vulkan-Headers]) |
| * Vulkan header files (also mirrored at |
| link:https://github.com/KhronosGroup/Vulkan-Headers[Vulkan-Headers]) |
| * Related tools and scripts. |
| |
| The authoritative public repository is located at |
| link:https://github.com/KhronosGroup/Vulkan-Docs/[Vulkan-Docs]. |
| It hosts a public Issue tracker, and outside developers can file proposed |
| changes (Pull Requests) against the Specification, subject to approval by |
| Khronos. |
| |
| If in doubt where to submit your Issue, consult the |
| link:https://github.com/KhronosGroup/Vulkan-Web-Registry/blob/main/Vulkan-Projects.adoc[Vulkan-Projects] list on the link:https://github.com/KhronosGroup/Vulkan-Web-Registry[Vulkan-Web-Registry] |
| repository. |
| |
| |
| == External Contributions |
| |
| Khronos welcomes feedback in Github Issues, and proposed changes in Github |
| Pull Requests (PRs), but will not necessarily accept all such changes. |
| |
| Please keep your issues and pull requests focused on solving a single |
| problem. Broader feedback that tries to solve multiple problems, or touches |
| many parts of the Specification at once, is difficult for the Vulkan Working |
| Group to review in a timely fashion. |
| |
| |
| == Branch Structure |
| |
| The current Specification is maintained in the default branch (currently |
| `main`) of the repository. |
| From this branch it is possible to generate Specifications for any published |
| version of Vulkan (1.2, 1.1, and 1.0), and incorporating any desired set of |
| extensions. |
| Each published update is tagged in the form `1.2.*release*` where *release* |
| is a constantly incrementing release number and `1.2` is the latest |
| published version of the API. |
| The last public spec update prior to Vulkan 1.2 is tagged `v1.1.130`. |
| |
| The last state of the default branch in Khronos' internal gitlab server, |
| before 1.2 content was merged into it, is tagged `1.1-archive` (this tag is |
| not in github). |
| |
| |
| == Directory Structure |
| |
| The directory structure is as follows: |
| |
| ``` |
| README.adoc This file |
| BUILD.adoc Documents how to build the specifications and reference pages |
| CONTRIBUTING.adoc Requirements for external contributions to the repository |
| COPYING.adoc Copyright and licensing information |
| CODE_OF_CONDUCT.adoc Code of Conduct |
| LICENSE.adoc Summary of licenses used by files in the repository |
| 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 |
| proposals/ Design documents for extensions |
| config/ Asciidoctor configuration, CSS, and index generator |
| images/ Images (figures, diagrams, icons) |
| gen/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 (link:xml/vk.xml[`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`. |
| |
