1// Copyright 2017-2021 The Khronos Group Inc. 2// SPDX-License-Identifier: CC-BY-4.0 3 4ifdef::env-github[] 5:note-caption: :information_source: 6endif::[] 7 8= Vulkan^(R)^ API Documentation Project 9 10This repository contains sources for the formal documentation of the Vulkan 11API. This includes: 12 13[options="compact"] 14 * The Vulkan API Specification 15 * Specification of Vulkan extensions 16 * API reference ("`man`") pages 17 * The XML API Registry (also mirrored at 18 link:https://github.com/KhronosGroup/Vulkan-Headers[Vulkan-Headers]) 19 * Vulkan header files (also mirrored at 20 link:https://github.com/KhronosGroup/Vulkan-Headers[Vulkan-Headers]) 21 * Related tools and scripts. 22 23The authoritative public repository is located at 24link:https://github.com/KhronosGroup/Vulkan-Docs/[Vulkan-Docs]. 25It hosts a public Issue tracker, and outside developers can file proposed 26changes (Pull Requests) against the Specification, subject to approval by 27Khronos. 28 29If in doubt where to submit your Issue, consult the 30link: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] 31repository. 32 33 34== External Contributions 35 36Khronos welcomes feedback in Github Issues, and proposed changes in Github 37Pull Requests (PRs), but will not necessarily accept all such changes. 38 39Please keep your issues and pull requests focused on solving a single 40problem. Broader feedback that tries to solve multiple problems, or touches 41many parts of the Specification at once, is difficult for the Vulkan Working 42Group to review in a timely fashion. 43 44 45== Branch Structure 46 47The current Specification is maintained in the default branch (currently 48`main`) of the repository. 49From this branch it is possible to generate Specifications for any published 50version of Vulkan (1.2, 1.1, and 1.0), and incorporating any desired set of 51extensions. 52Each published update is tagged in the form `1.2.*release*` where *release* 53is a constantly incrementing release number and `1.2` is the latest 54published version of the API. 55The last public spec update prior to Vulkan 1.2 is tagged `v1.1.130`. 56 57The last state of the default branch in Khronos' internal gitlab server, 58before 1.2 content was merged into it, is tagged `1.1-archive` (this tag is 59not in github). 60 61 62== Directory Structure 63 64The directory structure is as follows: 65 66``` 67README.adoc This file 68BUILD.adoc Documents how to build the specifications and reference pages 69CONTRIBUTING.adoc Requirements for external contributions to the repository 70COPYING.adoc Copyright and licensing information 71CODE_OF_CONDUCT.adoc Code of Conduct 72LICENSE.adoc Summary of licenses used by files in the repository 73ChangeLog.txt Change log summary for each public spec update 74Makefile, make* Makefile and helper build scripts (see BUILD.adoc) 75appendices/ Specification appendices 76chapters/ Specification chapters 77proposals/ Design documents for extensions 78config/ Asciidoctor configuration, CSS, and index generator 79images/ Images (figures, diagrams, icons) 80gen/out/ Default directory for the generated documents 81scripts/ Helper scripts used in specification, header, and reference page generation 82style/ Sources for "styleguide" (Vulkan Documentation and Extensions: Procedures and Conventions) 83xml/ XML API Registry (vk.xml) 84registry.txt Sources for documentation of the vk.xml format 85``` 86 87 88== Building the Specification and Reference Pages 89 90The document sources are marked up in Asciidoctor format, and we use 91`asciidoctor` and related toolchain components to generate output documents. 92See link:BUILD.adoc[BUILD.adoc] for more information on installing the 93toolchain and building the Specification. 94 95 96== Generating Headers and Related Files 97 98See link:xml/README.adoc[xml/README.adoc]. 99 100The header files (`include/vulkan/vulkan*.h`) and many parts of the 101specification and reference page documents are generated from descriptions 102in the XML API Registry (link:xml/vk.xml[`xml/vk.xml`]). 103The generated files are not checked into the repository. 104If you change `vk.xml`, you can regenerate the headers by going into 105`xml/` and running: 106 107 $ make clean install 108 109The other generated files are built as required via dependencies in 110the top-level `Makefile`. 111 112