Skip to content

Latest commit

 

History

History
116 lines (89 loc) · 4.78 KB

READMESC.adoc

File metadata and controls

116 lines (89 loc) · 4.78 KB

Vulkan® SC API Documentation Project

The VulkanSC-Docs repository (or the equivalent internal Khronos tracking repository) contains sources for the formal documentation of the Vulkan SC API. This includes:

  • The Vulkan SC API Specification

  • Specification of API extensions

  • API reference (“man”) pages

  • The XML API Registry (also mirrored at Vulkan-Headers under the sc_main branch)

  • Vulkan SC header files (also mirrored at Vulkan-Headers under the sc_main branch)

  • Related tools and scripts.

The authoritative public repository is located at VulkanSC-Docs. It hosts a public Issue tracker, and outside developers can file proposed changes (Pull Requests) against the Specification, subject to approval by Khronos.

Questions and feedback on the Vulkan SC specification can be made using the Github Issues and Discussions features on the VulkanSC-Docs repository.

For standard Vulkan (not Vulkan SC) related issues, consult the Vulkan-Projects list on the 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 SC Working Group to review in a timely fashion.

Branch Structure

The current Specification is maintained in the default branch (currently sc_main) of the repository. From this branch it is possible to generate Specifications for any published version of Vulkan SC, and incorporating any desired set of extensions. Each published update is tagged in the form vksc1.0.release where release is a constantly incrementing release number and 1.0 is the latest published version of the API.

Directory Structure

The directory structure is as follows:

README.adoc           Readme for the Vulkan specification
READMESC.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.adoc        Change log summary for each public Vulkan spec update
ChangeLogSC.adoc      Change log summary for each public Vulkan SC 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 SC Documentation and Extensions: Procedures and Conventions)
xml/                  XML API Registry (vk.xml)
registry.adoc         Sources for documentation of the 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 BUILD.adoc for more information on installing the toolchain and building the Specification.

Generating Headers and Related Files

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.