status-im
/
Vulkan-Docs
mirror of https://github.com/status-im/Vulkan-Docs.git
2
0
Fork 0
Code Issues Projects Releases Wiki Activity

Change log for February 17, 2017 Vulkan 1.0.41 spec update: 

* Bump API patch number and header version number to 41 for this update.

Github Issues:

  * Made all uses of `NULL` vs. code:VK_NULL_HANDLE consistent (public issue
    276).
  * Clarify render pass compatibility in different usage scenarios (public
    issues 303 and 304).
  * Add valid usage statements to slink:VkFramebufferCreateInfo requiring
    that the width, height, and number of layers of the framebuffer all be
    nonzero (public issue 432).
  * Allow `offset` and `align` in any GLSL version for the
    `GL_KHR_vulkan_glsl` extension (public issue 435).
  * Specify lifetime of string objects passed to the
    tlink:PFN_vkDebugReportCallbackEXT user callback in the
    +VK_EXT_debug_report+ extension (public issue 446).
  * Fix inter-page links in multi-file reference pages (public issue 454).

Internal Issues:

  * Update valid usage language for slink:VkImageCreateInfo to disallow
    creating images that have ename:VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT
    set without other attachment usage bits
    (ename:VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT,
    ename:VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT, or
    ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT) (internal issue 540).
  * Disable `VK_EXT_swapchain_colorspace` extension until internal issues
    640 and 661 are mutually resolved.
  * Allow alternative mipmap level selection when [eq]#lambda == 0.5# during
    texture <<textures-image-level-selection,Image Level(s) Selection>>
    (internal issue 680).

Other Issues:

  * Add a clarification to the style guide that the extension revision
    number is treated as a patch number, so that changes to published
    extensions should only include bug fixes and spec clarifications.
This commit is contained in:
Jon Leech 2017-02-17 03:57:46 -08:00
parent c1d03fdd6f
commit e29a51b231
32 changed files with 613 additions and 497 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

42
ChangeLog.txt
View File

@ -1912,3 +1912,45 @@ Other Issues:
flink:vkGetPhysicalDeviceSparseImageFormatProperties2KHR::pname:pFormatInfo flink:vkGetPhysicalDeviceSparseImageFormatProperties2KHR::pname:pFormatInfo
to be below the flink:VkPhysicalDeviceSparseImageFormatInfo2KHR to be below the flink:VkPhysicalDeviceSparseImageFormatInfo2KHR
structure. structure.
-----------------------------------------------------
Change log for February 17, 2017 Vulkan 1.0.41 spec update:
* Bump API patch number and header version number to 41 for this update.
Github Issues:
* Made all uses of `NULL` vs. code:VK_NULL_HANDLE consistent (public issue
276).
* Clarify render pass compatibility in different usage scenarios (public
issues 303 and 304).
* Add valid usage statements to slink:VkFramebufferCreateInfo requiring
that the width, height, and number of layers of the framebuffer all be
nonzero (public issue 432).
* Allow `offset` and `align` in any GLSL version for the
`GL_KHR_vulkan_glsl` extension (public issue 435).
* Specify lifetime of string objects passed to the
tlink:PFN_vkDebugReportCallbackEXT user callback in the
+VK_EXT_debug_report+ extension (public issue 446).
* Fix inter-page links in multi-file reference pages (public issue 454).
Internal Issues:
* Update valid usage language for slink:VkImageCreateInfo to disallow
creating images that have ename:VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT
set without other attachment usage bits
(ename:VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT,
ename:VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT, or
ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT) (internal issue 540).
* Disable `VK_EXT_swapchain_colorspace` extension until internal issues
640 and 661 are mutually resolved.
* Allow alternative mipmap level selection when [eq]#lambda == 0.5# during
texture <<textures-image-level-selection,Image Level(s) Selection>>
(internal issue 680).
Other Issues:
* Add a clarification to the style guide that the extension revision
number is treated as a patch number, so that changes to published
extensions should only include bug fixes and spec clarifications.

53
README.adoc Normal file
View File

@ -0,0 +1,53 @@
Vulkan^(R)^ API Documentation Project
=====================================
This repository contains formal documentation of the Vulkan API. This
includes the main API Specification, the reference (man) pages, the XML API
Registry, and related tools and scripts.
Single-Branch Model
-------------------
As of the 1.0.25 release, we have switched to a new "`single-branch`" model
in which all extensions are included in the source of the 1.0 branch of the
Specification, and can be configured in or out of the build using Makefile
options.
Repository Structure
--------------------
```
README.adoc This file
ChangeLog.txt Change log summary for each public spec update
doc/specs/ Main documentation tree
vulkan/ Vulkan specification
appendices/ Appendices - one file each
chapters/ Chapters - one file each
config/ asciidoc configuration
images/ Images (figures, diagrams, icons)
man/ Reference (manual) pages for API, mostly extracted from the spec source
misc/ Related specifications (GL_KHR_vulkan_glsl)
src/spec/ XML API Registry (vk.xml) and related scripts
src/vulkan/ Vulkan headers, generated from the Registry
```
Building the Specification and Reference Pages
----------------------------------------------
As of the 1.0.40 release, we have moved from the old `asciidoc` toolchain to
a new one based on `asciidoctor`. See `doc/specs/vulkan/README.adoc` for
more information on installing the toolchain and building the Specification.
Generating Headers and Related Files
------------------------------------
The header file (`src/vulkan/vulkan.h`) and many parts of the specification
and reference page documents are generated from descriptions in the XML API
Registry (`src/spec/vk.xml`). The generated files, with the exception of
`vulkan.h`, are not checked into the repository. If you change `vk.xml`, you
can regenerate the header by going to `src/spec` and running:
$ make clobber install
The other generated files are built as required via dependencies in
`doc/specs/vulkan/Makefile` .

118
README.md
View File

