| // Copyright 2017-2023 The Khronos Group Inc. |
| // SPDX-License-Identifier: CC-BY-4.0 |
| |
| ifdef::env-github[] |
| :note-caption: :information_source: |
| endif::[] |
| |
| = Vulkan^(R)^ and Vulkan^(R)^ SC API Documentation Project |
| |
| For Vulkan^(R)^ API specific documentation see link:READMEVK.adoc[READMEVK.adoc] |
| |
| For Vulkan^(R)^ SC API specific documentation see link:READMESC.adoc[READMESC.adoc] |
| |
| == Directory Structure |
| |
| The directory structure is as follows: |
| |
| ``` |
| README.adoc This file |
| READMESC.adoc Readme for the Vulkan SC specification |
| READMEVK.adoc Readme for the Vulkan specification |
| 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 Documentation and Extensions: Procedures and Conventions) |
| xml/ XML API Registry (`vk.xml`) as well as XML for non-Vulkan |
| data structures used with Video extensions (`video.xml`) |
| registry.adoc Source 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 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`. |
| |
