112 lines
4.4 KiB
Plaintext
112 lines
4.4 KiB
Plaintext
// 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`.
|
|
|