@ -1,118 +0,0 @@
Vulkan<sup>:registered:</sup> API Documentation Project
=======================================================
This repository contains formal documentation of the Vulkan API. This
includes the main API Specification, the reference (man) pages, the XML API
Registry, and related tools and scripts.
Single-Branch Model
-------------------
As of the 1.0.25 release, we have switch to a new 'single-branch' model in
which all extensions are included in the source of the 1.0 branch of the
Specification, and can be configured in or out of the build using Makefile
options.
The single-branch model seems to be working for all the spec builds,
although there are probably a few issues we haven't caught yet. The ref page
build needs some additional work, as genRef.py is creating reference pages
for all interfaces, not just those for the API and extensions being built,
and we'll get to that within a week or two. The validation scripts also need
to be tweaked further for the single-branch model.
Repository Structure
--------------------
```
README.md This file
ChangeLog.txt Change log summary
doc/specs/ Main documentation tree
vulkan/ Vulkan specification
appendices/ Appendices - one file each
chapters/ Chapters - one file each
config/ asciidoc configuration
images/ Images (figures, diagrams, icons)
man/ Reference (manual) pages for API, mostly extracted from the spec source
misc/ Related specifications (GL_KHR_vulkan_glsl)
src/spec/ XML API Registry (vk.xml) and related scripts
src/vulkan/ Vulkan headers, generated from the Registry
```
Building the Specification and Reference Pages
----------------------------------------------
To build the documents, you need to install, at a minimum:
* GNU-compatible make
* asciidoc (http://www.methods.co.nz/asciidoc/)
On some systems/build targets you may also need:
* dblatex
* source-highlight
These tools are known to work on several varieties of Linux, MacOS X, and
Cygwin running under Microsoft Windows.
There are several make targets in doc/specs/vulkan :
* make html - Build one large HTML specification document.
* make pdf - Build one large PDF specification document.
* make manhtml - Make HTML API reference (all man pages as one big file).
* make manpdf - Make a one-giant PDF API reference.
* make manhtmlpages - Make man pages as one-file-per-API.
* make allchecks - Run the validation rules on the specification.
The outputs will be written to $(OUTDIR), which defaults to out/ at the root
of the checked-out git repository.
To build PDF outputs (make pdf, make manpdf), you need
dblatex and a LaTeX processor. The PDF builds are
currently configured to use asciidoc to go from asciidoc markdown to docbook, and
then run the result through dblatex to go from there to LaTeX and then
through your LaTeX processor to PDF.
Spec Validation
---------------
There are a couple of validation tools which look for inconsistencies and
missing material between the specification and ref pages, and the canonical
description of the API in vk.xml :
* checkinc
* checklinks
* allchecks - both checkinc and checklinks
They are necessarily heuristic since they're dealing with lots of
hand-written material. To use them you'll also need to install:
* python3
The '''checkinc''' target uses Unix filters to determine which autogenerated
API include files are used (and not used) in the spec. It generates several
output files, but the only one you're likely to care about is
'''actual.only'''. This is a list of the include files which are *not*
referenced anywhere in the spec, and probably correspond to undocumented
material in the spec.
The '''checklinks''' target validates the various internal tagged links in
the man pages and spec (e.g. the '''fname:vkFuncBlah''',
'''sname:VkStructBlah''', etc.) against the canonical description of the API
in vk.xml . It generates two output files, manErrs.txt and specErrs.txt,
which report problematic tags and the filenames/lines on which those tags
were found.
Generating Headers and Related Files
------------------------------------
The header file (src/vulkan/vulkan.h) and many parts of the specification
and reference page documents are generated from descriptions in the XML API
Registry (src/spec/vk.xml). The generated files, with the exception
of vulkan.h, are not checked into the repository. If you change vk.xml, you
can regenerate the header by going to src/spec and running:
* make clobber install
The other generated files are built as required via dependencies in
doc/specs/vulkan/Makefile .

60
doc/specs/misc/GL_KHR_vulkan_glsl.txt
View File

@ -33,8 +33,8 @@ Status
Version Version
Last Modified Date: 26-Jan-2017 Last Modified Date: 07-Feb-2017
Revision: 34 Revision: 35
Number Number
@ -77,6 +77,8 @@ Overview
* specialization constants * specialization constants
* gl_VertexIndex and gl_InstanceIndex * gl_VertexIndex and gl_InstanceIndex
* subpass inputs * subpass inputs
* 'offset' and 'align' layout qualifiers for uniform/buffer blocks for
versions that did not support them
The following features are changed: The following features are changed:
* precision qualifiers (mediump and lowp) will be respected for all * precision qualifiers (mediump and lowp) will be respected for all
@ -898,26 +900,49 @@ Changes to Chapter 4 of the OpenGL Shading Language Specification
"However, when push_constant is declared, the default layout of the "However, when push_constant is declared, the default layout of the
buffer will be std430. There is no method to globally set this default." buffer will be std430. There is no method to globally set this default."
Change from: Add to section 4.4.5 Uniform and Shader Storage Block Layout Qualifiers,
for versions not having 'offset' and 'align' description language,
or replace with the following for versions that do have 'offset' and
'align' description language:
"It is a compile-time error to specify an offset that is smaller than the "The 'offset' qualifier can only be used on block members of 'uniform' or
offset of the previous member in the block or that lies within the 'buffer' blocks. The 'offset' qualifier forces the qualified member to
previous member of the block." start at or after the specified integral-constant-expression, which will
be its byte offset from the beginning of the buffer. It is a compile-time
error to have any offset, explicit or assigned, that lies within another
member of the block. Two blocks linked together in the same program with
the same block name must have the exact same set of members qualified
with 'offset' and their integral-constant-expression values must be the
same, or a link-time error results. The specified 'offset' must be a
multiple of the base alignment of the type of the block member it
qualifies, or a compile-time error results.
To instead say: "The 'align' qualifier can only be used on block members of 'uniform' or
'buffer' blocks. The 'align' qualifier makes the start of each block
buffer have a minimum byte alignment. It does not affect the internal
layout within each member, which will still follow the std140 or std430
rules. The specified alignment must be greater than 0 and a power of 2,
or a compile-time error results.
"It is a compile-time error to have any offset, explicit or assigned, "The actual alignment of a member will be the greater of the specified
that lies within another member of the block." 'align' alignment and the standard (e.g., std140) base alignment for the
member's type. The actual offset of a member is computed as follows:
If 'offset' was declared, start with that offset, otherwise start with
the offset immediately following the preceding member (in declaration
order). If the resulting offset is not a multiple of the actual
alignment, increase it to the first offset that is a multiple of the
actual alignment. This results in the actual offset the member will have.
Change from: "When 'align' is applied to an array, it affects only the start of the
array, not the array's internal stride. Both an 'offset' and an 'align'
qualifier can be specified on a declaration.
"If offset was declared, start with that offset, otherwise start with the "The 'align' qualifier, when used on a block, has the same effect as
next available offset." qualifying each member with the same 'align' value as declared on the
block, and gets the same compile-time results and errors as if this had
To instead say: been done. As described in general earlier, an individual member can
specify its own 'align', which overrides the block-level 'align', but
"If offset was declared, start with that offset, otherwise start with the just for that member."
offset immediately following the preceding member (in declaration order)."
Remove the following preamble from section 4.7, which exists for desktop Remove the following preamble from section 4.7, which exists for desktop
versions, but not ES versions. Removal: versions, but not ES versions. Removal:
@ -1330,6 +1355,7 @@ Revision History
Rev. Date Author Changes Rev. Date Author Changes
---- ----------- ------- -------------------------------------------- ---- ----------- ------- --------------------------------------------
35 07-Feb-2017 JohnK Add 'offset' and 'align' to all versions
34 26-Jan-2017 JohnK Allow the ternary operator to result in a 34 26-Jan-2017 JohnK Allow the ternary operator to result in a
specialization constant specialization constant
33 30-Aug-2016 JohnK Allow out-of-order offsets in a block 33 30-Aug-2016 JohnK Allow out-of-order offsets in a block

4
doc/specs/vulkan/Makefile
View File

@ -84,7 +84,7 @@ VERBOSE =
# $(EXTENSIONS)) # $(EXTENSIONS))
# ADOCOPTS options for asciidoc->HTML5 output # ADOCOPTS options for asciidoc->HTML5 output
NOTEOPTS = -a editing-notes -a implementation-guide NOTEOPTS = -a editing-notes -a implementation-guide
SPECREVISION = 1.0.40 SPECREVISION = 1.0.41
# Spell out RFC2822 format as not all date commands support -R # Spell out RFC2822 format as not all date commands support -R
SPECDATE = $(shell echo `date -u "+%a, %d %b %Y %T %z"`) SPECDATE = $(shell echo `date -u "+%a, %d %b %Y %T %z"`)
@ -256,7 +256,7 @@ manhtmlpages: man/apispec.txt $(MANHTML)
$(MANHTMLDIR)/%.html: KATEXDIR = ../../katex $(MANHTMLDIR)/%.html: KATEXDIR = ../../katex
$(MANHTMLDIR)/%.html: $(MANDIR)/%.txt $(MANCOPYRIGHT) $(GENINCLUDE) $(GENDEPENDS) katexinst $(MANHTMLDIR)/%.html: $(MANDIR)/%.txt $(MANCOPYRIGHT) $(GENINCLUDE) $(GENDEPENDS) katexinst
$(QUIET)$(MKDIR) $(MANHTMLDIR) $(QUIET)$(MKDIR) $(MANHTMLDIR)
$(QUIET)$(ASCIIDOC) -b html5 $(ADOCOPTS) $(ADOCHTMLOPTS) -d manpage -o $@ $< $(QUIET)$(ASCIIDOC) -b html5 -a cross-file-links $(ADOCOPTS) $(ADOCHTMLOPTS) -d manpage -o $@ $<
# These targets are HTML5 and PDF single-file versions of the ref pages # These targets are HTML5 and PDF single-file versions of the ref pages

296
doc/specs/vulkan/README.adoc
View File

@ -18,8 +18,8 @@ Dependencies>> below), go to `...path-to-git-repo/doc/specs/vulkan` .
$ make all $ make all
or make the individual targets `html`. `pdf`. `styleguide`. `manhtml`. or make the individual targets `html`, `pdf`, `styleguide`, `manhtml`,
`manpdf`. `manhtmlpages`. `checkinc`. and `checklinks`. `manpdf`, `manhtmlpages`, `checkinc`, and `checklinks`.
will generate a variety of targets in the directory specified by the will generate a variety of targets in the directory specified by the
Makefile variable `$(OUTDIR)` (by default, `../../../out/1.0`). Makefile variable `$(OUTDIR)` (by default, `../../../out/1.0`).
@ -45,7 +45,9 @@ targets, or they can individually be found as follows:
Once you have the basic build working, an appropriate parallelization option Once you have the basic build working, an appropriate parallelization option
to make, such as to make, such as
$ make -j 8 ----
make -j 8
----
may significantly speed up the reference page builds. may significantly speed up the reference page builds.
@ -105,7 +107,42 @@ Instead, all output forms required are checked into `images/` .
On the rare occasions that someone changes a source document and needs to On the rare occasions that someone changes a source document and needs to
regenerate the other forms: regenerate the other forms:
$ cd images ; make ----
cd images ; make
----
=== Validation Scripts
There are a several Makefile targets which look for inconsistencies and
missing material between the specification and ref pages, and the canonical
description of the API in `vk.xml` :
* `checkinc`
* `checklinks`
* `allchecks` - both `checkinc` and `checklinks`
They are necessarily heuristic since they're dealing with lots of
hand-written material.
To use them you'll also need to install:
* `python3`
The `checkinc` target uses Unix filters to determine which autogenerated API
include files are used (and not used) in the spec.
It generates several output files, but the only one you're likely to care
about is `actual.only`.
This is a list of the include files which are *not* referenced anywhere in
the spec, and probably correspond to undocumented material in the spec.
The `checklinks` target validates the various internal tagged links in the
man pages and spec (e.g. the `fname:vkFuncBlah`, `sname:VkStructBlah`, etc.)
against the canonical description of the API in `vk.xml`.
It generates two output files, `manErrs.txt` and `specErrs.txt`, which
report problematic tags and the filenames/lines on which those tags were
found.
[[macros]] [[macros]]
@ -148,7 +185,10 @@ automatically, when possible (e.g. for `Vk*FlagBits` pages).
If for some reason you want to regenerate the ref pages from scratch If for some reason you want to regenerate the ref pages from scratch
yourself, you can do so by yourself, you can do so by
$ rm man/apispec.txt ; make apispec.txt ----
rm man/apispec.txt
make apispec.txt
----
The `genRef.py` script will generate many warnings, but most are just The `genRef.py` script will generate many warnings, but most are just
reminders that some pages are automatically generated. reminders that some pages are automatically generated.
@ -232,13 +272,17 @@ For example,
For example, in chapter +synchronization.txt+: For example, in chapter +synchronization.txt+:
[[synchronization-primitives]] ----
Synchronization Primitives [[synchronization-primitives]]
Synchronization Primitives
----
Cross-references to those anchors can then be generated with, for example, Cross-references to those anchors can then be generated with, for example,
See the <<synchronization-primitives>> section for discussion of fences, ----
semaphores, and events. See the <<synchronization-primitives>> section for discussion of fences,
semaphores, and events.
----
You can also add anchors on arbitrary paragraphs, using a similar naming You can also add anchors on arbitrary paragraphs, using a similar naming
scheme. scheme.
@ -250,7 +294,9 @@ anchor whose name is the name of the function, struct, etc.
being defined. being defined.
Therefore you can say something like: Therefore you can say something like:
Fences are used with the +++<<vkQueueSubmit>>+++ command... ----
Fences are used with the +++<<vkQueueSubmit>>+++ command...
----
[[depends]] [[depends]]
@ -329,7 +375,11 @@ MinGW, or Cygwin.
When using the "`Ubuntu Subsystem`" for Windows 10, most dependencies can be When using the "`Ubuntu Subsystem`" for Windows 10, most dependencies can be
installed via apt-get: installed via apt-get:
$ sudo apt-get -qq -y install build-essential python3 git cmake bison flex libffi-dev libxml2-dev libgdk-pixbuf2.0-dev libcairo2-dev libpango1.0-dev ttf-lyx gtk-doc-tools ----
sudo apt-get -qq -y install build-essential python3 git cmake bison flex \
libffi-dev libxml2-dev libgdk-pixbuf2.0-dev libcairo2-dev \
libpango1.0-dev ttf-lyx gtk-doc-tools
----
The default ruby packages on Ubuntu are fairly out of date. The default ruby packages on Ubuntu are fairly out of date.
Ubuntu only provides `ruby` and `ruby2.0` - the latter is multiple revisions Ubuntu only provides `ruby` and `ruby2.0` - the latter is multiple revisions
@ -388,58 +438,61 @@ developed on an essentially out-of-the-box environment, follows.
If you try this, don't try to execute the entire thing at once. If you try this, don't try to execute the entire thing at once.
Do each step separately in case of errors we didn't encounter. Do each step separately in case of errors we didn't encounter.
# Install packages needed by `ruby_build` and by toolchain components. ----
# See https://github.com/rbenv/ruby-build/wiki and # Install packages needed by `ruby_build` and by toolchain components.
# https://github.com/asciidoctor/asciidoctor-mathematical#dependencies # See https://github.com/rbenv/ruby-build/wiki and
# https://github.com/asciidoctor/asciidoctor-mathematical#dependencies
sudo apt-get install autoconf bison build-essential libssl-dev \ sudo apt-get install autoconf bison build-essential libssl-dev \
libyaml-dev libreadline6-dev zlib1g-dev libncurses5-dev \ libyaml-dev libreadline6-dev zlib1g-dev libncurses5-dev \
libffi-dev libgdbm3 libgdbm-dev install cmake libxml2 \ libffi-dev libgdbm3 libgdbm-dev install cmake libxml2 \
libxml2-dev flex pkg-config install libglib2.0-dev \ libxml2-dev flex pkg-config install libglib2.0-dev \
libcairo-dev libpango1.0-dev libgdk-pixbuf2.0-dev \ libcairo-dev libpango1.0-dev libgdk-pixbuf2.0-dev \
libpangocairo-1.0 libpangocairo-1.0
# Install rbenv from https://github.com/rbenv/rbenv # Install rbenv from https://github.com/rbenv/rbenv
git clone https://github.com/rbenv/rbenv.git ~/.rbenv git clone https://github.com/rbenv/rbenv.git ~/.rbenv
# Set path to shim layers in .bashrc # Set path to shim layers in .bashrc
echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> .bashrc echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> .bashrc
~/.rbenv/bin/rbenv init ~/.rbenv/bin/rbenv init
# Set .rbenv environment variables in .bashrc
echo 'eval "$(rbenv init -)"' >> .bashrc
# Restart your shell (e.g. open a new terminal window). Note that # Set .rbenv environment variables in .bashrc
# you do not need to use the `-l` option, since the modifications echo 'eval "$(rbenv init -)"' >> .bashrc
# were made to .bashrc rather than .bash_profile. If successful,
# `type rbenv` should print 'rbenv is a function' followed by code.
# Install `ruby_build` plugin from https://github.com/rbenv/ruby-build # Restart your shell (e.g. open a new terminal window). Note that
# you do not need to use the `-l` option, since the modifications
# were made to .bashrc rather than .bash_profile. If successful,
# `type rbenv` should print 'rbenv is a function' followed by code.
git clone https://github.com/rbenv/ruby-build.git # Install `ruby_build` plugin from https://github.com/rbenv/ruby-build
~/.rbenv/plugins/ruby-build
# Install Ruby 2.3.3 git clone https://github.com/rbenv/ruby-build.git
# This takes in excess of 20 min. to build! ~/.rbenv/plugins/ruby-build
# https://github.com/rbenv/ruby-build/issues/1054#issuecomment-276934761
# suggests:
# "You can speed up Ruby installs by avoiding generating ri/RDoc
# documentation for them:
# RUBY_CONFIGURE_OPTS=--disable-install-doc rbenv install 2.3.3
# We have not tried this.
rbenv install 2.3.3 # Install Ruby 2.3.3
# This takes in excess of 20 min. to build!
# https://github.com/rbenv/ruby-build/issues/1054#issuecomment-276934761
# suggests:
# "You can speed up Ruby installs by avoiding generating ri/RDoc
# documentation for them:
# RUBY_CONFIGURE_OPTS=--disable-install-doc rbenv install 2.3.3
# We have not tried this.
# Configure rbenv globally to always use Ruby 2.3.3. rbenv install 2.3.3
echo "2.3.3" > ~/.rbenv/version
# Finally, install toolchain components. # Configure rbenv globally to always use Ruby 2.3.3.
# asciidoctor-mathematical also takes in excess of 20 min. to build! echo "2.3.3" > ~/.rbenv/version
# The same RUBY_CONFIGURE_OPTS advice above may apply here as well.
gem install asciidoctor coderay # Finally, install toolchain components.
gem install --pre asciidoctor-pdf # asciidoctor-mathematical also takes in excess of 20 min. to build!
MATHEMATICAL_SKIP_STRDUP=1 gem install asciidoctor-mathematical # The same RUBY_CONFIGURE_OPTS advice above may apply here as well.
gem install asciidoctor coderay
gem install --pre asciidoctor-pdf
MATHEMATICAL_SKIP_STRDUP=1 gem install asciidoctor-mathematical
----
[[depends-ubuntu-rvm]] [[depends-ubuntu-rvm]]
@ -447,11 +500,13 @@ Do each step separately in case of errors we didn't encounter.
Here are (sparser) instructions for using rvm to setup version 2.3.x: Here are (sparser) instructions for using rvm to setup version 2.3.x:
gpg --keyserver hkp://keys.gnupg.net --recv-keys 409B6B1796C275462A1703113804BB82D39DC0E3 ----
\curl -sSL https://get.rvm.io | bash -s stable --ruby gpg --keyserver hkp://keys.gnupg.net --recv-keys 409B6B1796C275462A1703113804BB82D39DC0E3
source ~/.rvm/scripts/rvm \curl -sSL https://get.rvm.io | bash -s stable --ruby
rvm install ruby-2.3 source ~/.rvm/scripts/rvm
rvm use ruby-2.3 rvm install ruby-2.3
rvm use ruby-2.3
----
NOTE: Windows 10 Bash will need to be launched with the "-l" option NOTE: Windows 10 Bash will need to be launched with the "-l" option
appended, so that it runs a login shell; otherwise RVM won't function appended, so that it runs a login shell; otherwise RVM won't function
@ -461,14 +516,13 @@ correctly on future launches.
[[depends-ubuntu-sys]] [[depends-ubuntu-sys]]
===== Ubuntu 16.04 using system Ruby ===== Ubuntu 16.04 using system Ruby
The Ubuntu 16.04.1 default Ruby install (v. 2.3.1) seems to be up-to-date The Ubuntu 16.04.1 default Ruby install (version 2.3.1) seems to be
enough to run all the required gems, but also needs the up-to-date enough to run all the required gems, but also needs the
`ruby-dev` package installed through the package manager. `ruby-dev` package installed through the package manager.
In addition, the library In addition, the library
`/var/lib/gems/2.3.0/gems/mathematical-1.6.7/ext/mathematical/lib/liblasem.so` `/var/lib/gems/2.3.0/gems/mathematical-1.6.7/ext/mathematical/lib/liblasem.so`
has to be copied or linked into a directory where the loader can find has to be copied or linked into a directory where the loader can find it.
it.
This requirement appears to be due to a problem with the This requirement appears to be due to a problem with the
asciidoctor-mathematical build process. asciidoctor-mathematical build process.
@ -489,9 +543,9 @@ installed by MinGW.
In the native Windows environment, you should also install the following In the native Windows environment, you should also install the following
native packages: native packages:
- Python 3.x (https://www.python.org/downloads/) * Python 3.x (https://www.python.org/downloads/)
- Ruby 2.x (https://rubyinstaller.org/) * Ruby 2.x (https://rubyinstaller.org/)
- Git command-line client (https://git-scm.com/download) * Git command-line client (https://git-scm.com/download)
Once this is setup, and the necessary <<depends-gems,Ruby Gems>> are Once this is setup, and the necessary <<depends-gems,Ruby Gems>> are
installed, launch the `msys` bash shell, and navigate to the spec Makefile. installed, launch the `msys` bash shell, and navigate to the spec Makefile.
@ -510,29 +564,32 @@ mingw32 build of it available.
When installing Cygwin, you should install the following packages via When installing Cygwin, you should install the following packages via
`setup`: `setup`:
autoconf ----
bison // "curl" is only used to download fonts, can be done in another way
cmake autoconf
curl // Only used to download fonts, can be done in another way bison
flex cmake
gcc-core curl
gcc-g++ flex
git gcc-core
libbz2-devel gcc-g++
libcairo-devel git
libcairo2 libbz2-devel
libffi-devel libcairo-devel
libgdk_pixbuf2.0-devel libcairo2
libiconv libffi-devel
liblasem0.4-devel libgdk_pixbuf2.0-devel
libpango1.0-devel libiconv
libpango1.0_0 liblasem0.4-devel
libxml2 libpango1.0-devel
libxml2-devel libpango1.0_0
make libxml2
python3 libxml2-devel
ruby make
ruby-devel python3
ruby
ruby-devel
----
NOTE: Native versions of some of these packages are usable, but care should NOTE: Native versions of some of these packages are usable, but care should
be taken for incompatibilities with various parts of cygwin - e.g. paths. be taken for incompatibilities with various parts of cygwin - e.g. paths.
@ -545,11 +602,15 @@ When it comes to installing the mathematical ruby gem, there are two things
that will require tweaking to get it working. that will require tweaking to get it working.
Firstly, instead of: Firstly, instead of:
MATHEMATICAL_SKIP_STRDUP=1 gem install asciidoctor-mathematical ----
MATHEMATICAL_SKIP_STRDUP=1 gem install asciidoctor-mathematical
----
You should use You should use
MATHEMATICAL_USE_SYSTEM_LASEM=1 gem install asciidoctor-mathematical ----
MATHEMATICAL_USE_SYSTEM_LASEM=1 gem install asciidoctor-mathematical
----
The latter causes it to use the lasem package already installed, rather than The latter causes it to use the lasem package already installed, rather than
trying to build a fresh one. trying to build a fresh one.
@ -558,7 +619,9 @@ The mathematical gem also looks for "liblasem" rather than "liblasem0.4" as
installed by the lasem0.4-devel package, so it is necessary to add a symlink installed by the lasem0.4-devel package, so it is necessary to add a symlink
to your /lib directory using: to your /lib directory using:
ln -s /lib/liblasem-0.4.dll.a /lib/liblasem.dll.a ----
ln -s /lib/liblasem-0.4.dll.a /lib/liblasem.dll.a
----
<<Ruby Gems>> are not installed to a location that is in your path normally. <<Ruby Gems>> are not installed to a location that is in your path normally.
Gems are installed to `~/bin/` - you should add this to your path before Gems are installed to `~/bin/` - you should add this to your path before
@ -569,16 +632,17 @@ calling make:
Finally, you'll need to manually install fonts for lasem via the following Finally, you'll need to manually install fonts for lasem via the following
commands: commands:
mkdir /usr/share/fonts/truetype ----
cd /usr/share/fonts/truetype mkdir /usr/share/fonts/truetype cd /usr/share/fonts/truetype
curl -LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/cmex10.ttf \ curl -LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/cmex10.ttf \
-LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/cmmi10.ttf \ -LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/cmmi10.ttf \
-LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/cmr10.ttf \ -LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/cmr10.ttf \
-LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/cmsy10.ttf \ -LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/cmsy10.ttf \
-LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/esint10.ttf \ -LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/esint10.ttf \
-LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/eufm10.ttf \ -LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/eufm10.ttf \
-LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/msam10.ttf \ -LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/msam10.ttf \
-LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/msbm10.ttf -LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/msbm10.ttf
----
[[depends-osx]] [[depends-osx]]
@ -591,15 +655,17 @@ package via `brew` rather than using a ruby-specific version manager.
You'll likely also need to install additional fonts for the PDF build via You'll likely also need to install additional fonts for the PDF build via
mathematical, which you can do with: mathematical, which you can do with:
cd ~/Library/Fonts ----
curl -LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/cmex10.ttf \ cd ~/Library/Fonts
-LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/cmmi10.ttf \ curl -LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/cmex10.ttf \
-LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/cmr10.ttf \ -LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/cmmi10.ttf \
-LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/cmsy10.ttf \ -LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/cmr10.ttf \
-LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/esint10.ttf \ -LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/cmsy10.ttf \
-LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/eufm10.ttf \ -LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/esint10.ttf \
-LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/msam10.ttf \ -LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/eufm10.ttf \
-LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/msbm10.ttf -LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/msam10.ttf \
-LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/msbm10.ttf
----
Then install the required <<depends-gems,Ruby Gems>>. Then install the required <<depends-gems,Ruby Gems>>.
@ -627,16 +693,19 @@ install the required <<depends-gems,Ruby Gems>>.
The following ruby gems can be installed directly via the `gem install` The following ruby gems can be installed directly via the `gem install`
command, once the platform is set up: command, once the platform is set up:
gem install rake asciidoctor coderay ----
gem install rake asciidoctor coderay
# Required only for pdf builds # Required only for pdf builds MATHEMATICAL_SKIP_STRDUP=1 gem install
MATHEMATICAL_SKIP_STRDUP=1 gem install asciidoctor-mathematical asciidoctor-mathematical gem install --pre asciidoctor-pdf
gem install --pre asciidoctor-pdf ----
[[history]] [[history]]
== Revision History == Revision History
* 2017-02-13 - Move some comments here from ../../../README.md. Tweak
asciidoctor markup to more clearly delineate shell command blocks.
* 2017-02-10 - Add more Ruby installation guidelines and reflow the * 2017-02-10 - Add more Ruby installation guidelines and reflow the
document in accordance with the style guide. document in accordance with the style guide.
* 2017-01-31 - Add rbenv instructions and update the README elsewhere. * 2017-01-31 - Add rbenv instructions and update the README elsewhere.
@ -644,7 +713,8 @@ command, once the platform is set up:
* 2017-01-06 - Replace MathJax with KaTeX. * 2017-01-06 - Replace MathJax with KaTeX.
* 2016-08-25 - Update for the single-branch model. * 2016-08-25 - Update for the single-branch model.
* 2016-07-10 - Update for current state of spec and ref page generation. * 2016-07-10 - Update for current state of spec and ref page generation.
* 2015-11-11 - Add new can: etc. macros and DBLATEXPREFIX variable. * 2015-11-11 - Add new can: etc.
macros and DBLATEXPREFIX variable.
* 2015-09-21 - Convert document to asciidoc and rename to README.md in the * 2015-09-21 - Convert document to asciidoc and rename to README.md in the
hope the gitlab browser will render it in some fashion. hope the gitlab browser will render it in some fashion.
* 2015-09-21 - Add descriptions of LaTeX and MathJax math support for all * 2015-09-21 - Add descriptions of LaTeX and MathJax math support for all

2
doc/specs/vulkan/appendices/VK_EXT_SMPTE2086_metadata.txt
View File

@ -59,7 +59,7 @@ It is up to the implementation to determine how to make use of the metadata.
1) Do we need a query function? 1) Do we need a query function?
PROPOSED: No, Vulkan does not provide queries for state that the PROPOSED: No, Vulkan does not provide queries for state that the
application can track on it's own. application can track on its own.
2) Should we specify default if not specified by the application? 2) Should we specify default if not specified by the application?

