The Vulkan API Specification and related tools
Go to file
Jon Leech 911a764694 Change log for October 7, 2018 Vulkan 1.1.87 spec update:
* Update release number to 87.

Public Issues:

  * Merge flink:vkCmdPipelineBarrier self-dependency barrier VUs referring
    to the same subpass dependency (public pull request 756).
  * Describe default value of `"optional"` attribute in the registry schema
    document (public issue 769)
  * Fix links in <<VK_NVX_raytracing>> extension (public pull request 805).
  * Mark the <<VK_KHR_mir_surface>> extension obsolete (see public issue 814
    - does not close this, however).
  * Fix missing endif in Image Creation block (public issue 817).

Internal Issues:

  * Clarify that the compressed texture formats corresponding to
    <<features-features-textureCompressionETC2>>,
    <<features-features-textureCompressionASTC_LDR>>, and
    <<features-features-textureCompressionBC>> is not contingent on the
    feature bits, and may be supported even if the features are not enabled
    (internal issue 663).
  * Clarify that code:FragStencilRefEXT is output only in the
    <<interfaces-builtin-variables, Built-In Variables>> section (internal
    issue 1173).
  * Identify and correct many overly-aggressive uses of "`undefined`", and
    narrow them down, where straightforward to do so. Mark such resolved
    uses of "`undefined`" with the custom undefined: macro. Add a new
    <<writing-undefined, Describing Undefined Behavior>> section (internal
    issue 1267).
  * Don't require code:inline_uniform_block descriptors to be populated
    before use in the flink:vkAllocateDescriptorSets section (internal issue
    1380).
  * Allow suppressing inline SVG images by controlling this with an
    attribute set in the Makefile, rather than the explicit [%inline]
    directive (internal issue 1391).
  * Mark 'Khronos' as a registered trademark in several places, now that it
    is one.
  * Fix typo in the <<VK_KHR_shader_atomic_int64>> appendix using the GLSL
    naming of the compare exchange op when referring to the SPIR-V op.
  * Specify in the flink:vkGetPhysicalDeviceQueueFamilyProperties section
    that all implementations must support at least one queue family, and
    that every queue family must contain at least one queue.
  * Make slink:VkPipelineDynamicStateCreateInfo::pname:dynamicStateCount,
    slink:VkSampleLocationsInfoEXT::pname:sampleLocationsPerPixel, and
    slink:VkSampleLocationsInfoEXT::pname:sampleLocationsCount optional, to
    fix bogus implicit valid usage checks that were causing failures in the
    conformance tests.
  * Fix vendor tag in reserved extension 237 constants. Does not affect
    anything since it's just a placeholder, but this should avoid further
    comments.
  * Minor markup fixes in some extension appendices.

New Extensions:

  * `<<VK_FUCHSIA_imagepipe_surface>>`
