1// Copyright 2017-2022 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.3, 1.2, 1.1, and 1.0), and incorporating any desired set of 51extensions. 52Each published update is tagged in the form `1.3.*release*` where *release* 53is a constantly incrementing release number and `1.3` is the latest 54published version of the API. 55The last public spec update prior to Vulkan 1.3 is tagged `v1.2.???`. 56 57The last state of the default branch in Khronos' internal GitLab server, 58before 1.3 content was merged into it, is tagged `1.2-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.adoc 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`) as well as XML for non-Vulkan 84 data structures used with Video extensions (`video.xml`) 85registry.adoc Source for documentation of the XML format 86``` 87 88 89== Building the Specification and Reference Pages 90 91The document sources are marked up in Asciidoctor format, and we use 92`asciidoctor` and related toolchain components to generate output documents. 93See link:BUILD.adoc[BUILD.adoc] for more information on installing the 94toolchain and building the Specification. 95 96 97== Generating Headers and Related Files 98 99See link:xml/README.adoc[xml/README.adoc]. 100 101The header files (`include/vulkan/vulkan*.h`) and many parts of the 102specification and reference page documents are generated from descriptions 103in the XML API Registry (link:xml/vk.xml[`xml/vk.xml`]). 104The generated files are not checked into the repository. 105If you change `vk.xml`, you can regenerate the headers by going into 106`xml/` and running: 107 108 $ make clean install 109 110The other generated files are built as required via dependencies in 111the top-level `Makefile`. 112 113