2
doc/specs/vulkan/appendices/VK_EXT_swapchain_colorspace.txt
View File

@ -155,7 +155,7 @@ what a particular implementation supports.
function for a colorspace? function for a colorspace?
*RESOLVED*: Extension indicates that implementation must: not do the OETF *RESOLVED*: Extension indicates that implementation must: not do the OETF
encoding if it's not sRGB. encoding if it is not sRGB.
That responsibility falls to the application shaders. That responsibility falls to the application shaders.
=== Version History === Version History

8
doc/specs/vulkan/appendices/extensions.txt
View File

@ -220,10 +220,6 @@ ifdef::VK_NV_dedicated_allocation[]
include::VK_NV_dedicated_allocation.txt[] include::VK_NV_dedicated_allocation.txt[]
endif::VK_NV_dedicated_allocation[] endif::VK_NV_dedicated_allocation[]
ifdef::VK_NV_glsl_shader[]
include::VK_NV_glsl_shader.txt[]
endif::VK_NV_glsl_shader[]
ifdef::VK_NV_external_memory_capabilities[] ifdef::VK_NV_external_memory_capabilities[]
include::VK_NV_external_memory_capabilities.txt[] include::VK_NV_external_memory_capabilities.txt[]
endif::VK_NV_external_memory_capabilities[] endif::VK_NV_external_memory_capabilities[]
@ -236,6 +232,10 @@ ifdef::VK_NV_external_memory_win32[]
include::VK_NV_external_memory_win32.txt[] include::VK_NV_external_memory_win32.txt[]
endif::VK_NV_external_memory_win32[] endif::VK_NV_external_memory_win32[]
ifdef::VK_NV_glsl_shader[]
include::VK_NV_glsl_shader.txt[]
endif::VK_NV_glsl_shader[]
ifdef::VK_NV_win32_keyed_mutex[] ifdef::VK_NV_win32_keyed_mutex[]
include::VK_NV_win32_keyed_mutex.txt[] include::VK_NV_win32_keyed_mutex.txt[]
endif::VK_NV_win32_keyed_mutex[] endif::VK_NV_win32_keyed_mutex[]

4
doc/specs/vulkan/chapters/VK_EXT_debug_report.txt
View File

@ -59,7 +59,7 @@ include::../api/enums/VkDebugReportFlagBitsEXT.txt[]
Such cases may not be immediately harmful, such as a fragment shader Such cases may not be immediately harmful, such as a fragment shader
outputting to a location with no attachment. outputting to a location with no attachment.
Other cases may point to behavior that is almost certainly bad when Other cases may point to behavior that is almost certainly bad when
unintended such as using an image whose memory hasn't been filled. unintended such as using an image whose memory has not been filled.
In general if you see a warning but you know that the behavior is In general if you see a warning but you know that the behavior is
intended/desired, then simply ignore the warning. intended/desired, then simply ignore the warning.
* ename:VK_DEBUG_REPORT_PERFORMANCE_WARNING_BIT_EXT indicates a * ename:VK_DEBUG_REPORT_PERFORMANCE_WARNING_BIT_EXT indicates a
@ -112,8 +112,10 @@ include::../api/funcpointers/PFN_vkDebugReportCallbackEXT.txt[]
triggered this callback. triggered this callback.
* pname:pLayerPrefix is the abbreviation of the component making the * pname:pLayerPrefix is the abbreviation of the component making the
callback. callback.
pname:pLayerPrefix is only valid for the duration of the callback.
* pname:pMessage is a null-terminated string detailing the trigger * pname:pMessage is a null-terminated string detailing the trigger
conditions. conditions.
pname:pMessage is only valid for the duration of the callback.
* pname:pUserData is the user data given when the DebugReportCallback was * pname:pUserData is the user data given when the DebugReportCallback was
created. created.

20
doc/specs/vulkan/chapters/VK_KHR_swapchain/wsi.txt
View File

@ -157,13 +157,13 @@ after reacquiring them and if their pixel shaders do not have any side
effects that require them to run for all pixels in the presentable image. effects that require them to run for all pixels in the presentable image.
==== ====
* pname:oldSwapchain, if not code:VK_NULL_HANDLE, specifies the swapchain * pname:oldSwapchain, if not dlink:VK_NULL_HANDLE, specifies the swapchain
that will be replaced by the new swapchain being created. that will be replaced by the new swapchain being created.
The new swapchain will be a descendant of pname:oldSwapchain. The new swapchain will be a descendant of pname:oldSwapchain.
Further, any descendants of the new swapchain will also be descendants Further, any descendants of the new swapchain will also be descendants
of pname:oldSwapchain. of pname:oldSwapchain.
Upon calling fname:vkCreateSwapchainKHR with a pname:oldSwapchain that Upon calling fname:vkCreateSwapchainKHR with a pname:oldSwapchain that
is not code:VK_NULL_HANDLE, any images not acquired by the application is not dlink:VK_NULL_HANDLE, any images not acquired by the application
may: be freed by the implementation, which may: occur even if creation may: be freed by the implementation, which may: occur even if creation
of the new swapchain fails. of the new swapchain fails.
The application must: destroy the old swapchain to free all memory The application must: destroy the old swapchain to free all memory
@ -395,8 +395,8 @@ include::../../api/protos/vkAcquireNextImageKHR.txt[]
* pname:swapchain is the swapchain from which an image is being acquired. * pname:swapchain is the swapchain from which an image is being acquired.
* pname:timeout indicates how long the function waits, in nanoseconds, if * pname:timeout indicates how long the function waits, in nanoseconds, if
no image is available. no image is available.
* pname:semaphore is code:VK_NULL_HANDLE or a semaphore to signal. * pname:semaphore is dlink:VK_NULL_HANDLE or a semaphore to signal.
* pname:fence is code:VK_NULL_HANDLE or a fence to signal. * pname:fence is dlink:VK_NULL_HANDLE or a fence to signal.
* pname:pImageIndex is a pointer to a code:uint32_t that is set to the * pname:pImageIndex is a pointer to a code:uint32_t that is set to the
index of the next image to use (i.e. an index into the array of images index of the next image to use (i.e. an index into the array of images
returned by fname:vkGetSwapchainImagesKHR). returned by fname:vkGetSwapchainImagesKHR).
@ -505,7 +505,7 @@ presentable images simultaneously, it must: request a minimum image count of
4 when creating the swapchain. 4 when creating the swapchain.
==== ====
If pname:semaphore is not code:VK_NULL_HANDLE, the semaphore must: be If pname:semaphore is not dlink:VK_NULL_HANDLE, the semaphore must: be
unsignaled and not have any uncompleted signal or wait operations pending. unsignaled and not have any uncompleted signal or wait operations pending.
It will become signaled when the application can: use the image. It will become signaled when the application can: use the image.
Queue operations that access the image contents must: wait until the Queue operations that access the image contents must: wait until the
@ -515,14 +515,14 @@ image away from the ename:VK_IMAGE_LAYOUT_PRESENT_SRC_KHR layout.
Use of the semaphore allows rendering operations to be recorded and Use of the semaphore allows rendering operations to be recorded and
submitted before the presentation engine has completed its use of the image. submitted before the presentation engine has completed its use of the image.
If pname:fence is not equal to code:VK_NULL_HANDLE, the fence must: be If pname:fence is not equal to dlink:VK_NULL_HANDLE, the fence must: be
unsignaled and not have any uncompleted signal operations pending. unsignaled and not have any uncompleted signal operations pending.
It will become signaled when the application can: use the image. It will become signaled when the application can: use the image.
Applications can: use this to meter their frame generation work to match the Applications can: use this to meter their frame generation work to match the
presentation rate. presentation rate.
pname:semaphore and pname:fence must: not both be equal to pname:semaphore and pname:fence must: not both be equal to
code:VK_NULL_HANDLE. dlink:VK_NULL_HANDLE.
An application must: wait until either the pname:semaphore or pname:fence is An application must: wait until either the pname:semaphore or pname:fence is
signaled before using the presentable image. signaled before using the presentable image.
@ -694,9 +694,9 @@ include::../../api/structs/VkPresentInfoKHR.txt[]
* pname:waitSemaphoreCount is the number of semaphores to wait for before * pname:waitSemaphoreCount is the number of semaphores to wait for before
issuing the present request. issuing the present request.
The number may: be zero. The number may: be zero.
* pname:pWaitSemaphores, if not code:VK_NULL_HANDLE, is an array of * pname:pWaitSemaphores, if not `NULL`, is an array of sname:VkSemaphore
sname:VkSemaphore objects with pname:waitSemaphoreCount entries, and objects with pname:waitSemaphoreCount entries, and specifies the
specifies the semaphores to wait for before issuing the present request. semaphores to wait for before issuing the present request.
* pname:swapchainCount is the number of swapchains being presented to by * pname:swapchainCount is the number of swapchains being presented to by
this command. this command.
* pname:pSwapchains is an array of sname:VkSwapchainKHR objects with * pname:pSwapchains is an array of sname:VkSwapchainKHR objects with

3
doc/specs/vulkan/chapters/VK_NN_vi_surface/platformCreateSurface_vi.txt
View File

@ -40,8 +40,7 @@ The sname:VkViSurfaceCreateInfoNN structure is defined as:
include::../../api/structs/VkViSurfaceCreateInfoNN.txt[] include::../../api/structs/VkViSurfaceCreateInfoNN.txt[]
* pname:sType is the type of this structure. * pname:sType is the type of this structure.
* pname:pNext is code:NULL or a pointer to an extension-specific * pname:pNext is `NULL` or a pointer to an extension-specific structure.
structure.
* pname:flags is reserved for future use. * pname:flags is reserved for future use.
* pname:window is the code:nn::code:vi::code:NativeWindowHandle for the * pname:window is the code:nn::code:vi::code:NativeWindowHandle for the
code:nn::code:vi::code:Layer with which to associate the surface. code:nn::code:vi::code:Layer with which to associate the surface.

10
doc/specs/vulkan/chapters/VK_NVX_device_generated_commands/generation.txt
View File

@ -84,12 +84,12 @@ include::../../api/structs/VkCmdProcessCommandsInfoNVX.txt[]
token command. token command.
* pname:maxSequencesCount is the maximum number of sequences for which * pname:maxSequencesCount is the maximum number of sequences for which
command buffer space will be reserved. command buffer space will be reserved.
If pname:sequencesCountBuffer is `NULL`, this is also the actual number If pname:sequencesCountBuffer is dlink:VK_NULL_HANDLE, this is also the
of sequences generated. actual number of sequences generated.
* pname:targetCommandBuffer can: be the secondary sname:VkCommandBuffer in * pname:targetCommandBuffer can: be the secondary sname:VkCommandBuffer in
which the commands should be recorded. which the commands should be recorded.
If `NULL` an implicit reservation as well as execution takes place on If pname:targetCommandBuffer is `NULL` an implicit reservation as well
the processing sname:VkCommandBuffer. as execution takes place on the processing sname:VkCommandBuffer.
* pname:sequencesCountBuffer can: be sname:VkBuffer from which the actual * pname:sequencesCountBuffer can: be sname:VkBuffer from which the actual
amount of sequences is sourced from as ftext:uint32_t value. amount of sequences is sourced from as ftext:uint32_t value.
* pname:sequencesCountOffset is the byte offset into * pname:sequencesCountOffset is the byte offset into
@ -98,7 +98,7 @@ include::../../api/structs/VkCmdProcessCommandsInfoNVX.txt[]
pname:indirectCommandsLayout's pname:indirectCommandsLayout's
ename:VK_INDIRECT_COMMANDS_LAYOUT_USAGE_INDEXED_SEQUENCES_BIT is set and ename:VK_INDIRECT_COMMANDS_LAYOUT_USAGE_INDEXED_SEQUENCES_BIT is set and
provides the used sequence indices as ftext:uint32_t array. provides the used sequence indices as ftext:uint32_t array.
Otherwise it must: be `NULL`. Otherwise it must: be dlink:VK_NULL_HANDLE.
* pname:sequencesIndexOffset is the byte offset into * pname:sequencesIndexOffset is the byte offset into
pname:sequencesIndexBuffer where the index values start. pname:sequencesIndexBuffer where the index values start.

