mirror of
https://github.com/status-im/Vulkan-Docs.git
synced 2025-01-10 05:55:38 +00:00
b557dd2167
* Update release number to 96.
Public Issues:
* Fix typo in `vk.xml` for `structextends` attribute of
slink:VkPhysicalDeviceShadingRateImagePropertiesNV (public PR 870).
* Fix links in optimized PDF output (public PR 879).
Internal Issues:
* Add a link to GitHub contributors in the <<credits, Other Credits>>
section (internal issue 808).
* Clarify the behavior of command aliases described in the <<versions,Core
Revisions>> and <<initialization-functionpointers, Command Function
Pointers>> sections and the registry schema document with respect to
whether they are or are not the same entry point, and what the behaviour
of the ftext:vkGet*ProcAddr commands is for each alias (internal issue
1462).
* Update slink:VkPipelineShaderStageCreateInfo valid usage statements for
writing to code:Layer and code:viewportIndex to apply to any vertex
processing stage (internal issue 1475).
* Make sparse image creation optional for Y'C~B~C~R~ formats in the
<<features-required-format-support, Required Format Support>> section
and the <<features-formats-requiring-sampler-ycbcr-conversion, Formats
requiring sampler Y'C~B~C~R~ conversion for
ename:VK_IMAGE_ASPECT_COLOR_BIT image views>> table (internal issue
1476).
* Modify the valid usage statement for
flink:vkCmdDrawIndirectByteCountEXT::pname:vertexStride to use the
pname:maxTransformFeedbackBufferDataStride limit rather than the
pname:maxVertexInputBindingStride limit, which is a better match for
transform feedback related operations (internal issue 1487).
* Changed all members of slink:VkPhysicalDevicePCIBusInfoPropertiesEXT to
have the `uint32_t` type. This is an imcompatible change to an EXT
that's very recently released; although this is against usual Vulkan WG
policy, we discussed and consider this an acceptable risk, but have
polled the mesa-dev list in case there are use cases we missed (internal
issue 1492).
* Set spec vetsion to 1 for `VK_GOOGLE_hlsl_functionality1` and
`VK_GOOGLE_decorate_string` in `vk.xml` (internal MR 2948).
* Remove redundant valid usage statement `VkImageCreateInfo-pNext-02395`
(internal MR 2950).
* Add `check_spec_links.py` script, use it in Gitlab CI, and fix many
minor markup issues discovered by the script (internal MR 2955).
* Update `BUILD.md` to the current Ruby version (2.5.3), and make some
corresponding updates to per-platform build instructions (internal MR
2956).
* Fix binding numbers and other details in
flink:vkUpdateDescriptorSetWithTemplate.txt example code blocks
(internal MR 2960).
* Remove some nautovalidity="true" in `vk.xml` for NV extensions where
it's clearly wrong (internal MR 2970).
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
* the 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 public Issue tracker, and accepts patches (Pull Requests) from the
general public.
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.
[NOTE]
====
Old revisions of the repository maintained the Vulkan 1.0 Specification in
the `1.0` branch, and extensions in the `1.0-VK_EXTENSION_NAME`.
These branches are now **obsolete**, and contain only very old versions of
the Specification (and 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
images/ Images (figures, diagrams, icons)
include/vulkan/ Vulkan headers, generated from the Registry
man/ Reference (man) pages for the API; mostly extracted from the spec source
out/ Default directory for the generated documents
scripts/ Related scripts (but many scripts are still in the root or xml/ directory)
src/ext_loader/ Extension loader library (deprecated)
style/ Sources for "styleguide" (Vulkan Documentation and Extensions: Procedures and Conventions)
xml/ XML API Registry (vk.xml) and related scripts
registry.txt Sources for documentation of the vk.xml format
```
This structure was adopted following 1.1.70 spec update.
There may be additional cleanup and simplification in the future.
== 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 (with the exception of header files) are not checked
into the repository.
If you change `vk.xml`, you can regenerate the header by going into `xml/`
and running:
$ make clean install
The other generated files are built as required via dependencies in
the top-level `Makefile`.