2018-10-07 06:10:21 -07:00
appendices Change log for October 7, 2018 Vulkan 1.1.87 spec update: 2018-10-07 06:10:21 -07:00
chapters Change log for October 7, 2018 Vulkan 1.1.87 spec update: 2018-10-07 06:10:21 -07:00
config Change log for October 7, 2018 Vulkan 1.1.87 spec update: 2018-10-07 06:10:21 -07:00
images Change log for September 19, 2018 Vulkan 1.1.85 spec update: 2018-09-15 18:35:16 -07:00
include/vulkan Change log for October 7, 2018 Vulkan 1.1.87 spec update: 2018-10-07 06:10:21 -07:00
katex Restructure the repository to put the specification Makefile and 2018-04-04 23:08:43 -07:00
man Restructure the repository to put the specification Makefile and 2018-04-04 23:08:43 -07:00
out Change log for March 5, 2018 Vulkan 1.1.72 spec update: 2018-04-05 04:24:56 -07:00
scripts Restructure the repository to put the specification Makefile and 2018-04-04 23:08:43 -07:00
src/ext_loader Change log for May 25, 2018 Vulkan 1.1.76 spec update: 2018-05-25 04:00:32 -07:00
style Change log for October 7, 2018 Vulkan 1.1.87 spec update: 2018-10-07 06:10:21 -07:00
xml Change log for October 7, 2018 Vulkan 1.1.87 spec update: 2018-10-07 06:10:21 -07:00
.gitattributes Restructure the repository to put the specification Makefile and 2018-04-04 23:08:43 -07:00
.gitignore Update gitignore 2018-04-10 01:10:03 +02:00
.gitlab-ci.yml Change log for May 16, 2018 Vulkan 1.1.75 spec update: 2018-05-17 02:38:41 -07:00
BUILD.adoc Restructure the repository to put the specification Makefile and 2018-04-04 23:08:43 -07:00
CODE_OF_CONDUCT.md Add CODE_OF_CONDUCT.md 2018-09-24 10:55:10 -04:00
COPYING.md Change log for June 24, 2017 Vulkan 1.0.53 spec update: 2017-06-26 19:32:10 -07:00
ChangeLog.txt Change log for October 7, 2018 Vulkan 1.1.87 spec update: 2018-10-07 06:10:21 -07:00
Makefile Change log for October 7, 2018 Vulkan 1.1.87 spec update: 2018-10-07 06:10:21 -07:00
README.adoc Restructure the repository to put the specification Makefile and 2018-04-04 23:08:43 -07:00
checkLinks.py Restructure the repository to put the specification Makefile and 2018-04-04 23:08:43 -07:00
copyright-ccby.txt Restructure the repository to put the specification Makefile and 2018-04-04 23:08:43 -07:00
copyright-spec.txt Change log for October 7, 2018 Vulkan 1.1.87 spec update: 2018-10-07 06:10:21 -07:00
fixupRef.py Restructure the repository to put the specification Makefile and 2018-04-04 23:08:43 -07:00
genRef.py Change log for April 15, 2018 Vulkan 1.1.73 spec update: 2018-04-15 03:32:07 -07:00
genRelease Minor build fixes. 2018-06-18 03:24:40 -07:00
genspec.py Minor build fixes. 2018-06-18 03:24:40 -07:00
installRelease Restructure the repository to put the specification Makefile and 2018-04-04 23:08:43 -07:00
makeAllExts Restructure the repository to put the specification Makefile and 2018-04-04 23:08:43 -07:00
makeExt Restructure the repository to put the specification Makefile and 2018-04-04 23:08:43 -07:00
makeKHR Restructure the repository to put the specification Makefile and 2018-04-04 23:08:43 -07:00
promote.py Fix Makefile PATCHVERSION to 72, and finish cleaning up after the 2018-04-05 05:07:37 -07:00
refDesc.py Restructure the repository to put the specification Makefile and 2018-04-04 23:08:43 -07:00
refPageNotes.md Restructure the repository to put the specification Makefile and 2018-04-04 23:08:43 -07:00
reflib.py Change log for April 15, 2018 Vulkan 1.1.73 spec update: 2018-04-15 03:32:07 -07:00
reflow.py Fix Makefile PATCHVERSION to 72, and finish cleaning up after the 2018-04-05 05:07:37 -07:00
reflow_count.py Change log for October 7, 2018 Vulkan 1.1.87 spec update: 2018-10-07 06:10:21 -07:00
registry.txt Change log for October 7, 2018 Vulkan 1.1.87 spec update: 2018-10-07 06:10:21 -07:00
sandboxCopy Change log for March 5, 2018 Vulkan 1.1.72 spec update: 2018-04-05 04:24:56 -07:00
styleguide.txt Change log for October 7, 2018 Vulkan 1.1.87 spec update: 2018-10-07 06:10:21 -07:00
update_valid_usage_ids.sh Fix Makefile PATCHVERSION to 72, and finish cleaning up after the 2018-04-05 05:07:37 -07:00
vkspec.txt Change log for October 7, 2018 Vulkan 1.1.87 spec update: 2018-10-07 06:10:21 -07:00

README.adoc

= Vulkan^(R)^ API Documentation Project

This repository contains formal documentation of the Vulkan API. This
includes the Specification of the Vulkan API, including extensions; the
reference ("`man`") pages; the XML API Registry; header files; and related
tools and scripts.

The authoritative public repository is located at
https://github.com/KhronosGroup/Vulkan-Docs/ . Issues, proposed fixes for
issues, and other suggested changes should be created using Github.


== Branch Structure

With the release of Vulkan 1.1, the current Specification is now maintained
in the `master` branch of the repository. It is possible to generate both
Vulkan 1.1 and Vulkan 1.0 Specifications from this branch.


=== `1.0` Branch Is Obsolete

The `1.0` branch in which the 1.0 Specification was previously maintained is
now obsolete. The `1.0` branch will not be updated going forward, and all
outstanding pull requests or merge requests against the `1.0` branch must be
rebased on, and retargeted to `master`.


== Directory Structure

The directory structure was changed following the 1.1.70 spec update to move
the specification directory to the root of the repository, and move other
content relative to that. There may be additional cleanup and simplification
in the future.


```
README.adoc             This file
BUILD.adoc              Build targets and methods for the specification
ChangeLog.txt           Change log summary for each public spec update
appendices/             Specification appendices
chapters/               Specification chapters
config/                 asciidoc configuration
images/                 Images (figures, diagrams, icons)
include/vulkan/         Vulkan headers, generated from the Registry
man/                    Reference (manual) pages for API, mostly extracted from the spec source
xml/                    XML API Registry (vk.xml) and related scripts
src/ext_loader/         Extension loader library
```


== 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 `BUILD.adoc` for more information on installing the toolchain and
building the Specification.


== Generating Headers and Related Files

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 to `xml/` and
running:

    $ make clean install

The other generated files are built as required via dependencies in
the top-level `Makefile`.