2
doc/specs/vulkan/chapters/clears.txt
View File

@ -67,7 +67,7 @@ endif::VK_KHR_maintenance1[]
include::../validity/protos/vkCmdClearColorImage.txt[] include::../validity/protos/vkCmdClearColorImage.txt[]
// refBegin vkCmdClearDepthStencilImage Fill regions of a combined depth-stencil image // refBegin vkCmdClearDepthStencilImage Fill regions of a combined depth/stencil image
To clear one or more subranges of a depth/stencil image, call: To clear one or more subranges of a depth/stencil image, call:

6
doc/specs/vulkan/chapters/cmdbuffers.txt
View File

@ -299,8 +299,8 @@ fname:vkAllocateCommandBuffers can: be used to create multiple command
buffers. buffers.
If the creation of any of those command buffers fails, the implementation If the creation of any of those command buffers fails, the implementation
must: destroy all successfully created command buffer objects from this must: destroy all successfully created command buffer objects from this
command, set all entries of the pname:pCommandBuffers array to command, set all entries of the pname:pCommandBuffers array to `NULL` and
dlink:VK_NULL_HANDLE and return the error. return the error.
endif::VK_KHR_maintenance1[] endif::VK_KHR_maintenance1[]
include::../validity/protos/vkAllocateCommandBuffers.txt[] include::../validity/protos/vkAllocateCommandBuffers.txt[]
@ -384,7 +384,7 @@ include::../api/protos/vkFreeCommandBuffers.txt[]
* All elements of pname:pCommandBuffers must: not be pending execution * All elements of pname:pCommandBuffers must: not be pending execution
* pname:pCommandBuffers must: be a pointer to an array of * pname:pCommandBuffers must: be a pointer to an array of
pname:commandBufferCount sname:VkCommandBuffer handles, each element of pname:commandBufferCount sname:VkCommandBuffer handles, each element of
which must: either be a valid handle or code:NULL which must: either be a valid handle or `NULL`
**** ****
include::../validity/protos/vkFreeCommandBuffers.txt[] include::../validity/protos/vkFreeCommandBuffers.txt[]

2
doc/specs/vulkan/chapters/features.txt
View File

@ -3973,7 +3973,7 @@ flink:vkGetPhysicalDeviceImageFormatProperties, with the ability to return
extended information via chained output structures. extended information via chained output structures.
If the loader implementation emulates If the loader implementation emulates
fname:vkGetPhysicalDeviceImageFormatProperties2KHR on a device that doesn't fname:vkGetPhysicalDeviceImageFormatProperties2KHR on a device that does not
support the extension, and the query involves a structure the loader does support the extension, and the query involves a structure the loader does
not support, fname:vkGetPhysicalDeviceImageFormatProperties2KHR returns not support, fname:vkGetPhysicalDeviceImageFormatProperties2KHR returns
ename:VK_ERROR_FORMAT_NOT_SUPPORTED. ename:VK_ERROR_FORMAT_NOT_SUPPORTED.

15
doc/specs/vulkan/chapters/fundamentals.txt
View File

