mirror of
https://github.com/status-im/Vulkan-Docs.git
synced 2025-01-31 16:46:05 +00:00
f1a7c4b4f3
* Update release number to 98.
Public Issues:
* Fix missing markup in flink:vkDestroyPipelineLayout valid usage
statement (pull request 882).
* Add missing contributors for `<<VK_EXT_buffer_device_address>>` (public
pull request 891).
Internal Issues:
* Detect nested bullet points in valid usage blocks and warn about them
during VUID assignment (internal issue 1382).
* Update the style guide to document the process for reserving new bits in
bitmask types (internal issue 1411).
* Clarify for slink:VkApplicationInfo::pname:apiVersion and in the
<<fundamentals-validusage-versions, Valid Usage for Newer Core
Versions>> section when it is valid for an application to use a certain
version of Vulkan API functionality (for an instance and for a
device/physical device); and when the validation layers must generate an
error (internal issue 1412).
* Add optional <<memory-model-availability-visibility, transitive
availability/visibility operations to the memory model, including a new
pname:vulkanMemoryModelAvailabilityVisibilityChains feature for
slink:VkPhysicalDeviceVulkanMemoryModelFeaturesKHR (internal issue
1460).
* Add the code:StorageBuffer storage class to those in the
<<interfaces-resources-descset, Descriptor Set Interface>> (internal
issue 1480).
* Add missing `returnedonly` tags for a number of returned extension
structures that can be passed in pname:pNext chains (internal issue
1515).
* Clean up and rearrange some spec language for
slink:VkRenderPassCreateInfo and slink:VkAttachmentReference.txt
(internal issue 1522).
* Correctly round the code:OpVectorTimesScalar and
code:OpMatrixTimesScalar SPIR-V operations in the <<Precision of core
SPIR-V Instructions>> table (internal merge request 2996).
* Work around cases in flink:vkCmdBeginTransformFeedbackEXT,
flink:vkCmdEndTransformFeedbackEXT, and
slink:VkPipelineCoverageModulationStateCreateInfoNV where an array
parameter is `optional` but the length is not in `vk.xml`. This is an
interim fix using `noautovalidity` + handcoded VU replacing those that
should be autogenerated (internal issue 2944 and
https://github.com/KhronosGroup/Vulkan-ValidationLayers/issues/480).
* Remove redundant capability validation of the code:float16 and code:int8
SPIR-V capabilities from the <<spirvenv-capabilities, Capabilities>>
section, since they are already covered in the preceding table.
* Update check_spec_links script, including validation for reference page
open blocks. Fix errors identified by the script.
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`.