mirror of
https://github.com/status-im/Vulkan-Docs.git
synced 2025-02-25 04:25:12 +00:00
521e98405f
* Update release number to 120.
Github Issues:
* Add slink:VkAccelerationStructureTypeNV explicitly to extension XML for
`<<VK_NV_ray_tracing>>` (public issue 848).
* Add missing valid usage statements for feature flags in
slink:VkCommandBufferInheritanceInfo (public pull request 1017).
Internal Issues:
* Clarify behavior of non-premultiplied destination colors for
`<<VK_EXT_blend_operation_advanced>>` prior to the definition of
slink:VkBlendOverlapEXT (internal issue 1766).
* Fix the confusing phrasing "`no other queue must: be (doing something)`"
for flink:vkQueuePresentKHR, flink:vkQueueSubmit, and
flink:vkQueueBindSparse (internal issue 1774).
* Add `<<VK_EXT_validation_features>>` flag to enable best practices
checks, which will soon be available in the validation layer (internal
issue 1779).
* Specify allowed characters for VUID tag name components in the style
guide (internal issue 1788).
* Update links to SPIR-V extension specifications, and parameterize their
markup in case the URLs change in the future (internal issue 1797).
* Fix an off-by-one error in the valid usage statement for
slink:VkPipelineExecutableInfoKHR (internal merge request 3303).
* Clean up markup indentation not matching the style guide (internal merge
request 3314).
* Minor script updates to allow refpage aliases, generate a dynamic TOC
for refpages, generate Apache rewrite rules for aliases, open external
links from refpages in a new window, and synchronize with the OpenCL
scripts. This will shortly enable a paned navigation setup for refpages,
similar to the OpenCL 2.2 refpages (internal merge request 3322).
* Script updates to add tests to the checker, refactor and reformat code,
generate better text for some valid usage statements, use more Pythonic
idioms, and synchronize with the OpenXR scripts (internal merge request
3239).
* Script updates and minor fixes in spec language to not raise checker
errors for refpage markup of pages not existing in the API, such as
VKAPI_NO_STDINT_H. Remove corresponding suppression of some
check_spec_links.py tests from .gitlab-ci.yml and 'allchecks' target
(internal merge request 3315).
ifdef::env-github[]
:note-caption: :information_source:
endif::[]
= Vulkan^(R)^ API Documentation Project
This repository contains sources for the formal documentation of the Vulkan
API. This includes:
[options="compact"]
* The Vulkan API Specification
* Specification of Vulkan extensions
* API reference ("`man`") pages
* The XML API Registry (also mirrored at
https://github.com/KhronosGroup/Vulkan-Headers)
* Vulkan header files (also mirrored at
https://github.com/KhronosGroup/Vulkan-Headers)
* Related tools and scripts.
The authoritative public repository is located at
https://github.com/KhronosGroup/Vulkan-Docs/.
It hosts a public Issue tracker, and outside developers can file proposed
patches (Pull Requests) against the Specification, subject to approval
by Khronos.
If in doubt where to submit your Issue, consult the
https://github.com/KhronosGroup/Vulkan-Ecosystem repo.
== Branch Structure
Everything is now maintained in the `master` branch of the repository.
From this branch it is possible to generate both Vulkan 1.1 and Vulkan 1.0
Specifications, as well as specifications for any set of Extensions.
== Directory Structure
The directory structure is as follows:
```
README.adoc This file
BUILD.adoc Documents how to build the specifications, and man pages
COPYING.md Copyright and licensing information
CODE_OF_CONDUCT.md Code of Conduct
ChangeLog.txt Change log summary for each public spec update
Makefile, make* Makefile and helper build scripts (see BUILD.adoc)
appendices/ Specification appendices
chapters/ Specification chapters
config/ Asciidoctor configuration, CSS, and index generator
images/ Images (figures, diagrams, icons)
man/ Reference (man) pages for the API; mostly extracted from the spec source
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)
registry.txt Sources for documentation of the vk.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 (`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`.