@ -660,12 +660,13 @@ An object handle is valid if:
* Any objects used by that object, either as part of creation or * Any objects used by that object, either as part of creation or
execution, must: also be valid. execution, must: also be valid.
The reserved handle dlink:VK_NULL_HANDLE can: be passed in place of valid The reserved values dlink:VK_NULL_HANDLE and `NULL` can: be used in place of
object handles when _explicitly called out in the specification_. valid non-dispatchable handles and dispatchable handles, respectively, when
Any command that creates an object successfully must: not return _explicitly called out in the specification_.
dlink:VK_NULL_HANDLE. Any command that creates an object successfully must: not return these
It is valid to pass dlink:VK_NULL_HANDLE to any ftext:vkDestroy* or values.
ftext:vkFree* command, which will silently ignore these values. It is valid to pass these values to ftext:vkDestroy* or ftext:vkFree*
commands, which will silently ignore these values.
[[fundamentals-validusage-pointers]] [[fundamentals-validusage-pointers]]
@ -752,7 +753,7 @@ appendix.
==== Valid Usage for Structure Pointer Chains ==== Valid Usage for Structure Pointer Chains
Any parameter that is a structure containing a `void*` ptext:pNext member Any parameter that is a structure containing a `void*` ptext:pNext member
must: have a value of ptext:pNext that is either `NULL`, or points to a must: have a value of pname:pNext that is either `NULL`, or points to a
valid structure defined by an extension, containing ptext:sType and valid structure defined by an extension, containing ptext:sType and
ptext:pNext members as described in the <<vulkan-styleguide,Vulkan ptext:pNext members as described in the <<vulkan-styleguide,Vulkan
Documentation and Extensions>> document in the section "`Extension Documentation and Extensions>> document in the section "`Extension

4
doc/specs/vulkan/chapters/initialization.txt
View File

@ -133,12 +133,12 @@ extension, an application can: use fname:vkGetInstanceProcAddr.
This function pointer may: point to dispatch code, which calls a different This function pointer may: point to dispatch code, which calls a different
real implementation for different sname:VkPhysicalDevice objects. real implementation for different sname:VkPhysicalDevice objects.
Behavior is undefined if an extension physical-device command is called on a Behavior is undefined if an extension physical-device command is called on a
physical device that doesn't support the extension. physical device that does not support the extension.
Device extensions may: define structures that can: be added to the Device extensions may: define structures that can: be added to the
pNext-chain of physical-device commands. pNext-chain of physical-device commands.
Behavior is undefined if such an extension structure is passed to a physical Behavior is undefined if such an extension structure is passed to a physical
device command for a physical device that doesn't support the extension. device command for a physical device that does not support the extension.
endif::VK_KHR_get_physical_device_properties2[] endif::VK_KHR_get_physical_device_properties2[]

14
doc/specs/vulkan/chapters/renderpass.txt
View File

@ -781,7 +781,7 @@ The subpass dependency operates as if defined with the following parameters:
VkPipelineStageFlags inputAttachmentStages = VK_PIPELINE_STAGE_FRAGMENT_SHADER_BIT; VkPipelineStageFlags inputAttachmentStages = VK_PIPELINE_STAGE_FRAGMENT_SHADER_BIT;
VkAccessFlags inputAttachmentAccess = VK_ACCESS_INPUT_ATTACHMENT_READ_BIT; VkAccessFlags inputAttachmentAccess = VK_ACCESS_INPUT_ATTACHMENT_READ_BIT;
// Used for depth stencil attachments // Used for depth/stencil attachments
VkPipelineStageFlags depthStencilAttachmentStages = VK_PIPELINE_STAGE_EARLY_FRAGMENT_TESTS_BIT | VK_PIPELINE_STAGE_LATE_FRAGMENT_TESTS_BIT; VkPipelineStageFlags depthStencilAttachmentStages = VK_PIPELINE_STAGE_EARLY_FRAGMENT_TESTS_BIT | VK_PIPELINE_STAGE_LATE_FRAGMENT_TESTS_BIT;
VkAccessFlags depthStencilAttachmentAccess = VK_ACCESS_DEPTH_STENCIL_ATTACHMENT_READ_BIT; VkAccessFlags depthStencilAttachmentAccess = VK_ACCESS_DEPTH_STENCIL_ATTACHMENT_READ_BIT;
@ -873,12 +873,9 @@ pairs of attachments are compatible.
If the arrays are of different lengths, attachment references not present in If the arrays are of different lengths, attachment references not present in
the smaller array are treated as ename:VK_ATTACHMENT_UNUSED. the smaller array are treated as ename:VK_ATTACHMENT_UNUSED.
Two render passes that contain only a single subpass are compatible if their Two render passes are compatible if their corresponding color, input,
corresponding color, input, resolve, and depth/stencil attachment references resolve, and depth/stencil attachment references are compatible and if they
are compatible. are otherwise identical except for:
If two render passes contain more than one subpass, they are compatible if
they are identical except for:
* Initial and final image layout in attachment descriptions * Initial and final image layout in attachment descriptions
* Load and store operations in attachment descriptions * Load and store operations in attachment descriptions
@ -990,10 +987,13 @@ slink:VkPipelineMultisampleStateCreateInfo::pname:rasterizationSamples.
level level
* Any given element of pname:pAttachments must: have been created with the * Any given element of pname:pAttachments must: have been created with the
identity swizzle identity swizzle
* pname:width must: be greater than `0`.
* pname:width must: be less than or equal to * pname:width must: be less than or equal to
sname:VkPhysicalDeviceLimits::pname:maxFramebufferWidth sname:VkPhysicalDeviceLimits::pname:maxFramebufferWidth
* pname:height must: be greater than `0`.
* pname:height must: be less than or equal to * pname:height must: be less than or equal to
sname:VkPhysicalDeviceLimits::pname:maxFramebufferHeight sname:VkPhysicalDeviceLimits::pname:maxFramebufferHeight
* pname:layers must: be greater than `0`.
* pname:layers must: be less than or equal to * pname:layers must: be less than or equal to
sname:VkPhysicalDeviceLimits::pname:maxFramebufferLayers sname:VkPhysicalDeviceLimits::pname:maxFramebufferLayers
ifdef::VK_KHR_maintenance1[] ifdef::VK_KHR_maintenance1[]

5
doc/specs/vulkan/chapters/resources.txt
View File

@ -562,6 +562,11 @@ endif::VK_KHR_maintenance1[]
ename:VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT, pname:extent.height must: be ename:VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT, pname:extent.height must: be
less than or equal to less than or equal to
sname:VkPhysicalDeviceLimits::pname:maxFramebufferHeight sname:VkPhysicalDeviceLimits::pname:maxFramebufferHeight
* If pname:usage includes ename:VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT,
pname:usage must: also contain at least one of
ename:VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT,
ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT, or
ename:VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT.
* pname:samples must: be a bit value that is set in * pname:samples must: be a bit value that is set in
sname:VkImageFormatProperties::pname:sampleCounts returned by sname:VkImageFormatProperties::pname:sampleCounts returned by
fname:vkGetPhysicalDeviceImageFormatProperties with pname:format, fname:vkGetPhysicalDeviceImageFormatProperties with pname:format,

6
doc/specs/vulkan/chapters/synchronization.txt
View File

@ -107,7 +107,7 @@ For example, a synchronization command with multiple
effectively generates one dependency between each source stage and each effectively generates one dependency between each source stage and each
destination stage. destination stage.
This can be useful to think about when considering how execution chains are This can be useful to think about when considering how execution chains are
formed if they don't involve all parts of a synchronization command's formed if they do not involve all parts of a synchronization command's
dependency. dependency.
Similarly, any set of adjacent dependencies in an execution dependency chain Similarly, any set of adjacent dependencies in an execution dependency chain
can: be considered an execution dependency chain in its own right. can: be considered an execution dependency chain in its own right.
@ -344,8 +344,8 @@ endif::VK_NVX_device_generated_commands[]
An execution dependency with only ename:VK_PIPELINE_STAGE_BOTTOM_OF_PIPE_BIT An execution dependency with only ename:VK_PIPELINE_STAGE_BOTTOM_OF_PIPE_BIT
in the destination stage mask will only prevent that stage from executing in in the destination stage mask will only prevent that stage from executing in
subsequently submitted commands. subsequently submitted commands.
As this stage doesn't perform any actual execution, this is not observable - As this stage does not perform any actual execution, this is not observable
in effect, it does not delay processing of subsequent commands. - in effect, it does not delay processing of subsequent commands.
Similarly an execution dependency with only Similarly an execution dependency with only
ename:VK_PIPELINE_STAGE_TOP_OF_PIPE_BIT in the source stage mask will ename:VK_PIPELINE_STAGE_TOP_OF_PIPE_BIT in the source stage mask will
effectively not wait for any prior commands to complete. effectively not wait for any prior commands to complete.

6
doc/specs/vulkan/chapters/textures.txt
View File

@ -1295,11 +1295,11 @@ then level d is used:
\begin{aligned} \begin{aligned}
d = d =
\begin{cases} \begin{cases}
level_{base}, & \lambda \leq \frac{1}{2} \\[.5em] level_{base}, & \lambda \leq 0 \\[.5em]
nearest(\lambda), & \lambda > \frac{1}{2}, nearest(\lambda), & \lambda > 0,
level_{base} + \lambda \leq level_{base} + \lambda \leq
q + \frac{1}{2} \\[.5em] q + \frac{1}{2} \\[.5em]
q, & \lambda > \frac{1}{2}, q, & \lambda > 0,
level_{base} + \lambda > q + \frac{1}{2} level_{base} + \lambda > q + \frac{1}{2}
\end{cases} \end{cases}
\end{aligned} \end{aligned}

3
doc/specs/vulkan/config/extDependency.sh
View File

@ -8,7 +8,6 @@ extensions[VK_EXT_debug_marker]="VK_EXT_debug_report"
extensions[VK_EXT_direct_mode_display]="VK_KHR_display VK_KHR_surface" extensions[VK_EXT_direct_mode_display]="VK_KHR_display VK_KHR_surface"
extensions[VK_EXT_display_control]="VK_EXT_display_surface_counter VK_KHR_display VK_KHR_surface VK_KHR_swapchain" extensions[VK_EXT_display_control]="VK_EXT_display_surface_counter VK_KHR_display VK_KHR_surface VK_KHR_swapchain"
extensions[VK_EXT_display_surface_counter]="VK_KHR_display VK_KHR_surface" extensions[VK_EXT_display_surface_counter]="VK_KHR_display VK_KHR_surface"
extensions[VK_EXT_swapchain_colorspace]="VK_KHR_surface"
extensions[VK_KHR_android_surface]="VK_KHR_surface" extensions[VK_KHR_android_surface]="VK_KHR_surface"
extensions[VK_KHR_display]="VK_KHR_surface" extensions[VK_KHR_display]="VK_KHR_surface"
extensions[VK_KHR_display_swapchain]="VK_KHR_display VK_KHR_surface VK_KHR_swapchain" extensions[VK_KHR_display_swapchain]="VK_KHR_display VK_KHR_surface VK_KHR_swapchain"
@ -24,5 +23,5 @@ extensions[VK_NV_external_memory_win32]="VK_NV_external_memory VK_NV_external_me
extensions[VK_NV_win32_keyed_mutex]="VK_NV_external_memory VK_NV_external_memory_capabilities VK_NV_external_memory_win32" extensions[VK_NV_win32_keyed_mutex]="VK_NV_external_memory VK_NV_external_memory_capabilities VK_NV_external_memory_win32"
# Define lists of all extensions and all KHR extensions # Define lists of all extensions and all KHR extensions
allExts="VK_AMD_draw_indirect_count VK_AMD_gcn_shader VK_AMD_gpu_shader_half_float VK_AMD_negative_viewport_height VK_AMD_rasterization_order VK_AMD_shader_ballot VK_AMD_shader_explicit_vertex_parameter VK_AMD_shader_trinary_minmax VK_EXT_acquire_xlib_display VK_EXT_debug_marker VK_EXT_debug_report VK_EXT_direct_mode_display VK_EXT_display_control VK_EXT_display_surface_counter VK_EXT_shader_subgroup_ballot VK_EXT_shader_subgroup_vote VK_EXT_swapchain_colorspace VK_EXT_validation_flags VK_IMG_filter_cubic VK_IMG_format_pvrtc VK_KHR_android_surface VK_KHR_display VK_KHR_display_swapchain VK_KHR_get_physical_device_properties2 VK_KHR_maintenance1 VK_KHR_mir_surface VK_KHR_sampler_mirror_clamp_to_edge VK_KHR_shader_draw_parameters VK_KHR_surface VK_KHR_swapchain VK_KHR_wayland_surface VK_KHR_win32_surface VK_KHR_xcb_surface VK_KHR_xlib_surface VK_NN_vi_surface VK_NVX_device_generated_commands VK_NV_dedicated_allocation VK_NV_external_memory VK_NV_external_memory_capabilities VK_NV_external_memory_win32 VK_NV_glsl_shader VK_NV_win32_keyed_mutex" allExts="VK_AMD_draw_indirect_count VK_AMD_gcn_shader VK_AMD_gpu_shader_half_float VK_AMD_negative_viewport_height VK_AMD_rasterization_order VK_AMD_shader_ballot VK_AMD_shader_explicit_vertex_parameter VK_AMD_shader_trinary_minmax VK_EXT_acquire_xlib_display VK_EXT_debug_marker VK_EXT_debug_report VK_EXT_direct_mode_display VK_EXT_display_control VK_EXT_display_surface_counter VK_EXT_shader_subgroup_ballot VK_EXT_shader_subgroup_vote VK_EXT_validation_flags VK_IMG_filter_cubic VK_IMG_format_pvrtc VK_KHR_android_surface VK_KHR_display VK_KHR_display_swapchain VK_KHR_get_physical_device_properties2 VK_KHR_maintenance1 VK_KHR_mir_surface VK_KHR_sampler_mirror_clamp_to_edge VK_KHR_shader_draw_parameters VK_KHR_surface VK_KHR_swapchain VK_KHR_wayland_surface VK_KHR_win32_surface VK_KHR_xcb_surface VK_KHR_xlib_surface VK_NN_vi_surface VK_NVX_device_generated_commands VK_NV_dedicated_allocation VK_NV_external_memory VK_NV_external_memory_capabilities VK_NV_external_memory_win32 VK_NV_glsl_shader VK_NV_win32_keyed_mutex"
khrExts="VK_KHR_android_surface VK_KHR_display VK_KHR_display_swapchain VK_KHR_get_physical_device_properties2 VK_KHR_maintenance1 VK_KHR_mir_surface VK_KHR_sampler_mirror_clamp_to_edge VK_KHR_shader_draw_parameters VK_KHR_surface VK_KHR_swapchain VK_KHR_wayland_surface VK_KHR_win32_surface VK_KHR_xcb_surface VK_KHR_xlib_surface" khrExts="VK_KHR_android_surface VK_KHR_display VK_KHR_display_swapchain VK_KHR_get_physical_device_properties2 VK_KHR_maintenance1 VK_KHR_mir_surface VK_KHR_sampler_mirror_clamp_to_edge VK_KHR_shader_draw_parameters VK_KHR_surface VK_KHR_swapchain VK_KHR_wayland_surface VK_KHR_win32_surface VK_KHR_xcb_surface VK_KHR_xlib_surface"

8
doc/specs/vulkan/config/vulkan-macros/extension.rb
View File

@ -33,7 +33,13 @@ end
class LinkInlineMacroBase < VulkanInlineMacroBase class LinkInlineMacroBase < VulkanInlineMacroBase
def process parent, target, attributes def process parent, target, attributes
'<code><a href="#' + target + '">' + target + '</a></code>' link = ''
if parent.document.attributes['cross-file-links']
link = '<code><a href="' + target + '.html">' + target + '</a></code>'
else
link = '<code><a href="#' + target + '">' + target + '</a></code>'
end
link
end end
end end

3
doc/specs/vulkan/genspec.py
View File

@ -63,7 +63,6 @@ allExtensions = KHRextensions + [
'VK_EXT_shader_subgroup_ballot', 'VK_EXT_shader_subgroup_ballot',
'VK_EXT_shader_subgroup_vote', 'VK_EXT_shader_subgroup_vote',
'VK_EXT_SMPTE2086_metadata', 'VK_EXT_SMPTE2086_metadata',
'VK_EXT_swapchain_colorspace',
'VK_EXT_validation_flags', 'VK_EXT_validation_flags',
'VK_IMG_filter_cubic', 'VK_IMG_filter_cubic',
'VK_NN_vi_surface', 'VK_NN_vi_surface',
@ -71,8 +70,8 @@ allExtensions = KHRextensions + [
'VK_NV_external_memory', 'VK_NV_external_memory',
'VK_NV_external_memory_capabilities', 'VK_NV_external_memory_capabilities',
'VK_NV_external_memory_win32', 'VK_NV_external_memory_win32',
'VK_NV_win32_keyed_mutex',
'VK_NV_glsl_shader', 'VK_NV_glsl_shader',
'VK_NV_win32_keyed_mutex',
'VK_NVX_device_generated_commands' 'VK_NVX_device_generated_commands'
] ]

250
doc/specs/vulkan/style/extensions.txt
View File

@ -74,7 +74,7 @@ Extensions and layers have formal _names_.
These names are used in a variety of places: These names are used in a variety of places:
* When specifying extensions and layers to enable in the API. * When specifying extensions and layers to enable in the API.
* As a preprocessor symbol in the +vulkan.h+ header file indicating that * As a preprocessor symbol in the `vulkan.h` header file indicating that
an extension interface is defined at compile time. an extension interface is defined at compile time.
* To control building the Vulkan Specification from asciidoc source * To control building the Vulkan Specification from asciidoc source
containing many extension, by explicitly enabling inclusion of one or containing many extension, by explicitly enabling inclusion of one or
@ -98,12 +98,12 @@ from GitHub.
There is a rigid syntax for these names: There is a rigid syntax for these names:
* Extensions are named with the syntax: +VK_AUTHOR_<name>+. * Extensions are named with the syntax: `VK_AUTHOR_<name>`.
* Layers are named with the syntax: +VK_LAYER_{AUTHOR|FQDN}_<name>+. * Layers are named with the syntax: `VK_LAYER_{AUTHOR|FQDN}_<name>`.
Both extensions and layer names include a +VK_+ prefix, as described in the Both extensions and layer names include a `VK_` prefix, as described in the
<<naming-preprocessor,Preprocessor Defines>> section above. <<naming-preprocessor,Preprocessor Defines>> section above.
In addition, layers add a +LAYER_+ prefix. In addition, layers add a `LAYER_` prefix.
Extension and layer names must both be valid C language identifiers. Extension and layer names must both be valid C language identifiers.
@ -111,7 +111,7 @@ Extension and layer names must both be valid C language identifiers.
[[extensions-naming-conventions-name-strings]] [[extensions-naming-conventions-name-strings]]
=== Extension and Layer Name Strings === Extension and Layer Name Strings
The +<name>+ portion of extension and layer names is a concise name The `<name>` portion of extension and layer names is a concise name
describing the purpose or functionality of the extension or layer. describing the purpose or functionality of the extension or layer.
The underscore (`_`) character is used as a delimiter between words. The underscore (`_`) character is used as a delimiter between words.
Every character of the name must be in lower case. Every character of the name must be in lower case.
@ -119,7 +119,7 @@ Every character of the name must be in lower case.
=== Author IDs === Author IDs
Extension and layer names also contain an _author ID_, indicated by +AUTHOR+ Extension and layer names also contain an _author ID_, indicated by `AUTHOR`
above, identifying the author of the extension/layer. above, identifying the author of the extension/layer.
This ID is a short, capitalized string identifying an author, such as a This ID is a short, capitalized string identifying an author, such as a
Khronos member developing Vulkan implementations for their devices, or a Khronos member developing Vulkan implementations for their devices, or a
@ -138,36 +138,36 @@ FQDNs cannot be used for extensions, only for layers.
* The following are examples of extension and layer names, demonstrating * The following are examples of extension and layer names, demonstrating
the above syntax: the above syntax:
** Extension names all use the base prefix +VK_+. ** Extension names all use the base prefix `VK_`.
** Khronos-ratified extensions add the reserved author ID +KHR+, and will ** Khronos-ratified extensions add the reserved author ID `KHR`, and will
use the prefix +VK_KHR_+. use the prefix `VK_KHR_`.
** The following author IDs are reserved and must not be used: ** The following author IDs are reserved and must not be used:
*** +VK+ - To avoid confusion with the top-level +VK_+ prefix. *** `VK` - To avoid confusion with the top-level `VK_` prefix.
*** +VULKAN+ - To avoid confusion with the name of the Vulkan API. *** `VULKAN` - To avoid confusion with the name of the Vulkan API.
*** +LAYER+ - To avoid confusion with the higher-level "`LAYER`" prefix. *** `LAYER` - To avoid confusion with the higher-level "`LAYER`" prefix.
*** +KHRONOS+ - To avoid confusion with the Khronos organization. *** `KHRONOS` - To avoid confusion with the Khronos organization.
** Multi-author extensions that have not been ratified by Khronos (those ** Multi-author extensions that have not been ratified by Khronos (those
developed via cooperation between, and intended to be supported by two developed via cooperation between, and intended to be supported by two
or more registered authors) add the special author ID +EXT+ to the base or more registered authors) add the special author ID `EXT` to the base
prefix, and will use the prefix +VK_EXT_+. prefix, and will use the prefix `VK_EXT_`.
** Traditional author-specific extensions developed by one author (or one ** Traditional author-specific extensions developed by one author (or one
author in cooperation with non-authors) add the author ID to the base author in cooperation with non-authors) add the author ID to the base
prefix. prefix.
For example, NVIDIA will use the prefix +VK_NV_+, and Valve will use For example, NVIDIA will use the prefix `VK_NV_`, and Valve will use
the prefix +VK_VALVE_+. the prefix `VK_VALVE_`.
Some authors can have additional registered author IDs for special Some authors can have additional registered author IDs for special
purposes. purposes.
For example, an Android extension developed by Google - but part of an For example, an Android extension developed by Google - but part of an
Android open-source community project, and so not a proprietary Google Android open-source community project, and so not a proprietary Google
extension - will use the author ID +ANDROID+. extension - will use the author ID `ANDROID`.
** Layer names follow the same conventions as extensions, but use the base ** Layer names follow the same conventions as extensions, but use the base
prefix +VK_LAYER_+. prefix `VK_LAYER_`.
** Because layers need not be registered with Khronos, an alternative ** Because layers need not be registered with Khronos, an alternative
mechanism is needed to allow creating unique layer names without mechanism is needed to allow creating unique layer names without
registering an author ID. registering an author ID.
Layer authors that prefer not to register an author ID can instead use Layer authors that prefer not to register an author ID can instead use
a fully-qualified domain name (FQDN) in reverse-order as an author ID, a fully-qualified domain name (FQDN) in reverse-order as an author ID,
replacing +.+ (period) with `_` (underscore) characters. replacing `.` (period) with `_` (underscore) characters.
The restriction that layer names must be valid C identifiers means that The restriction that layer names must be valid C identifiers means that
some FQDNs cannot be used as part of layer names. some FQDNs cannot be used as part of layer names.
@ -193,7 +193,7 @@ VK_LAYER_invalid_3dxcl_www
[NOTE] [NOTE]
.Note .Note
==== ====
To avoid linking to a nonexistent domain, the reserved TLD +.invalid+ is To avoid linking to a nonexistent domain, the reserved TLD `.invalid` is
used in the example above. used in the example above.
==== ====
@ -214,13 +214,14 @@ section above.
The canonical definition of the Vulkan APIs is kept in an XML file known as The canonical definition of the Vulkan APIs is kept in an XML file known as
the *Vulkan registry*. the *Vulkan registry*.
The registry is kept in +src/spec/vk.xml+ in the branch of the vulkan The registry is kept in `src/spec/vk.xml` in the `1.0` branch of the
project containing the most recently released core API specification. <<vulkan-docs,KhronosGroup/Vulkan-Docs>> project, containing the most
recently released Vulkan API specification.
The registry contains reserved author IDs, core and extension interface The registry contains reserved author IDs, core and extension interface
definitions, definitions of individual commands and structures, and other definitions, definitions of individual commands and structures, and other
information which must be agreed on by all implementations. information which must be agreed on by all implementations.
The registry is used to maintain a single, consistent global namespace for The registry is used to maintain a single, consistent global namespace for
the registered entities, to generate the Khronos-supplied +vulkan.h+, and to the registered entities, to generate the Khronos-supplied `vulkan.h`, and to
create a variety of related documentation used in generating the API create a variety of related documentation used in generating the API
specification and reference pages. specification and reference pages.
@ -237,14 +238,14 @@ A mechanism for non-members to register layers and extensions is provided.
Extension authors will be able to create an account on GitHub and register Extension authors will be able to create an account on GitHub and register
an author ID with Khronos through the an author ID with Khronos through the
+<<vulkan-docs,KhronosGroup/Vulkan-Docs>>+ project. <<vulkan-docs,KhronosGroup/Vulkan-Docs>> project.
The author ID must be used for any extensions that author registers. The author ID must be used for any extensions that author registers.
The same mechanism will be used to request registration of extensions or The same mechanism will be used to request registration of extensions or
layers with Khronos, as described below. layers with Khronos, as described below.
To reserve an author ID, propose a merge request against To reserve an author ID, propose a merge request against
<<extensions-api-registry,+vk.xml+>> in the +1.0+ branch. <<extensions-api-registry,`vk.xml`>> in the `1.0` branch.
The merge must add a +<tag>+ XML tag and fill in the +name+, +author+ and The merge must add a `<tag>` XML tag and fill in the `name`, `author` and
+contact+ attributes with the requested author ID, the author's formal name +contact+ attributes with the requested author ID, the author's formal name
(e.g. company or project name), and contact email address, respectively. (e.g. company or project name), and contact email address, respectively.
The author ID will only be reserved once this merge request is accepted. The author ID will only be reserved once this merge request is accepted.
@ -272,13 +273,13 @@ While vendor IDs are not directly related to API extensions, the reservation
process is very similar and so is described in this section. process is very similar and so is described in this section.
To reserve an Khronos vendor ID, you must first have a Khronos author ID. To reserve an Khronos vendor ID, you must first have a Khronos author ID.
Propose a merge request against <<extensions-api-registry,+vk.xml+>> in the Propose a merge request against <<extensions-api-registry,`vk.xml`>> in the
+1.0+ branch. +1.0+ branch.
The merge must add a +<vendorid>+ tag and fill in the +name+ and +id+ The merge must add a `<vendorid>` tag and fill in the `name` and `id`
attributes. attributes.
The +name+ attribute must be set to the author ID. The `name` attribute must be set to the author ID.
The +id+ attribute must be the first sequentially available ID in the list The `id` attribute must be the first sequentially available ID in the list
of +<vendorid>+ tags. of `<vendorid>` tags.
The vendor ID will be reserved only once this merge request has been The vendor ID will be reserved only once this merge request has been
accepted. accepted.
@ -293,16 +294,16 @@ Layers may be registered, and registration is strongly recommended.
Registration means: Registration means:
* Receiving an extension number. * Receiving an extension number.
* Adding the extension or layer name to the list in +vk.xml+ and appearing * Adding the extension or layer name to the list in `vk.xml` and appearing
on the Khronos registry website, which will link to associated on the Khronos registry website, which will link to associated
documentation hosted on Khronos. documentation hosted on Khronos.
* For extensions which add to the Vulkan API, including definitions of * For extensions which add to the Vulkan API, including definitions of
those additions to +vk.xml+. those additions to `vk.xml`.
Registration for Khronos members is handled by filing a merge request in the Registration for Khronos members is handled by filing a merge request in the
internal gitlab repository against the branch containing the core internal gitlab repository against the branch containing the core
specification against which the extension or layer will be written. specification against which the extension or layer will be written.
The merge must modify +vk.xml+ to define extension names, API interfaces, The merge must modify `vk.xml` to define extension names, API interfaces,
and related information. and related information.
Registration is not complete until the registry maintainer has validated and Registration is not complete until the registry maintainer has validated and
accepted the merge. accepted the merge.
@ -313,7 +314,7 @@ Non-Khronos members who want to create extensions must register with Khronos
by creating a GitHub account, and registering their author ID and/or FQDNs by creating a GitHub account, and registering their author ID and/or FQDNs
to that account. to that account.
They can then submit new extension registration requests by proposing merges They can then submit new extension registration requests by proposing merges
to +vk.xml+. to `vk.xml`.
On acceptance of the merge, the extension will be registered, though its On acceptance of the merge, the extension will be registered, though its
specification need not be checked into the Khronos GitHub repository at that specification need not be checked into the Khronos GitHub repository at that
point. point.
@ -322,50 +323,50 @@ The registration process can be split into several steps to accommodate
extension number assignment prior to extension publication: extension number assignment prior to extension publication:
* Acquire an extension number. * Acquire an extension number.
This is done by proposing a merge request against +vk.xml+ similarly to This is done by proposing a merge request against `vk.xml` similarly to
how <<extensions-author-ID,author IDs are reserved>>. how <<extensions-author-ID,author IDs are reserved>>.
The merge should add a new +<extension>+ tag at the end of the file with The merge should add a new `<extension>` tag at the end of the file with
attributes specifying the proposed extension +name+, the next unused attributes specifying the proposed extension `name`, the next unused
sequential extension +number+, the +author+ and +contact+ information sequential extension `number`, the `author` and `contact` information
(if different than that already specified for the author ID used in the (if different than that already specified for the author ID used in the
extension name), and finally, specifying +supported="disabled"+. extension name), and finally, specifying `supported="disabled"`.
The extension number will be reserved only once this merge request is The extension number will be reserved only once this merge request is
accepted into the +1.0+ branch. accepted into the `1.0` branch.
* Develop and test the extension using the registered extension number. * Develop and test the extension using the registered extension number.
* Publish the extension to Khronos using the previously registered * Publish the extension to Khronos using the previously registered
extension number, by submitting merge requests to the +1.0+ branch extension number, by submitting merge requests to the `1.0` branch
defining the changes specific to the extension. defining the changes specific to the extension.
Changes to both the specification source, and to +vk.xml+ will be Changes to both the specification source, and to `vk.xml` will be
needed. needed.
** Extension changes to the specification source must be protected by ** Extension changes to the specification source must be protected by
asciidoc conditionals as described in the asciidoc conditionals as described in the
<<extensions-documenting,Documenting Extensions>> section. <<extensions-documenting,Documenting Extensions>> section.
** Changes to +vk.xml+ must define the extension interfaces in the ** Changes to `vk.xml` must define the extension interfaces in the
+<extension>+ block, and must also change the +supported+ attribute `<extension>` block, and must also change the `supported` attribute
value of the +<extension>+ to +supported="vulkan"+. value of the `<extension>` to `supported="vulkan"`.
** When publishing an extension, mark it as enabled by proposing a merge ** When publishing an extension, mark it as enabled by proposing a merge
to the +1.0+ branch changing the +supported+ attribute value of the to the `1.0` branch changing the `supported` attribute value of the
+<extension>+ to +supported="vulkan"+. `<extension>` to `supported="vulkan"`.
This should be completely automated and under the control of the This should be completely automated and under the control of the
publishers, to allow them to align publication on Khronos with product publishers, to allow them to align publication on Khronos with product
releases. releases.
However, complete automation might be difficult, since steps such as However, complete automation might be difficult, since steps such as
regenerating and validating +vulkan.h+ are involved. regenerating and validating `vulkan.h` are involved.
Once the merge is accepted and the corresponding updated header with Once the merge is accepted and the corresponding updated header with
the new extension interface is committed to the +1.0+ branch, the new extension interface is committed to the `1.0` branch,
publication is complete. publication is complete.
** Publishing on the <<vulkan-docs,Khronos public GitHub repository>> is ** Publishing on the <<vulkan-docs,Khronos public GitHub repository>> is
preferred whenever possible. preferred whenever possible.
Khronos members may instead create branches on Khronos' internal gitlab Khronos members may instead create branches on Khronos' internal gitlab
server, but those branches will eventually be mirrored to GitHub. server, but those branches will eventually be mirrored to GitHub.
** Once the merge request defining an extension has been accepted into the ** Once the merge request defining an extension has been accepted into the
+1.0+ branch, publication is complete - although it may not be visible `1.0` branch, publication is complete - although it may not be visible
on GitHub until the next regular core Specification update is pushed on GitHub until the next regular core Specification update is pushed
out. out.
* It is still possible to publish a separate branch of the repository with * It is still possible to publish a separate branch of the repository with
appropriate changes relative to the core Vulkan API branch instead, but appropriate changes relative to the core Vulkan API branch instead, but
this approach is deprecated and discouraged. this approach is deprecated and discouraged.
If this is done, all changes to +vk.xml+ must still be made in the +1.0+ If this is done, all changes to `vk.xml` must still be made in the `1.0`
branch. branch.
ifdef::editing-notes[] ifdef::editing-notes[]
@ -392,18 +393,18 @@ Specification is built with an asciidoc attribute of that name defined.
.Note .Note
==== ====
This is referred to as the "`single-branch`" model, in contrast to the This is referred to as the "`single-branch`" model, in contrast to the
earlier model where each extension lived in a separate branch from the +1.0+ earlier model where each extension lived in a separate branch from the `1.0`
core Specification source. core Specification source.
==== ====
For example, the +VK_KHR_surface+ extension is now documented in the +1.0+ For example, the `VK_KHR_surface` extension is now documented in the `1.0`
branch of the GitHub +<<vulkan-docs,KhronosGroup/Vulkan-Docs>>+ project. branch of the GitHub `<<vulkan-docs,KhronosGroup/Vulkan-Docs>>` project.
However, specifications generated from this branch will only include the However, specifications generated from this branch will only include the
extension when the Makefile is invoked appropriately. extension when the Makefile is invoked appropriately.
Most language defining extensions can be localized either into a small Most language defining extensions can be localized either into a small
number of asciidoc include files which are conditionally included in the number of asciidoc include files which are conditionally included in the
core specification chapters and appendices, or into parts of +vk.xml+ core specification chapters and appendices, or into parts of `vk.xml`
defining the extension interfaces. defining the extension interfaces.
[NOTE] [NOTE]
@ -411,8 +412,8 @@ defining the extension interfaces.
==== ====
We do not yet fully document an example of including an extension in the We do not yet fully document an example of including an extension in the
single-branch model. single-branch model.
Instead, authors should refer to the +1.0+ branch and search for the names Instead, authors should refer to the `1.0` branch and search for the names
of existing extensions, such as +VK_KHR_surface+, as examples. of existing extensions, such as `VK_KHR_surface`, as examples.
Some aspects of the changes for this example extension are described below. Some aspects of the changes for this example extension are described below.
==== ====
@ -420,20 +421,20 @@ The KHR extensions were used to help prototype what changes need to be made
for extensions, which include (but may not be limited to) the following: for extensions, which include (but may not be limited to) the following:
* All extensions should add an appendix to the Vulkan specification. * All extensions should add an appendix to the Vulkan specification.
This can be modeled after what was done for the +VK_KHR_surface+ This can be modeled after what was done for the `VK_KHR_surface`
extension in +doc/specs/vulkan/appendices/VK_KHR_surface.txt+, which extension in `doc/specs/vulkan/appendices/VK_KHR_surface.txt`, which
contains metainformation about the extension (as well as code examples, contains metainformation about the extension (as well as code examples,
and revision history). and revision history).
This example is more complicated because +VK_KHR_surface+ is a base This example is more complicated because `VK_KHR_surface` is a base
extension on which many window system-specific extensions are layered. extension on which many window system-specific extensions are layered.
The +VK_EXT_debug_marker+ extension is a simpler, standalone example. The `VK_EXT_debug_marker` extension is a simpler, standalone example.
* Each extension's appendix file is included by adding an +include+ * Each extension's appendix file is included by adding an `include`
statement to the +doc/specs/vulkan/appendices/extensions.txt+ file. statement to the `doc/specs/vulkan/appendices/extensions.txt` file.
The +include+ statement must be protected by appropriate asciidoc The `include` statement must be protected by appropriate asciidoc
conditionals. conditionals.
The new file is grouped alphabetically by name, in a section of The new file is grouped alphabetically by name, in a section of
extensions sharing the same author ID. extensions sharing the same author ID.
For example, for +VK_EXT_debug_marker+, +appendices.txt+ is modified to For example, for `VK_EXT_debug_marker`, `appendices.txt` is modified to
add: add:
+ +
-- --
@ -448,8 +449,8 @@ for extensions, which include (but may not be limited to) the following:
specification. specification.
They often add an entirely new chapter, or a new section of an existing They often add an entirely new chapter, or a new section of an existing
chapter, defining the new functions, structures, and enumerants. chapter, defining the new functions, structures, and enumerants.
For example, in the case of +VK_EXT_debug_marker+, it adds a new section For example, in the case of `VK_EXT_debug_marker`, it adds a new section
of the "`Debugging`" chapter in +chapters/debugging.txt+, by including of the "`Debugging`" chapter in `chapters/debugging.txt`, by including
in that file: in that file:
+ +
-- --
@ -463,8 +464,8 @@ for extensions, which include (but may not be limited to) the following:
* In every other place where the extension alters the behavior of the core * In every other place where the extension alters the behavior of the core
Specification, make such changes and protect the modifications with the Specification, make such changes and protect the modifications with the
same asciidoc conditionals. same asciidoc conditionals.
For example, +VK_KHR_surface+ adds new error codes to Vulkan. For example, `VK_KHR_surface` adds new error codes to Vulkan.
These are added to +chapters/fundamentals.txt+ in the "`Return Codes`" These are added to `chapters/fundamentals.txt` in the "`Return Codes`"
section as follows: section as follows:
+ +
-- --
@ -477,20 +478,20 @@ for extensions, which include (but may not be limited to) the following:
---- ----
-- --
* For vendor extensions, changes made to existing core Specification * For vendor extensions, changes made to existing core Specification
source files and to +vk.xml+ all fall under the Contributor License source files and to `vk.xml` all fall under the Contributor License
Agreement. Agreement.
Vendors may use their own copyright on new files they add to the +1.0+ Vendors may use their own copyright on new files they add to the `1.0`
branch, although that copyright must be compatible with the branch, although that copyright must be compatible with the
Specification copyright. Specification copyright.
* In most cases, there will be at most two new files added to the * In most cases, there will be at most two new files added to the
specification: +extensions/*extension_name*.txt+, and specification: `extensions/*extension_name*.txt`, and
+chapters/*extension_name*.txt+. `chapters/*extension_name*.txt`.
If you need more than one new file in either the +chapters/+ or If you need more than one new file in either the `chapters/` or
+extensions/+ directories, create a subdirectory named with the `extensions/` directories, create a subdirectory named with the
extension name and place the new files there. extension name and place the new files there.
For example, instead of +chapters/VK_KHR_android_surface.txt+, there is For example, instead of `chapters/VK_KHR_android_surface.txt`, there is
+chapters/VK_KHR_android_surface/platformCreateSurface_android.txt+ and `chapters/VK_KHR_android_surface/platformCreateSurface_android.txt` and
+chapters/VK_KHR_android_surface/platformQuerySupport_android.txt+, both `chapters/VK_KHR_android_surface/platformQuerySupport_android.txt`, both
of which are conditionally included elsewhere in the core specification of which are conditionally included elsewhere in the core specification
files. files.
@ -532,7 +533,7 @@ basis.
The information needed to add new values to the XML are as follows: The information needed to add new values to the XML are as follows:
* The **extension name** (e.g. +VK_KHR_swapchain+) that is adding the new * The **extension name** (e.g. `VK_KHR_swapchain`) that is adding the new
enumeration constant. enumeration constant.
* The existing enumeration **type** being extended (e.g. * The existing enumeration **type** being extended (e.g.
stext:VkStructureType). stext:VkStructureType).
@ -541,7 +542,7 @@ The information needed to add new values to the XML are as follows:
* The **offset**, which is an integer between 0 and 999 relative to the * The **offset**, which is an integer between 0 and 999 relative to the
base being used for the extension. base being used for the extension.
* The **direction** may be specified to indicate a negative value * The **direction** may be specified to indicate a negative value
(+dir="-"+) when needed for negative etext:VkResult values indicating (`dir="-"`) when needed for negative etext:VkResult values indicating
errors, like etext:VK_ERROR_SURFACE_LOST_KHR. errors, like etext:VK_ERROR_SURFACE_LOST_KHR.
The default direction is positive, if not specified. The default direction is positive, if not specified.
@ -550,15 +551,15 @@ range of unused values offset against a global extension base value.
Individual enumerant values are calculated as offsets in that range. Individual enumerant values are calculated as offsets in that range.
Values are calculated as follows: Values are calculated as follows:
* [eq]#base_value = 1000000000# * [eq]#_base_value_ = 1000000000#
* [eq]#range_size = 1000# * [eq]#_range_size_ = 1000#
* [eq]#enum_offset(extension_number,offset) = base_value {plus} * [eq]#enum_offset(_extension_number_, _offset_) = _base_value_ {plus}
(extension_number - 1) {times} range_size + offset# (_extension_number_ - 1) {times} _range_size_ + _offset_#
* Positive values: [eq]#enum_offset(extension_number,offset)# * Positive values: [eq]#enum_offset(_extension_number_, _offset_})#
* Negative values: [eq]#-enum_offset(extension_number,offset)# * Negative values: [eq]#enum_offset(_extension_number_, _offset_})#
The exact syntax for specifying extension enumerant values is defined in the The exact syntax for specifying extension enumerant values is defined in the
+readme.pdf+ specifying the format of +vk.xml+, and extension authors can `readme.pdf` specifying the format of `vk.xml`, and extension authors can
also refer to existing extensions for examples. also refer to existing extensions for examples.
@ -581,24 +582,47 @@ specification until the reservation is merged into
In addition to any tokens specific to the functionality of an extension, all In addition to any tokens specific to the functionality of an extension, all
extensions must define two additional tokens. extensions must define two additional tokens.
* +VK_EXTNAME_SPEC_VERSION+ is an integer constant which is the revision * `VK_EXTNAME_SPEC_VERSION` is an integer constant which is the revision
of the extension named +VK_extname+ (+EXTNAME+ is all upper-case, while of the extension named `VK_extname` (`EXTNAME` is all upper-case, while
extname is the capitalization of the actual extension name) in extname is the capitalization of the actual extension name) in
+vulkan.h+. `vulkan.h`.
This value begins at 1 with the initial version of an extension This value begins at 1 with the initial version of an extension
specification, and is incremented when significant changes (bugfixes or specification, and is incremented when changes are made.
added functionality) are made. Note that the revision of an extension defined in `vulkan.h` and the
Note that the revision of an extension defined in +vulkan.h+ and the
revision supported by the Vulkan implementation (the pname:specVersion revision supported by the Vulkan implementation (the pname:specVersion
field of the slink:VkExtensionProperties structure corresponding to the field of the slink:VkExtensionProperties structure corresponding to the
extension and returned by one of the extension and returned by one of the
<<extended-functionality-extensions,extension queries>>) may differ. <<extended-functionality-extensions,extension queries>>) may differ.
In such cases, only the functionality and behavior of the The revision value indicates a patch version of the extension
lowest-numbered revision can be used. specification, and differences in this version number maintain full
* +VK_EXTNAME_EXTENSION_NAME+ is a string constant which is the name of compatibility, as defined in the
link:html/vkspec.html#fundamentals-versionnum[API Version Numbers and
Semantics] section of the <<vulkan-spec,Vulkan API Specification>>.
[NOTE]
.Note
====
Any changes requiring the addition or removal of a type or command should be
done by creating a new extension.
The resulting extension should take care to include the appropriate
dependency information on the original extension.
====
[NOTE]
.Note
====
When the Debug Report extension (VK_EXT_debug_report) was recently updated
to include the enum values of VK_DEBUG_REPORT_OBJECT_TYPE_DISPLAY_KHR_EXT
and VK_DEBUG_REPORT_OBJECT_TYPE_DISPLAY_MODE_KHR_EXT, we violated this
policy.
That change was done prior to this revision policy clarification.
From this point forward, we intend to follow this policy.
====
* `VK_EXTNAME_EXTENSION_NAME` is a string constant which is the name of
the extension. the extension.
For example, for the WSI extension +VK_KHR_surface+, at the time of writing For example, for the WSI extension `VK_KHR_surface`, at the time of writing
the following definitions were in effect: the following definitions were in effect:
[source,c] [source,c]
@ -613,16 +637,16 @@ the following definitions were in effect:
Expanding on previous discussion, extensions can add values to existing Expanding on previous discussion, extensions can add values to existing
enums; and can add their own commands, enums, typedefs, etc. enums; and can add their own commands, enums, typedefs, etc.
This is done by adding to <<extensions-api-registry,+vk.xml+>>. This is done by adding to <<extensions-api-registry,+vk.xml+>>.
All such additions will be included in the +vulkan.h+ header supplied by All such additions will be included in the `vulkan.h` header supplied by
Khronos. Khronos.
[NOTE] [NOTE]
.Note .Note
==== ====
Application developers are encouraged to be careful when using +switch+ Application developers are encouraged to be careful when using `switch`
statements with Vulkan API enums. statements with Vulkan API enums.
This is because extensions can add new values to existing enums. This is because extensions can add new values to existing enums.
The use of a +default:+ statement, within a +switch+, may avoid future The use of a `default:` statement, within a `switch`, may avoid future
compilation issues. compilation issues.
==== ====
@ -631,35 +655,35 @@ compilation issues.
== Extension Function Prototypes == Extension Function Prototypes
Function pointer declarations and function prototypes for all core Vulkan Function pointer declarations and function prototypes for all core Vulkan
API commands are included in the +vulkan.h+ file. API commands are included in the `vulkan.h` file.
These come from the official XML specification of the Vulkan API hosted by These come from the official XML specification of the Vulkan API hosted by
Khronos. Khronos.
Function pointer declarations are also included in the +vulkan.h+ file for Function pointer declarations are also included in the `vulkan.h` file for
all commands defined by registered extensions. all commands defined by registered extensions.
Function prototypes for extensions may be included in +vulkan.h+. Function prototypes for extensions may be included in `vulkan.h`.
Extension commands that are part of the Vulkan ABI must be flagged in the Extension commands that are part of the Vulkan ABI must be flagged in the
XML. XML.
Function prototypes will be included in +vulkan.h+ for all extension Function prototypes will be included in `vulkan.h` for all extension
commands that are part of the Vulkan ABI. commands that are part of the Vulkan ABI.
An extension can be considered platform specific, in which case its An extension can be considered platform specific, in which case its
interfaces in +vulkan.h+ are protected by #ifdefs. interfaces in `vulkan.h` are protected by #ifdefs.
This is orthogonal to whether an extension command is considered to be part This is orthogonal to whether an extension command is considered to be part
of the Vulkan ABI. of the Vulkan ABI.
The initial set of WSI extension commands (i.e. for +VK_KHR_surface+, The initial set of WSI extension commands (i.e. for `VK_KHR_surface`,
+VK_KHR_swapchain+, and +VK_KHR_*_surface+) are considered to be part of the `VK_KHR_swapchain`, and `VK_KHR_*_surface`) are considered to be part of the
Vulkan ABI. Vulkan ABI.
Function prototypes for these WSI commands are included in the +vulkan.h+ Function prototypes for these WSI commands are included in the `vulkan.h`
provided by Khronos, though the platform-specific portions of +vulkan.h+ are provided by Khronos, though the platform-specific portions of `vulkan.h` are
protected by #ifdefs. protected by #ifdefs.
[NOTE] [NOTE]
.Note .Note
==== ====
Based on feedback from implementers, Khronos expects that the Android, Based on feedback from implementers, Khronos expects that the Android,
Linux, and Windows Vulkan SDKs will include our +vulkan.h+ and export the Linux, and Windows Vulkan SDKs will include our `vulkan.h` and export the
supported WSI functions for those platforms from their loader libraries. supported WSI functions for those platforms from their loader libraries.
Other implementations can make different choices for their headers and Other implementations can make different choices for their headers and
loader libraries, but are encouraged to be consistent with these loader libraries, but are encouraged to be consistent with these

33
doc/specs/vulkan/style/markup.txt
View File

@ -105,16 +105,16 @@ The block types and delimiters are shown in the following table.
.Asciidoc Block Delimiters .Asciidoc Block Delimiters
[width="70%",options="header",cols="25%,10%,65%"] [width="70%",options="header",cols="25%,10%,65%"]
|==== |====
| Table Type | Delimiter | Comments | Table Type | Delimiter | Comments
| Open | `--` | For <<markup-sample-section-bullet-lists,continuation blocks>> | Open | `--` | For <<markup-sample-section-bullet-lists,continuation blocks>>
| Example | `====` | For <<markup-informative-notes,Notes>> | Example | `====` | For <<markup-informative-notes,Notes>>
| Passthrough | `++++` | For some kinds of <<writing-math,math markup>> | Passthrough | pass:[++++] | For some kinds of <<writing-math,math markup>>
| Comment | //// | | Comment | //// |
| Listing | ---- | For source code listings | Listing | ---- | For source code listings
| Sidebar | **** | For <<markup-implementors-notes,implementor's notes>> | Sidebar | pass:[****] | For <<markup-implementors-notes,implementor's notes>>
| Table | `\|====` | For <<markup-sample-section-tables,tables>> | Table | `\|====` | For <<markup-sample-section-tables,tables>>
| Quote | `____` | Currently unused in the Vulkan Specification | Quote | pass:[____] | Currently unused in the Vulkan Specification
| Literal | .... | Currently unused in the Vulkan Specification | Literal | .... | Currently unused in the Vulkan Specification
|==== |====
@ -309,7 +309,7 @@ image::images/imagename.svg[align="center",title="Figure caption",{fullimagewidt
There must be both .svg and .pdf versions of each figure checked into the There must be both .svg and .pdf versions of each figure checked into the
+images/+ directory, to support generating both HTML and PDF outputs. +images/+ directory, to support generating both HTML and PDF outputs.
It is best to create images in Inkscape as SVG files and then use the It is best to create images in Inkscape as SVG files and then use the
conversion rule in +doc/specs/vulkan/images/Makefile+ to generate PDF. conversion rule in `doc/specs/vulkan/images/Makefile` to generate PDF.
Asciidoc restricts captions in figures to be a single line in the source Asciidoc restricts captions in figures to be a single line in the source
document. document.
@ -436,9 +436,7 @@ table:
| code{cl} | Formats the macro argument as a code sample. Primarily | code{cl} | Formats the macro argument as a code sample. Primarily
used for SPIR-V keywords and builtin C types. Examples: used for SPIR-V keywords and builtin C types. Examples:
code{cl}uint32_t -> code:uint32_t, code{cl}uint32_t -> code:uint32_t,
code{cl}ClipDistance -> code:ClipDistance, code{cl}ClipDistance -> code:ClipDistance.
code{cl}VK_NULL_HANDLE -> code:VK_NULL_HANDLE,
code{cl}NULL -> code:NULL.
|==== |====
When referring to a compound name (function-parameter, or structure-member), When referring to a compound name (function-parameter, or structure-member),
@ -460,14 +458,13 @@ slink:VkMemoryHeap::pname:flags
Uses of standard Asciidoc markup are less common. Uses of standard Asciidoc markup are less common.
Occasional asterisk markup is used for *emphasis*. Occasional asterisk markup is used for *emphasis*.
Backtick markup is sometimes used for the C `NULL` macro, but the code{cl} Underscores are used for _glossary terms_.
macro should be used for code:NULL instead. Backtick markup is used for the C `NULL` macro.
.Example Markup .Example Markup
---- ----
*emphasis* *emphasis*
`NULL` `NULL`
code:NULL
---- ----
@ -603,7 +600,7 @@ Editing notes usually only appear in internal (non-published) versions of
documents, via asciidoc conditionals. documents, via asciidoc conditionals.
If they are not resolved, or are internal issues that should not be visible If they are not resolved, or are internal issues that should not be visible
in public, they should be removed from the source before pushing content to in public, they should be removed from the source before pushing content to
a canonical (+1.0+ or per-extension) public repository. a canonical (`1.0` or per-extension) public repository.
They usually tag places where an outstanding Gitlab/GitHub issue is being They usually tag places where an outstanding Gitlab/GitHub issue is being
worked, and are always given the title _editing-note_, as in the following worked, and are always given the title _editing-note_, as in the following
example: example:

8
doc/specs/vulkan/style/naming.txt
View File

@ -123,7 +123,7 @@ converted to the correct case (e.g. `VkStructureType` ->
This rule applies to all enumerants, with one exception. This rule applies to all enumerants, with one exception.
* The "VkResult" enumerants are split into two sub types: error and success * The `VkResult` enumerants are split into two sub types: error and success
codes. codes.
** Success codes are not prefixed with anything other than `VK_`. ** Success codes are not prefixed with anything other than `VK_`.
** Error codes are prefixed with `VK_ERROR_`. ** Error codes are prefixed with `VK_ERROR_`.
@ -220,10 +220,10 @@ as the length in the base structure.
These rules apply to all function parameters and struct/union members, with These rules apply to all function parameters and struct/union members, with
a single exception: a single exception:
* The 'sType' member of structures is abbreviated as it is used in almost * The `sType` member of structures is abbreviated as it is used in almost
every structure. every structure.
** The slightly odd naming prevents it clashing with any future variables. ** The slightly odd naming prevents it clashing with any future variables.
** The s stands for "structure", referring to its enumerant type. ** The `s` stands for "`structure`", referring to its enumerant type.
[source, c] [source, c]
.Example .Example
@ -311,7 +311,7 @@ definitions by the generator scripts.
[NOTE] [NOTE]
==== ====
There is one exception to this rule in the There is one exception to this rule in the
VK_KHR_sampler_mirror_clamp_to_edge extension. `VK_KHR_sampler_mirror_clamp_to_edge` extension.
This functionality was included in the original spec, but quickly separated This functionality was included in the original spec, but quickly separated
out at release. out at release.
Due to this late change, the single enum exposed has retained its original Due to this late change, the single enum exposed has retained its original

73
doc/specs/vulkan/style/writing.txt
View File

@ -158,10 +158,10 @@ Normative parts of the <<vulkan-spec,Vulkan API Specification>> should
describe _what_ something does, rather than _how_ or _why_ an application describe _what_ something does, rather than _how_ or _why_ an application
would want to use it. would want to use it.
When explicitly allowed by the Specification, the reserved value code:NULL When explicitly allowed by the Specification, the reserved value `NULL` may:
may: be used for Vulkan dispatchable objects, pointer parameters and be used for pointer parameters and members and dispatchable object handles,
members, and the reserved value dname:VK_NULL_HANDLE may: be used for Vulkan and the reserved value dname:VK_NULL_HANDLE may: be used for
non-dispatchable object handle parameters and members. non-dispatchable Vulkan object handle parameters and members.
Otherwise, pointers and handles must: refer to valid memory and valid Vulkan Otherwise, pointers and handles must: refer to valid memory and valid Vulkan
objects, respectively. objects, respectively.
@ -200,7 +200,7 @@ Where possible, math is marked up using straight asciidoc features.
For commonality with LaTeX math (see below), some common LaTeX operators and For commonality with LaTeX math (see below), some common LaTeX operators and
names are defined as asciidoc attributes using the same names, expanding to names are defined as asciidoc attributes using the same names, expanding to
the corresponding Unicode entities. the corresponding Unicode entities.
The complete set of these attributes is found in +config/attribs.txt+. The complete set of these attributes is found in `config/attribs.txt`.
.Spelling .Spelling
[width="100%",options="header",cols="20%,20%,60%"] [width="100%",options="header",cols="20%,20%,60%"]
@ -209,57 +209,57 @@ The complete set of these attributes is found in +config/attribs.txt+.
| Subscripts | Subscripts
| [eq]#a~x~# | [eq]#a~x~#
| `[eq]#a~x~#` | +++[eq]#a~x~#+++
| Superscripts | Superscripts
| [eq]#-2^(b-1)^# | [eq]#-2^(b-1)^#
| `[eq]#-2^(b-1)^#` | +++[eq]#-2^(b-1)^#+++
| Struct/parameter names as variables | Struct/parameter names as variables
| [eq]#2^pname:bits^# | [eq]#2^pname:bits^#
| `[eq]#2^pname:bits^#` | +++[eq]#2^pname:bits^#+++
| Greek Letters (selected) | Greek Letters (selected)
| [eq]#{alpha}, {beta}, {gamma}, {delta}, {DeltaUpper}, {epsilon}, {lambda}, | [eq]#{alpha}, {beta}, {gamma}, {delta}, {DeltaUpper}, {epsilon}, {lambda},
{rho}, {tau}# {rho}, {tau}#
| `[eq]#{alpha}, {beta}, {gamma}, {delta}, {DeltaUpper}, {epsilon}, {lambda}, | +++[eq]#{alpha}, {beta}, {gamma}, {delta}, {DeltaUpper}, {epsilon}, {lambda},
{rho}, {tau}#` {rho}, {tau}#+++
| Fractions | Fractions
| [eq]#{onequarter} + {onehalf}# | [eq]#{onequarter} + {onehalf}#
| `[eq]#{onequarter} + {onehalf}#` | +++[eq]#{onequarter} + {onehalf}#+++
| Closed Ranges | Closed Ranges
| [eq]#[0,1]# | [eq]#[0,1]#
| `[eq]#[0,1]#` | +++[eq]#[0,1]#+++
| Open Ranges | Open Ranges
| [eq]#[0,1)# | [eq]#[0,1)#
| `[eq]#[0,1)#` | +++[eq]#[0,1)#+++
| Arithmetic and Relational Operators | Arithmetic and Relational Operators
| [eq]#a {times} b#, [eq]#a {leq} b#, [eq]#a {neq} b#, [eq]#a {geq} b#, [eq]#{vert}x{vert}# | [eq]#a {times} b#, [eq]#a {leq} b#, [eq]#a {neq} b#, [eq]#a {geq} b#, [eq]#{vert}x{vert}#
| `[eq]#a {times} b#`, `[eq]#a {leq} b#`, `[eq]#a {neq} b#`, `[eq]#a {geq} b#`, `[eq]#{vert}x{vert}#` | +++[eq]#a {times} b#+++, +++[eq]#a {leq} b#+++, +++[eq]#a {neq} b#+++, +++[eq]#a {geq} b#+++, +++[eq]#{vert}x{vert}#+++
| Floor | Floor
| [eq]#{lfloor}w - {onehalf}{rfloor}# | [eq]#{lfloor}w - {onehalf}{rfloor}#
| `[eq]#{lfloor}w - {onehalf}{rfloor}#` | +++[eq]#{lfloor}w - {onehalf}{rfloor}#+++
| Ceiling | Ceiling
| [eq]#{lceil}log~2~(max(pname:width, pname:height)){rceil} + 1# | [eq]#{lceil}log~2~(max(pname:width, pname:height)){rceil} + 1#
| `[eq]#{lceil}log~2~(max(pname:width, pname:height)){rceil} + 1#` | +++[eq]#{lceil}log~2~(max(pname:width, pname:height)){rceil} + 1#+++
| Logical and Set Operators | Logical and Set Operators
| [eq]#{land} {lnot} {lor} {oplus} {elem}# | [eq]#{land} {lnot} {lor} {oplus} {elem}#
| `[eq]#{land} {lnot} {lor} {oplus} {elem}#` | +++[eq]#{land} {lnot} {lor} {oplus} {elem}#+++
| Partial Derivatives | Partial Derivatives
| [eq]#{partial}r~x~ / {partial}x = 0# | [eq]#{partial}r~x~ / {partial}x = 0#
| `[eq]#{partial}r~x~ / {partial}x = 0#` | +++[eq]#{partial}r~x~ / {partial}x = 0#+++
| Matrix/Vector Parameter Names | Matrix/Vector Parameter Names
| [eq]#**P** = t **P**~1~ + (1-t) **P**~2~# | [eq]#**P** = t **P**~1~ + (1-t) **P**~2~#
| `[eq]#**P** = t **P**~1~ + (1-t) **P**~2~#` | +++[eq]#**P** = t **P**~1~ + (1-t) **P**~2~#+++
|==== |====
@ -345,8 +345,8 @@ Some workarounds we've had to make are:
[width="70%",options="header",cols="20%,20%,60%"] [width="70%",options="header",cols="20%,20%,60%"]
|==== |====
| Replace | With | Comments | Replace | With | Comments
| `\begin{equation}` | `` | Unnecessary in blocks. Should not be used for inline. | `\begin{equation}` | _nothing_ | Unnecessary in blocks. Should not be used for inline.
| `\end{equation}` | `` | Unnecessary in blocks. Should not be used for inline. | `\end{equation}` | _nothing_ | Unnecessary in blocks. Should not be used for inline.
| `\begin{align*}` | `\begin{aligned}` | | `\begin{align*}` | `\begin{aligned}` |
| `\end{align*}` | `\end{aligned}` | | `\end{align*}` | `\end{aligned}` |
| `\operatorname{foo}` | `\mathbin{foo}` | | `\operatorname{foo}` | `\mathbin{foo}` |
@ -370,7 +370,8 @@ exists before using anything, but almost all standard functionality is
supported for both. supported for both.
==== ====
This example uses normal LaTeX math brackets to delimit the expression: This example is among the most complex expressions in the Vulkan
specification:
[latexmath] [latexmath]
+++++++++++++++++++ +++++++++++++++++++
@ -501,7 +502,7 @@ include::../validity/protos/vkCreateCommandPool.txt[]
.Guideline .Guideline
==== ====
Some parameter and member validation language for commands and structures is Some parameter and member validation language for commands and structures is
_implicit_ (autogenerated from +vk.xml+), and included from the _implicit_ (autogenerated from `vk.xml`), and included from the
`../validity/` directories. `../validity/` directories.
There may be additional validation language which is explicit, and such There may be additional validation language which is explicit, and such
language is written in a separate block in the specification preceding the language is written in a separate block in the specification preceding the
@ -525,7 +526,7 @@ include::../api/structs/VkCommandPoolCreateInfo.txt[]
[NOTE] [NOTE]
.Guideline .Guideline
==== ====
Begin the structure description with a +refBegin+ comment delimiting the Begin the structure description with a `refBegin` comment delimiting the
language for <<writing-refpages,automatic extraction into a reference page>> language for <<writing-refpages,automatic extraction into a reference page>>
and including a summary line for the reference page. and including a summary line for the reference page.
@ -633,7 +634,7 @@ This requires that the markup and writing conventions described above be
adhered to rigidly. adhered to rigidly.
The extraction scripts for a given page rely on the existence of the The extraction scripts for a given page rely on the existence of the
asciidoc +include+ of the autogenerated definition of that command, asciidoc `include` of the autogenerated definition of that command,
structure, or other API interface element. structure, or other API interface element.
Various heuristics are used to determine which text to extract for that Various heuristics are used to determine which text to extract for that
page; the general model is: page; the general model is:
@ -647,33 +648,33 @@ page; the general model is:
---- ----
+ +
* A paragraph of text introducing the definition of the interface. * A paragraph of text introducing the definition of the interface.
If the +refBegin+ comment does not exist, this paragraph must be If the `refBegin` comment does not exist, this paragraph must be
present. present.
* The +include+ line for the interface, which must be consistent with the * The `include` line for the interface, which must be consistent with the
interface name in the comment line. interface name in the comment line.
* A bullet list describing function parameters, structure members, * A bullet list describing function parameters, structure members,
enumerants in an enumerated type, etc. enumerants in an enumerated type, etc.
This list should contain no empty lines, as the extraction script This list should contain no empty lines, as the extraction script
classifies the uninterrupted block of text following the +include+ classifies the uninterrupted block of text following the `include`
directive as the +Parameters+ or +Members+ section of the ref page. directive as the `Parameters` or `Members` section of the ref page.
* Optional paragraphs of text making up the +Description+ section of the * Optional paragraphs of text making up the `Description` section of the
ref page. ref page.
If it is necessary due to constraints of asciidoc markup to have an If it is necessary due to constraints of asciidoc markup to have an
empty line in the bullet list section^1^, add a +refBody+ comment empty line in the bullet list section^1^, add a `refBody` comment
immediately following the bullet list and preceding this section: immediately following the bullet list and preceding this section:
+ +
---- ----
// refBody name // refBody name
---- ----
+ +
* The +include+ line for the validity statement of commands and * The `include` line for the validity statement of commands and
structures. structures.
Other interfaces such as enumerated types do not have validity Other interfaces such as enumerated types do not have validity
statements. statements.
* Comment line specifying the end of the extracted text for the reference * Comment line specifying the end of the extracted text for the reference
page and optional page names to link to in the +See Also+ section of the page and optional page names to link to in the `See Also` section of the
page. page.
If the validity +include+ is not present, this line must be present: If the validity `include` is not present, this line must be present:
+ +
---- ----
// refEnd name [seeAlsoNames]* // refEnd name [seeAlsoNames]*
@ -683,8 +684,8 @@ page; the general model is:
The only example of such markup in the 1.0.28 Vulkan Specification The only example of such markup in the 1.0.28 Vulkan Specification
source is the stext:VkPhysicalDeviceLimits structure description. source is the stext:VkPhysicalDeviceLimits structure description.
All elements specifying an interface name (+refBegin+, +refBody+, and All elements specifying an interface name (`refBegin`, `refBody`, and
+refEnd+ comments, interface +include+ line, and validity +include+ line) `refEnd` comments, interface `include` line, and validity `include` line)
must use the same interface name, if present. must use the same interface name, if present.
Otherwise the extraction script is either unable to extract that page, or Otherwise the extraction script is either unable to extract that page, or
will extract the wrong text. will extract the wrong text.

1
doc/specs/vulkan/styleguide.txt
View File

@ -154,6 +154,7 @@ include::style/writing.txt[]
= Revision History = Revision History
* 2017-02-11 - Finish transitioning to asciidoctor markup.
* 2016-09-28 - Add asciidoc math markup guidelines. * 2016-09-28 - Add asciidoc math markup guidelines.
* 2016-09-16 - Make style guide markup more consistent with its own * 2016-09-16 - Make style guide markup more consistent with its own
recommendations. recommendations.

30
src/spec/vk.xml
View File

@ -65,6 +65,7 @@ maintained in the master branch of the Khronos Vulkan GitHub project.
<tag name="NN" author="Nintendo Co., Ltd." contact="Yasuhiro Yoshioka @yoshioka_yasuhiro"/> <tag name="NN" author="Nintendo Co., Ltd." contact="Yasuhiro Yoshioka @yoshioka_yasuhiro"/>
<tag name="KHR" author="Khronos" contact="Tom Olson @tom.olson"/> <tag name="KHR" author="Khronos" contact="Tom Olson @tom.olson"/>
<tag name="EXT" author="Multivendor" contact="Jon Leech @oddhack"/> <tag name="EXT" author="Multivendor" contact="Jon Leech @oddhack"/>
<tag name="MESA" author="Mesa open source project" contact="Chad Versace @chadversary, Daniel Stone @fooishbar, David Airlie @airlied, Jason Ekstrand @jekstrand"/>
</tags> </tags>
<!-- SECTION: Vulkan type definitions --> <!-- SECTION: Vulkan type definitions -->
@ -109,7 +110,7 @@ maintained in the master branch of the Khronos Vulkan GitHub project.
<type category="define">// Vulkan 1.0 version number <type category="define">// Vulkan 1.0 version number
#define <name>VK_API_VERSION_1_0</name> <type>VK_MAKE_VERSION</type>(1, 0, 0)</type> <!-- The patch version here should never be set to anything other than 0 --> #define <name>VK_API_VERSION_1_0</name> <type>VK_MAKE_VERSION</type>(1, 0, 0)</type> <!-- The patch version here should never be set to anything other than 0 -->
<type category="define">// Version of this file <type category="define">// Version of this file
#define <name>VK_HEADER_VERSION</name> 40</type> #define <name>VK_HEADER_VERSION</name> 41</type>
<type category="define"> <type category="define">
#define <name>VK_DEFINE_HANDLE</name>(object) typedef struct object##_T* object;</type> #define <name>VK_DEFINE_HANDLE</name>(object) typedef struct object##_T* object;</type>
@ -5199,7 +5200,7 @@ maintained in the master branch of the Khronos Vulkan GitHub project.
<enum value="&quot;VK_NV_extension_104&quot;" name="VK_NV_EXTENSION_104_EXTENSION_NAME"/> <enum value="&quot;VK_NV_extension_104&quot;" name="VK_NV_EXTENSION_104_EXTENSION_NAME"/>
</require> </require>
</extension> </extension>
<extension name="VK_EXT_swapchain_colorspace" number="105" type="device" author="GOOGLE" contact="Courtney Goeltzenleuchter @courtneygo" requires="VK_KHR_surface" supported="vulkan"> <extension name="VK_EXT_swapchain_colorspace" number="105" type="device" author="GOOGLE" contact="Courtney Goeltzenleuchter @courtneygo" requires="VK_KHR_surface" supported="disabled">
<require> <require>
<enum value="1" name="VK_EXT_SWAPCHAIN_COLOR_SPACE_SPEC_VERSION"/> <enum value="1" name="VK_EXT_SWAPCHAIN_COLOR_SPACE_SPEC_VERSION"/>
<enum value="&quot;VK_EXT_swapchain_colorspace&quot;" name="VK_EXT_SWAPCHAIN_COLOR_SPACE_EXTENSION_NAME"/> <enum value="&quot;VK_EXT_swapchain_colorspace&quot;" name="VK_EXT_SWAPCHAIN_COLOR_SPACE_EXTENSION_NAME"/>
@ -5310,5 +5311,30 @@ maintained in the master branch of the Khronos Vulkan GitHub project.
<enum value="&quot;VK_KHR_extension_120&quot;" name="VK_KHR_EXTENSION_120_EXTENSION_NAME"/> <enum value="&quot;VK_KHR_extension_120&quot;" name="VK_KHR_EXTENSION_120_EXTENSION_NAME"/>
</require> </require>
</extension> </extension>
<extension name="VK_KHR_variable_pointers" number="121" author="KHR" contact="John Kessenich @johnk" supported="disabled">
<require>
<enum value="0" name="VK_KHR_variable_pointers_SPEC_VERSION"/>
<enum value="&quot;VK_KHR_variable_pointers&quot;" name="VK_KHR_variable_pointers_EXTENSION_NAME"/>
</require>
</extension>
<extension name="VK_KHR_extension_122" number="122" author="KHR" contact="James Jones @cubanismo" supported="disabled">
<require>
<enum value="0" name="VK_KHR_EXTENSION_122_SPEC_VERSION"/>
<enum value="&quot;VK_KHR_extension_122&quot;" name="VK_KHR_EXTENSION_122_EXTENSION_NAME"/>
</require>
</extension>
<!-- padding 123-125, for unpublished extensions under review -->
<extension name="VK_MESA_extension_126" number="126" author="MESA" contact="Chad Versace @chadversary" supported="disabled">
<require>
<enum value="0" name="VK_MESA_EXTENSION_126_SPEC_VERSION"/>
<enum value="&quot;VK_MESA_extension_126&quot;" name="VK_MESA_EXTENSION_126_EXTENSION_NAME"/>
</require>
</extension>
<extension name="VK_MESA_extension_127" number="127" author="MESA" contact="Chad Versace @chadversary" supported="disabled">
<require>
<enum value="0" name="VK_MESA_EXTENSION_127_SPEC_VERSION"/>
<enum value="&quot;VK_MESA_extension_127&quot;" name="VK_MESA_EXTENSION_127_EXTENSION_NAME"/>
</require>
</extension>
</extensions> </extensions>
</registry> </registry>

19
src/vulkan/vulkan.h
View File

@ -43,7 +43,7 @@ extern "C" {
#define VK_VERSION_MINOR(version) (((uint32_t)(version) >> 12) & 0x3ff) #define VK_VERSION_MINOR(version) (((uint32_t)(version) >> 12) & 0x3ff)
#define VK_VERSION_PATCH(version) ((uint32_t)(version) & 0xfff) #define VK_VERSION_PATCH(version) ((uint32_t)(version) & 0xfff)
// Version of this file // Version of this file
#define VK_HEADER_VERSION 40 #define VK_HEADER_VERSION 41
#define VK_NULL_HANDLE 0 #define VK_NULL_HANDLE 0
@ -3225,18 +3225,6 @@ VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkSurfaceKHR)
typedef enum VkColorSpaceKHR { typedef enum VkColorSpaceKHR {
VK_COLOR_SPACE_SRGB_NONLINEAR_KHR = 0, VK_COLOR_SPACE_SRGB_NONLINEAR_KHR = 0,
VK_COLOR_SPACE_DISPLAY_P3_LINEAR_EXT = 1000104001,
VK_COLOR_SPACE_DISPLAY_P3_NONLINEAR_EXT = 1000104002,
VK_COLOR_SPACE_SCRGB_LINEAR_EXT = 1000104003,
VK_COLOR_SPACE_SCRGB_NONLINEAR_EXT = 1000104004,
VK_COLOR_SPACE_DCI_P3_LINEAR_EXT = 1000104005,
VK_COLOR_SPACE_DCI_P3_NONLINEAR_EXT = 1000104006,
VK_COLOR_SPACE_BT709_LINEAR_EXT = 1000104007,
VK_COLOR_SPACE_BT709_NONLINEAR_EXT = 1000104008,
VK_COLOR_SPACE_BT2020_LINEAR_EXT = 1000104009,
VK_COLOR_SPACE_BT2020_NONLINEAR_EXT = 1000104010,
VK_COLOR_SPACE_ADOBERGB_LINEAR_EXT = 1000104011,
VK_COLOR_SPACE_ADOBERGB_NONLINEAR_EXT = 1000104012,
VK_COLOR_SPACE_BEGIN_RANGE_KHR = VK_COLOR_SPACE_SRGB_NONLINEAR_KHR, VK_COLOR_SPACE_BEGIN_RANGE_KHR = VK_COLOR_SPACE_SRGB_NONLINEAR_KHR,
VK_COLOR_SPACE_END_RANGE_KHR = VK_COLOR_SPACE_SRGB_NONLINEAR_KHR, VK_COLOR_SPACE_END_RANGE_KHR = VK_COLOR_SPACE_SRGB_NONLINEAR_KHR,
VK_COLOR_SPACE_RANGE_SIZE_KHR = (VK_COLOR_SPACE_SRGB_NONLINEAR_KHR - VK_COLOR_SPACE_SRGB_NONLINEAR_KHR + 1), VK_COLOR_SPACE_RANGE_SIZE_KHR = (VK_COLOR_SPACE_SRGB_NONLINEAR_KHR - VK_COLOR_SPACE_SRGB_NONLINEAR_KHR + 1),
@ -4751,11 +4739,6 @@ VKAPI_ATTR VkResult VKAPI_CALL vkGetSwapchainCounterEXT(
uint64_t* pCounterValue); uint64_t* pCounterValue);
#endif #endif
#define VK_EXT_swapchain_colorspace 1
#define VK_EXT_SWAPCHAIN_COLOR_SPACE_SPEC_VERSION 1
#define VK_EXT_SWAPCHAIN_COLOR_SPACE_EXTENSION_NAME "VK_EXT_swapchain_colorspace"
#ifdef __cplusplus #ifdef __cplusplus
} }
#endif #endif