1// Copyright 2017-2023 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)^ and Vulkan^(R)^ SC API Documentation Project
9
10For Vulkan^(R)^ API specific documentation see link:READMEVK.adoc[READMEVK.adoc]
11
12For Vulkan^(R)^ SC API specific documentation see link:READMESC.adoc[READMESC.adoc]
13
14== Directory Structure
15
16The directory structure is as follows:
17
18```
19README.adoc           This file
20READMESC.adoc         Readme for the Vulkan SC specification
21READMEVK.adoc         Readme for the Vulkan specification
22BUILD.adoc            Documents how to build the specifications and reference pages
23CONTRIBUTING.adoc     Requirements for external contributions to the repository
24COPYING.adoc          Copyright and licensing information
25CODE_OF_CONDUCT.adoc  Code of Conduct
26LICENSE.adoc          Summary of licenses used by files in the repository
27ChangeLog.adoc        Change log summary for each public Vulkan spec update
28ChangeLogSC.adoc      Change log summary for each public Vulkan SC spec update
29Makefile, make*       Makefile and helper build scripts (see BUILD.adoc)
30appendices/           Specification appendices
31chapters/             Specification chapters
32proposals/            Design documents for extensions
33config/               Asciidoctor configuration, CSS, and index generator
34images/               Images (figures, diagrams, icons)
35gen/out/              Default directory for the generated documents
36scripts/              Helper scripts used in specification, header, and reference page generation
37style/                Sources for "styleguide" (Vulkan Documentation and Extensions: Procedures and Conventions)
38xml/                  XML API Registry (`vk.xml`) as well as XML for non-Vulkan
39                      data structures used with Video extensions (`video.xml`)
40registry.adoc         Source for documentation of the XML format
41```
42
43
44== Building the Specification and Reference Pages
45
46The document sources are marked up in Asciidoctor format, and we use
47`asciidoctor` and related toolchain components to generate output documents.
48See link:BUILD.adoc[BUILD.adoc] for more information on installing the
49toolchain and building the Specification.
50
51
52== Generating Headers and Related Files
53
54See link:xml/README.adoc[xml/README.adoc].
55
56The header files (`include/vulkan/vulkan*.h`) and many parts of the
57specification and reference page documents are generated from descriptions
58in the XML API Registry (link:xml/vk.xml[`xml/vk.xml`]).
59The generated files are not checked into the repository.
60If you change `vk.xml`, you can regenerate the headers by going into
61`xml/` and running:
62
63    $ make clean install
64
65The other generated files are built as required via dependencies in
66the top-level `Makefile`.
67
68