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 March 7, 2018 Vulkan 1.1.70 spec update: 

* Vulkan 1.1 initial release. Bump API patch number and header version
    number to 70 for this update. The patch number will be used for both
    Vulkan 1.1 and Vulkan 1.0 updates, and continues to increment
    continuously from the previous Vulkan 1.0.69 update.

    NOTE: We are not publishing an updated 1.0.70 specification, or 1.1
    reference pages, along with 1.1.70. There are still minor issues to work
    out with those build targets. However, we will soon generate all three
    types of documents as part of the regular spec update cycle.

    NOTE: The GitHub KhronosGroup/Vulkan-Docs repository now maintains the
    current specification in the `master` branch. The `1.0` branch is out of
    date and will not be maintained, since we will be generating both 1.1
    and 1.0 specifications from the `master` branch in the future.

Github Issues:

  * Clarify how mapped memory ranges are flushed in
    flink:vkFlushMappedMemoryRanges (public issue 127).
  * Specify that <<synchronization-pipeline-stages, Pipeline Stages>> are a
    list of tasks that each command performs, rather than necessarily being
    discrete pieces of hardware that one task flows through. Add a
    "`synchronization command`" pipeline type which all synchronization
    command execute (it's just TOP + BOTTOM), with an explanatory note
    (public issue 554).

Internal Issues:

  * Regenerate all images used in the spec in Inkscape with a consistent
    look-and-feel, and adjust image size attributes so they're all legible,
    and not too large with respect to the spec body text (internal issue
    701).
  * Document in the <<extensions,extensions>> appendix and in the style
    guide that `KHX` extensions are no longer supported or used in the
    Vulkan 1.1 timeframe (internal issue 714).
  * Remove the leftover equations_temp directory after PDF build completes
    (internal issue 925).
  * Update the <<credits, Credits (Informative)>> appendix to include
    contributors to Vulkan 1.1, and to list them according to the API
    version(s) they contributed to (internal issue 987).
  * Add a NOTE to the introduction explaining that interfaces defined by
    extensions which were promoted to Vulkan 1.1 are now expressed as
    aliases of the Vulkan 1.1 type (internal issue 991).
  * Instrument spec source conditionals so spec can be built with 1.1
    features, extensions promoted to 1.1, or both (internal issues 992,
    998).
  * Modify the XML schema and tools to support explicit aliasing of types,
    structures, and commands, and use this to express the promotion of 1.0
    extensions to 1.1 core features, by making the extension interfaces
    aliases of the core features they were promoted to. Mark up promoted
    interfaces to allow still generating 1.0 + extension specifications
    (internal issue 991).
  * Platform names, along with corresponding preprocessor symbols to enable
    extensions specific to those platforms, are now reserved in vk.xml using
    the <platform> tag. Update the registry schema and schema specification
    to match (internal issue 1011).
  * Updated the <<textures-texel-replacement, Texel Replacement>> section to
    clarify that reads from invalid texels for image resources result in
    undefined values (internal issue 1014).
  * Modify description of patch version so it continues to increment across
    minor version changes (internal issue 1033).
  * Clarify and unify language describing physical device-level core and
    extension functionality in the <<fundamentals-validusage-extensions,
    Valid Usage for Extensions>>, <<fundamentals-validusage-versions, Valid
    Usage for Newer Core Versions>>, <<initialization-functionpointers
    Command Function Pointers>>, <<initialization-phys-dev-extensions,
    Extending Physical Device From Device Extensions>>
    <<extended-functionality-instance-extensions-and-devices, Instance
    Extensions and Device Extensions>> sections and for
    flink:vkGetPhysicalDeviceImageFormatProperties2. This documents that
    instance-level functionality is tied to the loader, and independent of
    the ICD; physical device-level functionality is tied to the ICD, and
    associated with device extensions; physical devices are treated more
    uniformly between core and extensions; and instance and physical
    versions can be different (internal issue 1048).
  * Updated the <<commandbuffers-lifecycle, Command Buffer Lifecycle>>
    section to clarify the ability for pending command buffers to transition
    to the invalid state after submission, and add a command buffer
    lifecycle diagram (internal issue 1050).
  * Clarify that some flink:VkDescriptorUpdateTemplateCreateInfo parameters
    are ignored when push descriptors are not supported (internal issue
    1054).
  * Specify that flink:vkCreateImage will return an error if the image is
    too large, in a NOTE in the slink:VkImageFormatProperties description
    (internal issue 1078).
  * Remove near-duplicate NOTEs about when to query function pointers
    dynamically in the <<initialization, Initialization>> chapter and
    replace by extending the NOTE in the <<fundamentals-abi, Application
    Binary Interface>> section (internal issue 1085).
  * Restore missing references to "`Sparse Resource Features`" in the
    flink:VkBufferCreateFlagBits description (internal issue 1086).
  * Tidy up definitions of descriptor types in the `GL_KHR_vulkan_glsl`
    specification, the <<descriptorsets, Resource Descriptors>> section and
    its subsections, and the <<interfaces-resources-descset, Descriptor Set
    Interface>> for consistency, reduction of duplicate information, and
    removal of GLSL correspondance/examples (internal issue 1090).
  * Correctly describe code:PrimitiveId as an Input for tessellation control
    and evaluation shaders, not an Output (internal issue 1109).
  * Relax the requirements on chroma offsets for nearest filtering in
    <<textures-implict-reconstruction, Implicit Reconstruction>> (internal
    issue 1116).

Other Issues:

  * Clarify the intended relationship between specification language and
    certain terms defined in the Khronos Intellectual Property Rights
    policy. Specific changes include:
  ** Rewrote IP/Copyright preamble and introduction to better agree with
     normative language both as laid out in the introduction, and the
     Khronos IPR policy.
  ** Added notion of fully informative sections, which are now tagged with
     "`(Informative)`" in their titles.
  ** Removed non-normative uses of the phrase "`not required`"
  ** Clarified the distinction between terms "`optional`" and "`not
     required:`" as they relate to the IPR Policy, and updated specification
     text to use terms consistent with the intent.
  ** Reduced additions to RFC 2119, and ensured the specification agreed
     with the leaner language.
  ** Removed the terms "`hardware`", "`software`", "`CPU`", and "`GPU`" from
     normative text.
  ** Moved several paragraphs that should not have been normative to
     informative notes.
  ** Clarified a number of definitions in the Glossary.
  ** Updated the document writing guide to match new terminology changes.
  * Explicitly state in the <<fundamentals-objectmodel-lifetime-acquire,
    application memory lifetime>> language that that for objects other than
    descriptor sets, a slink:VkDescriptorSetLayout object used in the
    creation of another object (such as slink:VkPipelineLayout or
    slink:VkDescriptorUpdateTemplateKHR) is only in use during the creation
    of that object and can be safely destroyed afterwards.
  * Updated the <<textures-scale-factor, Scale Factor Operation>> section to
    use the ratio of anisotropy, rather than the integer sample rate, to
    perform the LOD calculation. The spec still allows use of the sample
    rate as the value used to calculate the LOD, but no longer requires it.
  * Update `vulkan_ext.c` to include all platform-related definitions from
    the Vulkan platform headers, following the split of the headers into
    platform-specific and non-platform-specific files.
  * Fix bogus anchor name in the <<commandbuffers, Command Buffers>> chapter
    which accidentally duplicated an anchor in the pipelines chapter. There
    were no reference to this anchor, fortunately.
  * Add valid usage statement for slink:VkWriteDescriptorSet and
    slink:VkCopyDescriptorSet requiring that the slink:VkDescriptorSetLayout
    used to allocate the source and destination sets must not have been
    destroyed at the time flink:vkUpdateDescriptorSets is called.
  * Document mapping of subgroup barrier functions to SPIR-V, and clarify a
    place where subgroupBarrier sounds like it's execution-only in the
    standalone `GL_KHR_shader_subgroup` specification.
  * Use an HTML stylesheet derived from the Asciidoctor `colony` theme, with
    the default Arial font family replaced by the sans-serif Noto font
    family.
  * Numerous minor updates to README.adoc, build scripts, Makefiles, and
    registry and style guide specifications to support Vulkan 1.1 outputs,
    use them as defaults, and remove mention of `KHX` extensions, which are
    no longer supported.

New Extensions:

  * `VK_EXT_vertex_attrib_divisor`
This commit is contained in:
Jon Leech 2018-03-07 04:18:52 -08:00
parent ab08f0951e
commit ce60b9c887
201 changed files with 57051 additions and 52550 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

164
ChangeLog.txt
View File

@ -8,6 +8,170 @@ public pull requests that have been accepted.
-----------------------------------------------------
Change log for March 7, 2018 Vulkan 1.1.70 spec update:
* Vulkan 1.1 initial release. Bump API patch number and header version
number to 70 for this update. The patch number will be used for both
Vulkan 1.1 and Vulkan 1.0 updates, and continues to increment
continuously from the previous Vulkan 1.0.69 update.
NOTE: We are not publishing an updated 1.0.70 specification, or 1.1
reference pages, along with 1.1.70. There are still minor issues to work
out with those build targets. However, we will soon generate all three
types of documents as part of the regular spec update cycle.
NOTE: The GitHub KhronosGroup/Vulkan-Docs repository now maintains the
current specification in the `master` branch. The `1.0` branch is out of
date and will not be maintained, since we will be generating both 1.1
and 1.0 specifications from the `master` branch in the future.
Github Issues:
* Clarify how mapped memory ranges are flushed in
flink:vkFlushMappedMemoryRanges (public issue 127).
* Specify that <<synchronization-pipeline-stages, Pipeline Stages>> are a
list of tasks that each command performs, rather than necessarily being
discrete pieces of hardware that one task flows through. Add a
"`synchronization command`" pipeline type which all synchronization
command execute (it's just TOP + BOTTOM), with an explanatory note
(public issue 554).
Internal Issues:
* Regenerate all images used in the spec in Inkscape with a consistent
look-and-feel, and adjust image size attributes so they're all legible,
and not too large with respect to the spec body text (internal issue
701).
* Document in the <<extensions,extensions>> appendix and in the style
guide that `KHX` extensions are no longer supported or used in the
Vulkan 1.1 timeframe (internal issue 714).
* Remove the leftover equations_temp directory after PDF build completes
(internal issue 925).
* Update the <<credits, Credits (Informative)>> appendix to include
contributors to Vulkan 1.1, and to list them according to the API
version(s) they contributed to (internal issue 987).
* Add a NOTE to the introduction explaining that interfaces defined by
extensions which were promoted to Vulkan 1.1 are now expressed as
aliases of the Vulkan 1.1 type (internal issue 991).
* Instrument spec source conditionals so spec can be built with 1.1
features, extensions promoted to 1.1, or both (internal issues 992,
998).
* Modify the XML schema and tools to support explicit aliasing of types,
structures, and commands, and use this to express the promotion of 1.0
extensions to 1.1 core features, by making the extension interfaces
aliases of the core features they were promoted to. Mark up promoted
interfaces to allow still generating 1.0 + extension specifications
(internal issue 991).
* Platform names, along with corresponding preprocessor symbols to enable
extensions specific to those platforms, are now reserved in vk.xml using
the <platform> tag. Update the registry schema and schema specification
to match (internal issue 1011).
* Updated the <<textures-texel-replacement, Texel Replacement>> section to
clarify that reads from invalid texels for image resources result in
undefined values (internal issue 1014).
* Modify description of patch version so it continues to increment across
minor version changes (internal issue 1033).
* Clarify and unify language describing physical device-level core and
extension functionality in the <<fundamentals-validusage-extensions,
Valid Usage for Extensions>>, <<fundamentals-validusage-versions, Valid
Usage for Newer Core Versions>>, <<initialization-functionpointers
Command Function Pointers>>, <<initialization-phys-dev-extensions,
Extending Physical Device From Device Extensions>>
<<extended-functionality-instance-extensions-and-devices, Instance
Extensions and Device Extensions>> sections and for
flink:vkGetPhysicalDeviceImageFormatProperties2. This documents that
instance-level functionality is tied to the loader, and independent of
the ICD; physical device-level functionality is tied to the ICD, and
associated with device extensions; physical devices are treated more
uniformly between core and extensions; and instance and physical
versions can be different (internal issue 1048).
* Updated the <<commandbuffers-lifecycle, Command Buffer Lifecycle>>
section to clarify the ability for pending command buffers to transition
to the invalid state after submission, and add a command buffer
lifecycle diagram (internal issue 1050).
* Clarify that some flink:VkDescriptorUpdateTemplateCreateInfo parameters
are ignored when push descriptors are not supported (internal issue
1054).
* Specify that flink:vkCreateImage will return an error if the image is
too large, in a NOTE in the slink:VkImageFormatProperties description
(internal issue 1078).
* Remove near-duplicate NOTEs about when to query function pointers
dynamically in the <<initialization, Initialization>> chapter and
replace by extending the NOTE in the <<fundamentals-abi, Application
Binary Interface>> section (internal issue 1085).
* Restore missing references to "`Sparse Resource Features`" in the
flink:VkBufferCreateFlagBits description (internal issue 1086).
* Tidy up definitions of descriptor types in the `GL_KHR_vulkan_glsl`
specification, the <<descriptorsets, Resource Descriptors>> section and
its subsections, and the <<interfaces-resources-descset, Descriptor Set
Interface>> for consistency, reduction of duplicate information, and
removal of GLSL correspondance/examples (internal issue 1090).
* Correctly describe code:PrimitiveId as an Input for tessellation control
and evaluation shaders, not an Output (internal issue 1109).
* Relax the requirements on chroma offsets for nearest filtering in
<<textures-implict-reconstruction, Implicit Reconstruction>> (internal
issue 1116).
Other Issues:
* Clarify the intended relationship between specification language and
certain terms defined in the Khronos Intellectual Property Rights
policy. Specific changes include:
** Rewrote IP/Copyright preamble and introduction to better agree with
normative language both as laid out in the introduction, and the
Khronos IPR policy.
** Added notion of fully informative sections, which are now tagged with
"`(Informative)`" in their titles.
** Removed non-normative uses of the phrase "`not required`"
** Clarified the distinction between terms "`optional`" and "`not
required:`" as they relate to the IPR Policy, and updated specification
text to use terms consistent with the intent.
** Reduced additions to RFC 2119, and ensured the specification agreed
with the leaner language.
** Removed the terms "`hardware`", "`software`", "`CPU`", and "`GPU`" from
normative text.
** Moved several paragraphs that should not have been normative to
informative notes.
** Clarified a number of definitions in the Glossary.
** Updated the document writing guide to match new terminology changes.
* Explicitly state in the <<fundamentals-objectmodel-lifetime-acquire,
application memory lifetime>> language that that for objects other than
descriptor sets, a slink:VkDescriptorSetLayout object used in the
creation of another object (such as slink:VkPipelineLayout or
slink:VkDescriptorUpdateTemplateKHR) is only in use during the creation
of that object and can be safely destroyed afterwards.
* Updated the <<textures-scale-factor, Scale Factor Operation>> section to
use the ratio of anisotropy, rather than the integer sample rate, to
perform the LOD calculation. The spec still allows use of the sample
rate as the value used to calculate the LOD, but no longer requires it.
* Update `vulkan_ext.c` to include all platform-related definitions from
the Vulkan platform headers, following the split of the headers into
platform-specific and non-platform-specific files.
* Fix bogus anchor name in the <<commandbuffers, Command Buffers>> chapter
which accidentally duplicated an anchor in the pipelines chapter. There
were no reference to this anchor, fortunately.
* Add valid usage statement for slink:VkWriteDescriptorSet and
slink:VkCopyDescriptorSet requiring that the slink:VkDescriptorSetLayout
used to allocate the source and destination sets must not have been
destroyed at the time flink:vkUpdateDescriptorSets is called.
* Document mapping of subgroup barrier functions to SPIR-V, and clarify a
place where subgroupBarrier sounds like it's execution-only in the
standalone `GL_KHR_shader_subgroup` specification.
* Use an HTML stylesheet derived from the Asciidoctor `colony` theme, with
the default Arial font family replaced by the sans-serif Noto font
family.
* Numerous minor updates to README.adoc, build scripts, Makefiles, and
registry and style guide specifications to support Vulkan 1.1 outputs,
use them as defaults, and remove mention of `KHX` extensions, which are
no longer supported.
New Extensions:
* `VK_EXT_vertex_attrib_divisor`
-----------------------------------------------------
Change log for February 19, 2018 Vulkan 1.0.69 spec update:
* Bump API patch number and header version number to 69 for this update.

65
README.adoc
View File

@ -1,20 +1,31 @@
Vulkan^(R)^ API Documentation Project
=====================================
= 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.
includes the Specification of the Vulkan API, including extensions; the
reference ("`man`") pages; the XML API Registry; header files; and related
tools and scripts.
Single-Branch Model
-------------------
The authoritative public repository is located at
https://github.com/KhronosGroup/Vulkan-Docs/ . Issues, proposed fixes for
issues, and other suggested changes should be created using Github.
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
--------------------
== Branch Structure
With the release of Vulkan 1.1, the current Specification is now maintained
in the `master` branch of the repository. It is possible to generate both
Vulkan 1.1 and Vulkan 1.0 Specifications from this branch.
=== `1.0` Branch Is Obsolete
The `1.0` branch in which the 1.0 Specification was previously maintained is
now obsolete. The `1.0` branch will not be updated going forward, and all
outstanding pull requests or merge requests against the `1.0` branch must be
rebased on, and retargeted to `master`.
== Directory Structure
```
README.adoc This file
@ -26,28 +37,30 @@ doc/specs/ Main documentation tree
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
src/ext_loader/ Extension loader library
```
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.
== Building the Specification and Reference Pages
Generating Headers and Related Files
------------------------------------
The document sources are marked up in `asciidoctor` format, and we use
asciidoctor and related toolchain components to generate output documents.
See `doc/specs/vulkan/README.adoc` for more information on installing the
toolchain and building the Specification.
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
== Generating Headers and Related Files
The header files (`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 header files, are not checked into the repository. If you
change `vk.xml`, you can regenerate the header by going to `src/spec` and
running:
$ make clean install
The other generated files are built as required via dependencies in
`doc/specs/vulkan/Makefile` .

41
doc/specs/vulkan/Makefile
View File

@ -14,6 +14,13 @@
# Vulkan Specification makefile
#
# To build the spec with a specific version included, set the
# $(VERSIONS) variable on the make command line to a space-separated
# list of version names (e.g. VK_VERSION_1_1) *including all previous
# versions of the API* (e.g. VK_VERSION_1_1 must also include
# VK_VERSION_1_0). $(VERSIONS) is converted into asciidoc and generator
# script arguments $(VERSIONATTRIBS) and $(VERSIONOPTIONS)
#
# To build the specification and reference pages with optional
# extensions included, set the $(EXTENSIONS) variable on the make
# command line to a space-separated list of extension names. The
@ -27,6 +34,10 @@
# runs of `make`.
.DELETE_ON_ERROR:
VERSIONS := VK_VERSION_1_0 VK_VERSION_1_1
VERSIONATTRIBS := $(foreach version,$(VERSIONS),-a $(version))
VERSIONOPTIONS := $(foreach version,$(VERSIONS),-feature $(version))
EXTS := $(sort VK_KHR_sampler_mirror_clamp_to_edge $(EXTENSIONS) $(DIFFEXTENSIONS))
EXTATTRIBS := $(foreach ext,$(EXTS),-a $(ext))
EXTOPTIONS := $(foreach ext,$(EXTS),-extension $(ext))
@ -86,13 +97,22 @@ PDFMATHDIR:=$(OUTDIR)/equations_temp
VERBOSE =
# asciidoc attributes to set.
# PATCHVERSION must == VK_HEADER_VERSION from vk.xml / vulkan_core.h
# NOTEOPTS sets options controlling which NOTEs are generated
# ATTRIBOPTS sets the api revision and enables MathJax generation
# VERSIONATTRIBS sets attributes for enabled API versions (set above
# based on $(VERSIONS))
# EXTATTRIBS sets attributes for enabled extensions (set above based on
# $(EXTENSIONS))
# ADOCOPTS options for asciidoc->HTML5 output
NOTEOPTS = -a editing-notes -a implementation-guide
SPECREVISION = 1.0.69
PATCHVERSION = 70
ifneq (,$(findstring VK_VERSION_1_1,$(VERSIONS)))
SPECREVISION = 1.1.$(PATCHVERSION)
else
SPECREVISION = 1.0.$(PATCHVERSION)
endif
# Spell out ISO 8601 format as not all date commands support --rfc-3339
SPECDATE = $(shell echo `date -u "+%Y-%m-%d %TZ"`)
@ -111,6 +131,7 @@ ATTRIBOPTS = -a revnumber="$(SPECREVISION)" \
-a revremark="$(SPECREMARK)" \
-a apititle="$(APITITLE)" \
-a stem=latexmath \
$(VERSIONATTRIBS) \
$(EXTATTRIBS)
ADOCEXTS = -r $(CURDIR)/config/vulkan-macros.rb -r $(CURDIR)/config/tilde_open_block.rb
@ -118,10 +139,14 @@ ADOCOPTS = -d book $(ATTRIBOPTS) $(NOTEOPTS) $(VERBOSE) $(ADOCEXTS)
ADOCHTMLEXTS = -r $(CURDIR)/config/katex_replace.rb
# ADOCHTMLOPTS relies on the relative KATEXDIR path being set correctly
# for each target using the variable.
# ADOCHTMLOPTS relies on the relative runtime path from the output HTML
# file to the katex scripts being set with KATEXDIR. This is overridden
# by some targets.
# ADOCHTMLOPTS also relies on the absolute build-time path to the
# 'stylesdir' containing our custom CSS.
KATEXDIR = katex
ADOCHTMLOPTS = $(ADOCHTMLEXTS) -a katexpath=$(KATEXDIR)
ADOCHTMLOPTS = $(ADOCHTMLEXTS) -a katexpath=$(KATEXDIR) \
-a stylesheet=khronos.css -a stylesdir=$(CURDIR)/config
ADOCPDFEXTS = -r asciidoctor-pdf -r asciidoctor-mathematical -r $(CURDIR)/config/asciidoctor-mathematical-ext.rb
ADOCPDFOPTS = $(ADOCPDFEXTS) -a mathematical-format=svg \
@ -188,6 +213,7 @@ else
$(QUIET)rm $@
$(QUIET)mv $(PDFDIR)/vkspec-optimized.pdf $@
endif
$(QUIET)rm -rf $(PDFMATHDIR)
validusage: $(VUDIR)/validusage.json $(SPECSRC) $(COMMONDOCS)
@ -282,7 +308,7 @@ MANCOPYRIGHT = $(MANDIR)/copyright-ccby.txt $(MANDIR)/footer.txt
#
# @@ Needs to pass in $(EXTOPTIONS) and use that to determine which
# pages to generate. As it stands, all the extension ref pages are
# also generated, though they are not useable at present.
# also generated, though they are not usable at present.
LOGFILE = man/logfile
man/apispec.txt: $(SPECFILES) genRef.py reflib.py vkapi.py
@ -375,13 +401,16 @@ checklinks: vkapi.py
# validity/timeMarker - proxy for API validity include files under validity/*/*.txt
# appendices/meta/timeMarker - proxy for extension appendix metadata include files under appendices/*.txt
#
# $(VERSIONOPTIONS) specifies the core API versions which are included
# in these targets, and is set above based on $(VERSIONS)
#
# $(EXTOPTIONS) specifies the extensions which are included in these
# targets, and is set above based on $(EXTENSIONS).
REGISTRY = ../../../src/spec
VKXML = $(REGISTRY)/vk.xml
GENVK = $(REGISTRY)/genvk.py
GENVKOPTS= $(EXTOPTIONS) -registry $(VKXML)
GENVKOPTS= $(VERSIONOPTIONS) $(EXTOPTIONS) -registry $(VKXML)
vkapi.py: $(VKXML) $(GENVK)
$(PYTHON) $(GENVK) $(GENVKOPTS) -o . vkapi.py

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

@ -1,6 +1,6 @@
= Vulkan^(R)^ Specification Build Instructions and Notes
:toc2:
:toclevels: 1
:toclevels: 2
[[intro]]
@ -16,13 +16,28 @@ specification and reference pages building properly.
Once you have all the right tools installed (see <<depends,Software
Dependencies>> below), go to `...path-to-git-repo/doc/specs/vulkan` .
$ make html
builds an HTML5 specification output.
$ make all
or make the individual targets `html`, `pdf`, `styleguide`, `manhtml`,
`manpdf`, `manhtmlpages`, `checkinc`, and `checklinks`.
builds the spec targets `html`, `pdf`, `styleguide`, `manhtml`, `manpdf`,
`manhtmlpages`, `checkinc`, and `checklinks`.
NOTE: The `validusage` target is not built as part of `make all`, due to it
needing to be built with all extensions - it will fail without.
[NOTE]
.Notes
====
* `make all` takes a long time to run, and generates outputs that are
irrelevant for most users.
Usually `make html` is used to update the HTML target, which is all
that's needed for quick verification and viewing of changes.
* The default `make` options build a Vulkan 1.1 specification with no
optional extensions.
* The `validusage` target is not built as part of `make all`, due to it
needing to be built with all extensions enabled. Building this target
will fail otherwise.
====
These targets generate a variety of output documents in the directory
specified by the Makefile variable `$(OUTDIR)` (by default,
@ -31,7 +46,7 @@ The checked-in file `../../../out/1.0/index.html` links to all these
targets, or they can individually be found as follows:
* API spec:
** `html` - Single-file HTML5 in `$(OUTDIR)/html/vkspec.html`
** `html` - HTML5 in `$(OUTDIR)/html/vkspec.html`
** `pdf` - PDF in `$(OUTDIR)/pdf/vkspec.pdf`
* "`Vulkan Documentation and Extensions`" guide:
** `styleguide` - Single-file HTML5 in `$(OUTDIR)/styleguide.html`
@ -75,6 +90,21 @@ then try <<ruby-enum-downgrade,downgrading ruby-enum>>
as described below
[[building-versions]]
=== Building Specifications For Different API Versions
The `Makefile` defaults to building a Vulkan 1.1 specification.
This is controlled by asciidoc attributes passed in the Makefile variable
`$(VERSIONS)`
To instead build a Vulkan 1.0 specification, pass
----
VERSIONS="VK_VERSION_1_0"
----
on the `make` command line.
[[building-extensions]]
=== Building With Extensions Included
@ -94,44 +124,49 @@ generated files depends on `$(EXTENSIONS)`.
There are several helper scripts which clean these files and then build one
or more specified targets for specified extensions:
* `makeExt` - generate outputs with a single extension enabled.
Usage is `makeExt extension-name target(s)`, where `extension-name` is
the extension name string, such as `VK_EXT_debug_report`.
* `makeExt` - generate outputs with one or more extensions enabled.
Usage is `makeExt extension-names target(s)`, where `extension-names` is
a space-separated list of extension names, such as
`VK_EXT_debug_report`.
If more than one extension is specified, `extension-names` must be
quoted on the command line.
* `makeKHR` - generate outputs with all Khronos (`VK_KHR_*`) extensions
enabled.
Usage is `makeKHR target(s)`.
* `makeKHRAndKHX` - generate outputs with all Khronos (`VK_KHR_*`) and
Khronox Experimental (`VK_KHX_*`) extensions enabled.
Usage is `makeKHRAndKHX target(s)`.
The `target(s)` passed to these scripts are arbitrary `make` options, and
can be used to set Makefile variables and options, as well as specify actual
build targets.
The Makefile variable `$(APITITLE)` defines an additional string which is
appended to the specification title.
When building with extensions enabled, this should be set to something like
`(with extension VK_extension_name)`.
The `makeExt`, `makeKHR`, and `makeKHRAndKHX` scripts already do this.
The `makeExt` and `makeKHR` scripts already do this.
[[building-diff]]
==== Building A Highlighted Extension Diff
The "diff_html" target in the makefile can be used to generate a version of
The `diff_html` target in the makefile can be used to generate a version of
the specification which highlights changes made to the specification by the
inclusion of a particular set of extensions.
Extensions in the "EXTENSIONS" attribute defines the base extensions to be
enabled by the specification, and these will not be highlighted in the
output.
Extensions in the "DIFFEXTENSIONS" attribute defines the set of extensions
whose changes to the text will be highlighted when they are enabled.
Any extensions in both environment variables will be treated as if they were
only included in DIFFEXTENSIONS.
The DIFFEXTENSIONS environment variable can be used alongside the make*
scripts in this repository.
Extensions in the Makefile variable `$(EXTENSIONS)` define the base
extensions to be enabled by the specification, and these will not be
highlighted in the output.
Extensions in the Makefile variable `$(DIFFEXTENSIONS)` define the set of
extensions whose changes to the text will be highlighted when they are
enabled.
Any extensions in both variables will be treated as if they were only
included in `$(DIFFEXTENSIONS)`.
`$(DIFFEXTENSIONS)` can be set when using the `make*` scripts described
above.
In the resulting html document, content that has been added by one of the
In the resulting HTML document, content that has been added by one of the
extensions will be highlighted with a lime background, and content that was
removed will be highlighted with a pink background.
Each section has an anchor of "#differenceN", with an arrow (=>) at the end
Each section has an anchor of `"#differenceN"`, with an arrow (=>) at the end
of each section which links to the next difference section.
The first diff section is "difference1".
@ -145,27 +180,25 @@ The asciidoctor HTML build is very fast, even for the whole Specification,
but PDF builds take several minutes.
=== Rebuilding The Generated Images
=== Images Used In The Specification
There are some images in the `images/` directory which are maintained in one
format but need to be converted to another format for corresponding types of
output.
Most are SVG converted to PDF, some are PPT converted to PDF converted to
SVG.
SVG are needed by all builds.
These files are not automatically converted by the Makefile.
Instead, all output forms required are checked into `images/` .
On the rare occasions that someone changes a source document and needs to
regenerate the other forms:
----
cd images ; make
----
All images used in the specification are in the `images/` directory in SVG
format, and were created with Inkscape.
We recommend using Inkscape to modify or create new images, as we've had
problems using SVG files created by some other tools, especially in the PDF
builds.
=== Validation Scripts
[NOTE]
.Note
====
The validation scripts have not been kept up to date, and probably don't
work properly at present due to numerous changes in the macro and
conditional markup used in the specification sources.
====
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` :
@ -195,8 +228,6 @@ report problematic tags and the filenames/lines on which those tags were
found.
[[macros]]
== Our Asciidoc Macros
@ -255,15 +286,17 @@ them, and build properly.
[[styles]]
== Our stylesheets
NOTE: Section mostly TBD.
We use the default Asciidoctor stylesheet.
We use an HTML stylesheet `config/khronos.css` derived from the
http://asciidoctor.org/docs/produce-custom-themes-using-asciidoctor-stylesheet-factory/[Asciidoctor
stylesheet factory] "`colony`" theme, with the default Arial font family
replaced by the sans-serif https://en.wikipedia.org/wiki/Noto_fonts[Noto
font family].
=== Marking Normative Language
Normative language is marked as *bold*, and also with the [purple]#purple#
role for html output.
role for HTML output.
It can be used to mark entire paragraphs or spans of words.
In addition, the normative terminology macros, such as must: and may: and
cannot:, always use this role.
@ -277,8 +310,12 @@ We may add a way to disable this formatting at build time.
== Imbedding Equations
Where possible, equations should be written using straight asciidoc markup
using the _eq_ role.
with the _eq_ role.
This covers many common equations and is faster than the alternatives.
A variety of mathematical symbols are defined using attributes in the
included `config/attribs.txt`.
These symbols are defined using attribute names the same as the comparable
LaTeX macro names, where possible.
For more complex equations, such as multi-case statements, matrices, and
complex fractions, equations should be written using the latexmath: inline
@ -287,7 +324,7 @@ The contents of the latexmath: blocks should be LaTeX math notation.
LaTeX math markup delimiters are now inserted by the asciidoctor toolchain.
LaTeX math is passed through unmodified to all HTML output forms, which is
subsequently rendered with the KaTeX engine when the html is loaded.
subsequently rendered with the KaTeX engine when the HTML is loaded.
A local copy of the KaTeX release is kept in `doc/specs/vulkan/katex` and
copied to the HTML output directory during spec generation.
Math is processed into SVGs via asciidoctor-mathematical for PDF output.
@ -382,10 +419,10 @@ environment managers below.
Please read the remainder of this document (other than platform-specific
parts you don't use) completely before trying to install.
* Asciidoctor (asciidoctor, version: 1.5.5)
* Coderay (coderay, version 1.1.1)
* JSON Schema (json-schema, version 2.0.0)
* Asciidoctor PDF (asciidoctor-pdf, version: 1.5.0.alpha15)
* Asciidoctor (asciidoctor, version: 1.5.6.1)
* Coderay (coderay, version 1.1.2)
* JSON Schema (json-schema, version 2.8.0)
* Asciidoctor PDF (asciidoctor-pdf, version: 1.5.0.alpha16)
* Asciidoctor Mathematical (asciidoctor-mathematical, version 0.2.2)
* https://github.com/asciidoctor/asciidoctor-mathematical#dependencies[Dependencies
for asciidoctor-mathematical] (There are a lot of these!)
@ -396,10 +433,10 @@ parts you don't use) completely before trying to install.
.Note
[NOTE]
====
Asciidoctor-pdf versions before `1.5.0.alpha15` have issues with multi-page
valid usage blocks, in that the background only renders for the first page.
`alpha.15` fixes this issue (as well as a few others); do not use prior
versions.
Older versions of these packages may work, but are not recommended.
In particular, the latest versions of asciidoctor-pdf and
asciidoctor-mathematical contain important patches working around issues
we've discovered, and those patches may not be present in earlier versions.
====
Only the `asciidoctor` and `coderay` gems are needed if you don't intend to
@ -810,6 +847,7 @@ https://github.com/KhronosGroup/Vulkan-Docs/issues/476
[[history]]
== Revision History
* 2018-03-05 - Update README for Vulkan 1.1 release.
* 2017-03-20 - Add description of prawn versioning problem and how to fix
it.
* 2017-03-06 - Add description of ruby-enum versioning problem and how to

20
doc/specs/vulkan/appendices/VK_AMD_negative_viewport_height.txt
View File

@ -8,9 +8,29 @@ include::meta/VK_AMD_negative_viewport_height.txt[]
- Matthaeus G. Chajdas, AMD
- Graham Sellers, AMD
- Baldur Karlsson
*Interactions and External Dependencies*::
- Deprecated by VK_KHR_maintenance1
- Deprecated by Vulkan 1.1
This extension allows an application to specify a negative viewport height.
The result is that the viewport transformation will flip along the y-axis.
* Allow negative height to be specified in the
slink::VkViewport::pname:height field to perform y-inversion of the
clip-space to framebuffer-space transform.
This allows apps to avoid having to use gl_Position.y = -gl_Position.y
in shaders also targeting other APIs.
=== Deprecation by VK_KHR_maintenance1 and Vulkan 1.1
Functionality in this extension is included in VK_KHR_maintenance1 and
Vulkan 1.1.
Due to some slight behavioral differences, this extension must: not be
enabled alongside VK_KHR_maintenance1, or when the device reports Vulkan 1.1
support.
=== Version History
* Revision 1, 2016-09-02 (Matthaeus Chajdas)
- Initial draft

10
doc/specs/vulkan/appendices/VK_AMD_texture_gather_bias_lod.txt
View File

@ -66,14 +66,14 @@ struct VkTextureLODGatherFormatPropertiesAMD
// ----------------------------------------------------------------------------------------
// How to detect if an image format can be used with the new function prototypes.
VkPhysicalDeviceImageFormatInfo2KHR formatInfo;
VkImageFormatProperties2KHR formatProps;
VkPhysicalDeviceImageFormatInfo2 formatInfo;
VkImageFormatProperties2 formatProps;
VkTextureLODGatherFormatPropertiesAMD textureLODGatherSupport;
textureLODGatherSupport.sType = VK_STRUCTURE_TYPE_TEXTURE_LOD_GATHER_FORMAT_PROPERTIES_AMD;
textureLODGatherSupport.pNext = nullptr;
formatInfo.sType = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_IMAGE_FORMAT_INFO_2_KHR;
formatInfo.sType = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_IMAGE_FORMAT_INFO_2;
formatInfo.pNext = nullptr;
formatInfo.format = ...;
formatInfo.type = ...;
@ -81,10 +81,10 @@ formatInfo.tiling = ...;
formatInfo.usage = ...;
formatInfo.flags = ...;
formatProps.sType = VK_STRUCTURE_TYPE_IMAGE_FORMAT_PROPERTIES_2_KHR;
formatProps.sType = VK_STRUCTURE_TYPE_IMAGE_FORMAT_PROPERTIES_2;
formatProps.pNext = &textureLODGatherSupport;
vkGetPhysicalDeviceImageFormatProperties2KHR(physical_device, &formatInfo, &formatProps);
vkGetPhysicalDeviceImageFormatProperties2(physical_device, &formatInfo, &formatProps);
if (textureLODGatherSupport.supportsTextureGatherLODBiasAMD == VK_TRUE)
{

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

@ -13,7 +13,7 @@ include::meta/VK_EXT_debug_marker.txt[]
The `VK_EXT_debug_marker` extension is a device extension.
It introduces concepts of object naming and tagging, for better tracking of
Vulkan objects, as well as additional commands for recording annotations of
named sections of a workload to aid organisation and offline analysis in
named sections of a workload to aid organization and offline analysis in
external tools.
=== New Object Types

6
doc/specs/vulkan/appendices/VK_EXT_debug_report.txt
View File

@ -1,7 +1,7 @@
include::meta/VK_EXT_debug_report.txt[]
*Last Modified Date*::
2017-04-27
2017-09-12
*IP Status*::
No known IP claims.
*Contributors*::
@ -48,7 +48,6 @@ to the application for events of interest to the application.
* tlink:PFN_vkDebugReportCallbackEXT
=== Examples
`VK_EXT_debug_report` allows an application to register multiple callbacks
@ -212,3 +211,6 @@ could be useful debugging the Vulkan implementation itself.
* Revision 8, 2017-04-21 (Courtney Goeltzenleuchter)
- Remove unused enum VkDebugReportErrorEXT
* Revision 9, 2017-09-12 (Tobias Hector)
- Added interactions with Vulkan 1.1

377
doc/specs/vulkan/appendices/VK_EXT_debug_utils.txt Normal file
View File

@ -0,0 +1,377 @@
include::meta/VK_EXT_debug_utils.txt[]
*Last Modified Date*::
2017-09-14
*Revision*::
1
*IP Status*::
No known IP claims.
*Dependencies*::
- This extension is written against version 1.0 of the Vulkan API.
- Requires elink:VkObjectType
*Contributors*::
- Mark Young, LunarG
- Baldur Karlsson
- Ian Elliott, Google
- Courtney Goeltzenleuchter, Google
- Karl Schultz, LunarG
- Mark Lobodzinski, LunarG
- Mike Schuchardt, LunarG
- Jaakko Konttinen, AMD
- Dan Ginsburg, Valve Software
- Rolando Olivares, Epic Games
- Dan Baker, Oxide Games
- Kyle Spagnoli, NVIDIA
- Jon Ashburn, LunarG
Due to the nature of the Vulkan interface, there is very little error
information available to the developer and application.
By using the `VK_EXT_debug_utils` extension, developers can: obtain more
information.
When combined with validation layers, even more detailed feedback on the
application's use of Vulkan will be provided.
This extension provides the following capabilities:
- The ability to create a debug messenger which will pass along debug
messages to an application supplied callback.
- The ability to identify specific Vulkan objects using a name or tag to
improve tracking.
- The ability to identify specific sections within a sname:VkQueue or
sname:VkCommandBuffer using labels to aid organization and offline
analysis in external tools.
The main difference between this extension and `<<VK_EXT_debug_report>>` and
`<<VK_EXT_debug_marker>>` is that those extensions use
elink:VkDebugReportObjectTypeEXT to identify objects.
This extension uses the core elink:VkObjectType in place of
ename:VkDebugReportObjectTypeEXT.
The primary reason for this move is that no future object type handle
enumeration values will be added to ename:VkDebugReportObjectTypeEXT since
the creation of ename:VkObjectType.
In addition, this extension combines the functionality of both
`<<VK_EXT_debug_report>>` and `<<VK_EXT_debug_marker>>` by allowing object
name and debug markers (now called labels) to be returned to the
application's callback function.
This should assist in clarifying the details of a debug message including:
what objects are involved and potentially which location within a VkQueue or
VkCommandBuffer the message occurred.
=== New Object Types
* slink:VkDebugUtilsMessengerEXT
=== New Enum Constants
* Extending elink:VkStructureType:
** ename:VK_STRUCTURE_TYPE_DEBUG_UTILS_OBJECT_NAME_INFO_EXT
** ename:VK_STRUCTURE_TYPE_DEBUG_UTILS_OBJECT_TAG_INFO_EXT
** ename:VK_STRUCTURE_TYPE_DEBUG_UTILS_LABEL_EXT
** ename:VK_STRUCTURE_TYPE_DEBUG_UTILS_MESSENGER_CALLBACK_DATA_EXT
** ename:VK_STRUCTURE_TYPE_DEBUG_UTILS_MESSENGER_CREATE_INFO_EXT
* Extending elink:VkResult:
** ename:VK_ERROR_VALIDATION_FAILED_EXT
=== New Enums
* elink:VkDebugUtilsMessageSeverityFlagBitsEXT
* elink:VkDebugUtilsMessageTypeFlagBitsEXT
=== New Structures
* slink:VkDebugUtilsObjectNameInfoEXT
* slink:VkDebugUtilsObjectTagInfoEXT
* slink:VkDebugUtilsLabelEXT
* slink:VkDebugUtilsMessengerCallbackDataEXT
* slink:VkDebugUtilsMessengerCreateInfoEXT
=== New Functions
* flink:vkSetDebugUtilsObjectNameEXT
* flink:vkSetDebugUtilsObjectTagEXT
* flink:vkQueueBeginDebugUtilsLabelEXT
* flink:vkQueueEndDebugUtilsLabelEXT
* flink:vkQueueInsertDebugUtilsLabelEXT
* flink:vkCmdBeginDebugUtilsLabelEXT
* flink:vkCmdEndDebugUtilsLabelEXT
* flink:vkCmdInsertDebugUtilsLabelEXT
* flink:vkCreateDebugUtilsMessengerEXT
* flink:vkDestroyDebugUtilsMessengerEXT
* flink:vkSubmitDebugUtilsMessageEXT
=== New Function Pointers
* tlink:PFN_vkDebugUtilsMessengerCallbackEXT
=== Examples
**Example 1**
`VK_EXT_debug_utils` allows an application to register multiple callbacks
with any Vulkan component wishing to report debug information.
Some callbacks may log the information to a file, others may cause a debug
break point or other application defined behavior.
An application can: register callbacks even when no validation layers are
enabled, but they will only be called for loader and, if implemented, driver
events.
To capture events that occur while creating or destroying an instance an
application can: link a slink:VkDebugUtilsMessengerCreateInfoEXT structure
to the pname:pNext element of the slink:VkInstanceCreateInfo structure given
to flink:vkCreateInstance.
This callback is only valid for the duration of the flink:vkCreateInstance
and the flink:vkDestroyInstance call.
Use flink:vkCreateDebugUtilsMessengerEXT to create persistent callback
objects.
Example uses: Create three callback objects.
One will log errors and warnings to the debug console using Windows
code:OutputDebugString.
The second will cause the debugger to break at that callback when an error
happens and the third will log warnings to stdout.
[source,c++]
------------------------------------------------------------------------------
extern VkInstance instance;
VkResult res;
VkDebugUtilsMessengerEXT cb1, cb2, cb3;
// Must call extension functions through a function pointer:
PFN_vkCreateDebugUtilsMessengerEXT pfnCreateDebugUtilsMessengerEXT = (PFN_vkCreateDebugUtilsMessengerEXT)vkGetDeviceProcAddr(device, "vkCreateDebugUtilsMessengerEXT");
PFN_vkDestroyDebugUtilsMessengerEXT pfnDestroyDebugUtilsMessengerEXT = (PFN_vkDestroyDebugUtilsMessengerEXT)vkGetDeviceProcAddr(device, "vkDestroyDebugUtilsMessengerEXT");
VkDebugUtilsMessengeCreateInfoEXT callback1 = {
VK_STRUCTURE_TYPE_DEBUG_UTILS_MESSENGER_CREATE_INFO_EXT, // sType
NULL, // pNext
0, // flags
VK_DEBUG_UTILS_MESSAGE_SEVERITY_ERROR_BIT_EXT | // messageSeverity
VK_DEBUG_UTILS_MESSAGE_SEVERITY_WARNING_BIT_EXT,
VK_DEBUG_UTILS_MESSAGE_TYPE_GENERAL_BIT_EXT | // messageType
VK_DEBUG_UTILS_MESSAGE_TYPE_VALIDATION_BIT_EXT,
myOutputDebugString, // pfnUserCallback
NULL // pUserData
};
res = pfnCreateDebugUtilsMessengerEXT(instance, &callback1, &cb1);
if (res != VK_SUCCESS) {
// Do error handling for VK_ERROR_OUT_OF_MEMORY
}
callback1.messageSeverity = VK_DEBUG_UTILS_MESSAGE_SEVERITY_ERROR_BIT_EXT;
callback1.pfnCallback = myDebugBreak;
callback1.pUserData = NULL;
res = pfnCreateDebugUtilsMessengerEXT(instance, &callback1, &cb2);
if (res != VK_SUCCESS) {
// Do error handling for VK_ERROR_OUT_OF_MEMORY
}
VkDebugUtilsMessengerCreateInfoEXT callback3 = {
VK_STRUCTURE_TYPE_DEBUG_UTILS_MESSENGER_CREATE_INFO_EXT, // sType
NULL, // pNext
0, // flags
VK_DEBUG_UTILS_MESSAGE_SEVERITY_WARNING_BIT_EXT, // messageSeverity
VK_DEBUG_UTILS_MESSAGE_TYPE_GENERAL_BIT_EXT | // messageType
VK_DEBUG_UTILS_MESSAGE_TYPE_VALIDATION_BIT_EXT,
mystdOutLogger, // pfnUserCallback
NULL // pUserData
};
res = pfnCreateDebugUtilsMessengerEXT(instance, &callback3, &cb3);
if (res != VK_SUCCESS) {
// Do error handling for VK_ERROR_OUT_OF_MEMORY
}
...
// Remove callbacks when cleaning up
pfnDestroyDebugUtilsMessengerEXT(instance, cb1);
pfnDestroyDebugUtilsMessengerEXT(instance, cb2);
pfnDestroyDebugUtilsMessengerEXT(instance, cb3);
------------------------------------------------------------------------------
**Example 2**
Associate a name with an image, for easier debugging in external tools or
with validation layers that can print a friendly name when referring to
objects in error messages.
[source,c++]
----------------------------------------
extern VkDevice device;
extern VkImage image;
// Must call extension functions through a function pointer:
PFN_vkSetDebugUtilsObjectNameEXT pfnSetDebugUtilsObjectNameEXT = (PFN_vkSetDebugUtilsObjectNameEXT)vkGetDeviceProcAddr(device, "vkSetDebugUtilsObjectNameEXT");
// Set a name on the image
const VkDebugUtilsObjectNameInfoEXT imageNameInfo =
{
VK_STRUCTURE_TYPE_DEBUG_UTILS_OBJECT_NAME_INFO_EXT, // sType
NULL, // pNext
VK_OBJECT_TYPE_IMAGE, // objectType
(uint64_t)image, // object
"Brick Diffuse Texture", // pObjectName
};
pfnSetDebugUtilsObjectNameEXT(device, &imageNameInfo);
// A subsequent error might print:
// Image 'Brick Diffuse Texture' (0xc0dec0dedeadbeef) is used in a
// command buffer with no memory bound to it.
----------------------------------------
**Example 3**
Annotating regions of a workload with naming information so that offline
analysis tools can display a more usable visualization of the commands
submitted.
[source,c++]
----------------------------------------
extern VkDevice device;
extern VkCommandBuffer commandBuffer;
// Must call extension functions through a function pointer:
PFN_vkQueueBeginDebugUtilsLabelEXT pfnQueueBeginDebugUtilsLabelEXT = (PFN_vkQueueBeginDebugUtilsLabelEXT)vkGetDeviceProcAddr(device, "vkQueueBeginDebugUtilsLabelEXT");
PFN_vkQueueEndDebugUtilsLabelEXT pfnQueueEndDebugUtilsLabelEXT = (PFN_vkQueueEndDebugUtilsLabelEXT)vkGetDeviceProcAddr(device, "vkQueueEndDebugUtilsLabelEXT");
PFN_vkCmdBeginDebugUtilsLabelEXT pfnCmdBeginDebugUtilsLabelEXT = (PFN_vkCmdBeginDebugUtilsLabelEXT)vkGetDeviceProcAddr(device, "vkCmdBeginDebugUtilsLabelEXT");
PFN_vkCmdEndDebugUtilsLabelEXT pfnCmdEndDebugUtilsLabelEXT = (PFN_vkCmdEndDebugUtilsLabelEXT)vkGetDeviceProcAddr(device, "vkCmdEndDebugUtilsLabelEXT");
PFN_vkCmdInsertDebugUtilsLabelEXT pfnCmdInsertDebugUtilsLabelEXT = (PFN_vkCmdInsertDebugUtilsLabelEXT)vkGetDeviceProcAddr(device, "vkCmdInsertDebugUtilsLabelEXT");
// Describe the area being rendered
const VkDebugUtilsLabelEXT houseLabel =
{
VK_STRUCTURE_TYPE_DEBUG_UTILS_LABEL_EXT, // sType
NULL, // pNext
"Brick House", // pLabelName
{ 1.0f, 0.0f, 0.0f, 1.0f }, // color
};
// Start an annotated group of calls under the 'Brick House' name
pfnCmdBeginDebugUtilsLabelEXT(commandBuffer, &houseLabel);
{
// A mutable structure for each part being rendered
VkDebugUtilsLabelEXT housePartLabel =
{
VK_STRUCTURE_TYPE_DEBUG_UTILS_LABEL_EXT, // sType
NULL, // pNext
NULL, // pLabelName
{ 0.0f, 0.0f, 0.0f, 0.0f }, // color
};
// Set the name and insert the marker
housePartLabel.pLabelName = "Walls";
pfnCmdInsertDebugUtilsLabelEXT(commandBuffer, &housePartLabel);
// Insert the drawcall for the walls
vkCmdDrawIndexed(commandBuffer, 1000, 1, 0, 0, 0);
// Insert a recursive region for two sets of windows
housePartLabel.pLabelName = "Windows";
pfnCmdBeginDebugUtilsLabelEXT(commandBuffer, &housePartLabel);
{
vkCmdDrawIndexed(commandBuffer, 75, 6, 1000, 0, 0);
vkCmdDrawIndexed(commandBuffer, 100, 2, 1450, 0, 0);
}
pfnCmdEndDebugUtilsLabelEXT(commandBuffer);
housePartLabel.pLabelName = "Front Door";
pfnCmdInsertDebugUtilsLabelEXT(commandBuffer, &housePartLabel);
vkCmdDrawIndexed(commandBuffer, 350, 1, 1650, 0, 0);
housePartLabel.pLabelName = "Roof";
pfnCmdInsertDebugUtilsLabelEXT(commandBuffer, &housePartLabel);
vkCmdDrawIndexed(commandBuffer, 500, 1, 2000, 0, 0);
}
// End the house annotation started above
pfnCmdEndDebugUtilsLabelEXT(commandBuffer);
// Do other work
vkEndCommandBuffer(commandBuffer);
// Describe the queue being used
const VkDebugUtilsLabelEXT queueLabel =
{
VK_STRUCTURE_TYPE_DEBUG_UTILS_LABEL_EXT, // sType
NULL, // pNext
"Main Render Work", // pLabelName
{ 0.0f, 1.0f, 0.0f, 1.0f }, // color
};
// Identify the queue label region
pfnQueueBeginDebugUtilsLabelEXT(queue, &queueLabel);
// Submit the work for the main render thread
const VkCommandBuffer cmd_bufs[] = {commandBuffer};
VkSubmitInfo submit_info = {.sType = VK_STRUCTURE_TYPE_SUBMIT_INFO,
.pNext = NULL,
.waitSemaphoreCount = 0,
.pWaitSemaphores = NULL,
.pWaitDstStageMask = NULL,
.commandBufferCount = 1,
.pCommandBuffers = cmd_bufs,
.signalSemaphoreCount = 0,
.pSignalSemaphores = NULL};
vkQueueSubmit(queue, 1, &submit_info, fence);
// End the queue label region
pfnQueueEndDebugUtilsLabelEXT(queue);
----------------------------------------
=== Issues
1) Should we just name this extension `VK_EXT_debug_report2`
**RESOLVED**: No.
There is enough additional changes to the structures to break backwards
compatibility.
So, a new name was decided that would not indicate any interaction with the
previous extension.
2) Will validation layers immediately support all the new features.
**RESOLVED**: Not immediately.
As one can imagine, there is a lot of work involved with converting the
validation layer logging over to the new functionality.
Basic logging, as seen in the origin
<<VK_EXT_debug_report,VK_EXT_debug_report>> extension will be made available
immediately.
However, adding the labels and object names will take time.
Since the priority for Khronos at this time is to continue focusing on Valid
Usage statements, it may take a while before the new functionality is fully
exposed.
3) If the validation layers won't expose the new functionality immediately,
then what's the point of this extension?
**RESOLVED**: We needed a replacement for
<<VK_EXT_debug_report,VK_EXT_debug_report>> because the
elink:VkDebugReportObjectTypeEXT enumeration will no longer be updated and
any new objects will need to be debugged using the new functionality
provided by this extension.
4) Should this extension be split into two separate parts (1 extension that
is an instance extension providing the callback functionality, and another
device extension providing the general debug marker and annotation
functionality)?
**RESOLVED**: No, the functionality for this extension is too closely
related.
If we did split up the extension, where would the structures and enums live,
and how would you define that the device behavior in the instance extension
is really only valid if the device extension is enabled, and the
functionality is passed in.
It's cleaner to just define this all as an instance extension, plus it
allows the application to enable all debug functionality provided with one
enable string during flink:vkCreateInstance.
=== Version History
* Revision 1, 2017-09-14 (Mark Young and all listed Contributors)
** Initial draft, based on <<VK_EXT_debug_report,VK_EXT_debug_report>> and
<<VK_EXT_debug_marker,VK_EXT_debug_marker>> in addition to previous
feedback supplied from various companies including Valve, Epic, and
Oxide games.

11
doc/specs/vulkan/appendices/VK_EXT_discard_rectangles.txt
View File

@ -2,6 +2,9 @@ include::meta/VK_EXT_discard_rectangles.txt[]
*Last Modified Date*::
2016-12-22
*Interactions and External Dependencies*::
- Interacts with VK_KHR_device_group
- Interacts with Vulkan 1.1
*Contributors*::
- Daniel Koch, NVIDIA
- Jeff Bolz, NVIDIA
@ -21,9 +24,11 @@ rejected if the fragment is within any of the operational discard rectangles
These discard rectangles operate orthogonally to the existing scissor test
functionality.
If the `<<VK_KHX_device_group>>` extension is enabled the discard rectangles
can be different for each physical device in the device group by specifying
the device mask and setting discard rectangle dynamic state.
ifdef::VK_VERSION_1_1,VK_KHR_device_group[]
The discard rectangles can be different for each physical device in a device
group by specifying the device mask and setting discard rectangle dynamic
state.
endif::VK_VERSION_1_1,VK_KHR_device_group[]
=== New Object Types

87
doc/specs/vulkan/appendices/VK_EXT_vertex_attribute_divisor.txt Normal file
View File

@ -0,0 +1,87 @@
include::meta/VK_EXT_vertex_attribute_divisor.txt[]
*Last Modified Date*::
2018-02-08
*IP Status*::
No known IP claims.
*Contributors*::
- Vikram Kushwaha, NVIDIA
This extension allows instance-rate vertex attributes to be repeated for
certain number of instances instead of advancing for every instance when
instanced rendering is enabled.
=== New Object Types
None.
=== New Enum Constants
Extending elink:VkStructureType:
** ename:VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VERTEX_ATTRIBUTE_DIVISOR_PROPERTIES_EXT
** ename:VK_STRUCTURE_TYPE_PIPELINE_VERTEX_INPUT_DIVISOR_STATE_CREATE_INFO_EXT
=== New Enums
None.
=== New Structures
* Extending slink:VkPipelineVertexInputStateCreateInfo:
** slink:VkPipelineVertexInputDivisorStateCreateInfoEXT
* slink:VkPhysicalDeviceVertexAttributeDivisorPropertiesEXT
* slink:VkVertexInputBindingDivisorDescriptionEXT
=== New Functions
None.
=== Issues
None.
=== Examples
To create a vertex binding such that the first binding uses instanced rendering and
the same attribute is used for every 4 draw instances, an application could use the
following set of structures:
[source,c++]
----------------------------------------
const VkVertexInputBindingDivisorDescriptionEXT divisorDesc =
{
0,
4
};
const VkPipelineVertexInputDivisorStateCreateInfoEXT divisorInfo =
{
VK_STRUCTURE_TYPE_PIPELINE_VERTEX_INPUT_DIVISOR_STATE_CREATE_INFO_EXT, // sType
NULL, // pNext
1, // vertexBindingDivisorCount
&divisorDesc // pVertexBindingDivisors
}
const VkVertexInputBindingDescription binding =
{
0, // binding
sizeof(Vertex), // stride
VK_VERTEX_INPUT_RATE_INSTANCE // inputRate
};
const VkPipelineVertexInputStateCreateInfo viInfo =
{
VK_STRUCTURE_TYPE_PIPELINE_VERTEX_INPUT_CREATE_INFO, // sType
&divisorInfo, // pNext
...
};
//...
----------------------------------------
=== Version History
* Revision 1, 2017-12-04 (Vikram Kushwaha)
- First Version

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

@ -10,7 +10,7 @@ to Vulkan, using a Catmull-Rom bicubic filter.
Performing this kind of filtering can be done in a shader by using 16
samples and a number of instructions, but this can be inefficient.
The cubic filter mode exposes an optimized high quality texture sampling
using fixed texture sampling hardware.
using fixed texture sampling functionality.
=== New Enum Constants

16
doc/specs/vulkan/appendices/VK_KHR_16bit_storage.txt
View File

@ -4,13 +4,14 @@
include::meta/VK_KHR_16bit_storage.txt[]
*Last Modified Date*::
2017-09-05
*IP Status*::
No known IP claims.
*Interactions and External Dependencies*::
- This extension requires
https://www.khronos.org/registry/spir-v/extensions/KHR/SPV_KHR_16bit_storage.html[+SPV_KHR_16bit_storage+]
*Last Modified Date*::
2017-03-23
*IP Status*::
No known IP claims.
- Promoted to Vulkan 1.1 Core
*Contributors*::
- Alexander Galazin, ARM
- Jan-Harald Fredriksen, ARM
@ -47,6 +48,13 @@ assignment and component assignment rules.
* <<spirvenv-capabilities-table-16bitstorage,code:StoragePushConstant16>>
* <<spirvenv-capabilities-table-16bitstorage,code:StorageInputOutput16>>
=== Promotion to Vulkan 1.1
All functionality in this extension is included in core Vulkan 1.1, with the
KHR suffix omitted.
The original type, enum and command names are still available as aliases of
the core functionality.
=== Issues
=== Version History

6
doc/specs/vulkan/appendices/VK_KHR_android_surface.txt
View File

@ -63,9 +63,9 @@ None
physical device (and queue family?) and a specific Android display?
*RESOLVED*: No.
Currently on Android, any GPU is expected to be able to present to the
system compositor, and all queue families must support the necessary image
layout transitions and synchronization operations.
Currently on Android, any physical device is expected to be able to present
to the system compositor, and all queue families must support the necessary
image layout transitions and synchronization operations.
=== Version History

11
doc/specs/vulkan/appendices/VK_KHR_bind_memory2.txt
View File

@ -5,9 +5,11 @@
include::meta/VK_KHR_bind_memory2.txt[]
*Last Modified Date*::
2017-05-19
2017-09-05
*IP Status*::
No known IP claims.
*Interactions and External Dependencies*::
- Promoted to Vulkan 1.1 Core
*Contributors*::
- Jeff Bolz, NVIDIA
- Tobias Hector, Imagination Technologies
@ -55,6 +57,13 @@ None.
None.
=== Promotion to Vulkan 1.1
All functionality in this extension is included in core Vulkan 1.1, with the
KHR suffix omitted.
The original type, enum and command names are still available as aliases of
the core functionality.
=== Issues
None.

28
doc/specs/vulkan/appendices/VK_KHR_dedicated_allocation.txt
View File

@ -5,9 +5,11 @@
include::meta/VK_KHR_dedicated_allocation.txt[]
*Last Modified Date*::
2017-08-07
2017-09-05
*IP Status*::
No known IP claims.
*Interactions and External Dependencies*::
- Promoted to Vulkan 1.1 Core
*Contributors*::
- Jeff Bolz, NVIDIA
- Jason Ekstrand, Intel
@ -22,10 +24,9 @@ allocation, memory aliasing and sparse binding, which could interfere with
some optimizations.
Applications should query the implementation for when a dedicated allocation
may: be beneficial by adding sname:VkMemoryDedicatedRequirementsKHR to the
pname:pNext chain of the sname:VkMemoryRequirements2KHR structure passed as
the pname:pMemoryRequirements parameter to a call to
fname:vkGetBufferMemoryRequirements2KHR or
fname:vkGetImageMemoryRequirements2KHR.
pname:pNext chain of the sname:VkMemoryRequirements2 structure passed as the
pname:pMemoryRequirements parameter to a call to
fname:vkGetBufferMemoryRequirements2 or fname:vkGetImageMemoryRequirements2.
Certain external handle types and external images or buffers may: also
depend on dedicated allocations on implementations that associate image or
buffer metadata with OS-level memory objects.
@ -58,6 +59,13 @@ None.
None.
=== Promotion to Vulkan 1.1
All functionality in this extension is included in core Vulkan 1.1, with the
KHR suffix omitted.
The original type, enum and command names are still available as aliases of
the core functionality.
=== Issues
None.
@ -88,20 +96,20 @@ None.
NULL, // pNext
};
VkMemoryRequirements2KHR memoryRequirements =
VkMemoryRequirements2 memoryRequirements =
{
VK_STRUCTURE_TYPE_MEMORY_REQUIREMENTS_2_KHR,
VK_STRUCTURE_TYPE_MEMORY_REQUIREMENTS_2,
&dedicatedRequirements, // pNext
};
const VkImageMemoryRequirementsInfo2KHR imageRequirementsInfo =
const VkImageMemoryRequirementsInfo2 imageRequirementsInfo =
{
VK_STRUCTURE_TYPE_IMAGE_MEMORY_REQUIREMENTS_INFO_2_KHR,
VK_STRUCTURE_TYPE_IMAGE_MEMORY_REQUIREMENTS_INFO_2,
NULL, // pNext
image
};
vkGetImageMemoryRequirements2KHR(
vkGetImageMemoryRequirements2(
device,
&imageRequirementsInfo,
&memoryRequirements);

22
doc/specs/vulkan/appendices/VK_KHR_descriptor_update_template.txt
View File

@ -5,11 +5,12 @@
include::meta/VK_KHR_descriptor_update_template.txt[]
*Last Modified Date*::
2016-01-11
2017-09-05
*IP Status*::
No known IP claims.
*Interactions and External Dependencies*::
- Interacts with `<<VK_KHR_push_descriptor>>`
- Promoted to Vulkan 1.1 Core
*Contributors*::
- Jeff Bolz, NVIDIA
- Michael Worcester, Imagination Technologies
@ -49,16 +50,23 @@ Extending elink:VkStructureType:
* flink:vkCreateDescriptorUpdateTemplateKHR
* flink:vkDestroyDescriptorUpdateTemplateKHR
* flink:vkUpdateDescriptorSetWithTemplateKHR
ifdef::VK_KHR_push_descriptor[]
* flink:vkCmdPushDescriptorSetWithTemplateKHR
endif::VK_KHR_push_descriptor[]
=== Examples
=== Promotion to Vulkan 1.1
[source,c++]
----------------------------------------
ifdef::VK_KHR_push_descriptor[]
flink:vkCmdPushDescriptorSetWithTemplateKHR is included as an interaction
with `<<VK_KHR_push_descriptor>>`.
If Vulkan 1.1 and VK_KHR_push_descriptor are supported, this is included by
`<<VK_KHR_push_descriptor>>`.
endif::VK_KHR_push_descriptor[]
// TODO: Write some sample code here.
----------------------------------------
The base functionality in this extension is included in core Vulkan 1.1,
with the KHR suffix omitted.
The original type, enum and command names are still available as aliases of
the core functionality.
=== Version History

161
doc/specs/vulkan/appendices/VK_KHR_device_group.txt Normal file
View File

@ -0,0 +1,161 @@
// Copyright (c) 2016-2018 Khronos Group. This work is licensed under a
// Creative Commons Attribution 4.0 International License; see
// http://creativecommons.org/licenses/by/4.0/
include::meta/VK_KHR_device_group.txt[]
*Last Modified Date*::
2017-10-06
*IP Status*::
No known IP claims.
*Interactions and External Dependencies*::
- Promoted to Vulkan 1.1 Core
*Contributors*::
- Jeff Bolz, NVIDIA
- Tobias Hector, Imagination Technologies
This extension provides functionality to use a logical device that consists
of multiple physical devices, as created with the
`<<VK_KHR_device_group_creation>>` extension.
A device group can allocate memory across the subdevices, bind memory from
one subdevice to a resource on another subdevice, record command buffers
where some work executes on an arbitrary subset of the subdevices, and
potentially present a swapchain image from one or more subdevices.
=== New Object Types
None.
=== New Enum Constants
* Extending elink:VkStructureType:
** ename:VK_STRUCTURE_TYPE_MEMORY_ALLOCATE_FLAGS_INFO_KHR
** ename:VK_STRUCTURE_TYPE_DEVICE_GROUP_RENDER_PASS_BEGIN_INFO_KHR
** ename:VK_STRUCTURE_TYPE_DEVICE_GROUP_COMMAND_BUFFER_BEGIN_INFO_KHR
** ename:VK_STRUCTURE_TYPE_DEVICE_GROUP_SUBMIT_INFO_KHR
** ename:VK_STRUCTURE_TYPE_DEVICE_GROUP_BIND_SPARSE_INFO_KHR
ifdef::VK_KHR_swapchain[]
** ename:VK_STRUCTURE_TYPE_DEVICE_GROUP_PRESENT_CAPABILITIES_KHR
** ename:VK_STRUCTURE_TYPE_IMAGE_SWAPCHAIN_CREATE_INFO_KHR
** ename:VK_STRUCTURE_TYPE_BIND_IMAGE_MEMORY_SWAPCHAIN_INFO_KHR
** ename:VK_STRUCTURE_TYPE_ACQUIRE_NEXT_IMAGE_INFO_KHR
** ename:VK_STRUCTURE_TYPE_DEVICE_GROUP_PRESENT_INFO_KHR
** ename:VK_STRUCTURE_TYPE_DEVICE_GROUP_SWAPCHAIN_CREATE_INFO_KHR
endif::VK_KHR_swapchain[]
** ename:VK_STRUCTURE_TYPE_BIND_BUFFER_MEMORY_DEVICE_GROUP_INFO_KHR
** ename:VK_STRUCTURE_TYPE_BIND_IMAGE_MEMORY_DEVICE_GROUP_INFO_KHR
* Extending elink:VkImageCreateFlagBits
** ename:VK_IMAGE_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT_KHR
* Extending elink:VkPipelineCreateFlagBits
** ename:VK_PIPELINE_CREATE_VIEW_INDEX_FROM_DEVICE_INDEX_BIT_KHR
** ename:VK_PIPELINE_CREATE_DISPATCH_BASE_KHR
* Extending elink:VkDependencyFlagBits
** ename:VK_DEPENDENCY_DEVICE_GROUP_BIT_KHR
ifdef::VK_KHR_swapchain[]
* Extending elink:VkSwapchainCreateFlagBitsKHR
** ename:VK_SWAPCHAIN_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT_KHR
endif::VK_KHR_swapchain[]
=== New Enums
* elink:VkPeerMemoryFeatureFlagBitsKHR
* elink:VkMemoryAllocateFlagBitsKHR
ifdef::VK_KHR_swapchain[]
* elink:VkDeviceGroupPresentModeFlagBitsKHR
endif::VK_KHR_swapchain[]
=== New Structures
* slink:VkMemoryAllocateFlagsInfoKHR
* slink:VkDeviceGroupRenderPassBeginInfoKHR
* slink:VkDeviceGroupCommandBufferBeginInfoKHR
* slink:VkDeviceGroupSubmitInfoKHR
* slink:VkDeviceGroupBindSparseInfoKHR
* slink:VkBindBufferMemoryDeviceGroupInfoKHR
* slink:VkBindImageMemoryDeviceGroupInfoKHR
ifdef::VK_KHR_swapchain[]
* slink:VkDeviceGroupPresentCapabilitiesKHR
* slink:VkImageSwapchainCreateInfoKHR
* slink:VkBindImageMemorySwapchainInfoKHR
* slink:VkAcquireNextImageInfoKHR
* slink:VkDeviceGroupPresentInfoKHR
* slink:VkDeviceGroupSwapchainCreateInfoKHR
endif::VK_KHR_swapchain[]
=== New Functions
* flink:vkGetDeviceGroupPeerMemoryFeaturesKHR
* flink:vkCmdSetDeviceMaskKHR
* flink:vkCmdDispatchBaseKHR
ifdef::VK_KHR_swapchain[]
* flink:vkGetDeviceGroupPresentCapabilitiesKHR
* flink:vkGetDeviceGroupSurfacePresentModesKHR
* flink:vkGetPhysicalDevicePresentRectanglesKHR
* flink:vkAcquireNextImage2KHR
endif::VK_KHR_swapchain[]
=== New Built-In Variables
* <<interfaces-builtin-variables-deviceindex,code:DeviceIndex>>
=== New SPIR-V Capabilities
* <<spirvenv-capabilities,code:DeviceGroup>>
=== Promotion to Vulkan 1.1
ifdef::VK_KHR_swapchain[]
The following enums, types and commands are included as interactions with
`<<VK_KHR_swapchain>>`:
* ename:VK_STRUCTURE_TYPE_DEVICE_GROUP_PRESENT_CAPABILITIES_KHR
* ename:VK_STRUCTURE_TYPE_IMAGE_SWAPCHAIN_CREATE_INFO_KHR
* ename:VK_STRUCTURE_TYPE_BIND_IMAGE_MEMORY_SWAPCHAIN_INFO_KHR
* ename:VK_STRUCTURE_TYPE_ACQUIRE_NEXT_IMAGE_INFO_KHR
* ename:VK_STRUCTURE_TYPE_DEVICE_GROUP_PRESENT_INFO_KHR
* ename:VK_STRUCTURE_TYPE_DEVICE_GROUP_SWAPCHAIN_CREATE_INFO_KHR
* ename:VK_SWAPCHAIN_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT_KHR
* elink:VkDeviceGroupPresentModeFlagBitsKHR
* slink:VkDeviceGroupPresentCapabilitiesKHR
* slink:VkImageSwapchainCreateInfoKHR
* slink:VkBindImageMemorySwapchainInfoKHR
* slink:VkAcquireNextImageInfoKHR
* slink:VkDeviceGroupPresentInfoKHR
* slink:VkDeviceGroupSwapchainCreateInfoKHR
* flink:vkGetDeviceGroupPresentCapabilitiesKHR
* flink:vkGetDeviceGroupSurfacePresentModesKHR
* flink:vkGetPhysicalDevicePresentRectanglesKHR
* flink:vkAcquireNextImage2KHR
If Vulkan 1.1 and VK_KHR_swapchain are supported, these are included by
VK_KHR_swapchain.
endif::VK_KHR_swapchain[]
The base functionality in this extension is included in core Vulkan 1.1,
with the KHR suffix omitted.
The original type, enum and command names are still available as aliases of
the core functionality.
=== Issues
None.
=== Examples
TODO
=== Version History
* Revision 1, 2016-10-19 (Jeff Bolz)
- Internal revisions
* Revision 2, 2017-05-19 (Tobias Hector)
- Removed extended memory bind functions to VK_KHR_bind_memory2, added
dependency on that extension, and device-group-specific structs for
those functions.
* Revision 3, 2017-10-06 (Ian Elliott)
- Corrected Vulkan 1.1 interactions with the WSI extensions.
All Vulkan 1.1 WSI interactions are with the VK_KHR_swapchain
extension.
* Revision 4, 2017-10-10 (Jeff Bolz)
- Rename "SFR" bits and structure members to use the phrase "split
instance bind regions".

35
doc/specs/vulkan/appendices/VK_KHX_device_group_creation.txt → doc/specs/vulkan/appendices/VK_KHR_device_group_creation.txt
View File

@ -2,12 +2,14 @@
// Creative Commons Attribution 4.0 International License; see
// http://creativecommons.org/licenses/by/4.0/
include::meta/VK_KHX_device_group_creation.txt[]
include::meta/VK_KHR_device_group_creation.txt[]
*Last Modified Date*::
2016-10-19
*IP Status*::
No known IP claims.
*Interactions and External Dependencies*::
- Promoted to Vulkan 1.1 Core
*Contributors*::
- Jeff Bolz, NVIDIA
@ -15,7 +17,7 @@ This extension provides instance-level commands to enumerate groups of
physical devices, and to create a logical device from a subset of one of
those groups.
Such a logical device can then be used with new features in the
`<<VK_KHX_device_group>>` extension.
`<<VK_KHR_device_group>>` extension.
=== New Object Types
@ -24,9 +26,9 @@ None.
=== New Enum Constants
* Extending elink:VkStructureType:
** ename:VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_GROUP_PROPERTIES_KHX
** ename:VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_GROUP_PROPERTIES_KHR
* Extending elink:VkMemoryHeapFlagBits
** ename:VK_MEMORY_HEAP_MULTI_INSTANCE_BIT_KHX
** ename:VK_MEMORY_HEAP_MULTI_INSTANCE_BIT_KHR
=== New Enums
@ -35,12 +37,19 @@ None.
=== New Structures
* slink:VkPhysicalDeviceGroupPropertiesKHX
* slink:VkDeviceGroupDeviceCreateInfoKHX
* slink:VkPhysicalDeviceGroupPropertiesKHR
* slink:VkDeviceGroupDeviceCreateInfoKHR
=== New Functions
* flink:vkEnumeratePhysicalDeviceGroupsKHX
* flink:vkEnumeratePhysicalDeviceGroupsKHR
=== Promotion to Vulkan 1.1
All functionality in this extension is included in core Vulkan 1.1, with the
KHR suffix omitted.
The original type, enum and command names are still available as aliases of
the core functionality.
=== Issues
@ -54,22 +63,22 @@ None.
VkDeviceCreateInfo devCreateInfo = { VK_STRUCTURE_TYPE_DEVICE_CREATE_INFO };
// (not shown) fill out devCreateInfo as usual.
uint32_t deviceGroupCount = 0;
VkPhysicalDeviceGroupPropertiesKHX *props = NULL;
VkPhysicalDeviceGroupPropertiesKHR *props = NULL;
// Query the number of device groups
vkEnumeratePhysicalDeviceGroupsKHX(g_vkInstance, &deviceGroupCount, NULL);
vkEnumeratePhysicalDeviceGroupsKHR(g_vkInstance, &deviceGroupCount, NULL);
// Allocate and initialize structures to query the device groups
props = (VkPhysicalDeviceGroupPropertiesKHX *)malloc(deviceGroupCount*sizeof(VkPhysicalDeviceGroupPropertiesKHX));
props = (VkPhysicalDeviceGroupPropertiesKHR *)malloc(deviceGroupCount*sizeof(VkPhysicalDeviceGroupPropertiesKHR));
for (i = 0; i < deviceGroupCount; ++i) {
props[i].sType = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_GROUP_PROPERTIES_KHX;
props[i].sType = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_GROUP_PROPERTIES_KHR;
props[i].pNext = NULL;
}
vkEnumeratePhysicalDeviceGroupsKHX(g_vkInstance, &deviceGroupCount, props);
vkEnumeratePhysicalDeviceGroupsKHR(g_vkInstance, &deviceGroupCount, props);
// If the first device group has more than one physical device. create
// a logical device using all of the physical devices.
VkDeviceGroupDeviceCreateInfoKHX deviceGroupInfo = { VK_STRUCTURE_TYPE_DEVICE_GROUP_DEVICE_CREATE_INFO_KHX };
VkDeviceGroupDeviceCreateInfoKHR deviceGroupInfo = { VK_STRUCTURE_TYPE_DEVICE_GROUP_DEVICE_CREATE_INFO_KHR };
if (props[0].physicalDeviceCount > 1) {
deviceGroupInfo.physicalDeviceCount = props[0].physicalDeviceCount;
deviceGroupInfo.pPhysicalDevices = props[0].physicalDevices;

9
doc/specs/vulkan/appendices/VK_KHR_external_fence.txt
View File

@ -8,6 +8,8 @@ include::meta/VK_KHR_external_fence.txt[]
2017-05-08
*IP Status*::
No known IP claims.
*Interactions and External Dependencies*::
- Promoted to Vulkan 1.1 Core
*Contributors*::
- Jesse Hall, Google
- James Jones, NVIDIA
@ -41,6 +43,13 @@ None.
None.
=== Promotion to Vulkan 1.1
All functionality in this extension is included in core Vulkan 1.1, with the
KHR suffix omitted.
The original type, enum and command names are still available as aliases of
the core functionality.
=== Issues
This extension borrows concepts, semantics, and language from

9
doc/specs/vulkan/appendices/VK_KHR_external_fence_capabilities.txt
View File

@ -8,6 +8,8 @@ include::meta/VK_KHR_external_fence_capabilities.txt[]
2017-05-08
*IP Status*::
No known IP claims.
*Interactions and External Dependencies*::
- Promoted to Vulkan 1.1 Core
*Contributors*::
- Jesse Hall, Google
- James Jones, NVIDIA
@ -48,6 +50,13 @@ None.
* flink:vkGetPhysicalDeviceExternalFencePropertiesKHR
=== Promotion to Vulkan 1.1
All functionality in this extension is included in core Vulkan 1.1, with the
KHR suffix omitted.
The original type, enum and command names are still available as aliases of
the core functionality.
=== Issues
None.

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

@ -11,6 +11,7 @@ include::meta/VK_KHR_external_memory.txt[]
*Interactions and External Dependencies*::
- Interacts with `<<VK_KHR_dedicated_allocation>>`.
- Interacts with `<<VK_NV_dedicated_allocation>>`.
- Promoted to Vulkan 1.1 Core
*Contributors*::
- Jason Ekstrand, Intel
- Ian Elliot, Google
@ -57,6 +58,13 @@ None.
None.
=== Promotion to Vulkan 1.1
All functionality in this extension is included in core Vulkan 1.1, with the
KHR suffix omitted.
The original type, enum and command names are still available as aliases of
the core functionality.
=== Issues
1) How do applications correlate two physical devices across process or

10
doc/specs/vulkan/appendices/VK_KHR_external_memory_capabilities.txt
View File

@ -9,10 +9,9 @@ include::meta/VK_KHR_external_memory_capabilities.txt[]
*IP Status*::
No known IP claims.
*Interactions and External Dependencies*::
- This extension is written against version 1.0 of the Vulkan API.
- Requires `<<VK_KHR_get_physical_device_properties2>>`.
- Interacts with `<<VK_KHR_dedicated_allocation>>`.
- Interacts with `<<VK_NV_dedicated_allocation>>`.
- Promoted to Vulkan 1.1 Core
*Contributors*::
- Ian Elliot, Google
- Jesse Hall, Google
@ -56,6 +55,13 @@ None.
* flink:vkGetPhysicalDeviceExternalBufferPropertiesKHR
=== Promotion to Vulkan 1.1
All functionality in this extension is included in core Vulkan 1.1, with the
KHR suffix omitted.
The original type, enum and command names are still available as aliases of
the core functionality.
=== Issues
1) Why do so many external memory capabilities need to be queried on a

9
doc/specs/vulkan/appendices/VK_KHR_external_semaphore.txt
View File

@ -8,6 +8,8 @@ include::meta/VK_KHR_external_semaphore.txt[]
2016-10-21
*IP Status*::
No known IP claims.
*Interactions and External Dependencies*::
- Promoted to Vulkan 1.1 Core
*Contributors*::
- Jason Ekstrand, Intel
- Jesse Hall, Google
@ -45,6 +47,13 @@ None.
None.
=== Promotion to Vulkan 1.1
All functionality in this extension is included in core Vulkan 1.1, with the
KHR suffix omitted.
The original type, enum and command names are still available as aliases of
the core functionality.
=== Issues
1) Should there be restrictions on what side effects can occur when waiting

9
doc/specs/vulkan/appendices/VK_KHR_external_semaphore_capabilities.txt
View File

@ -8,6 +8,8 @@ include::meta/VK_KHR_external_semaphore_capabilities.txt[]
2016-10-20
*IP Status*::
No known IP claims.
*Interactions and External Dependencies*::
- Promoted to Vulkan 1.1 Core
*Contributors*::
- Jesse Hall, Google
- James Jones, NVIDIA
@ -46,4 +48,11 @@ None.
* flink:vkGetPhysicalDeviceExternalSemaphorePropertiesKHR
=== Promotion to Vulkan 1.1
All functionality in this extension is included in core Vulkan 1.1, with the
KHR suffix omitted.
The original type, enum and command names are still available as aliases of
the core functionality.
=== Issues

11
doc/specs/vulkan/appendices/VK_KHR_get_memory_requirements2.txt
View File

@ -5,9 +5,11 @@
include::meta/VK_KHR_get_memory_requirements2.txt[]
*Last Modified Date*::
2017-03-23
2017-09-05
*IP Status*::
No known IP claims.
*Interactions and External Dependencies*::
- Promoted to Vulkan 1.1 Core
*Contributors*::
- Jason Ekstrand, Intel
- Jeff Bolz, NVIDIA
@ -56,6 +58,13 @@ None.
* flink:vkGetBufferMemoryRequirements2KHR
* flink:vkGetImageSparseMemoryRequirements2KHR
=== Promotion to Vulkan 1.1
All functionality in this extension is included in core Vulkan 1.1, with the
KHR suffix omitted.
The original type, enum and command names are still available as aliases of
the core functionality.
=== Issues
None.

11
doc/specs/vulkan/appendices/VK_KHR_get_physical_device_properties2.txt
View File

@ -5,9 +5,11 @@
include::meta/VK_KHR_get_physical_device_properties2.txt[]
*Last Modified Date*::
2016-11-02
2017-09-05
*IP Status*::
No known IP claims.
*Interactions and External Dependencies*::
- Promoted to Vulkan 1.1 Core
*Contributors*::
- Jeff Bolz, NVIDIA
- Ian Elliott, Google
@ -72,6 +74,13 @@ None.
* flink:vkGetPhysicalDeviceMemoryProperties2KHR
* flink:vkGetPhysicalDeviceSparseImageFormatProperties2KHR
=== Promotion to Vulkan 1.1
All functionality in this extension is included in core Vulkan 1.1, with the
KHR suffix omitted.
The original type, enum and command names are still available as aliases of
the core functionality.
=== Issues
None.

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

@ -53,7 +53,7 @@ None.
Other alternatives:
* `VK_KHR_surface2`
* One extension, combined with `<<VK_KHR_get_display_properties2>>`
* One extension, combining a separate display-specific query extension.
2) Should additional WSI query functions be extended?

11
doc/specs/vulkan/appendices/VK_KHR_maintenance1.txt
View File

@ -5,7 +5,9 @@
include::meta/VK_KHR_maintenance1.txt[]
*Last Modified Date*::
2016-10-26
2017-09-05
*Interactions and External Dependencies*::
- Promoted to Vulkan 1.1 Core
*Contributors*::
- Dan Ginsburg, Valve
- Daniel Koch, NVIDIA
@ -83,6 +85,13 @@ None.
* flink:vkTrimCommandPoolKHR
=== Promotion to Vulkan 1.1
All functionality in this extension is included in core Vulkan 1.1, with the
KHR suffix omitted.
The original type, enum and command names are still available as aliases of
the core functionality.
=== Issues
None.

11
doc/specs/vulkan/appendices/VK_KHR_maintenance2.txt
View File

@ -5,7 +5,9 @@
include::meta/VK_KHR_maintenance2.txt[]
*Last Modified Date*::
2017-04-28
2017-09-05
*Interactions and External Dependencies*::
- Promoted to Vulkan 1.1 Core
*Contributors*::
- Michael Worcester, Imagination Technologies
- Stuart Smith, Imagination Technologies
@ -86,6 +88,13 @@ None.
None.
=== Promotion to Vulkan 1.1
All functionality in this extension is included in core Vulkan 1.1, with the
KHR suffix omitted.
The original type, enum and command names are still available as aliases of
the core functionality.
=== Input Attachment Specification Example
Consider the case where a render pass has two subpasses and two attachments.

65
doc/specs/vulkan/appendices/VK_KHR_maintenance3.txt Normal file
View File

@ -0,0 +1,65 @@
// Copyright (c) 2016-2018 Khronos Group. This work is licensed under a
// Creative Commons Attribution 4.0 International License; see
// http://creativecommons.org/licenses/by/4.0/
include::meta/VK_KHR_maintenance3.txt[]
*Status*::
Draft
*Last Modified Date*::
2017-09-05
*Interactions and External Dependencies*::
- Promoted to Vulkan 1.1 Core
*Contributors*::
- Jeff Bolz, NVIDIA
`VK_KHR_maintenance3` adds a collection of minor features that were
intentionally left out or overlooked from the original Vulkan 1.0 release.
The new features are as follows:
* A limit on the maximum number of descriptors that are supported in a
single descriptor set layout.
Some implementations have a limit on the total size of descriptors in a
set, which can't be expressed in terms of the limits in Vulkan 1.0.
* A limit on the maximum size of a single memory allocation.
Some platforms have kernel interfaces that limit the maximum size of an
allocation.
=== New Object Types
None.
=== New Enum Constants
* Extending elink:VkStructureType:
** ename:VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MAINTENANCE_3_PROPERTIES_KHR
** ename:VK_STRUCTURE_TYPE_DESCRIPTOR_SET_LAYOUT_SUPPORT_KHR
=== New Enums
None.
=== New Structures
* slink:VkPhysicalDeviceMaintenance3PropertiesKHR
* slink:VkDescriptorSetLayoutSupportKHR
=== New Functions
* flink:vkGetDescriptorSetLayoutSupportKHR
=== Promotion to Vulkan 1.1
All functionality in this extension is included in core Vulkan 1.1, with the
KHR suffix omitted.
The original type, enum and command names are still available as aliases of
the core functionality.
=== Issues
None.
=== Version History
* Revision 1, 2017-08-22

27
doc/specs/vulkan/appendices/VK_KHX_multiview.txt → doc/specs/vulkan/appendices/VK_KHR_multiview.txt
View File

@ -2,12 +2,14 @@
// Creative Commons Attribution 4.0 International License; see
// http://creativecommons.org/licenses/by/4.0/
include::meta/VK_KHX_multiview.txt[]
include::meta/VK_KHR_multiview.txt[]
*Last Modified Date*::
2016-10-28
*IP Status*::
No known IP claims.
*Interactions and External Dependencies*::
- Promoted to Vulkan 1.1 Core
*Contributors*::
- Jeff Bolz, NVIDIA
@ -27,12 +29,12 @@ None.
=== New Enum Constants
* Extending elink:VkStructureType:
** ename:VK_STRUCTURE_TYPE_RENDER_PASS_MULTIVIEW_CREATE_INFO_KHX
** ename:VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MULTIVIEW_FEATURES_KHX
** ename:VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MULTIVIEW_PROPERTIES_KHX
** ename:VK_STRUCTURE_TYPE_RENDER_PASS_MULTIVIEW_CREATE_INFO_KHR
** ename:VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MULTIVIEW_FEATURES_KHR
** ename:VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MULTIVIEW_PROPERTIES_KHR
* Extending elink:VkDependencyFlagBits
** ename:VK_DEPENDENCY_VIEW_LOCAL_BIT_KHX
** ename:VK_DEPENDENCY_VIEW_LOCAL_BIT_KHR
=== New Enums
@ -40,20 +42,29 @@ None.
=== New Structures
* slink:VkPhysicalDeviceMultiviewFeaturesKHX
* slink:VkPhysicalDeviceMultiviewPropertiesKHX
* slink:VkRenderPassMultiviewCreateInfoKHX
* slink:VkPhysicalDeviceMultiviewFeaturesKHR
* slink:VkPhysicalDeviceMultiviewPropertiesKHR
* slink:VkRenderPassMultiviewCreateInfoKHR
=== New Functions
None.
=== New Built-In Variables
* <<interfaces-builtin-variables-viewindex,code:ViewIndex>>
=== New SPIR-V Capabilities
* <<spirvenv-capabilities-table-multiview,code:MultiView>>
=== Promotion to Vulkan 1.1
All functionality in this extension is included in core Vulkan 1.1, with the
KHR suffix omitted.
The original type, enum and command names are still available as aliases of
the core functionality.
=== Issues
None.

16
doc/specs/vulkan/appendices/VK_KHR_push_descriptor.txt
View File

@ -5,7 +5,7 @@
include::meta/VK_KHR_push_descriptor.txt[]
*Last Modified Date*::
2016-10-15
2017-09-12
*IP Status*::
No known IP claims.
*Contributors*::
@ -29,6 +29,10 @@ None.
* Extending elink:VkDescriptorSetLayoutCreateFlagBits
** ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_PUSH_DESCRIPTOR_BIT_KHR
ifdef::VK_VERSION_1_1[]
* Extending elink:VkDescriptorUpdateTemplateType
** ename:VK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_PUSH_DESCRIPTORS_KHR
endif::VK_VERSION_1_1[]
=== New Enums
None.
@ -40,6 +44,9 @@ None.
=== New Functions
* flink:vkCmdPushDescriptorSetKHR
ifdef::VK_VERSION_1_1[]
* flink:vkCmdPushDescriptorSetWithTemplateKHR
endif::VK_VERSION_1_1[]
=== Issues
@ -51,5 +58,8 @@ None.
=== Version History
* Revision 1, 2016-10-15 (Jeff Bolz)
- Internal revisions
* Revision 1, 2016-10-15 (Jeff Bolz)
- Internal revisions
* Revision 2, 2017-09-12 (Tobias Hector)
- Added interactions with Vulkan 1.1

9
doc/specs/vulkan/appendices/VK_KHR_relaxed_block_layout.txt
View File

@ -8,6 +8,8 @@ include::meta/VK_KHR_relaxed_block_layout.txt[]
2017-03-26
*IP Status*::
No known IP claims.
*Interactions and External Dependencies*::
- Promoted to Vulkan 1.1 Core
*Contributors*::
- John Kessenich, Google
@ -18,5 +20,12 @@ For example, placing a vector of three floats at an offset of 16*N + 4.
See <<interfaces-resources-layout,Offset and Stride Assignment>> for
details.
=== Promotion to Vulkan 1.1
All functionality in this extension is included in core Vulkan 1.1, with the
KHR suffix omitted.
The original type, enum and command names are still available as aliases of
the core functionality.
=== Version History
* Revision 1, 2017-03-26 (JohnK)

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

@ -9,6 +9,7 @@ include::meta/VK_KHR_sampler_ycbcr_conversion.txt[]
*IP Status*::
No known IP claims.
*Interactions and External Dependencies*::
- Promoted to Vulkan 1.1 Core
- This extension interacts with `<<VK_EXT_debug_report>>`
*Contributors*::
- Andrew Garrard, Samsung Electronics
@ -115,7 +116,12 @@ bind memory to the planes of an image collectively or separately.
* slink:VkSamplerYcbcrConversionKHR
=== Issues
=== Promotion to Vulkan 1.1
All functionality in this extension is included in core Vulkan 1.1, with the
KHR suffix omitted.
The original type, enum and command names are still available as aliases of
the core functionality.
=== Version History

11
doc/specs/vulkan/appendices/VK_KHR_shader_draw_parameters.txt
View File

@ -5,7 +5,7 @@
include::meta/VK_KHR_shader_draw_parameters.txt[]
*Last Modified Date*::
2016-10-05
2017-09-05
*IP Status*::
No known IP claims.
*Interactions and External Dependencies*::
@ -15,6 +15,7 @@ include::meta/VK_KHR_shader_draw_parameters.txt[]
- Requires
https://www.khronos.org/registry/OpenGL/extensions/ARB/ARB_shader_draw_parameters.txt[+GL_ARB_shader_draw_parameters+]
for GLSL source languages.
- Promoted to Vulkan 1.1 Core
*Contributors*::
- Daniel Koch, NVIDIA Corporation
- Jeff Bolz, NVIDIA
@ -73,7 +74,13 @@ None.
=== New SPIR-V Capabilities
* <<spirvenv-capabilities-table-drawparameters,DrawParameters>>
* <<spirvenv-capabilities,DrawParameters>>
=== Promotion to Vulkan 1.1
All functionality in this extension is included in core Vulkan 1.1, however
a <<features-features-shaderDrawParameters,feature bit was added>> to
distinguish whether it's actually available or not.
=== Issues

7
doc/specs/vulkan/appendices/VK_KHR_storage_buffer_storage_class.txt
View File

@ -5,13 +5,14 @@
include::meta/VK_KHR_storage_buffer_storage_class.txt[]
*Last Modified Date*::
2017-03-23
2017-09-05
*IP Status*::
No known IP claims.
*Interactions and External Dependencies*::
- This extension requires the
https://www.khronos.org/registry/spir-v/extensions/KHR/SPV_KHR_storage_buffer_storage_class.html[+SPV_KHR_storage_buffer_storage_class+]
SPIR-V extension.
- Promoted to Vulkan 1.1 Core
*Contributors*::
- Alexander Galazin, ARM
- David Neto, Google
@ -32,6 +33,10 @@ None.
None.
=== Promotion to Vulkan 1.1
All functionality in this extension is included in core Vulkan 1.1.
=== Issues
None.

39
doc/specs/vulkan/appendices/VK_KHR_swapchain.txt
View File

@ -5,9 +5,11 @@
include::meta/VK_KHR_swapchain.txt[]
*Last Modified Date*::
2016-05-04
2017-10-06
*IP Status*::
No known IP claims.
*Interactions and External Dependencies*::
- Interacts with Vulkan 1.1
*Contributors*::
- Patrick Doane, Blizzard
- Ian Elliott, LunarG
@ -39,6 +41,14 @@ present rendering results to a surface.
* Extending elink:VkStructureType:
** ename:VK_STRUCTURE_TYPE_SWAPCHAIN_CREATE_INFO_KHR
** ename:VK_STRUCTURE_TYPE_PRESENT_INFO_KHR
ifdef::VK_VERSION_1_1[]
** ename:VK_STRUCTURE_TYPE_DEVICE_GROUP_PRESENT_CAPABILITIES_KHR
** ename:VK_STRUCTURE_TYPE_IMAGE_SWAPCHAIN_CREATE_INFO_KHR
** ename:VK_STRUCTURE_TYPE_BIND_IMAGE_MEMORY_SWAPCHAIN_INFO_KHR
** ename:VK_STRUCTURE_TYPE_ACQUIRE_NEXT_IMAGE_INFO_KHR
** ename:VK_STRUCTURE_TYPE_DEVICE_GROUP_PRESENT_INFO_KHR
** ename:VK_STRUCTURE_TYPE_DEVICE_GROUP_SWAPCHAIN_CREATE_INFO_KHR
endif::VK_VERSION_1_1[]
* Extending elink:VkImageLayout:
** ename:VK_IMAGE_LAYOUT_PRESENT_SRC_KHR
* Extending elink:VkResult:
@ -47,12 +57,23 @@ present rendering results to a surface.
=== New Enums
None
ifdef::VK_VERSION_1_1[]
* slink:VkDeviceGroupPresentModeFlagBitsKHR
* elink:VkSwapchainCreateFlagBitsKHR
endif::VK_VERSION_1_1[]
=== New Structures
* slink:VkSwapchainCreateInfoKHR
* slink:VkPresentInfoKHR
ifdef::VK_VERSION_1_1[]
* slink:VkDeviceGroupPresentCapabilitiesKHR
* slink:VkImageSwapchainCreateInfoKHR
* slink:VkBindImageMemorySwapchainInfoKHR
* slink:VkAcquireNextImageInfoKHR
* slink:VkDeviceGroupPresentInfoKHR
* slink:VkDeviceGroupSwapchainCreateInfoKHR
endif::VK_VERSION_1_1[]
=== New Functions
@ -61,6 +82,12 @@ None
* flink:vkGetSwapchainImagesKHR
* flink:vkAcquireNextImageKHR
* flink:vkQueuePresentKHR
ifdef::VK_VERSION_1_1[]
* flink:vkGetDeviceGroupPresentCapabilitiesKHR
* flink:vkGetDeviceGroupSurfacePresentModesKHR
* flink:vkGetPhysicalDevicePresentRectanglesKHR
* flink:vkAcquireNextImage2KHR
endif::VK_VERSION_1_1[]
=== Issues
@ -724,7 +751,7 @@ https://github.com/KhronosGroup/Vulkan-LoaderAndValidationLayers/blob/master/dem
* Revision 56, 2015-09-18 (James Jones)
- Added fence argument to vkAcquireNextImageKHR
- Added example of how to meter a CPU thread based on presentation rate.
- Added example of how to meter a host thread based on presentation rate.
* Revision 57, 2015-09-26 (Jesse Hall)
- Replace VkSurfaceDescriptionKHR with VkSurfaceKHR.
@ -787,3 +814,9 @@ https://github.com/KhronosGroup/Vulkan-LoaderAndValidationLayers/blob/master/dem
* 2016-08-25 (Ian Elliott)
- A note was added at the beginning of the example code, stating that it
will be removed from future versions of the appendix.
* Revision 69, 2017-09-07 (Tobias Hector)
- Added interactions with Vulkan 1.1
* Revision 70, 2017-10-06 (Ian Elliott)
- Corrected interactions with Vulkan 1.1

12
doc/specs/vulkan/appendices/VK_KHR_variable_pointers.txt
View File

@ -5,13 +5,14 @@
include::meta/VK_KHR_variable_pointers.txt[]
*Last Modified Date*::
2017-03-14
2017-09-05
*IP Status*::
No known IP claims.
*Interactions and External Dependencies*::
- Requires the
https://www.khronos.org/registry/spir-v/extensions/KHR/SPV_KHR_variable_pointers.html[+SPV_KHR_variable_pointers+]
SPIR-V extension.
- Promoted to Vulkan 1.1 Core
*Contributors*::
- John Kessenich, Google
- Neil Henning, Codeplay
@ -48,6 +49,15 @@ The second, code:VariablePointers, is optional.
* <<spirvenv-capabilities-table-variablepointers,VariablePointersStorageBuffer>>
* <<spirvenv-capabilities-table-variablepointers,VariablePointers>>
=== Promotion to Vulkan 1.1
All functionality in this extension is included in core Vulkan 1.1, with the
KHR suffix omitted, however support for the
<<features-features-variablePointersStorageBuffer,
pname:variablePointersStorageBuffer>> feature is made optional.
The original type, enum and command names are still available as aliases of
the core functionality.
=== Issues
1) Do we need an optional property for the SPIR-V

108
doc/specs/vulkan/appendices/VK_KHX_device_group.txt
View File

@ -1,108 +0,0 @@
// Copyright (c) 2016-2018 Khronos Group. This work is licensed under a
// Creative Commons Attribution 4.0 International License; see
// http://creativecommons.org/licenses/by/4.0/
include::meta/VK_KHX_device_group.txt[]
*Last Modified Date*::
2017-05-19
*IP Status*::
No known IP claims.
*Contributors*::
- Jeff Bolz, NVIDIA
- Tobias Hector, Imagination Technologies
This extension provides functionality to use a logical device that consists
of multiple physical devices, as created with the
`<<VK_KHX_device_group_creation>>` extension.
A device group can allocate memory across the subdevices, bind memory from
one subdevice to a resource on another subdevice, record command buffers
where some work executes on an arbitrary subset of the subdevices, and
potentially present a swapchain image from one or more subdevices.
=== New Object Types
None.
=== New Enum Constants
* Extending elink:VkStructureType:
** ename:VK_STRUCTURE_TYPE_MEMORY_ALLOCATE_FLAGS_INFO_KHX
** ename:VK_STRUCTURE_TYPE_DEVICE_GROUP_RENDER_PASS_BEGIN_INFO_KHX
** ename:VK_STRUCTURE_TYPE_DEVICE_GROUP_COMMAND_BUFFER_BEGIN_INFO_KHX
** ename:VK_STRUCTURE_TYPE_DEVICE_GROUP_SUBMIT_INFO_KHX
** ename:VK_STRUCTURE_TYPE_DEVICE_GROUP_BIND_SPARSE_INFO_KHX
** ename:VK_STRUCTURE_TYPE_DEVICE_GROUP_PRESENT_CAPABILITIES_KHX
** ename:VK_STRUCTURE_TYPE_IMAGE_SWAPCHAIN_CREATE_INFO_KHX
** ename:VK_STRUCTURE_TYPE_BIND_IMAGE_MEMORY_SWAPCHAIN_INFO_KHX
** ename:VK_STRUCTURE_TYPE_ACQUIRE_NEXT_IMAGE_INFO_KHX
** ename:VK_STRUCTURE_TYPE_DEVICE_GROUP_PRESENT_INFO_KHX
** ename:VK_STRUCTURE_TYPE_DEVICE_GROUP_SWAPCHAIN_CREATE_INFO_KHX
** ename:VK_STRUCTURE_TYPE_BIND_BUFFER_MEMORY_DEVICE_GROUP_INFO_KHX
** ename:VK_STRUCTURE_TYPE_BIND_IMAGE_MEMORY_DEVICE_GROUP_INFO_KHX
* Extending elink:VkImageCreateFlagBits
** ename:VK_IMAGE_CREATE_BIND_SFR_BIT_KHX
* Extending elink:VkPipelineCreateFlagBits
** ename:VK_PIPELINE_CREATE_VIEW_INDEX_FROM_DEVICE_INDEX_BIT_KHX
** ename:VK_PIPELINE_CREATE_DISPATCH_BASE_KHX
* Extending elink:VkDependencyFlagBits
** ename:VK_DEPENDENCY_DEVICE_GROUP_BIT_KHX
* Extending elink:VkSwapchainCreateFlagBitsKHR
** ename:VK_SWAPCHAIN_CREATE_BIND_SFR_BIT_KHX
=== New Enums
* slink:VkPeerMemoryFeatureFlagBitsKHX
* slink:VkMemoryAllocateFlagBitsKHX
* slink:VkDeviceGroupPresentModeFlagBitsKHX
=== New Structures
* slink:VkMemoryAllocateFlagsInfoKHX
* slink:VkDeviceGroupRenderPassBeginInfoKHX
* slink:VkDeviceGroupCommandBufferBeginInfoKHX
* slink:VkDeviceGroupSubmitInfoKHX
* slink:VkDeviceGroupBindSparseInfoKHX
* slink:VkDeviceGroupPresentCapabilitiesKHX
* slink:VkImageSwapchainCreateInfoKHX
* slink:VkBindImageMemorySwapchainInfoKHX
* slink:VkAcquireNextImageInfoKHX
* slink:VkDeviceGroupPresentInfoKHX
* slink:VkDeviceGroupSwapchainCreateInfoKHX
* slink:VkBindBufferMemoryDeviceGroupInfoKHX
* slink:VkBindImageMemoryDeviceGroupInfoKHX
=== New Functions
* flink:vkGetDeviceGroupPeerMemoryFeaturesKHX
* flink:vkCmdSetDeviceMaskKHX
* flink:vkGetDeviceGroupPresentCapabilitiesKHX
* flink:vkGetDeviceGroupSurfacePresentModesKHX
* flink:vkAcquireNextImage2KHX
* flink:vkCmdDispatchBaseKHX
* flink:vkGetPhysicalDevicePresentRectanglesKHX
=== New Built-In Variables
* <<interfaces-builtin-variables-deviceindex,code:DeviceIndex>>
=== New SPIR-V Capabilities
* <<spirvenv-capabilities-table-devicegroup,code:DeviceGroup>>
=== Issues
None.
=== Examples
TODO
=== Version History
* Revision 2, 2017-05-19 (Tobias Hector)
- Removed extended memory bind functions to VK_KHR_bind_memory2, added
dependency on that extension, and device-group-specific structs for
those functions.
* Revision 1, 2016-10-19 (Jeff Bolz)
- Internal revisions

1
doc/specs/vulkan/appendices/VK_NV_external_memory_capabilities.txt
View File

@ -5,6 +5,7 @@ include::meta/VK_NV_external_memory_capabilities.txt[]
*IP Status*::
No known IP claims.
*Interactions and External Dependencies*::
- Interacts with +Vulkan 1.1+.
- Interacts with `<<VK_KHR_dedicated_allocation>>`.
- Interacts with `<<VK_NV_dedicated_allocation>>`.
*Contributors*::

301
doc/specs/vulkan/appendices/boilerplate.txt
View File

@ -11,15 +11,128 @@ for a complete functional description of Vulkan, but do not logically belong
elsewhere in the Specification.
[[boilerplate-macros]]
== Macro Definitions in +vulkan.h+
[[boilerplate-headers]]
== Vulkan Header Files
The supplied +vulkan.h+ header defines a small number of C preprocessor
macros that are described below.
Vulkan is defined as an API in the C99 language.
Khronos provides a corresponding set of header files for applications using
the API, which may be used in either C or C++ code.
The interface descriptions in the specification are the same as the
interfaces defined in these header files, and both are derived from the
`vk.xml` XML API Registry, which is the canonical machine-readable
description of the Vulkan API.
The Registry, scripts used for processing it into various forms, and
documentation of the registry schema are available as described at
https://www.khronos.org/registry/vulkan/#apiregistry .
Language bindings for other languages can be defined using the information
in the Specification and the Registry.
Khronos does not provide any such bindings, but third-party developers have
created some additional bindings.
[[boilerplate-vulkan-h]]
=== Vulkan Combined API Header `vulkan.h` (Informative)
Applications normally will include the header `vulkan.h`.
In turn, `vulkan.h` always includes the following headers:
* <<boilerplate-vk-platform,`vk_platform.h`>>, defining platform-specific
macros and headers.
* <<boilerplate-vulkan-core,`vulkan_core.h`>>, defining APIs for the
Vulkan core and all registered extensions _other_ than window
system-specific extensions.
In addition, specific preprocessor macros defined at the time `vulkan.h` is
included cause header files for the corresponding <<boilerplate-wsi-header,
window system-specific extension interfaces>> to be included.
[[boilerplate-platform-macros]]
=== Vulkan Platform-Specific Header `vk_platform.h` (Informative)
Platform-specific macros and interfaces are defined in `vk_platform.h`.
These macros are used to control platform-dependent behavior, and their
exact definitions are under the control of specific platforms and Vulkan
implementations.
[[boilerplate-platform-specific-calling-conventions]]
==== Platform-Specific Calling Conventions
On many platforms the following macros are empty strings, causing platform-
and compiler-specific default calling conventions to be used.
// @refBegin VKAPI_ATTR Vulkan function attributes
dname:VKAPI_ATTR is a macro placed before the return type in Vulkan API
function declarations.
This macro controls calling conventions for C++11 and GCC/Clang-style
compilers.
// @refEnd VKAPI_ATTR VKAPI_CALL VKAPI_PTR
// @refBegin VKAPI_CALL Vulkan function calling conventions
dname:VKAPI_CALL is a macro placed after the return type in Vulkan API
function declarations.
This macro controls calling conventions for MSVC-style compilers.
// @refEnd VKAPI_CALL VKAPI_ATTR VKAPI_PTR
// @refBegin VKAPI_PTR Vulkan function pointer calling conventions
dname:VKAPI_PTR is a macro placed between the '(' and '*' in Vulkan API
function pointer declarations.
This macro also controls calling conventions, and typically has the same
definition as dname:VKAPI_ATTR or dname:VKAPI_CALL, depending on the
compiler.
// @refEnd VKAPI_PTR VKAPI_ATTR VKAPI_CALL
With these macros, a Vulkan function declaration takes the form of:
[source,c++]
----------------------------------------
VKAPI_ATTR <return_type> VKAPI_CALL <command_name>(<command_parameters>);
----------------------------------------
Additionaly, a Vulkan function pointer type declaration takes the form of:
[source,c++]
----------------------------------------
typedef <return_type> (VKAPI_PTR *PFN_<command_name>)(<command_parameters>);
----------------------------------------
==== Platform-Specific Header Control
// @refBegin VK_NO_STDINT_H Control definition of `<stdint.h>` types
If the code:VK_NO_STDINT_H macro is defined by the application at compile
time, extended integer types used by the Vulkan API, such as code:uint8_t,
must: also be defined by the application.
Otherwise, the Vulkan headers will not compile.
If code:VK_NO_STDINT_H is not defined, the system `<stdint.h>` is used to
define these types.
There is a fallback path when Microsoft Visual Studio version 2008 and
earlier versions are detected at compile time.
// @refEnd VK_NO_STDINT_H
[[boilerplate-vulkan-core]]
=== Vulkan Core API Header `vulkan_core.h`
Applications that do not make use of window system-specific extensions may
simply include `vulkan_core.h` instead of `vulkan.h`, although there is
usually no reason to do so.
In addition to the Vulkan API, `vulkan_core.h` also defines a small number
of C preprocessor macros that are described below.
[[boilerplate-versions]]
=== Vulkan Version Number Macros
==== Vulkan Version Number Macros
<<fundamentals-versionnum,API Version Numbers>> are packed into integers.
These macros manipulate version numbers in useful ways.
@ -66,10 +179,25 @@ include::../api/defines/VK_API_VERSION_1_0.txt[]
--
ifdef::VK_VERSION_1_1[]
[open,refpage='VK_API_VERSION_1_1',desc='Return API version number for Vulkan 1.1',type='defines',xrefs='vkCreateInstance vkGetPhysicalDeviceProperties']
--
dname:VK_API_VERSION_1_1 returns the API version number for Vulkan 1.1.
The patch version number in this macro will always be zero.
The supported patch version for a physical device can: be queried with
flink:vkGetPhysicalDeviceProperties.
include::../api/defines/VK_API_VERSION_1_1.txt[]
--
endif::VK_VERSION_1_1[]
[open,refpage='VK_API_VERSION',desc='Deprecated version number macro',type='defines']
--
dname:VK_API_VERSION is now commented out of +vulkan.h+ and cannot: be used.
dname:VK_API_VERSION is now commented out of `vulkan_core.h` and cannot: be
used.
include::../api/defines/VK_API_VERSION.txt[]
@ -93,23 +221,21 @@ flink:vkCreateInstance.
--
=== Vulkan Header File Version Number
==== Vulkan Header File Version Number
[open,refpage='VK_HEADER_VERSION',desc='Vulkan header file version number',type='defines']
--
dname:VK_HEADER_VERSION is the version number of the +vulkan.h+ header.
This value is currently kept synchronized with the release number of the
dname:VK_HEADER_VERSION is the version number of the `vulkan_core.h` header.
This value is kept synchronized with the patch version of the released
Specification.
However, it is not guaranteed to remain synchronized, since most
Specification updates have no effect on +vulkan.h+.
include::../api/defines/VK_HEADER_VERSION.txt[]
--
=== Vulkan Handle Macros
==== Vulkan Handle Macros
[open,refpage='VK_DEFINE_HANDLE',desc='Declare a dispatchable object handle',type='defines',xrefs='VkCommandBuffer VkDevice VkInstance VkPhysicalDevice VkQueue']
--
@ -141,10 +267,11 @@ Most Vulkan handle types, such as slink:VkBuffer, are non-dispatchable.
[NOTE]
.Note
====
The +vulkan.h+ header allows the dname:VK_DEFINE_NON_DISPATCHABLE_HANDLE
definition to be overridden by the application.
If dname:VK_DEFINE_NON_DISPATCHABLE_HANDLE is already defined when the
+vulkan.h+ header is compiled the default definition is skipped.
The `vulkan_core.h` header allows the
dname:VK_DEFINE_NON_DISPATCHABLE_HANDLE definition to be overridden by the
application.
If dname:VK_DEFINE_NON_DISPATCHABLE_HANDLE is already defined when
`vulkan_core.h` is compiled, the default definition is skipped.
This allows the application to define a binary-compatible custom handle
which may: provide more type-safety or other features needed by the
application.
@ -169,116 +296,74 @@ include::../api/defines/VK_NULL_HANDLE.txt[]
--
[[boilerplate-platform-macros]]
== Platform-Specific Macro Definitions in +vk_platform.h+
Additional platform-specific macros and interfaces are defined using the
included +vk_platform.h+ file.
These macros are used to control platform-dependent behavior, and their
exact definitions are under the control of specific platforms and Vulkan
implementations.
[[boilerplate-platform-specific-calling-conventions]]
=== Platform-Specific Calling Conventions
On many platforms the following macros are empty strings, causing platform-
and compiler-specific default calling conventions to be used.
// @refBegin VKAPI_ATTR Vulkan function attributes
dname:VKAPI_ATTR is a macro placed before the return type in Vulkan API
function declarations.
This macro controls calling conventions for C++11 and GCC/Clang-style
compilers.
// @refEnd VKAPI_ATTR VKAPI_CALL VKAPI_PTR
// @refBegin VKAPI_CALL Vulkan function calling conventions
dname:VKAPI_CALL is a macro placed after the return type in Vulkan API
function declarations.
This macro controls calling conventions for MSVC-style compilers.
// @refEnd VKAPI_CALL VKAPI_ATTR VKAPI_PTR
// @refBegin VKAPI_PTR Vulkan function pointer calling conventions
dname:VKAPI_PTR is a macro placed between the "`(`" and "`*`" in Vulkan API
function pointer declarations.
This macro also controls calling conventions, and typically has the same
definition as dname:VKAPI_ATTR or dname:VKAPI_CALL, depending on the
compiler.
// @refEnd VKAPI_PTR VKAPI_ATTR VKAPI_CALL
With these macros, a Vulkan function declaration takes the form of:
[source,c++]
----------------------------------------
VKAPI_ATTR <return_type> VKAPI_CALL <command_name>(<command_parameters>);
----------------------------------------
Additionaly, a Vulkan function pointer type declaration takes the form of:
[source,c++]
----------------------------------------
typedef <return_type> (VKAPI_PTR *PFN_<command_name>)(<command_parameters>);
----------------------------------------
=== Platform-Specific Header Control
// @refBegin VK_NO_STDINT_H Control definition of <stdint.h> types
If the dname:VK_NO_STDINT_H macro is defined by the application at compile
time, extended integer types used by `vulkan.h`, such as code:uint8_t, must:
also be defined by the application.
Otherwise, `vulkan.h` will not compile.
If dname:VK_NO_STDINT_H is not defined, the system `<stdint.h>` is used to
define these types, or there is a fallback path when Microsoft Visual Studio
version 2008 and earlier versions are detected at compile time.
// @refEnd VK_NO_STDINT_H
[[boilerplate-wsi-header]]
=== Window System-Specific Header Control
== Window System-Specific Header Control (Informative)
// @refBegin WSIheaders Control inclusion of window system interface extensions
To use a Vulkan extension supporting a platform-specific window system,
header files for that window systems must: be included at compile time.
header files for that window systems must: be included at compile time, or
platform-specific types must: be forward-declared.
The Vulkan header files cannot determine whether or not an external header
is available at compile time, so applications wishing to use such an
extension must: `#define` a macro causing such headers to be included.
If this is not done, the corresponding extension interfaces will not be
defined and they will be unusable.
is available at compile time, so platform-specific extensions are provided
in separate headers from the core API and platform-independent extensions,
allowing applications to decide which ones should be defined and how the
external headers are included.
The extensions, required: compile time symbols to enable them, window
systems they correspond to, and external header files that are included when
the macro is ``#define``d are shown in the
Extensions dependent on particular sets of platform headers, or that
forward-declare platform-specific types, are declared in a header named for
that platform.
Before including these platform-specific Vulkan headers, applications must:
include both `vulkan_core.h` and any external native headers the platform
extensions depend on.
As a convenience for applications that do not need the flexibility of
separate platform-specific Vulkan headers, `vulkan.h` includes
`vulkan_core.h`, and then conditionally includes platform-specific Vulkan
headers and the external headers they depend on.
Applications control which platform-specific headers are included by
#defining macros before including `vulkan.h`.
The correspondence between platform-specific extensions, external headers
they require, the platform-specific header which declares them, and the
preprocessor macros which enable inclusion by `vulkan.h` are shown in the
<<boilerplate-wsi-header-table,following table>>.
[[boilerplate-wsi-header-table]]
.Window System Extensions and Required Compile Time Symbol Definitions
.Window System Extensions and Headers
[options="header"]
|====
| Extension Name | Required Compile Time Symbol | Window System Name | External Header Files Used
| `<<VK_KHR_android_surface>>` | dname:VK_USE_PLATFORM_ANDROID_KHR | Android Native | `<android/native_window.h>`
| `<<VK_KHR_mir_surface>>` | dname:VK_USE_PLATFORM_MIR_KHR | Mir | `<mir_toolkit/client_types.h>`
| `<<VK_KHR_wayland_surface>>` | dname:VK_USE_PLATFORM_WAYLAND_KHR | Wayland | `<wayland-client.h>`
| `<<VK_KHR_win32_surface>>` | dname:VK_USE_PLATFORM_WIN32_KHR | Microsoft Windows | `<windows.h>`
| `<<VK_KHR_xcb_surface>>` | dname:VK_USE_PLATFORM_XCB_KHR | X Window System Xcb library | `<xcb/xcb.h>`
| `<<VK_KHR_xlib_surface>>` | dname:VK_USE_PLATFORM_XLIB_KHR | X Window System Xlib library | `<X11/Xlib.h>`
| Extension Name | Window System Name | Platform-specific Header | Required External Headers | Controlling `vulkan.h` Macro
| `<<VK_KHR_android_surface>>` | Android | `vulkan_android.h` | None | dname:VK_USE_PLATFORM_ANDROID_KHR
| `<<VK_KHR_mir_surface>>` | Mir | `vulkan_mir.h` | `<mir_toolkit/client_types.h>` | dname:VK_USE_PLATFORM_MIR_KHR
| `<<VK_KHR_wayland_surface>>` | Wayland | `vulkan_wayland.h` | `<wayland-client.h>` | dname:VK_USE_PLATFORM_WAYLAND_KHR
| `<<VK_KHR_win32_surface>>`,
`<<VK_KHR_external_memory_win32>>`,
`<<VK_KHR_win32_keyed_mutex>>`,
`<<VK_KHR_external_semaphore_win32>>`,
`<<VK_KHR_external_fence_win32>>`,
ifdef::VK_NV_external_memory_win32[]
`<<VK_NV_external_memory_win32>>`,
endif::VK_NV_external_memory_win32[]
ifdef::VK_NV_win32_keyed_mutex[]
`<<VK_NV_win32_keyed_mutex>>`
endif::VK_NV_win32_keyed_mutex[]
| Microsoft Windows | `vulkan_win32.h` | `<windows.h>` | dname:VK_USE_PLATFORM_WIN32_KHR
| `<<VK_KHR_xcb_surface>>` | X11 Xcb | `vulkan_xcb.h` | `<xcb/xcb.h>` | dname:VK_USE_PLATFORM_XCB_KHR
| `<<VK_KHR_xlib_surface>>` | X11 Xlib | `vulkan_xlib.h` | `<X11/Xlib.h>` | dname:VK_USE_PLATFORM_XLIB_KHR
ifdef::VK_EXT_acquire_xlib_display[]
| `<<VK_EXT_acquire_xlib_display>>` | X11 XRAndR | `vulkan_xlib_xrandr.h` | `<X11/Xlib.h>`,
`<X11/extensions/Xrandr.h>` | dname:VK_USE_PLATFORM_XLIB_XRANDR_EXT
endif::VK_EXT_acquire_xlib_display[]
ifdef::VK_MVK_ios_surface[]
| `<<VK_MVK_ios_surface>>` | dname:VK_USE_PLATFORM_IOS_MVK | iOS | None
| `<<VK_MVK_ios_surface>>` | iOS | `vulkan_ios.h` | None | dname:VK_USE_PLATFORM_IOS_MVK
endif::VK_MVK_ios_surface[]
ifdef::VK_MVK_macos_surface[]
| `<<VK_MVK_macos_surface>>` | dname:VK_USE_PLATFORM_MACOS_MVK | macOS | None
| `<<VK_MVK_macos_surface>>` | macOS | `vulkan_macos.h` | None | dname:VK_USE_PLATFORM_MACOS_MVK
endif::VK_MVK_macos_surface[]
ifdef::VK_NN_vi_surface[]
| `<<VK_NN_vi_surface>>` | dname:VK_USE_PLATFORM_VI_NN | VI | None
| `<<VK_NN_vi_surface>>` | VI | `vulkan_vi.h` | None | dname:VK_USE_PLATFORM_VI_NN
endif::VK_NN_vi_surface[]
|====

240
doc/specs/vulkan/appendices/credits.txt
View File

@ -4,161 +4,239 @@
[appendix]
[[credits]]
= Credits
= Credits (Informative)
Vulkan 1.0 is the result of contributions from many people and companies
Vulkan 1.1 is the result of contributions from many people and companies
participating in the Khronos Vulkan Working Group, as well as input from the
Vulkan Advisory Panel.
Members of the Working Group, including the company that they represented at
the time of their contributions, are listed below.
the time of their most recent contribution, are listed in the following
sections.
Some specific contributions made by individuals are listed together with
their name.
== Working Group Contributors to Vulkan 1.1 and 1.0
* Adam Jackson, Red Hat
* Adam Śmigielski, Mobica
* Alexander Galazin, Arm
* Alex Bourd, Qualcomm Technologies, Inc.
* Alexander Galazin, ARM
* Allen Hux, Intel
* Alon Or-bach, Samsung Electronics (WSI technical sub-group chair)
* Andrew Cox, Samsung Electronics
* Andrew Garrard, Samsung Electronics (format wrangler)
* Andrew Woloszyn, Google
* Antoine Labour, Google
* Bill Licea-Kane, Qualcomm Technologies, Inc.
* Cass Everitt, Oculus VR
* Chad Versace, Google
* Christophe Riccio, Unity Technologies
* Dan Baker, Oxide Games
* Dan Ginsburg, Valve Software
* Daniel Johnston, Intel
* Daniel Koch, NVIDIA (<<interfaces,Shader Interfaces>>; <<features,Features, Limits, and Formats>>)
* Daniel Rakos, AMD
* David Airlie, Red Hat
* David Miller, Miller & Mattson (Vulkan reference card)
* David Neto, Google
* Dominik Witczak, AMD
* Graeme Leese, Broadcom
* Graham Sellers, AMD
* Ian Romanick, Intel
* James Jones, NVIDIA
* Jan-Harald Fredriksen, Arm
* Jan Hermes, Continental Corporation
* Jason Ekstrand, Intel
* Jeff Bolz, NVIDIA (extensive contributions, exhaustive review and rewrites for technical correctness)
* Jeff Juliano, NVIDIA
* Jesse Barker, Unity Technologies
* Jesse Hall, Google
* Johannes van Waveren, Oculus VR
* John Kessenich, Google (SPIR-V and GLSL for Vulkan spec author)
* John McDonald, Valve Software
* Jonas Gustavsson, Samsung Electronics
* Jon Ashburn, LunarG
* Jon Leech, Independent (XML toolchain, normative language, release wrangler)
* Jungwoo Kim, Samsung Electronics
* Kathleen Mattson, Miller & Mattson (Vulkan reference card)
* Kenneth Benzie, Codeplay Software Ltd.
* Kerch Holt, NVIDIA (SPIR-V technical sub-group chair)
* Kristian Kristensen, Intel
* Mark Lobodzinski, LunarG
* Mathias Heyer, NVIDIA
* Mathias Schott, NVIDIA
* Maurice Ribble, Qualcomm Technologies, Inc.
* Michael Worcester, Imagination Technologies
* Mika Isojarvi, Google
* Mitch Singer, AMD
* Neil Henning, Codeplay Software Ltd.
* Neil Trevett, NVIDIA
* Norbert Nopper, Independent
* Pierre Boudier, NVIDIA
* Pierre-Loup Griffais, Valve Software
* Piers Daniell, NVIDIA (dynamic state, copy commands, memory types)
* Pyry Haulos, Google (Vulkan conformance test subcommittee chair)
* Ray Smith, Arm
* Robert Simpson, Qualcomm Technologies, Inc.
* Rolando Caloca Olivares, Epic Games
* Sean Harmer, KDAB Group
* Shannon Woods, Google
* Slawomir Cygan, Intel
* Slawomir Grajewski, Intel
* Stuart Smith, Imagination Technologies
* Timothy Lottes, AMD
* Tobias Hector, Imagination Technologies (validity language and toolchain)
* Tom Olson, Arm (working group chair)
* Tony Barbour, LunarG
* Yanjun Zhang, VeriSilicon
== Working Group Contributors to Vulkan 1.1
* Aaron Greig, Codeplay Software Ltd.
* Aaron Hagan, AMD
* Alan Ward, Google
* Alejandro Piñeiro, Igalia
* Andres Gomez, Igalia
* Baldur Karlsson, Independent
* Barthold Lichtenbelt, NVIDIA
* Bas Nieuwenhuizen, Google
* Bill Hollings, Brenwill
* Colin Riley, AMD
* Cort Stratton, Google
* Courtney Goeltzenleuchter, Google
* Dae Kim, Imagination Technologies
* Daniel Stone, Collabora
* David Pinedo, LunarG
* Dejan Mircevski, Google
* Dzmitry Malyshau, Mozilla
* Erika Johnson, LunarG
* Greg Fischer, LunarG
* Hans-Kristian Arntzen, Arm
* Iago Toral, Igalia
* Ian Elliott, Google
* Jeff Leger, Qualcomm Technologies, Inc.
* Jeff Vigil, Samsung Electronics
* Jens Owen, Google
* Joe Davis, Samsung Electronics
* John Zulauf, LunarG
* Jordan Justen, Intel
* Jörg Wagner, Arm
* Kalle Raita, Google
* Karen Ghavam, LunarG
* Karl Schultz, LunarG
* Kenneth Russell, Google
* Kevin O'Neil, AMD
* Lauri Ilola, Nokia
* Lenny Komow, LunarG
* Lionel Landwerlin, Intel
* Maciej Jesionowski, AMD
* Mais Alnasser, AMD
* Marcin Rogucki, Mobica
* Mark Callow, Independent
* Mark Kilgard, NVIDIA
* Markus Tavenrath, NVIDIA
* Mark Young, LunarG
* Matthäus Chajdas, AMD
* Matt Netsch, Qualcomm Technologies, Inc.
* Michael O'Hara, AMD
* Michael Wong, Codeplay Software Ltd.
* Mike Schuchardt, LunarG
* Mike Weiblen, LunarG
* Nicolai Hähnle, AMD
* Nuno Subtil, NVIDIA
* Patrick Cozzi, Independent
* Petros Bantolas, Imagination Technologies
* Ralph Potter, Codeplay Software Ltd.
* Rob Barris, NVIDIA
* Ruihao Zhang, Qualcomm Technologies, Inc.
* Sorel Bosan, AMD
* Stephen Huang, Mediatek
* Tilmann Scheller, Samsung Electronics
* Tomasz Bednarz, Independent
* Victor Eruhimov, ???
* Wolfgang Engel, ???
== Working Group Contributors to Vulkan 1.0
* Adam Śmigielski, Mobica
* Allen Hux, Intel
* Andrew Cox, Samsung Electronics
* Andrew Poole, Samsung Electronics
* Andrew Rafter, Samsung Electronics
* Andrew Richards, Codeplay Software Ltd.
* Andrew Woloszyn, Google
* Antoine Labour, Google
* Aras Pranckevičius, Unity
* Aras Pranckevičius, Unity Technologies
* Ashwin Kolhe, NVIDIA
* Ben Bowman, Imagination Technologies
* Benj Lipchak
* Bill Hollings, The Brenwill Workshop
* Bill Licea-Kane, Qualcomm Technologies, Inc.
* Brent E. Insko, Intel
* Brian Ellis, Qualcomm Technologies, Inc.
* Cass Everitt, Oculus VR
* Cemil Azizoglu, Canonical
* Chad Versace, Intel
* Chang-Hyo Yu, Samsung Electronics
* Chia-I Wu, LunarG
* Chris Frascati, Qualcomm Technologies, Inc.
* Christophe Riccio, Unity
* Cody Northrop, LunarG
* Courtney Goeltzenleuchter, LunarG
* Damien Leone, NVIDIA
* Dan Baker, Oxide Games
* Dan Ginsburg, Valve
* Daniel Johnston, Intel
* Daniel Koch, NVIDIA (<<interfaces,Shader Interfaces>>;
<<features,Features, Limits, and Formats>>)
* Daniel Rakos, AMD
* David Airlie, Red Hat
* David Neto, Google
* David Mao, AMD
* David Yu, Pixar
* Dominik Witczak, AMD
* Frank (LingJun) Chen, Qualcomm Technologies, Inc.
* Fred Liao, Mediatek
* Gabe Dagani, Freescale
* Graeme Leese, Broadcom
* Graham Connor, Imagination Technologies
* Graham Sellers, AMD
* Hwanyong Lee, Kyungpook National University
* Ian Elliott, LunarG
* Ian Romanick, Intel
* James Jones, NVIDIA
* James Hughes, Oculus VR
* Jan Hermes, Continental Corporation
* Jan-Harald Fredriksen, ARM
* Jason Ekstrand, Intel
* Jeff Bolz, NVIDIA (extensive contributions, exhaustive review and
rewrites for technical correctness)
* Jeff Juliano, NVIDIA
* Jeff Vigil, Qualcomm Technologies, Inc.
* Jens Owen, LunarG
* Jeremy Hayes, LunarG
* Jesse Barker, Unity
* Jesse Hall, Google
* Johannes van Waveren, Oculus VR
* John Kessenich, Google (SPIR-V and GLSL for Vulkan spec author)
* John McDonald, Valve
* Jon Ashburn, LunarG
* Jon Leech, Independent (XML toolchain, normative language, release
wrangler)
* Jonas Gustavsson, Sony Mobile
* Jonathan Hamilton, Imagination Technologies
* Jungwoo Kim, Samsung Electronics
* Kenneth Benzie, Codeplay Software Ltd.
* Kerch Holt, NVIDIA (SPIR-V technical sub-group chair)
* Kristian Kristensen, Intel
* Krzysztof Iwanicki, Samsung Electronics
* Larry Seiler, Intel
* Lutz Latta, Lucasfilm
* Maria Rovatsou, Codeplay Software Ltd.
* Mark Callow
* Mark Lobodzinski, LunarG
* Mateusz Przybylski, Intel
* Mathias Heyer, NVIDIA
* Mathias Schott, NVIDIA
* Maxim Lukyanov, Samsung Electronics
* Maurice Ribble, Qualcomm Technologies, Inc.
* Michael Lentine, Google
* Michael Worcester, Imagination Technologies
* Michal Pietrasiuk, Intel
* Mika Isojarvi, Google
* Mike Stroyan, LunarG
* Minyoung Son, Samsung Electronics
* Mitch Singer, AMD
* Mythri Venugopal, Samsung Electronics
* Naveen Leekha, Google
* Neil Henning, Codeplay Software Ltd.
* Neil Trevett, NVIDIA
* Nick Penwarden, Epic Games
* Niklas Smedberg, Unity
* Norbert Nopper, Freescale
* Niklas Smedberg, Unity Technologies
* Pat Brown, NVIDIA
* Patrick Doane, Blizzard Entertainment
* Peter Lohrmann, Valve
* Pierre Boudier, NVIDIA
* Pierre-Loup A. Griffais, Valve
* Piers Daniell, NVIDIA (dynamic state, copy commands, memory types)
* Peter Lohrmann, Valve Software
* Piotr Bialecki, Intel
* Prabindh Sundareson, Samsung Electronics
* Pyry Haulos, Google (Vulkan conformance test subcommittee chair)
* Ray Smith, ARM
* Rob Stepinski, Transgaming
* Robert J. Simpson, Qualcomm Technologies, Inc.
* Rolando Caloca Olivares, Epic Games
* Roy Ju, Mediatek
* Rufus Hamede, Imagination Technologies
* Sean Ellis, ARM
* Sean Harmer, KDAB
* Shannon Woods, Google
* Slawomir Cygan, Intel
* Slawomir Grajewski, Intel
* Sean Ellis, Arm
* Stefanus Du Toit, Google
* Steve Hill, Broadcom
* Steve Viggers, Core Avionics & Industrial Inc.
* Stuart Smith, Imagination Technologies
* Tim Foley, Intel
* Timo Suoranta, AMD
* Timothy Lottes, AMD
* Tobias Hector, Imagination Technologies (validity language and
toolchain)
* Tobin Ehlis, LunarG
* Tom Olson, ARM (working group chair)
* Tomasz Kubale, Intel
* Tony Barbour, LunarG
* Wayne Lister, Imagination Technologies
* Yanjun Zhang, Vivante
* Zhenghong Wang, Mediatek
== Other Credits
In addition to the Working Group, the Vulkan Advisory Panel members provided
important real-world usage information and advice that helped guide design
decisions.
Administrative support to the Working Group was provided by members of Gold
Standard Group, including Andrew Riegel, Elizabeth Riegel, Glenn Fredericks,
Kathleen Mattson and Michelle Clark.
Administrative support to the Working Group for Vulkan 1.1 was provided by
Khronos staff including Angela Cheng, Ann Thorsnes, Emily Stearns, Liz
Maitral, and Dominic Agoro-Ombaka; and by Alex Crabb of Caster
Communications.
Administrative support for Vulkan 1.0 was provided by Andrew Riegel,
Elizabeth Riegel, Glenn Fredericks, Kathleen Mattson and Michelle Clark of
Gold Standard Group.
Technical support was provided by James Riordon, webmaster of Khronos.org
and OpenGL.org.

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

@ -5,7 +5,7 @@
[appendix]
[[extensions]]
= Layers & Extensions
= Layers & Extensions (Informative)
Extensions to the Vulkan API can: be defined by authors, groups of authors,
and the Khronos Vulkan Working Group.
@ -35,25 +35,21 @@ Versions of the Specification published in the Registry include:
* Core API + all registered and published Khronos (`KHR`) extensions.
* Core API + all registered and published extensions.
Extensions are grouped as Khronos `KHR`, Khronos `KHX`, multivendor `EXT`,
and then alphabetically by author ID.
Extensions are grouped as Khronos `KHR`, multivendor `EXT`, and then
alphabetically by author ID.
Within each group, extensions are listed in alphabetical order by their
name.
[NOTE]
.Note
====
The `KHX` author ID indicates that an extension is experimental, and is
being considered for standardization in future `KHR` or core Vulkan API
versions.
Developers are encouraged to experiment with them and provide feedback, but
should: not use them as the basis for production applications.
`KHX` extensions are expected to be supported for a limited time only.
They may: change their interfaces and behavior in significant ways as a
result of feedback, and may: be withdrawn or replaced with stable `KHR` or
core functionality at any time.
Implementations of these extensions receive limited or no testing when
submitted to the Khronos conformance process.
As of the initial Vulkan 1.1 public release, the `KHX` author ID is no
longer used.
All `KHX` extensions have been promoted to `KHR` status.
Previously, this author ID was used to indicate that an extension was
experimental, and is being considered for standardization in future `KHR` or
core Vulkan API versions.
We no longer use this mechanism for exposing experimental functionality.
Some vendors may use an alternate author ID ending in `X` for some of their
extensions.
@ -81,13 +77,21 @@ ifdef::VK_KHR_bind_memory2[]
include::VK_KHR_bind_memory2.txt[]
endif::VK_KHR_bind_memory2[]
ifdef::VK_KHR_dedicated_allocation[]
include::VK_KHR_dedicated_allocation.txt[]
endif::VK_KHR_dedicated_allocation[]
ifdef::VK_KHR_descriptor_update_template[]
include::VK_KHR_descriptor_update_template.txt[]
endif::VK_KHR_descriptor_update_template[]
ifdef::VK_KHR_dedicated_allocation[]
include::VK_KHR_dedicated_allocation.txt[]
endif::VK_KHR_dedicated_allocation[]
ifdef::VK_KHR_device_group[]
include::VK_KHR_device_group.txt[]
endif::VK_KHR_device_group[]
ifdef::VK_KHR_device_group_creation[]
include::VK_KHR_device_group_creation.txt[]
endif::VK_KHR_device_group_creation[]
ifdef::VK_KHR_display[]
include::VK_KHR_display.txt[]
@ -173,10 +177,18 @@ ifdef::VK_KHR_maintenance2[]
include::VK_KHR_maintenance2.txt[]
endif::VK_KHR_maintenance2[]
ifdef::VK_KHR_maintenance3[]
include::VK_KHR_maintenance3.txt[]
endif::VK_KHR_maintenance3[]
ifdef::VK_KHR_mir_surface[]
include::VK_KHR_mir_surface.txt[]
endif::VK_KHR_mir_surface[]
ifdef::VK_KHR_multiview[]
include::VK_KHR_multiview.txt[]
endif::VK_KHR_multiview[]
ifdef::VK_KHR_push_descriptor[]
include::VK_KHR_push_descriptor.txt[]
endif::VK_KHR_push_descriptor[]
@ -235,20 +247,6 @@ ifdef::VK_KHR_xlib_surface[]
include::VK_KHR_xlib_surface.txt[]
endif::VK_KHR_xlib_surface[]
// == Khronos `KHX` Extensions
//
ifdef::VK_KHX_device_group[]
include::VK_KHX_device_group.txt[]
endif::VK_KHX_device_group[]
ifdef::VK_KHX_device_group_creation[]
include::VK_KHX_device_group_creation.txt[]
endif::VK_KHX_device_group_creation[]
ifdef::VK_KHX_multiview[]
include::VK_KHX_multiview.txt[]
endif::VK_KHX_multiview[]
// == Multivendor `EXT` Extensions
//
@ -274,6 +272,10 @@ ifdef::VK_EXT_debug_report[]
include::VK_EXT_debug_report.txt[]
endif::VK_EXT_debug_report[]
ifdef::VK_EXT_debug_utils[]
include::VK_EXT_debug_utils.txt[]
endif::VK_EXT_debug_utils[]
ifdef::VK_EXT_depth_range_unrestricted[]
include::VK_EXT_depth_range_unrestricted.txt[]
endif::VK_EXT_depth_range_unrestricted[]
@ -354,6 +356,10 @@ ifdef::VK_EXT_validation_cache[]
include::VK_EXT_validation_cache.txt[]
endif::VK_EXT_validation_cache[]
ifdef::VK_EXT_vertex_attribute_divisor[]
include::VK_EXT_vertex_attribute_divisor.txt[]
endif::VK_EXT_vertex_attribute_divisor[]
// :leveloffset: 1
@ -482,14 +488,14 @@ ifdef::VK_NV_dedicated_allocation[]
include::VK_NV_dedicated_allocation.txt[]
endif::VK_NV_dedicated_allocation[]
ifdef::VK_NV_external_memory[]
include::VK_NV_external_memory.txt[]
endif::VK_NV_external_memory[]
ifdef::VK_NV_external_memory_capabilities[]
include::VK_NV_external_memory_capabilities.txt[]
endif::VK_NV_external_memory_capabilities[]
ifdef::VK_NV_external_memory[]
include::VK_NV_external_memory.txt[]
endif::VK_NV_external_memory[]
ifdef::VK_NV_external_memory_win32[]
include::VK_NV_external_memory_win32.txt[]
endif::VK_NV_external_memory_win32[]

165
doc/specs/vulkan/appendices/glossary.txt
View File

@ -7,6 +7,7 @@
// API/extension-writing-guidelines appendix, anyway.
[glossary]
[[glossary]]
= Glossary
The terms defined in this section are used consistently throughout this
@ -276,7 +277,7 @@ Device::
The processor(s) and execution environment that perform tasks requested
by the application via the Vulkan API.
ifdef::VK_KHX_device_group_creation[]
ifdef::VK_VERSION_1_1,VK_KHR_device_group_creation[]
Device Group::
A set of physical devices that support accessing each other's memory and
recording a single command buffer that can: be executed on all the
@ -293,16 +294,24 @@ Device Mask::
A device mask value is valid if every bit that is set in the mask is at
a bit position that is less than the number of physical devices in the
logical device.
endif::VK_KHX_device_group_creation[]
endif::VK_VERSION_1_1,VK_KHR_device_group_creation[]
Device Memory::
Memory accessible to the device.
Represented by a slink:VkDeviceMemory object.
Device-Level Command::
Any command that is dispatched from a logical device, or from a child
object of a logical device.
Device-Level Functionality::
All device-level commands and objects, and their structures, enumerated
types, and enumerants.
Device-Level Object::
Logical device objects and their child objects For example,
slink:VkDevice, slink:VkQueue, and slink:VkCommandBuffer objects are
device-level objects.
Logical device objects and their child objects.
For example, slink:VkDevice, slink:VkQueue, and slink:VkCommandBuffer
objects are device-level objects.
Device-Local Memory::
Memory that is connected to the device, and may: be more performant for
@ -314,13 +323,13 @@ Direct Drawing Commands::
_indirect drawing commands_).
Includes flink:vkCmdDraw, and flink:vkCmdDrawIndexed.
ifdef::VK_KHR_sampler_ycbcr_conversion[]
ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
Disjoint::
_Disjoint planes_ are _image planes_ to which memory is bound
independently. +
A _disjoint image_ consists of multiple _disjoint planes_, and is
created with the ename:VK_IMAGE_CREATE_DISJOINT_BIT_KHR bit set.
endif::VK_KHR_sampler_ycbcr_conversion[]
created with the ename:VK_IMAGE_CREATE_DISJOINT_BIT bit set.
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
Dispatchable Handle::
A handle of a pointer handle type which may: be used by layers as part
@ -386,20 +395,20 @@ Execution Dependency Chain::
A sequence of execution dependencies that transitively act as a single
execution dependency.
ifdef::VK_KHR_sampler_ycbcr_conversion[]
ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
Explicit chroma reconstruction::
An implementation of sampler Y'C~B~C~R~ conversion which reconstructs
reduced-resolution chroma samples to luma resolution and then separately
performs texture sample interpolation.
This is distinct from an implicit implementation, which incorporates
chroma sample reconstruction into texture sample interpolation.
endif::VK_KHR_sampler_ycbcr_conversion[]
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
Extension Scope::
The set of objects and commands that can: be affected by an extension.
Extensions are either device scope or instance scope.
ifdef::VK_KHR_external_memory_capabilities,VK_KHR_external_semaphore_capabilities,VK_KHR_external_fence_capabilities[]
ifdef::VK_VERSION_1_1,VK_KHR_external_memory_capabilities,VK_KHR_external_semaphore_capabilities,VK_KHR_external_fence_capabilities[]
External Handle::
A resource handle which has meaning outside of a specific Vulkan device
or its parent instance.
@ -410,7 +419,7 @@ External Handle::
instance and may: be transferred between processes, or otherwise
manipulated via functionality defined by the platform for that handle
type.
endif::VK_KHR_external_memory_capabilities,VK_KHR_external_semaphore_capabilities,VK_KHR_external_fence_capabilities[]
endif::VK_VERSION_1_1,VK_KHR_external_memory_capabilities,VK_KHR_external_semaphore_capabilities,VK_KHR_external_fence_capabilities[]
External synchronization::
A type of synchronization required: of the application, where parameters
@ -548,7 +557,7 @@ Identically Defined Objects::
allocation functions, with the exception of pname:pAllocator, are +
. Vulkan handles which refer to the same object or
. identical scalar or enumeration values or
. CPU pointers which point to an array of values or structures which
. Host pointers which point to an array of values or structures which
also satisfy these three constraints.
Image::
@ -573,7 +582,7 @@ Immutable Sampler::
and that is used for that binding in all descriptor sets allocated from
the layout, and cannot be changed.
ifdef::VK_KHR_sampler_ycbcr_conversion[]
ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
Implicit chroma reconstruction::
An implementation of sampler Y'C~B~C~R~ conversion which reconstructs
the reduced-resolution chroma samples directly at the sample point, as
@ -582,7 +591,7 @@ Implicit chroma reconstruction::
implementation, which reconstructs the reduced-resolution chroma samples
to the resolution of the luma samples, then filters the result as part
of texture sample interpolation.
endif::VK_KHR_sampler_ycbcr_conversion[]
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
Implicitly-Enabled Layer::
A layer enabled by a loader-defined mechanism outside the Vulkan API,
@ -645,13 +654,20 @@ Instance::
connection to the implementation.
Represented by a slink:VkInstance object.
Instance-Level Object::
High-level Vulkan objects, which are not logical devices, nor children
of logical devices.
For example, slink:VkInstance and slink:VkPhysicalDevice objects are
instance-level objects.
Instance-Level Command::
Any command that is dispatched from an instance, or from a child object
of an instance, except for physical devices and their children.
ifdef::VK_KHX_device_group[]
Instance-Level Functionality::
All instance-level commands and objects, and their structures,
enumerated types, and enumerants.
Instance-Level Object::
High-level Vulkan objects, which are not physical devices, nor children
of physical devices.
For example, slink:VkInstance is an instance-level object.
ifdef::VK_VERSION_1_1,VK_KHR_device_group[]
Instance (Memory)::
In a logical device representing more than one physical device, some
device memory allocations have the requested amount of memory allocated
@ -663,7 +679,7 @@ Instance (Resource)::
and image resources exist on all physical devices but can: be bound to
memory differently on each.
Each such replicated resource is an instance of the resource.
endif::VK_KHX_device_group[]
endif::VK_VERSION_1_1,VK_KHR_device_group[]
Internal Synchronization::
A type of synchronization required: of the implementation, where
@ -689,7 +705,8 @@ Linear Resource::
Local Workgroup::
A collection of compute shader invocations invoked by a single dispatch
command, which share shared memory and can synchronize with each other.
command, which share data via code:WorkgroupLocal variables and can
synchronize with each other.
Logical Device::
An object that represents the application's interface to the physical
@ -703,8 +720,8 @@ Logical Operation::
attachment.
Lost Device::
A state that a logical device may: be in as a result of hardware errors
or other exceptional conditions.
A state that a logical device may: be in as a result of unrecoverable
implementation errors, or other exceptional conditions.
Mappable::
See Host-Visible Memory.
@ -729,7 +746,7 @@ Mip Tail Region::
small to fill a sparse block, and that must: all be bound to memory
collectively and opaquely.
ifdef::VK_KHR_sampler_ycbcr_conversion[]
ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
Multi-planar::
A _multi-planar format_ (or "`planar format`") is an image format
consisting of more than one _plane_, identifiable with a etext:_2PLANE
@ -737,7 +754,7 @@ Multi-planar::
<<features-formats-requiring-sampler-ycbcr-conversion>>.
A _multi-planar image_ (or "`planar image`") is an image of a
multi-planar format.
endif::VK_KHR_sampler_ycbcr_conversion[]
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
Non-Dispatchable Handle::
A handle of an integer handle type.
@ -792,23 +809,34 @@ Passthrough Geometry Shader::
vertices.
endif::VK_NV_geometry_shader_passthrough[]
ifdef::VK_KHR_external_semaphore,VK_KHR_external_fence[]
ifdef::VK_VERSION_1_1,VK_KHR_external_semaphore,VK_KHR_external_fence[]
Payload::
Importable or exportable reference to the internal data of an object in
Vulkan.
endif::VK_KHR_external_semaphore,VK_KHR_external_fence[]
endif::VK_VERSION_1_1,VK_KHR_external_semaphore,VK_KHR_external_fence[]
ifdef::VK_KHX_device_group[]
ifdef::VK_VERSION_1_1,VK_KHR_device_group[]
Peer Memory::
An instance of memory corresponding to a different physical device than
the physical device performing the memory access, in a logical device
that represents multiple physical devices.
endif::VK_KHX_device_group[]
endif::VK_VERSION_1_1,VK_KHR_device_group[]
Physical Device::
An object that represents a single device in the system.
Represented by a slink:VkPhysicalDevice object.
Physical-Device-Level Command::
Any command that is dispatched from a physical device.
Physical-Device-Level Functionality::
All physical-device-level commands and objects, and their structures,
enumerated types, and enumerants.
Physical-Device-Level Object::
Physical device objects.
For example, slink:VkPhysicalDevice is a physical-device-level object.
Pipeline::
An object that controls how graphics or compute work is executed on the
device.
@ -843,7 +871,7 @@ pname:pNext Chain::
A set of structures <<fundamentals-validusage-pNext,chained together>>
through their ptext:pNext members.
ifdef::VK_KHR_sampler_ycbcr_conversion[]
ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
Planar::
See _multi-planar_.
@ -856,10 +884,10 @@ Plane::
The host-accessible properties of each image plane are accessed in a
linear layout using flink:vkGetImageSubresourceLayout.
If a multi-planar image is created with the
ename:VK_IMAGE_CREATE_DISJOINT_BIT_KHR bit set, the image is described
as _disjoint_, and its planes are therefore are bound to memory
ename:VK_IMAGE_CREATE_DISJOINT_BIT bit set, the image is described as
_disjoint_, and its planes are therefore are bound to memory
independently.
endif::VK_KHR_sampler_ycbcr_conversion[]
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
Point Sampling (Rasterization)::
A rule that determines whether a fragment sample location is covered by
@ -887,6 +915,33 @@ Primitive Topology::
State that controls how vertices are assembled into primitives, e.g. as
lists of triangles, strips of lines, etc..
ifdef::VK_VERSION_1_1[]
Promoted::
An extension whose interfaces are later made available as part of a
<<versions-1.1,core version of the API>>, with the author ID suffixes
removed, is said to be _promoted_ to that core version.
Minor differences, such as making the availability of specific features
from the extension supported only if a corresponding feature bit is
enabled, may still exist.
Protected Buffer::
A buffer to which protected device memory can: be bound.
Protected-capable Device Queue::
A device queue to which protected command buffers can: be submitted.
Protected Command Buffer::
A command buffer which can: be submitted to a protected-capable device
queue.
Protected Device Memory::
Device memory which can: be visible to the device but must: not be
visible to the host.
Protected Image::
An image to which protected device memory can: be bound.
endif::VK_VERSION_1_1[]
Provoking Vertex::
The vertex in a primitive from which flat shaded attribute values are
taken.
@ -912,13 +967,13 @@ Push Descriptors::
shaders without allocating or modifying descriptor sets for each update.
endif::VK_KHR_push_descriptor[]
ifdef::VK_KHR_descriptor_update_template[]
ifdef::VK_VERSION_1_1,VK_KHR_descriptor_update_template[]
Descriptor Update Template::
An object that specifies a mapping from descriptor update information in
host memory to elements in a descriptor set, which helps enable more
efficient descriptor set updates.
endif::VK_KHR_descriptor_update_template[]
endif::VK_VERSION_1_1,VK_KHR_descriptor_update_template[]
Query Pool::
An object that contains a number of query entries and their associated
@ -1042,10 +1097,10 @@ Side Effect::
A store to memory or atomic operation on memory from a shader
invocation.
ifdef::VK_KHR_sampler_ycbcr_conversion[]
ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
Single-plane format::
A format that is not _multi-planar_.
endif::VK_KHR_sampler_ycbcr_conversion[]
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
Sparse Block::
An element of a sparse resource that can be independently bound to
@ -1083,20 +1138,20 @@ Storage Texel Buffer::
A descriptor type that represents a buffer view, and supports
unfiltered, formatted reads, writes, and atomics in a shader.
ifdef::VK_EXT_shader_subgroup_vote[]
ifdef::VK_EXT_shader_subgroup_vote,VK_VERSION_1_1[]
Subgroup::
The set of shader invocations exposed as running concurrently with the
current shader invocation.
A set of shader invocations that can: synchronize and share data with
each other efficiently.
In compute shaders, the _local workgroup_ is a superset of the subgroup.
endif::VK_EXT_shader_subgroup_vote[]
endif::VK_EXT_shader_subgroup_vote,VK_VERSION_1_1[]
ifdef::VK_EXT_shader_subgroup_ballot[]
ifdef::VK_EXT_shader_subgroup_ballot,VK_VERSION_1_1[]
Subgroup Mask::
A bitmask for all invocations in the current subgroup with one bit per
invocation, starting with the least significant bit in the first vector
component, continuing to the last bit (less than code:SubgroupSize) in
the last required vector component.
endif::VK_EXT_shader_subgroup_ballot[]
endif::VK_EXT_shader_subgroup_ballot,VK_VERSION_1_1[]
Subpass::
A phase of rendering within a render pass, that reads and writes a
@ -1138,6 +1193,22 @@ Unnormalized::
A value that is interpreted according to its conventional
interpretation, and is not normalized.
ifdef::VK_VERSION_1_1[]
Unprotected Buffer::
A buffer to which unprotected device memory can: be bound.
Unprotected Command Buffer::
A command buffer which can: be submitted to an unprotected device queue
or a protected-capable device queue.
Unprotected Device Memory::
Device memory which can: be visible to the device and can: be visible to
the host.
Unprotected Image::
An image to which unprotected device memory can: be bound.
endif::VK_VERSION_1_1[]
User-Defined Variable Interface::
A shader entry point's variables with code:Input or code:Output storage
class that are not built-in variables.
@ -1168,11 +1239,11 @@ Vertex Processing Stages::
control shader, tessellation evaluation shader, and geometry shader
stages.
ifdef::VK_KHX_multiview[]
ifdef::VK_VERSION_1_1,VK_KHR_multiview[]
View Mask::
When multiview is enabled, a view mask is a property of a subpass
controlling which views the rendering commands are broadcast to.
endif::VK_KHX_multiview[]
endif::VK_VERSION_1_1,VK_KHR_multiview[]
View Volume::
A subspace in homogeneous coordinates, corresponding to post-projection

128
doc/specs/vulkan/appendices/spirvenv.txt
View File

@ -14,8 +14,15 @@ shaders.
== Versions and Formats
ifdef::VK_VERSION_1_1[]
A Vulkan 1.1 implementation must: support the 1.0, 1.1, 1.2, and 1.3
versions of SPIR-V and the 1.0 version of the SPIR-V Extended Instructions
for GLSL.
endif::VK_VERSION_1_1[]
ifndef::VK_VERSION_1_1[]
A Vulkan 1.0 implementation must: support the 1.0 version of SPIR-V and the
1.0 version of the SPIR-V Extended Instructions for GLSL.
endif::VK_VERSION_1_1[]
A SPIR-V module passed into flink:vkCreateShaderModule is interpreted as a
series of 32-bit words in host endianness, with literal strings packed as
@ -40,14 +47,19 @@ code:OpCapability:
* code:ImageBuffer
* code:ImageQuery
* code:DerivativeControl
ifdef::VK_VERSION_1_1,VK_KHR_device_group[]
* code:DeviceGroup
endif::VK_VERSION_1_1,VK_KHR_device_group[]
ifdef::VK_VERSION_1_1,VK_KHR_multiview[]
* code:MultiView
endif::VK_VERSION_1_1,VK_KHR_multiview[]
Implementations may: support features that are not required: by the
Specification, as described in the <<features-features,Features>> chapter.
If such a feature is supported, then any capability operand(s) corresponding
to that feature must: also be supported.
If the implementation supports any of the optional: features described in
the <<features-features,Features>> chapter, then the capability operand(s)
corresponding to that feature must: also be supported.
[[spirvenv-capabilities-table]]
.SPIR-V Capabilities which are not required:, and corresponding feature or extension names
.List of optional: SPIR-V Capabilities and corresponding feature or extension names
[options="header"]
|====
| SPIR-V OpCapability | Vulkan feature or extension name
@ -77,15 +89,26 @@ to that feature must: also be supported.
| code:StorageImageReadWithoutFormat | <<features-features-shaderStorageImageReadWithoutFormat,shaderStorageImageReadWithoutFormat>>
| code:StorageImageWriteWithoutFormat | <<features-features-shaderStorageImageWriteWithoutFormat,shaderStorageImageWriteWithoutFormat>>
| code:MultiViewport | <<features-features-multiViewport,multiViewport>>
ifdef::VK_KHR_shader_draw_parameters[]
[[spirvenv-capabilities-table-drawparameters]]
| code:DrawParameters | `<<VK_KHR_shader_draw_parameters>>`
endif::VK_KHR_shader_draw_parameters[]
ifdef::VK_KHR_variable_pointers[]
ifdef::VK_VERSION_1_1,VK_KHR_shader_draw_parameters[]
| code:DrawParameters
| `<<VK_KHR_shader_draw_parameters>>`
ifdef::VK_VERSION_1_1[]
or <<features-features-shaderDrawParameters,shaderDrawParameters>>
endif::VK_VERSION_1_1[]
endif::VK_VERSION_1_1,VK_KHR_shader_draw_parameters[]
ifndef::VK_VERSION_1_1[]
ifdef::VK_KHR_multiview[]
| code:MultiView | <<VK_KHR_multiview,VK_KHR_multiview>>
endif::VK_KHR_multiview[]
ifdef::VK_KHR_device_group[]
| code:DeviceGroup | <<VK_KHR_device_group,VK_KHR_device_group>>
endif::VK_KHR_device_group[]
endif::VK_VERSION_1_1[]
ifdef::VK_VERSION_1_1,VK_KHR_variable_pointers[]
[[spirvenv-capabilities-table-variablepointers]]
| code:VariablePointersStorageBuffer | <<features-features-variablePointersStorageBuffer,variablePointersStorageBuffer>>
| code:VariablePointers | <<features-features-variablePointers,variablePointers>>
endif::VK_KHR_variable_pointers[]
endif::VK_VERSION_1_1,VK_KHR_variable_pointers[]
ifdef::VK_EXT_shader_stencil_export[]
[[spirvenv-capabilities-table-shaderstencilexportext]]
| code:StencilExportEXT | `<<VK_EXT_shader_stencil_export>>`
@ -98,14 +121,6 @@ ifdef::VK_EXT_shader_subgroup_vote[]
[[spirvenv-capabilities-table-subgroupvote]]
| code:SubgroupVoteKHR | `<<VK_EXT_shader_subgroup_vote>>`
endif::VK_EXT_shader_subgroup_vote[]
ifdef::VK_KHX_multiview[]
[[spirvenv-capabilities-table-multiview]]
| code:MultiView | `<<VK_KHX_multiview>>`
endif::VK_KHX_multiview[]
ifdef::VK_KHX_device_group[]
[[spirvenv-capabilities-table-devicegroup]]
| code:DeviceGroup | `<<VK_KHX_device_group>>`
endif::VK_KHX_device_group[]
ifdef::VK_AMD_shader_image_load_store_lod[]
[[spirvenv-capabilities-table-imagereadwritelodamd]]
| code:ImageReadWriteLodAMD | `<<VK_AMD_shader_image_load_store_lod>>`
@ -139,23 +154,34 @@ ifdef::VK_NVX_multiview_per_view_attributes[]
[[spirvenv-capabilities-table-perviewattributes]]
| code:PerViewAttributesNV | `<<VK_NVX_multiview_per_view_attributes>>`
endif::VK_NVX_multiview_per_view_attributes[]
ifdef::VK_KHR_16bit_storage[]
ifdef::VK_VERSION_1_1,VK_KHR_16bit_storage[]
[[spirvenv-capabilities-table-16bitstorage]]
| code:StorageBuffer16BitAccess | <<features-features-storageBuffer16BitAccess, StorageBuffer16BitAccess>>
| code:UniformAndStorageBuffer16BitAccess | <<features-features-uniformAndStorageBuffer16BitAccess,UniformAndStorageBuffer16BitAccess>>
| code:StoragePushConstant16 | <<features-features-storagePushConstant16,storagePushConstant16>>
| code:StorageInputOutput16 | <<features-features-storageInputOutput16,storageInputOutput16>>
endif::VK_KHR_16bit_storage[]
endif::VK_VERSION_1_1,VK_KHR_16bit_storage[]
ifdef::VK_VERSION_1_1[]
[[spirvenv-capabilities-table-subgroup]]
| code:GroupNonUniform | <<features-features-subgroup-basic,VK_SUBGROUP_FEATURE_BASIC_BIT>>
| code:GroupNonUniformVote | <<features-features-subgroup-vote,VK_SUBGROUP_FEATURE_VOTE_BIT>>
| code:GroupNonUniformArithmetic | <<features-features-subgroup-arithmetic,VK_SUBGROUP_FEATURE_ARITHMETIC_BIT>>
| code:GroupNonUniformBallot | <<features-features-subgroup-ballot,VK_SUBGROUP_FEATURE_BALLOT_BIT>>
| code:GroupNonUniformShuffle | <<features-features-subgroup-shuffle,VK_SUBGROUP_FEATURE_SHUFFLE_BIT>>
| code:GroupNonUniformShuffleRelative | <<features-features-subgroup-shuffle-relative,VK_SUBGROUP_FEATURE_SHUFFLE_RELATIVE_BIT>>
| code:GroupNonUniformClustered | <<features-features-subgroup-clustered,VK_SUBGROUP_FEATURE_CLUSTERED_BIT>>
| code:GroupNonUniformQuad | <<features-features-subgroup-quad,VK_SUBGROUP_FEATURE_QUAD_BIT>>
endif::VK_VERSION_1_1[]
ifdef::VK_EXT_post_depth_coverage[]
[[spirvenv-capabilities-table-postdepthcoverage]]
| code:SampleMaskPostDepthCoverage | `<<VK_EXT_post_depth_coverage>>`
endif::VK_EXT_post_depth_coverage[]
|====
ifdef::VK_KHR_variable_pointers[]
ifdef::VK_VERSION_1_1,VK_KHR_variable_pointers[]
The application can: pass a SPIR-V module to flink:vkCreateShaderModule that
uses the +SPV_KHR_variable_pointers+ SPIR-V extension.
endif::VK_KHR_variable_pointers[]
endif::VK_VERSION_1_1,VK_KHR_variable_pointers[]
ifdef::VK_AMD_shader_explicit_vertex_parameter[]
The application can: pass a SPIR-V module to flink:vkCreateShaderModule that
@ -202,24 +228,24 @@ The application can: pass a SPIR-V module to flink:vkCreateShaderModule that
uses the +SPV_AMD_texture_gather_bias_lod+ SPIR-V extension.
endif::VK_AMD_texture_gather_bias_lod[]
ifdef::VK_KHR_shader_draw_parameters[]
ifdef::VK_VERSION_1_1,VK_KHR_shader_draw_parameters[]
The application can: pass a SPIR-V module to flink:vkCreateShaderModule that
uses the +SPV_KHR_shader_draw_parameters+ SPIR-V extension.
endif::VK_KHR_shader_draw_parameters[]
endif::VK_VERSION_1_1,VK_KHR_shader_draw_parameters[]
ifdef::VK_KHR_16bit_storage[]
ifdef::VK_VERSION_1_1,VK_KHR_16bit_storage[]
The application can: pass a SPIR-V module to flink:vkCreateShaderModule that
uses the
https://www.khronos.org/registry/spir-v/extensions/KHR/SPV_KHR_16bit_storage.html[+SPV_KHR_16bit_storage+]
SPIR-V extension.
endif::VK_KHR_16bit_storage[]
endif::VK_VERSION_1_1,VK_KHR_16bit_storage[]
ifdef::VK_KHR_storage_buffer_storage_class[]
ifdef::VK_VERSION_1_1,VK_KHR_storage_buffer_storage_class[]
The application can: pass a SPIR-V module to flink:vkCreateShaderModule that
uses the
https://www.khronos.org/registry/spir-v/extensions/KHR/SPV_KHR_storage_buffer_storage_class.html[+SPV_KHR_storage_buffer_storage_class+]
SPIR-V extension.
endif::VK_KHR_storage_buffer_storage_class[]
endif::VK_VERSION_1_1,VK_KHR_storage_buffer_storage_class[]
ifdef::VK_EXT_post_depth_coverage[]
The application can: pass a SPIR-V module to flink:vkCreateShaderModule that
@ -291,7 +317,14 @@ following rules:
* *Scope* for memory must: be limited to:
** *Device*
** *Workgroup*
ifdef::VK_VERSION_1_1[]
** *Subgroup*
endif::VK_VERSION_1_1[]
** *Invocation*
ifdef::VK_VERSION_1_1[]
* *Scope* for *Non Uniform Group Operations* must: be limited to:
** *Subgroup*
endif::VK_VERSION_1_1[]
* *Storage Class* must: be limited to:
** *UniformConstant*
** *Input*
@ -302,9 +335,9 @@ following rules:
** *Function*
** *PushConstant*
** *Image*
ifdef::VK_KHR_storage_buffer_storage_class[]
ifdef::VK_VERSION_1_1,VK_KHR_storage_buffer_storage_class[]
** *StorageBuffer*
endif::VK_KHR_storage_buffer_storage_class[]
endif::VK_VERSION_1_1,VK_KHR_storage_buffer_storage_class[]
* Memory semantics must: obey the following rules:
** *Acquire* must: not be used with code:OpAtomicStore.
** *Release* must: not be used with code:OpAtomicLoad.
@ -363,29 +396,52 @@ ifdef::VK_NV_viewport_array2[]
both be statically used by one or more code:OpEntryPoint's that form
the vertex processing stages of a graphics pipeline.
endif::VK_NV_viewport_array2[]
ifdef::VK_KHR_16bit_storage[]
ifdef::VK_VERSION_1_1,VK_KHR_16bit_storage[]
** Only the round-to-nearest-even and the round-to-zero rounding modes
can: be used for the code:FPRoundingMode decoration.
** The code:FPRoundingMode decoration can: only be used for the
floating-point conversion instructions as described in the
https://www.khronos.org/registry/spir-v/extensions/KHR/SPV_KHR_16bit_storage.html[+SPV_KHR_16bit_storage+]
SPIR-V extension.
endif::VK_KHR_16bit_storage[]
endif::VK_VERSION_1_1,VK_KHR_16bit_storage[]
* code:OpTypeRuntimeArray must: only be used for the last member of an
code:OpTypeStruct
ifdef::VK_KHR_storage_buffer_storage_class[]
ifdef::VK_VERSION_1_1,VK_KHR_storage_buffer_storage_class[]
that is in the code:StorageBuffer storage class decorated as code:Block,
or
endif::VK_KHR_storage_buffer_storage_class[]
endif::VK_VERSION_1_1,VK_KHR_storage_buffer_storage_class[]
that is in the code:Uniform storage class decorated as code:BufferBlock.
* Linkage: See <<interfaces,Shader Interfaces>> for additional linking and
validation rules.
ifdef::VK_VERSION_1_1[]
* If code:OpControlBarrier is used in fragment, vertex, tessellation
evaluation, or geometry stages, the execution Scope must: be
code:Subgroup.
endif::VK_VERSION_1_1[]
* Compute Shaders
** For each compute shader entry point, either a code:LocalSize execution
mode or an object decorated with the code:WorkgroupSize decoration
must: be specified.
ifdef::VK_VERSION_1_1[]
* "`Result Type`" for *Non Uniform Group Operations* must: be limited to
32-bit float, 32-bit integer, boolean, or vectors of these types.
If the code:Float64 capability is enabled, double and vector of double
types are also permitted.
* "`Mask`" for code:OpGroupNonUniformShuffleXor must: be a specialization
constant or a constant, or if the dynamic instance is called within a
loop construct it must: be one of:
. A specialization constant.
. A constant.
. An arthimetic operation whose operands are 1., 2., or 4.
. A phi node whose operands are 1., 2., or 3.
* If code:OpGroupNonUniformBallotBitCount is used, the group operation
must: be one of:
** *Reduce*
** *InclusiveScan*
** *ExclusiveScan*
endif::VK_VERSION_1_1[]
* Atomic instructions must: declare a scalar 32-bit integer type for the
"`Result Type`".
_Result Type_ and the type of the value pointed to by _Pointer_.
[[spirvenv-precision-operation]]

372
doc/specs/vulkan/appendices/versions.txt Normal file
View File

@ -0,0 +1,372 @@
// Copyright (c) 2015-2018 Khronos Group. This work is licensed under a
// Creative Commons Attribution 4.0 International License; see
// http://creativecommons.org/licenses/by/4.0/
[appendix]
[[versions]]
= Core Revisions (Informative)
New minor versions of the Vulkan API are defined periodically by the Khronos
Vulkan Working Group.
These consist of some amount of additional functionality added to the core
API, some of which may: be promoted from extensions, other parts of which
may: be new.
Extensions that are promoted in this way typically have their functionality
replicated directly in the core, but with extension suffixes dropped.
The existing values with suffixes are still present in the API itself as
aliases of the original extension functionality.
Any differences between the core and extension version of the functionality
will be documented in the extension appendix, and mentioned briefly in the
version description in this appendix.
It's possible to build the specification for earlier versions, but to aid
readability of the latest versions, this appendix gives an overview of the
changes as compared to earlier versions.
ifdef::VK_VERSION_1_1[]
[[versions-1.1]]
== Version 1.1
Vulkan Version 1.1 _promoted_ a number of key extensions into the core API:
* <<VK_KHR_16bit_storage>>
* <<VK_KHR_bind_memory2>>
* <<VK_KHR_dedicated_allocation>>
* <<VK_KHR_descriptor_update_template>>
* <<VK_KHR_device_group>>
* <<VK_KHR_device_group_creation>>
* <<VK_KHR_external_memory>>
* <<VK_KHR_external_memory_capabilities>>
* <<VK_KHR_external_semaphore>>
* <<VK_KHR_external_semaphore_capabilities>>
* <<VK_KHR_external_fence>>
* <<VK_KHR_external_fence_capabilities>>
* <<VK_KHR_get_memory_requirements2>>
* <<VK_KHR_get_physical_device_properties2>>
* <<VK_KHR_maintenance1>>
* <<VK_KHR_maintenance2>>
* <<VK_KHR_maintenance3>>
* <<VK_KHR_multiview>>
* <<VK_KHR_relaxed_block_layout>>
* <<VK_KHR_sampler_ycbcr_conversion>>
* <<VK_KHR_shader_draw_parameters>>
* <<VK_KHR_storage_buffer_storage_class>>
* <<VK_KHR_variable_pointers>>
The only changes to the functionality added by these extensions were to
VK_KHR_shader_draw_parameters, which had a
<<features-feature-shaderDrawParameters, feature bit>> added to determine
support in the core API, and
<<features-feature-variablePointerStorageBuffer,
pname:variablePointerStorageBuffer>> from VK_KHR_variable_pointers was made
optional.
Additionally, Vulkan 1.1 added support for
<<VkPhysicalDeviceSubgroupProperties, subgroup operations>>,
<<VkPhysicalDeviceProtectedMemoryFeatures, protected memory>>, and a new
command to <<vkEnumerateInstanceVersion, enumerate the instance version>>.
=== New Object Types
* VkDescriptorUpdateTemplate
* VkSamplerYcbcrConversion
=== New Defines
* VK_API_VERSION_1_1
=== New Enum Constants
* Extending elink:VkBufferCreateFlagBits:
** ename:VK_BUFFER_CREATE_PROTECTED_BIT
* Extending elink:VkCommandPoolCreateFlagBits:
** ename:VK_COMMAND_POOL_CREATE_PROTECTED_BIT
* Extending elink:VkDependencyFlagBits:
** ename:VK_DEPENDENCY_DEVICE_GROUP_BIT
** ename:VK_DEPENDENCY_VIEW_LOCAL_BIT
* Extending elink:VkDeviceQueueCreateFlagBits:
** ename:VK_DEVICE_QUEUE_CREATE_PROTECTED_BIT
* Extending elink:VkFormat:
** ename:VK_FORMAT_G8B8G8R8_422_UNORM
** ename:VK_FORMAT_B8G8R8G8_422_UNORM
** ename:VK_FORMAT_G8_B8_R8_3PLANE_420_UNORM
** ename:VK_FORMAT_G8_B8R8_2PLANE_420_UNORM
** ename:VK_FORMAT_G8_B8_R8_3PLANE_422_UNORM
** ename:VK_FORMAT_G8_B8R8_2PLANE_422_UNORM
** ename:VK_FORMAT_G8_B8_R8_3PLANE_444_UNORM
** ename:VK_FORMAT_R10X6_UNORM_PACK16
** ename:VK_FORMAT_R10X6G10X6_UNORM_2PACK16
** ename:VK_FORMAT_R10X6G10X6B10X6A10X6_UNORM_4PACK16
** ename:VK_FORMAT_G10X6B10X6G10X6R10X6_422_UNORM_4PACK16
** ename:VK_FORMAT_B10X6G10X6R10X6G10X6_422_UNORM_4PACK16
** ename:VK_FORMAT_G10X6_B10X6_R10X6_3PLANE_420_UNORM_3PACK16
** ename:VK_FORMAT_G10X6_B10X6R10X6_2PLANE_420_UNORM_3PACK16
** ename:VK_FORMAT_G10X6_B10X6_R10X6_3PLANE_422_UNORM_3PACK16
** ename:VK_FORMAT_G10X6_B10X6R10X6_2PLANE_422_UNORM_3PACK16
** ename:VK_FORMAT_G10X6_B10X6_R10X6_3PLANE_444_UNORM_3PACK16
** ename:VK_FORMAT_R12X4_UNORM_PACK16
** ename:VK_FORMAT_R12X4G12X4_UNORM_2PACK16
** ename:VK_FORMAT_R12X4G12X4B12X4A12X4_UNORM_4PACK16
** ename:VK_FORMAT_G12X4B12X4G12X4R12X4_422_UNORM_4PACK16
** ename:VK_FORMAT_B12X4G12X4R12X4G12X4_422_UNORM_4PACK16
** ename:VK_FORMAT_G12X4_B12X4_R12X4_3PLANE_420_UNORM_3PACK16
** ename:VK_FORMAT_G12X4_B12X4R12X4_2PLANE_420_UNORM_3PACK16
** ename:VK_FORMAT_G12X4_B12X4_R12X4_3PLANE_422_UNORM_3PACK16
** ename:VK_FORMAT_G12X4_B12X4R12X4_2PLANE_422_UNORM_3PACK16
** ename:VK_FORMAT_G12X4_B12X4_R12X4_3PLANE_444_UNORM_3PACK16
** ename:VK_FORMAT_G16B16G16R16_422_UNORM
** ename:VK_FORMAT_B16G16R16G16_422_UNORM
** ename:VK_FORMAT_G16_B16_R16_3PLANE_420_UNORM
** ename:VK_FORMAT_G16_B16R16_2PLANE_420_UNORM
** ename:VK_FORMAT_G16_B16_R16_3PLANE_422_UNORM
** ename:VK_FORMAT_G16_B16R16_2PLANE_422_UNORM
** ename:VK_FORMAT_G16_B16_R16_3PLANE_444_UNORM
* Extending elink:VkFormatFeatureFlagBits:
** ename:VK_FORMAT_FEATURE_TRANSFER_SRC_BIT
** ename:VK_FORMAT_FEATURE_TRANSFER_DST_BIT
** ename:VK_FORMAT_FEATURE_MIDPOINT_CHROMA_SAMPLES_BIT
** ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_LINEAR_FILTER_BIT
** ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_SEPARATE_RECONSTRUCTION_FILTER_BIT
** ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_CHROMA_RECONSTRUCTION_EXPLICIT_BIT
** ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_CHROMA_RECONSTRUCTION_EXPLICIT_FORCEABLE_BIT
** ename:VK_FORMAT_FEATURE_DISJOINT_BIT
** ename:VK_FORMAT_FEATURE_COSITED_CHROMA_SAMPLES_BIT
* Extending elink:VkImageAspectFlagBits:
** ename:VK_IMAGE_ASPECT_PLANE_0_BIT
** ename:VK_IMAGE_ASPECT_PLANE_1_BIT
** ename:VK_IMAGE_ASPECT_PLANE_2_BIT
* Extending elink:VkImageCreateFlagBits:
** ename:VK_IMAGE_CREATE_ALIAS_BIT
** ename:VK_IMAGE_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT
** ename:VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT
** ename:VK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT
** ename:VK_IMAGE_CREATE_EXTENDED_USAGE_BIT
** ename:VK_IMAGE_CREATE_PROTECTED_BIT
** ename:VK_IMAGE_CREATE_DISJOINT_BIT
* Extending elink:VkImageCreateFlagBits:
** ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL
** ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL
* Extending elink:VkMemoryHeapFlagBits:
** ename:VK_MEMORY_HEAP_MULTI_INSTANCE_BIT
* Extending elink:VkMemoryPropertyFlagBits:
** ename:VK_MEMORY_PROPERTY_PROTECTED_BIT
* Extending elink:VkObjectType:
** ename:VK_OBJECT_TYPE_SAMPLER_YCBCR_CONVERSION
** ename:VK_OBJECT_TYPE_DESCRIPTOR_UPDATE_TEMPLATE
* Extending elink:VkPipelineCreateFlagBits:
** ename:VK_PIPELINE_CREATE_VIEW_INDEX_FROM_DEVICE_INDEX_BIT
** ename:VK_PIPELINE_CREATE_DISPATCH_BASE
* Extending elink:VkQueueFlagBits:
** ename:VK_QUEUE_PROTECTED_BIT
* Extending elink:VkResult:
** ename:VK_ERROR_OUT_OF_POOL_MEMORY
** ename:VK_ERROR_INVALID_EXTERNAL_HANDLE
* Extending elink:VkStructureType:
** ename:VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SUBGROUP_PROPERTIES
** ename:VK_STRUCTURE_TYPE_BIND_BUFFER_MEMORY_INFO
** ename:VK_STRUCTURE_TYPE_BIND_IMAGE_MEMORY_INFO
** ename:VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_16BIT_STORAGE_FEATURES
** ename:VK_STRUCTURE_TYPE_MEMORY_DEDICATED_REQUIREMENTS
** ename:VK_STRUCTURE_TYPE_MEMORY_DEDICATED_ALLOCATE_INFO
** ename:VK_STRUCTURE_TYPE_MEMORY_ALLOCATE_FLAGS_INFO
** ename:VK_STRUCTURE_TYPE_DEVICE_GROUP_RENDER_PASS_BEGIN_INFO
** ename:VK_STRUCTURE_TYPE_DEVICE_GROUP_COMMAND_BUFFER_BEGIN_INFO
** ename:VK_STRUCTURE_TYPE_DEVICE_GROUP_SUBMIT_INFO
** ename:VK_STRUCTURE_TYPE_DEVICE_GROUP_BIND_SPARSE_INFO
** ename:VK_STRUCTURE_TYPE_BIND_BUFFER_MEMORY_DEVICE_GROUP_INFO
** ename:VK_STRUCTURE_TYPE_BIND_IMAGE_MEMORY_DEVICE_GROUP_INFO
** ename:VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_GROUP_PROPERTIES
** ename:VK_STRUCTURE_TYPE_DEVICE_GROUP_DEVICE_CREATE_INFO
** ename:VK_STRUCTURE_TYPE_BUFFER_MEMORY_REQUIREMENTS_INFO_2
** ename:VK_STRUCTURE_TYPE_IMAGE_MEMORY_REQUIREMENTS_INFO_2
** ename:VK_STRUCTURE_TYPE_IMAGE_SPARSE_MEMORY_REQUIREMENTS_INFO_2
** ename:VK_STRUCTURE_TYPE_MEMORY_REQUIREMENTS_2
** ename:VK_STRUCTURE_TYPE_SPARSE_IMAGE_MEMORY_REQUIREMENTS_2
** ename:VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FEATURES_2
** ename:VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PROPERTIES_2
** ename:VK_STRUCTURE_TYPE_FORMAT_PROPERTIES_2
** ename:VK_STRUCTURE_TYPE_IMAGE_FORMAT_PROPERTIES_2
** ename:VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_IMAGE_FORMAT_INFO_2
** ename:VK_STRUCTURE_TYPE_QUEUE_FAMILY_PROPERTIES_2
** ename:VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MEMORY_PROPERTIES_2
** ename:VK_STRUCTURE_TYPE_SPARSE_IMAGE_FORMAT_PROPERTIES_2
** ename:VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SPARSE_IMAGE_FORMAT_INFO_2
** ename:VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_POINT_CLIPPING_PROPERTIES
** ename:VK_STRUCTURE_TYPE_RENDER_PASS_INPUT_ATTACHMENT_ASPECT_CREATE_INFO
** ename:VK_STRUCTURE_TYPE_IMAGE_VIEW_USAGE_CREATE_INFO
** ename:VK_STRUCTURE_TYPE_PIPELINE_TESSELLATION_DOMAIN_ORIGIN_STATE_CREATE_INFO
** ename:VK_STRUCTURE_TYPE_RENDER_PASS_MULTIVIEW_CREATE_INFO
** ename:VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MULTIVIEW_FEATURES
** ename:VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MULTIVIEW_PROPERTIES
** ename:VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VARIABLE_POINTER_FEATURES
** ename:VK_STRUCTURE_TYPE_PROTECTED_SUBMIT_INFO
** ename:VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PROTECTED_MEMORY_FEATURES
** ename:VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PROTECTED_MEMORY_PROPERTIES
** ename:VK_STRUCTURE_TYPE_DEVICE_QUEUE_INFO_2
** ename:VK_STRUCTURE_TYPE_SAMPLER_YCBCR_CONVERSION_CREATE_INFO
** ename:VK_STRUCTURE_TYPE_SAMPLER_YCBCR_CONVERSION_INFO
** ename:VK_STRUCTURE_TYPE_BIND_IMAGE_PLANE_MEMORY_INFO
** ename:VK_STRUCTURE_TYPE_IMAGE_PLANE_MEMORY_REQUIREMENTS_INFO
** ename:VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SAMPLER_YCBCR_CONVERSION_FEATURES
** ename:VK_STRUCTURE_TYPE_SAMPLER_YCBCR_CONVERSION_IMAGE_FORMAT_PROPERTIES
** ename:VK_STRUCTURE_TYPE_DESCRIPTOR_UPDATE_TEMPLATE_CREATE_INFO
** ename:VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_EXTERNAL_IMAGE_FORMAT_INFO
** ename:VK_STRUCTURE_TYPE_EXTERNAL_IMAGE_FORMAT_PROPERTIES
** ename:VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_EXTERNAL_BUFFER_INFO
** ename:VK_STRUCTURE_TYPE_EXTERNAL_BUFFER_PROPERTIES
** ename:VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_ID_PROPERTIES
** ename:VK_STRUCTURE_TYPE_EXTERNAL_MEMORY_BUFFER_CREATE_INFO
** ename:VK_STRUCTURE_TYPE_EXTERNAL_MEMORY_IMAGE_CREATE_INFO
** ename:VK_STRUCTURE_TYPE_EXPORT_MEMORY_ALLOCATE_INFO
** ename:VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_EXTERNAL_FENCE_INFO
** ename:VK_STRUCTURE_TYPE_EXTERNAL_FENCE_PROPERTIES
** ename:VK_STRUCTURE_TYPE_EXPORT_FENCE_CREATE_INFO
** ename:VK_STRUCTURE_TYPE_EXPORT_SEMAPHORE_CREATE_INFO
** ename:VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_EXTERNAL_SEMAPHORE_INFO
** ename:VK_STRUCTURE_TYPE_EXTERNAL_SEMAPHORE_PROPERTIES
** ename:VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MAINTENANCE_3_PROPERTIES
** ename:VK_STRUCTURE_TYPE_DESCRIPTOR_SET_LAYOUT_SUPPORT
** ename:VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_DRAW_PARAMETER_FEATURES
=== New Enums
* elink:VkChromaLocation
* elink:VkDescriptorUpdateTemplateType
* elink:VkExternalFenceFeatureFlagBits
* elink:VkExternalFenceHandleTypeFlagBits
* elink:VkExternalMemoryFeatureFlagBits
* elink:VkExternalMemoryHandleTypeFlagBits
* elink:VkExternalSemaphoreFeatureFlagBits
* elink:VkExternalSemaphoreHandleTypeFlagBits
* elink:VkFenceImportFlagBits
* elink:VkMemoryAllocateFlagBits
* elink:VkPeerMemoryFeatureFlagBits
* elink:VkPointClippingBehavior
* elink:VkSamplerYcbcrModelConversion
* elink:VkSamplerYcbcrRange
* elink:VkSemaphoreImportFlagBits
* elink:VkSubgroupFeatureFlagBits
* elink:VkTessellationDomainOrigin
* elink:VkCommandPoolTrimFlags
* elink:VkDescriptorUpdateTemplateCreateFlags
* elink:VkExternalFenceFeatureFlags
* elink:VkExternalFenceHandleTypeFlags
* elink:VkExternalMemoryFeatureFlags
* elink:VkExternalMemoryHandleTypeFlags
* elink:VkExternalSemaphoreFeatureFlags
* elink:VkExternalSemaphoreHandleTypeFlags
* elink:VkFenceImportFlags
* elink:VkMemoryAllocateFlags
* elink:VkPeerMemoryFeatureFlags
* elink:VkSemaphoreImportFlags
* elink:VkSubgroupFeatureFlags
=== New Structures
* slink:VkBindBufferMemoryDeviceGroupInfo
* slink:VkBindBufferMemoryInfo
* slink:VkBindImageMemoryDeviceGroupInfo
* slink:VkBindImageMemoryInfo
* slink:VkBindImagePlaneMemoryInfo
* slink:VkBufferMemoryRequirementsInfo2
* slink:VkDescriptorSetLayoutSupport
* slink:VkDescriptorUpdateTemplateCreateInfo
* slink:VkDescriptorUpdateTemplateEntry
* slink:VkDeviceGroupBindSparseInfo
* slink:VkDeviceGroupCommandBufferBeginInfo
* slink:VkDeviceGroupDeviceCreateInfo
* slink:VkDeviceGroupRenderPassBeginInfo
* slink:VkDeviceGroupSubmitInfo
* slink:VkDeviceQueueInfo2
* slink:VkExportFenceCreateInfo
* slink:VkExportMemoryAllocateInfo
* slink:VkExportSemaphoreCreateInfo
* slink:VkExternalBufferProperties
* slink:VkExternalFenceProperties
* slink:VkExternalImageFormatProperties
* slink:VkExternalMemoryBufferCreateInfo
* slink:VkExternalMemoryImageCreateInfo
* slink:VkExternalMemoryProperties
* slink:VkExternalSemaphoreProperties
* slink:VkFormatProperties2
* slink:VkImageFormatProperties2
* slink:VkImageMemoryRequirementsInfo2
* slink:VkImagePlaneMemoryRequirementsInfo
* slink:VkImageSparseMemoryRequirementsInfo2
* slink:VkImageViewUsageCreateInfo
* slink:VkInputAttachmentAspectReference
* slink:VkMemoryAllocateFlagsInfo
* slink:VkMemoryDedicatedAllocateInfo
* slink:VkMemoryDedicatedRequirements
* slink:VkMemoryRequirements2
* slink:VkPhysicalDevice16BitStorageFeatures
* slink:VkPhysicalDeviceExternalBufferInfo
* slink:VkPhysicalDeviceExternalFenceInfo
* slink:VkPhysicalDeviceExternalImageFormatInfo
* slink:VkPhysicalDeviceExternalSemaphoreInfo
* slink:VkPhysicalDeviceFeatures2
* slink:VkPhysicalDeviceGroupProperties
* slink:VkPhysicalDeviceIDProperties
* slink:VkPhysicalDeviceImageFormatInfo2
* slink:VkPhysicalDeviceMaintenance3Properties
* slink:VkPhysicalDeviceMemoryProperties2
* slink:VkPhysicalDeviceMultiviewFeatures
* slink:VkPhysicalDeviceMultiviewProperties
* slink:VkPhysicalDevicePointClippingProperties
* slink:VkPhysicalDeviceProperties2
* slink:VkPhysicalDeviceProtectedMemoryFeatures
* slink:VkPhysicalDeviceProtectedMemoryProperties
* slink:VkPhysicalDeviceSamplerYcbcrConversionFeatures
* slink:VkPhysicalDeviceShaderDrawParameterFeatures
* slink:VkPhysicalDeviceSparseImageFormatInfo2
* slink:VkPhysicalDeviceSubgroupProperties
* slink:VkPhysicalDeviceVariablePointerFeatures
* slink:VkPipelineTessellationDomainOriginStateCreateInfo
* slink:VkProtectedSubmitInfo
* slink:VkQueueFamilyProperties2
* slink:VkRenderPassInputAttachmentAspectCreateInfo
* slink:VkRenderPassMultiviewCreateInfo
* slink:VkSamplerYcbcrConversionCreateInfo
* slink:VkSamplerYcbcrConversionImageFormatProperties
* slink:VkSamplerYcbcrConversionInfo
* slink:VkSparseImageFormatProperties2
* slink:VkSparseImageMemoryRequirements2
=== New Functions
* flink:vkBindBufferMemory2
* flink:vkBindImageMemory2
* flink:vkCmdDispatchBase
* flink:vkCmdSetDeviceMask
* flink:vkCreateDescriptorUpdateTemplate
* flink:vkCreateSamplerYcbcrConversion
* flink:vkDestroyDescriptorUpdateTemplate
* flink:vkDestroySamplerYcbcrConversion
* flink:vkEnumerateInstanceVersion
* flink:vkEnumeratePhysicalDeviceGroups
* flink:vkGetBufferMemoryRequirements2
* flink:vkGetDescriptorSetLayoutSupport
* flink:vkGetDeviceGroupPeerMemoryFeatures
* flink:vkGetDeviceQueue2
* flink:vkGetImageMemoryRequirements2
* flink:vkGetImageSparseMemoryRequirements2
* flink:vkGetPhysicalDeviceExternalBufferProperties
* flink:vkGetPhysicalDeviceExternalFenceProperties
* flink:vkGetPhysicalDeviceExternalSemaphoreProperties
* flink:vkGetPhysicalDeviceFeatures2
* flink:vkGetPhysicalDeviceFormatProperties2
* flink:vkGetPhysicalDeviceImageFormatProperties2
* flink:vkGetPhysicalDeviceMemoryProperties2
* flink:vkGetPhysicalDeviceProperties2
* flink:vkGetPhysicalDeviceQueueFamilyProperties2
* flink:vkGetPhysicalDeviceSparseImageFormatProperties2
* flink:vkTrimCommandPool
* flink:vkUpdateDescriptorSetWithTemplate
endif::VK_VERSION_1_1[]

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

@ -219,9 +219,14 @@ ifdef::VK_NVX_device_generated_commands[]
| ename:VK_DEBUG_REPORT_OBJECT_TYPE_OBJECT_TABLE_NVX_EXT | slink:VkObjectTableNVX
| ename:VK_DEBUG_REPORT_OBJECT_TYPE_INDIRECT_COMMANDS_LAYOUT_NVX_EXT | slink:VkIndirectCommandsLayoutNVX
endif::VK_NVX_device_generated_commands[]
ifdef::VK_KHR_descriptor_update_template[]
| ename:VK_DEBUG_REPORT_OBJECT_TYPE_DESCRIPTOR_UPDATE_TEMPLATE_KHR_EXT | slink:VkDescriptorUpdateTemplateKHR
endif::VK_KHR_descriptor_update_template[]
ifndef::VK_VERSION_1_1[]
ifdef::VK_VERSION_1_1,VK_KHR_descriptor_update_template[]
| ename:VK_DEBUG_REPORT_OBJECT_TYPE_DESCRIPTOR_UPDATE_TEMPLATE_KHR_EXT | slink:VkDescriptorUpdateTemplate
endif::VK_VERSION_1_1,VK_KHR_descriptor_update_template[]
endif::VK_VERSION_1_1[]
ifdef::VK_VERSION_1_1[]
| ename:VK_DEBUG_REPORT_OBJECT_TYPE_DESCRIPTOR_UPDATE_TEMPLATE_EXT | slink:VkDescriptorUpdateTemplate
endif::VK_VERSION_1_1[]
|====
[NOTE]

651
doc/specs/vulkan/chapters/VK_EXT_debug_utils.txt Normal file
View File

@ -0,0 +1,651 @@
[[debugging-debug-utils]]
== Debug Utilities
Vulkan provides flexible debugging utilities for debugging an application.
The <<debugging-object-debug-annotation,Object Debug Annotation>> section
describes how to associate either a name or binary data with a specific
Vulkan object.
The <<debugging-queue-labels,Queue Labels>> section describes how to
annotate and group the work submitted to a queue.
The <<debugging-command-buffer-labels,Command Buffer Labels>> section
describes how to associate logical elements of the scene with commands in a
slink:VkCommandBuffer.
The <<debug-messengers,Debug Messengers>> section describes how to create
debug messenger objects associated with an application supplied callback to
capture debug messages from a variety of Vulkan components.
[[debugging-object-debug-annotation]]
=== Object Debug Annotation
It can be useful for an application to provide its own content relative to a
specific Vulkan object.
The following commands allow application developers to associate
user-defined information with Vulkan objects.
[[debugging-object-naming]]
==== Object Naming
An object can be provided a user-defined name by calling
fname:vkSetDebugUtilsObjectNameEXT as defined below.
// refBegin vkSetDebugUtilsObjectNameEXT Give a user-friendly name to an object
include::../api/protos/vkSetDebugUtilsObjectNameEXT.txt[]
* pname:device is the device that created the object.
* pname:pNameInfo is a pointer to an instance of the
slink:VkDebugUtilsObjectNameInfoEXT structure specifying the parameters
of the name to set on the object.
include::../validity/protos/vkSetDebugUtilsObjectNameEXT.txt[]
// refEnd vkSetDebugUtilsObjectNameEXT
// refBegin VkDebugUtilsObjectNameInfoEXT Specify parameters of a name to give to an object
The sname:VkDebugUtilsObjectNameInfoEXT structure is defined as:
include::../api/structs/VkDebugUtilsObjectNameInfoEXT.txt[]
* pname:sType is the type of this structure.
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
* pname:objectType is a elink:VkObjectType specifying the type of the
object to be named.
* pname:objectHandle is the object to be named.
* pname:pObjectName is a null-terminated UTF-8 string specifying the name
to apply to pname:objectHandle.
Applications may: change the name associated with an object simply by
calling fname:vkSetDebugUtilsObjectNameEXT again with a new string.
If pname:pObjectName is an empty string, then any previously set name is
removed.
.Valid Usage
****
* pname:objectType must: not be ename:VK_OBJECT_TYPE_UNKNOWN
* pname:objectHandle must: not be dlink:VK_NULL_HANDLE
* pname:objectHandle must: be a Vulkan object of the type associated with
pname:objectType as defined in <<debugging-object-types>>.
****
include::../validity/structs/VkDebugUtilsObjectNameInfoEXT.txt[]
// refEnd VkDebugUtilsObjectNameInfoEXT
[[debugging-object-data-association]]
==== Object Data Association
In addition to setting a name for an object, debugging and validation layers
may: have uses for additional binary data on a per-object basis that have no
other place in the Vulkan API.
For example, a sname:VkShaderModule could have additional debugging data
attached to it to aid in offline shader tracing.
Additional data can be attached to an object by calling
fname:vkSetDebugUtilsObjectTagEXT as defined below.
// refBegin vkSetDebugUtilsObjectTagEXT Attach arbitrary data to an object
include::../api/protos/vkSetDebugUtilsObjectTagEXT.txt[]
* pname:device is the device that created the object.
* pname:pTagInfo is a pointer to an instance of the
slink:VkDebugUtilsObjectTagInfoEXT structure specifying the parameters
of the tag to attach to the object.
include::../validity/protos/vkSetDebugUtilsObjectTagEXT.txt[]
// refEnd vkSetDebugUtilsObjectTagEXT
// refBegin VkDebugUtilsObjectTagInfoEXT Specify parameters of a tag to attach to an object
The sname:VkDebugUtilsObjectTagInfoEXT structure is defined as:
include::../api/structs/VkDebugUtilsObjectTagInfoEXT.txt[]
* pname:sType is the type of this structure.
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
* pname:objectType is a elink:VkObjectType specifying the type of the
object to be named.
* pname:objectHandle is the object to be tagged.
* pname:tagName is a numerical identifier of the tag.
* pname:tagSize is the number of bytes of data to attach to the object.
* pname:pTag is an array of pname:tagSize bytes containing the data to be
associated with the object.
The pname:tagName parameter gives a name or identifier to the type of data
being tagged.
This can be used by debugging layers to easily filter for only data that can
be used by that implementation.
.Valid Usage
****
* pname:objectType must: not be ename:VK_OBJECT_TYPE_UNKNOWN
* pname:objectHandle must: not be dlink:VK_NULL_HANDLE
* pname:objectHandle must: be a Vulkan object of the type associated with
pname:objectType as defined in <<debugging-object-types>>.
****
include::../validity/structs/VkDebugUtilsObjectTagInfoEXT.txt[]
// refEnd VkDebugUtilsObjectTagInfoEXT
[[debugging-queue-labels]]
=== Queue Labels
All Vulkan work must be submitted using queues.
It is possible for an application to use multiple queues, each containing
multiple command buffers, when performing work.
It can be useful to identify which queue, or even where in a queue,
something has occurred.
To begin identifying a region using a debug label inside a queue, you may
use the flink:vkQueueBeginDebugUtilsLabelEXT command.
Then, when the region of interest has passed, you may end the label region
using flink:vkQueueEndDebugUtilsLabelEXT.
Additionally, a single debug label may be inserted at any time using
flink:vkQueueInsertDebugUtilsLabelEXT.
// refBegin vkQueueBeginDebugUtilsLabelEXT Open a queue debug label region
A queue debug label region is opened by calling:
include::../api/protos/vkQueueBeginDebugUtilsLabelEXT.txt[]
* pname:queue is the queue in which to start a debug label region.
* pname:pLabelInfo is a pointer to an instance of the
slink:VkDebugUtilsLabelEXT structure specifying the parameters of the
label region to open.
include::../validity/protos/vkQueueBeginDebugUtilsLabelEXT.txt[]
// refEnd vkQueueBeginDebugUtilsLabelEXT
// refBegin VkDebugUtilsLabelEXT Specify parameters of a label region
The sname:VkDebugUtilsLabelEXT structure is defined as:
include::../api/structs/VkDebugUtilsLabelEXT.txt[]
* pname:sType is the type of this structure.
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
* pname:pLabelName is a pointer to a null-terminated UTF-8 string that
contains the name of the label.
* pname:color is an optional RGBA color value that can be associated with
the label.
A particular implementation may: choose to ignore this color value.
The values contain RGBA values in order, in the range 0.0 to 1.0.
If all elements in pname:color are set to 0.0 then it is ignored.
include::../validity/structs/VkDebugUtilsLabelEXT.txt[]
// refEnd VkDebugUtilsLabelEXT
// refBegin vkQueueEndDebugUtilsLabelEXT Close a queue debug label region
A queue debug label region is closed by calling:
include::../api/protos/vkQueueEndDebugUtilsLabelEXT.txt[]
* pname:queue is the queue in which a debug label region should be closed.
The calls to flink:vkQueueBeginDebugUtilsLabelEXT and
flink:vkQueueEndDebugUtilsLabelEXT must: be matched and balanced.
.Valid Usage
****
* There must: be an outstanding fname:vkQueueBeginDebugUtilsLabelEXT
command prior to the fname:vkQueueEndDebugUtilsLabelEXT on the queue
****
include::../validity/protos/vkQueueEndDebugUtilsLabelEXT.txt[]
// refEnd vkQueueEndDebugUtilsLabelEXT
// refBegin vkQueueInsertDebugUtilsLabelEXT Insert a label into a queue
A single label can be inserted into a queue by calling:
include::../api/protos/vkQueueInsertDebugUtilsLabelEXT.txt[]
* pname:queue is the queue into which a debug label will be inserted.
* pname:pLabelInfo is a pointer to an instance of the
slink:VkDebugUtilsLabelEXT structure specifying the parameters of the
label to insert.
include::../validity/protos/vkQueueInsertDebugUtilsLabelEXT.txt[]
// refEnd vkQueueInsertDebugUtilsLabelEXT
[[debugging-command-buffer-labels]]
=== Command Buffer Labels
Typical Vulkan applications will submit many command buffers in each frame,
with each command buffer containing a large number of individual commands.
Being able to logically annotate regions of command buffers that belong
together as well as hierarchically subdivide the frame is important to a
developer's ability to navigate the commands viewed holistically.
To identify the beginning of a debug label region in a command buffer,
flink:vkCmdBeginDebugUtilsLabelEXT can: be used as defined below.
To indicate the end of a debug label region in a command buffer,
flink:vkCmdEndDebugUtilsLabelEXT can: be used.
To insert a single command buffer debug label inside of a command buffer,
flink:vkCmdInsertDebugUtilsLabelEXT can: be used as defined below.
// refBegin vkCmdBeginDebugUtilsLabelEXT Open a command buffer debug label region
A command buffer debug label region can be opened by calling:
include::../api/protos/vkCmdBeginDebugUtilsLabelEXT.txt[]
* pname:commandBuffer is the command buffer into which the command is
recorded.
* pname:pLabelInfo is a pointer to an instance of the
slink:VkDebugUtilsLabelEXT structure specifying the parameters of the
label region to open.
include::../validity/protos/vkCmdBeginDebugUtilsLabelEXT.txt[]
// refEnd vkCmdBeginDebugUtilsLabelEXT
// refBegin vkCmdEndDebugUtilsLabelEXT Close a command buffer label region
A command buffer label region can be closed by calling:
include::../api/protos/vkCmdEndDebugUtilsLabelEXT.txt[]
* pname:commandBuffer is the command buffer into which the command is
recorded.
An application may: open a debug label region in one command buffer and
close it in another, or otherwise split debug label regions across multiple
command buffers or multiple queue submissions.
When viewed from the linear series of submissions to a single queue, the
calls to flink:vkCmdBeginDebugUtilsLabelEXT and
flink:vkCmdEndDebugUtilsLabelEXT must: be matched and balanced.
.Valid Usage
****
* There must: be an outstanding fname:vkCmdBeginDebugUtilsLabelEXT command
prior to the fname:vkCmdEndDebugUtilsLabelEXT on the queue that
pname:commandBuffer is submitted to
* If pname:commandBuffer is a secondary command buffer, there must: be an
outstanding fname:vkCmdBeginDebugUtilsLabelEXT command recorded to
pname:commandBuffer that has not previously been ended by a call to
fname:vkCmdEndDebugUtilsLabelEXT.
****
include::../validity/protos/vkCmdEndDebugUtilsLabelEXT.txt[]
// refEnd vkCmdEndDebugUtilsLabelEXT
// refBegin vkCmdInsertDebugUtilsLabelEXT Insert a label into a command buffer
A single debug label can be inserted into a command buffer by calling:
include::../api/protos/vkCmdInsertDebugUtilsLabelEXT.txt[]
* pname:commandBuffer is the command buffer into which the command is
recorded.
* pname:pInfo is a pointer to an instance of the
slink:VkDebugUtilsLabelEXT structure specifying the parameters of the
label to insert.
include::../validity/protos/vkCmdInsertDebugUtilsLabelEXT.txt[]
// refEnd vkCmdInsertDebugUtilsLabelEXT
[[debugging-debug-messengers]]
=== Debug Messengers
Vulkan allows an application to register multiple callbacks with any Vulkan
component wishing to report debug information.
Some callbacks may log the information to a file, others may cause a debug
break point or other application defined behavior.
A primary producer of callback messages are the validation layers.
An application can: register callbacks even when no validation layers are
enabled, but they will only be called for the Vulkan loader and, if
implemented, other layer and driver events.
// refBegin VkDebugUtilsMessengerEXT Opaque handle to a debug messenger object
A sname:VkDebugUtilsMessengerEXT is a messenger object which handles passing
along debug messages to a provided debug callback.
include::../api/handles/VkDebugUtilsMessengerEXT.txt[]
The debug messenger will provide detailed feedback on the application's use
of Vulkan when events of interest occur.
When an event of interest does occur, the debug messenger will submit a
debug message to the debug callback that was provided during its creation.
Additionally, the debug messenger is responsible with filtering out debug
messages that the callback isn't interested in and will only provide desired
debug messages.
// refEnd VkDebugUtilsMessengerEXT
// refBegin vkCreateDebugUtilsMessengerEXT Create a debug messenger object
A debug messenger triggers a debug callback with a debug message when an
event of interest occurs.
To create a debug messenger which will trigger a debug callback, call:
include::../api/protos/vkCreateDebugUtilsMessengerEXT.txt[]
* pname:instance the instance the messenger will be used with.
* pname:pCreateInfo points to a slink:VkDebugUtilsMessengerCreateInfoEXT
structure which contains the callback pointer as well as defines the
conditions under which this messenger will trigger the callback.
* pname:pAllocator controls host memory allocation as described in the
<<memory-allocation, Memory Allocation>> chapter.
* pname:pMessenger is a pointer to record the
sname:VkDebugUtilsMessengerEXT object created.
include::../validity/protos/vkCreateDebugUtilsMessengerEXT.txt[]
// refEnd VkDebugUtilsMessengerEXT
// refBegin VkDebugUtilsMessengerCreateInfoEXT Structure specifying parameters of a newly created debug messenger
The definition of sname:VkDebugUtilsMessengerCreateInfoEXT is:
include::../api/structs/VkDebugUtilsMessengerCreateInfoEXT.txt[]
* pname:sType is the type of this structure.
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
* pname:flags is 0 and reserved for future use.
* pname:messageSeverity is a bitmask of
elink:VkDebugUtilsMessageSeverityFlagBitsEXT specifying which severity
of event(s) will cause this callback to be called.
* pname:messageTypes is a bitmask of
elink:VkDebugUtilsMessageTypeFlagBitsEXT specifying which type of
event(s) will cause this callback to be called.
* pname:pfnUserCallback is the application callback function to call.
* pname:pUserData is user data to be passed to the callback.
For each sname:VkDebugUtilsMessengerEXT that is created the
sname:VkDebugUtilsMessengerCreateInfoEXT::pname:messageSeverity and
sname:VkDebugUtilsMessengerCreateInfoEXT::pname:messageTypes determine when
that sname:VkDebugUtilsMessengerCreateInfoEXT::pname:pfnUserCallback is
called.
The process to determine if the user's pfnUserCallback is triggered when an
event occurs is as follows:
. The implementation will perform a bitwise AND of the event's
elink:VkDebugUtilsMessageSeverityFlagBitsEXT with the
pname:messageSeverity provided during creation of the
slink:VkDebugUtilsMessengerEXT object.
.. If the value is 0, the message is skipped.
. The implementation will perform bitwise AND of the event's
elink:VkDebugUtilsMessageTypeFlagBitsEXT with the pname:messageType
provided during the creation of the slink:VkDebugUtilsMessengerEXT
object.
.. If the value is 0, the message is skipped.
. The callback will trigger a debug message for the current event
The callback will come directly from the component that detected the event,
unless some other layer intercepts the calls for its own purposes (filter
them in a different way, log to a system error log, etc.).
An application can: receive multiple callbacks if multiple
sname:VkDebugUtilsMessengerEXT objects are created.
A callback will always be executed in the same thread as the originating
Vulkan call.
A callback can: be called from multiple threads simultaneously (if the
application is making Vulkan calls from multiple threads).
.Valid Usage
****
* pname:pfnUserCallback must: be a valid
tlink:PFN_vkDebugUtilsMessengerCallbackEXT
****
include::../validity/structs/VkDebugUtilsMessengerCreateInfoEXT.txt[]
// refEnd VkDebugUtilsMessengerCreateInfoEXT
// refBegin VkDebugUtilsMessageSeverityFlagBitsEXT Bitmask specifying which severities of events cause a debug messenger callback
Bits which can: be set in
slink:VkDebugUtilsMessengerCreateInfoEXT::pname:messageSeverity, specifying
event severities which cause a debug messenger to call the callback, are:
include::../api/enums/VkDebugUtilsMessageSeverityFlagBitsEXT.txt[]
* ename:VK_DEBUG_UTILS_MESSAGE_SEVERITY_VERBOSE_BIT_EXT specifies the most
verbose output indicating all diagnostic messages from the Vulkan
loader, layers, and drivers should be captured.
* ename:VK_DEBUG_UTILS_MESSAGE_SEVERITY_INFO_BIT_EXT specifies an
informational message such as resource details that may be handy when
debugging an application.
* ename:VK_DEBUG_UTILS_MESSAGE_SEVERITY_WARNING_BIT_EXT specifies use of
Vulkan that may: expose an app bug.
Such cases may not be immediately harmful, such as a fragment shader
outputting to a location with no attachment.
Other cases may: point to behavior that is almost certainly bad when
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
intended/desired, then simply ignore the warning.
* ename:VK_DEBUG_UTILS_MESSAGE_SEVERITY_ERROR_BIT_EXT specifies that an
error that may cause undefined results, including an application crash.
// refEnd VkDebugUtilsMessageSeverityFlagBitsEXT
[NOTE]
.Note
====
The values of ename:VkDebugUtilsMessageSeverityFlagBitsEXT are sorted based
on severity.
The higher the flag value, the more severe the message.
This allows for simple boolean operation comparisons when looking at
ename:VkDebugUtilsMessageSeverityFlagBitsEXT values.
For example:
[source,c++]
----------------------------------------
if (messageSeverity >= VK_DEBUG_UTILS_MESSAGE_SEVERITY_WARNING_BIT_EXT) {
// Do something for warnings and errors
}
----------------------------------------
In addition, space has been left between the enums to allow for later
addition of new severities in between the existing values.
====
// refBegin VkDebugUtilsMessageTypeFlagBitsEXT Bitmask specifying which types of events cause a debug messenger callback
Bits which can: be set in
slink:VkDebugUtilsMessengerCreateInfoEXT::pname:messageTypes, specifying
event types which cause a debug messenger to call the callback, are:
include::../api/enums/VkDebugUtilsMessageTypeFlagBitsEXT.txt[]
* ename:VK_DEBUG_UTILS_MESSAGE_TYPE_GENERAL_BIT_EXT specifies that some
general event has occurred.
This is typically a non-specification, non-performance event.
* ename:VK_DEBUG_UTILS_MESSAGE_TYPE_VALIDATION_BIT_EXT specifies that
something has occurred during validation against the Vulkan
specification that may indicate invalid behavior.
* ename:VK_DEBUG_UTILS_MESSAGE_TYPE_PERFORMANCE_BIT_EXT specifies a
potentially non-optimal use of Vulkan, e.g. using
flink:vkCmdClearColorImage when setting
slink:VkAttachmentDescription::pname:loadOp to
ename:VK_ATTACHMENT_LOAD_OP_CLEAR would have worked.
// refEnd VkDebugUtilsMessageTypeFlagBitsEXT
// refBegin PFN_vkDebugUtilsMessengerCallbackEXT Application-defined debug messenger callback function
The prototype for the
slink:VkDebugUtilsMessengerCreateInfoEXT::pname:pfnUserCallback function
implemented by the application is:
include::../api/funcpointers/PFN_vkDebugUtilsMessengerCallbackEXT.txt[]
* pname:messageSeverity indicates the
elink:VkDebugUtilsMessageSeverityFlagBitsEXT that triggered this
callback.
* pname:messageTypes indicates the
elink:VkDebugUtilsMessageTypeFlagBitsEXT that triggered this callback.
* pname:pCallbackData contains all the callback related data in the
slink:VkDebugUtilsMessengerCallbackDataEXT structure.
* pname:pUserData is the user data provided when the
slink:VkDebugUtilsMessengerEXT was created.
The callback must: not call flink:vkDestroyDebugUtilsMessengerEXT.
The callback returns a basetype:VkBool32, which is interpreted in a
layer-specified manner.
The application should: always return ename:VK_FALSE.
The ename:VK_TRUE value is reserved for use in layer development.
// refEnd PFN_vkDebugUtilsMessengerCallbackEXT
// refBegin VkDebugUtilsMessengerCallbackDataEXT Structure specifying parameters returned to the callback
The definition of sname:VkDebugUtilsMessengerCallbackDataEXT is:
include::../api/structs/VkDebugUtilsMessengerCallbackDataEXT.txt[]
* pname:sType is the type of this structure.
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
* pname:flags is 0 and reserved for future use.
* pname:pMessageIdName is a null-terminated string that identifies the the
particular message ID that is associated with the provided message.
If the message corresponds to a validation layer message, then this
string may contain the portion of the Vulkan specification that is
believed to have been violated.
* pname:messageIdNumber is the ID number of the triggering message.
If the message corresponds to a validation layer message, then this
number is related to the internal number associated with the message
being triggered.
* pname:pMessage is a null-terminated string detailing the trigger
conditions.
* pname:queueLabelCount is a count of items contained in the
pname:pQueueLabels array.
* pname:pQueueLabels is NULL or a pointer to an array of
slink:VkDebugUtilsLabelEXT active in the current sname:VkQueue at the
time the callback was triggered.
Refer to <<debugging-queue-labels,Queue Labels>> for more information.
* pname:cmdBufLabelCount is a count of items contained in the
pname:pCmdBufLabels array.
* pname:pCmdBufLabels is NULL or a pointer to an array of
slink:VkDebugUtilsLabelEXT active in the current sname:VkCommandBuffer
at the time the callback was triggered.
Refer to <<debugging-command-buffer-labels, Command Buffer Labels>> for
more information.
* pname:objectCount is a count of items contained in the pname:pObjects
array.
* pname:pObjects is a pointer to an array of
slink:VkDebugUtilsObjectNameInfoEXT objects related to the detected
issue.
The array is roughly in order or importance, but the 0th element is
always guaranteed to be the most important object for this message.
[NOTE]
.Note
====
This structure should only be considered valid during the lifetime of the
triggered callback.
====
Since adding queue and command buffer labels behaves like pushing and
popping onto a stack, the order of both pname:pQueueLabels and
pname:pCmdBufLabels is based on the order the labels were defined.
The result is that the first label in either pname:pQueueLabels or
pname:pCmdBufLabels will be the first defined (and therefore the oldest)
while the last label in each list will be the most recent.
[NOTE]
.Note
====
pname:pQueueLabels will only be non-NULL if one of the objects in
pname:pObjects can be related directly to a defined sname:VkQueue which has
had one or more labels associated with it.
Likewise, pname:pCmdBufLabels will only be non-NULL if one of the objects in
pname:pObjects can be related directly to a defined sname:VkCommandBuffer
which has had one or more labels associated with it.
Additionally, while command buffer labels allow for beginning and ending
across different command buffers, the debug messaging framework cannot:
guarantee that labels in pname:pCmdBufLables will contain those defined
outside of the associated command buffer.
This is partially due to the fact that the association of one command buffer
with another may not have been defined at the time the debug message is
triggered.
====
include::../validity/structs/VkDebugUtilsMessengerCallbackDataEXT.txt[]
// refEnd VkDebugUtilsMessengerCallbackDataEXT
// refBegin vkSubmitDebugUtilsMessageEXT Inject a message into a debug stream
There may be times that a user wishes to intentionally submit a debug
message.
To do this, call:
include::../api/protos/vkSubmitDebugUtilsMessageEXT.txt[]
* pname:instance is the debug stream's sname:VkInstance.
* pname:messageSeverity is the
elink:VkDebugUtilsMessageSeverityFlagBitsEXT severity of this
event/message.
* pname:messageTypes is a bitmask of
elink:VkDebugUtilsMessageTypeFlagBitsEXT specifying which type of
event(s) to identify with this message.
* pname:pCallbackData contains all the callback related data in the
slink:VkDebugUtilsMessengerCallbackDataEXT structure.
The call will propagate through the layers and generate callback(s) as
indicated by the message's flags.
The parameters are passed on to the callback in addition to the
pname:pUserData value that was defined at the time the messenger was
registered.
include::../validity/protos/vkSubmitDebugUtilsMessageEXT.txt[]
// refEnd vkSubmitDebugUtilsMessageEXT
// refBegin vkDestroyDebugUtilsMessengerEXT Destroy a debug messenger object
To destroy a sname:VkDebugUtilsMessengerEXT object, call:
include::../api/protos/vkDestroyDebugUtilsMessengerEXT.txt[]
* pname:instance the instance where the callback was created.
* pname:messenger the sname:VkDebugUtilsMessengerEXT object to destroy.
pname:messenger is an externally synchronized object and must: not be
used on more than one thread at a time.
This means that fname:vkDestroyDebugUtilsMessengerEXT must: not be called
when a callback is active.
* pname:pAllocator controls host memory allocation as described in the
<<memory-allocation, Memory Allocation>> chapter.
.Valid Usage
****
* If sname:VkAllocationCallbacks were provided when pname:messenger was
created, a compatible set of callbacks must: be provided here
* If no sname:VkAllocationCallbacks were provided when pname:messenger was
created, pname:pAllocator must: be `NULL`
****
include::../validity/protos/vkDestroyDebugUtilsMessengerEXT.txt[]
// refEnd vkDestroyDebugUtilsMessengerEXT

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

@ -64,7 +64,7 @@ include::../api/structs/VkHdrMetadataEXT.txt[]
in nits
[NOTE]
.note
.Note
====
The validity and use of this data is outside the scope of Vulkan and thus no
+Valid Usage+ is given.

7
doc/specs/vulkan/chapters/VK_GOOGLE_display_timing/queries.txt
View File

@ -72,9 +72,11 @@ include::../../validity/structs/VkRefreshCycleDurationGOOGLE.txt[]
--
[NOTE]
.Note
====
The rate at which an application renders and presents new images is known as
the image present rate (IPR, a.k.a.
frame rate).
the image present rate (IPR, aka frame rate).
The inverse of IPR, or the duration between each image present, is the image
present duration (IPD).
In order to provide a smooth, stutter-free animation, an application will
@ -113,6 +115,7 @@ but adjustments to a smaller IPD should only happen if the
pname:actualPresentTime and pname:earliestPresentTime members of the
slink:VkPastPresentationTimingGOOGLE structure are consistently different,
and if pname:presentMargin is consistently large, over multiple images.
====
[open,refpage='vkGetPastPresentationTimingGOOGLE',desc='Obtain timing of a previously-presented image',type='protos']
--

54
doc/specs/vulkan/chapters/VK_KHR_16bit_storage/16bit_storage_feature_struct.txt
View File

@ -1,54 +0,0 @@
[open,refpage='VkPhysicalDevice16BitStorageFeaturesKHR',desc='Structure describing features supported by VK_KHR_16bit_storage',type='structs']
--
To query features additionally supported by the `<<VK_KHR_16bit_storage>>`
extension, call flink:vkGetPhysicalDeviceFeatures2KHR with a
sname:VkPhysicalDevice16BitStorageFeaturesKHR structure included in the
pname:pNext chain of its pname:pFeatures parameter.
The sname:VkPhysicalDevice16BitStorageFeaturesKHR structure can: also be in
the pname:pNext chain of a slink:VkDeviceCreateInfo structure, in which case
it controls which additional features are enabled in the device.
The slink:VkPhysicalDevice16BitStorageFeaturesKHR structure is defined as:
include::../../api/structs/VkPhysicalDevice16BitStorageFeaturesKHR.txt[]
* pname:sType is the type of this structure.
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
* [[features-features-storageBuffer16BitAccess]]
pname:storageBuffer16BitAccess indicates whether objects in the
code:StorageBuffer storage class with the code:Block decoration can:
have 16-bit integer and 16-bit floating-point members.
If this feature is not enabled, 16-bit integer or 16-bit floating-point
members must: not be used in such objects.
This also indicates whether shader modules can: declare the
code:StorageBuffer16BitAccess capability.
* [[features-features-uniformAndStorageBuffer16BitAccess]]
pname:uniformAndStorageBuffer16BitAccess indicates whether objects in
the code:Uniform storage class with the code:Block decoration and in
the code:StorageBuffer storage class with the same decoration can:
have 16-bit integer and 16-bit floating-point members.
If this feature is not enabled, 16-bit integer or 16-bit floating-point
members must: not be used in such objects.
This also indicates whether shader modules can: declare the
code:UniformAndStorageBuffer16BitAccess capability.
* [[features-features-storagePushConstant16]]
pname:storagePushConstant16 indicates whether objects in the
code:PushConstant storage class can: have 16-bit integer and 16-bit
floating-point members.
If this feature is not enabled, 16-bit integer or floating-point
members must: not be used in such objects.
This also indicates whether shader modules can: declare the
code:StoragePushConstant16 capability.
* [[features-features-storageInputOutput16]]
pname:storageInputOutput16 indicates whether objects in the
code:Input and code:Output storage classes can: have 16-bit integer and
16-bit floating-point members.
If this feature is not enabled, 16-bit integer or 16-bit floating-point
members must: not be used in such objects.
This also indicates whether shader modules can: declare the
code:StorageInputOutput16 capability.
include::../../validity/structs/VkPhysicalDevice16BitStorageFeaturesKHR.txt[]
--

8
doc/specs/vulkan/chapters/VK_KHR_display/display.txt
View File

@ -114,6 +114,7 @@ ifdef::VK_EXT_direct_mode_display[]
include::../VK_EXT_direct_mode_display/acquire_release_displays.txt[]
endif::VK_EXT_direct_mode_display[]
==== Display Planes
[open,refpage='vkGetPhysicalDeviceDisplayPlanePropertiesKHR',desc='Query the plane properties',type='protos']
@ -397,8 +398,9 @@ include::../../api/structs/VkDisplayPlaneCapabilitiesKHR.txt[]
Unlike the ptext:*Src* offsets, pname:minDstPosition and
pname:maxDstPosition may: contain negative values.
The minimum and maximum position and extent fields describe the hardware
limits, if any, as they apply to the specified display mode and plane.
The minimum and maximum position and extent fields describe the
implementation limits, if any, as they apply to the specified display mode
and plane.
Vendors may: support displaying a subset of a swapchain's presentable images
on the specified display plane.
This is expressed by returning pname:minSrcPosition, pname:maxSrcPosition,
@ -421,7 +423,7 @@ pname:maxSrcPosition, pname:minDstPosition, and pname:maxDstPosition, and
(display mode width, display mode height) for pname:minSrcExtent,
pname:maxSrcExtent, pname:minDstExtent, and pname:maxDstExtent.
These values indicate the limits of the hardware's individual fields.
These values indicate the limits of the implementation's individual fields.
Not all combinations of values within the offset and extent ranges returned
in sname:VkDisplayPlaneCapabilitiesKHR are guaranteed to be supported.
Vendors may: still fail presentation requests that specify unsupported

81
doc/specs/vulkan/chapters/VK_KHR_surface/wsi.txt
View File

@ -29,8 +29,17 @@ Use of these extensions is guarded by preprocessor symbols as defined in the
<<boilerplate-wsi-header,Window System-Specific Header Control>> appendix.
In order for an application to be compiled to use WSI with a given platform,
it must: #define the appropriate preprocessor symbol prior to including the
`vulkan.h` header file.
it must either:
* #define the appropriate preprocessor symbol prior to including the
`vulkan.h` header file, or
* include `vulkan_core.h` and any native platform headers, followed by the
appropriate platform-specific header.
The preprocessor symbols and platform-specific headers are defined in the
<<boilerplate-wsi-header-table, Window System Extensions and Headers>>
table.
Each platform-specific extension is an instance extension.
The application must: enable instance extensions with fname:vkCreateInstance
before using them.
@ -1074,12 +1083,12 @@ equivalent to the behavior of {wgl|glX}SwapBuffers with a swap interval of
--
ifdef::VK_KHR_swapchain[]
ifdef::VK_KHX_device_group[]
ifdef::VK_VERSION_1_1,VK_KHR_device_group[]
== Device Group Queries
[open,refpage='vkGetDeviceGroupPresentCapabilitiesKHX',desc='Query present capabilities from other physical devices',type='protos']
[open,refpage='vkGetDeviceGroupPresentCapabilitiesKHR',desc='Query present capabilities from other physical devices',type='protos']
--
A logical device that represents multiple physical devices may: support
@ -1088,22 +1097,22 @@ from multiple physical devices.
To query these capabilities, call:
include::../../api/protos/vkGetDeviceGroupPresentCapabilitiesKHX.txt[]
include::../../api/protos/vkGetDeviceGroupPresentCapabilitiesKHR.txt[]
* pname:device is the logical device.
* pname:pDeviceGroupPresentCapabilities is a pointer to a structure of
type slink:VkDeviceGroupPresentCapabilitiesKHX that is filled with the
type slink:VkDeviceGroupPresentCapabilitiesKHR that is filled with the
logical device's capabilities.
include::../../validity/protos/vkGetDeviceGroupPresentCapabilitiesKHX.txt[]
include::../../validity/protos/vkGetDeviceGroupPresentCapabilitiesKHR.txt[]
--
[open,refpage='VkDeviceGroupPresentCapabilitiesKHX',desc='Present capabilities from other physical devices',type='structs']
[open,refpage='VkDeviceGroupPresentCapabilitiesKHR',desc='Present capabilities from other physical devices',type='structs']
--
The sname:VkDeviceGroupPresentCapabilitiesKHX structure is defined as:
The sname:VkDeviceGroupPresentCapabilitiesKHR structure is defined as:
include::../../api/structs/VkDeviceGroupPresentCapabilitiesKHX.txt[]
include::../../api/structs/VkDeviceGroupPresentCapabilitiesKHR.txt[]
* pname:sType is the type of this structure.
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
@ -1113,54 +1122,54 @@ include::../../api/structs/VkDeviceGroupPresentCapabilitiesKHX.txt[]
device [eq]#i# can: present swapchain images from physical device
[eq]#j#.
If element [eq]#i# is non-zero, then bit [eq]#i# must: be set.
* pname:modes is a bitmask of elink:VkDeviceGroupPresentModeFlagBitsKHX
* pname:modes is a bitmask of elink:VkDeviceGroupPresentModeFlagBitsKHR
indicating which device group presentation modes are supported.
pname:modes always has ename:VK_DEVICE_GROUP_PRESENT_MODE_LOCAL_BIT_KHX set.
pname:modes always has ename:VK_DEVICE_GROUP_PRESENT_MODE_LOCAL_BIT_KHR set.
The present mode flags are also used when presenting an image, in
slink:VkDeviceGroupPresentInfoKHX::pname:mode.
slink:VkDeviceGroupPresentInfoKHR::pname:mode.
If a device group only includes a single physical device, then pname:modes
must: equal ename:VK_DEVICE_GROUP_PRESENT_MODE_LOCAL_BIT_KHX.
must: equal ename:VK_DEVICE_GROUP_PRESENT_MODE_LOCAL_BIT_KHR.
include::../../validity/structs/VkDeviceGroupPresentCapabilitiesKHX.txt[]
include::../../validity/structs/VkDeviceGroupPresentCapabilitiesKHR.txt[]
--
[open,refpage='VkDeviceGroupPresentModeFlagBitsKHX',desc='Bitmask specifying supported device group present modes',type='enums']
[open,refpage='VkDeviceGroupPresentModeFlagBitsKHR',desc='Bitmask specifying supported device group present modes',type='enums']
--
Bits which may: be set in
slink:VkDeviceGroupPresentCapabilitiesKHX::pname:modes to indicate which
slink:VkDeviceGroupPresentCapabilitiesKHR::pname:modes to indicate which
device group presentation modes are supported are:
include::../../api/enums/VkDeviceGroupPresentModeFlagBitsKHX.txt[]
include::../../api/enums/VkDeviceGroupPresentModeFlagBitsKHR.txt[]
* ename:VK_DEVICE_GROUP_PRESENT_MODE_LOCAL_BIT_KHX indicates that any
* ename:VK_DEVICE_GROUP_PRESENT_MODE_LOCAL_BIT_KHR indicates that any
physical device with a presentation engine can: present its own
swapchain images.
* ename:VK_DEVICE_GROUP_PRESENT_MODE_REMOTE_BIT_KHX indicates that any
* ename:VK_DEVICE_GROUP_PRESENT_MODE_REMOTE_BIT_KHR indicates that any
physical device with a presentation engine can: present swapchain images
from any physical device in its pname:presentMask.
* ename:VK_DEVICE_GROUP_PRESENT_MODE_SUM_BIT_KHX indicates that any
* ename:VK_DEVICE_GROUP_PRESENT_MODE_SUM_BIT_KHR indicates that any
physical device with a presentation engine can: present the sum of
swapchain images from any physical devices in its pname:presentMask.
* ename:VK_DEVICE_GROUP_PRESENT_MODE_LOCAL_MULTI_DEVICE_BIT_KHX indicates
* ename:VK_DEVICE_GROUP_PRESENT_MODE_LOCAL_MULTI_DEVICE_BIT_KHR indicates
that multiple physical devices with a presentation engine can: each
present their own swapchain images.
--
[open,refpage='VkDeviceGroupPresentModeFlagsKHX',desc='Bitmask of VkDeviceGroupPresentModeFlagBitsKHX',type='enums']
[open,refpage='VkDeviceGroupPresentModeFlagsKHR',desc='Bitmask of VkDeviceGroupPresentModeFlagBitsKHR',type='enums']
--
include::../../api/flags/VkDeviceGroupPresentModeFlagsKHX.txt[]
include::../../api/flags/VkDeviceGroupPresentModeFlagsKHR.txt[]
sname:VkDeviceGroupPresentModeFlagsKHX is a bitmask type for setting a mask
of zero or more slink:VkDeviceGroupPresentModeFlagBitsKHX.
sname:VkDeviceGroupPresentModeFlagsKHR is a bitmask type for setting a mask
of zero or more slink:VkDeviceGroupPresentModeFlagBitsKHR.
--
[open,refpage='vkGetDeviceGroupSurfacePresentModesKHX',desc='Query present capabilities for a surface',type='protos']
[open,refpage='vkGetDeviceGroupSurfacePresentModesKHR',desc='Query present capabilities for a surface',type='protos']
--
Some surfaces may: not be capable of using all the device group present
@ -1169,27 +1178,27 @@ modes.
To query the supported device group present modes for a particular surface,
call:
include::../../api/protos/vkGetDeviceGroupSurfacePresentModesKHX.txt[]
include::../../api/protos/vkGetDeviceGroupSurfacePresentModesKHR.txt[]
* pname:device is the logical device.
* pname:surface is the surface.
* pname:pModes is a pointer to a value of type
sname:VkDeviceGroupPresentModeFlagsKHX that is filled with the supported
sname:VkDeviceGroupPresentModeFlagsKHR that is filled with the supported
device group present modes for the surface.
The modes returned by this command are not invariant, and may: change in
response to the surface being moved, resized, or occluded.
These modes must: be a subset of the modes returned by
flink:vkGetDeviceGroupPresentCapabilitiesKHX.
flink:vkGetDeviceGroupPresentCapabilitiesKHR.
include::../../validity/protos/vkGetDeviceGroupSurfacePresentModesKHX.txt[]
include::../../validity/protos/vkGetDeviceGroupSurfacePresentModesKHR.txt[]
--
[open,refpage='vkGetPhysicalDevicePresentRectanglesKHX',desc='Query present rectangles for a surface on a physical device',type='protos']
[open,refpage='vkGetPhysicalDevicePresentRectanglesKHR',desc='Query present rectangles for a surface on a physical device',type='protos']
--
When using ename:VK_DEVICE_GROUP_PRESENT_MODE_LOCAL_MULTI_DEVICE_BIT_KHX,
When using ename:VK_DEVICE_GROUP_PRESENT_MODE_LOCAL_MULTI_DEVICE_BIT_KHR,
the application may: need to know which regions of the surface are used when
presenting locally on each physical device.
Presentation of swapchain images to this surface need only have valid
@ -1198,7 +1207,7 @@ contents in the regions returned by this command.
To query a set of rectangles used in presentation on the physical device,
call:
include::../../api/protos/vkGetPhysicalDevicePresentRectanglesKHX.txt[]
include::../../api/protos/vkGetPhysicalDevicePresentRectanglesKHR.txt[]
* pname:physicalDevice is the physical device.
* pname:surface is the surface.
@ -1224,11 +1233,11 @@ response to the surface being moved, resized, or occluded.
The rectangles returned by this command must: not overlap.
include::../../validity/protos/vkGetPhysicalDevicePresentRectanglesKHX.txt[]
include::../../validity/protos/vkGetPhysicalDevicePresentRectanglesKHR.txt[]
--
endif::VK_KHX_device_group[]
endif::VK_VERSION_1_1,VK_KHR_device_group[]
ifdef::VK_GOOGLE_display_timing[]
include::../VK_GOOGLE_display_timing/queries.txt[]

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

@ -28,12 +28,12 @@ time.
Further, swapchains cannot: be created for native windows that have a
non-Vulkan graphics API surface associated with them.
The presentation engine is an abstraction for the platform's compositor or
hardware/software display engine.
[NOTE]
.Note
====
The presentation engine is an abstraction for the platform's compositor or
display engine.
The presentation engine may: be synchronous or asynchronous with respect to
the application and/or logical device.
@ -300,23 +300,23 @@ endif::VK_KHR_shared_presentable_image[]
* [[VUID-VkSwapchainCreateInfoKHR-imageSharingMode-01278]]
If pname:imageSharingMode is ename:VK_SHARING_MODE_CONCURRENT,
pname:queueFamilyIndexCount must: be greater than `1`
ifndef::VK_KHR_get_physical_device_properties2[]
ifndef::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[]
* [[VUID-VkSwapchainCreateInfoKHR-imageSharingMode-01393]]
If pname:imageSharingMode is ename:VK_SHARING_MODE_CONCURRENT, each
element of pname:pQueueFamilyIndices must: be unique and must: be less
than pname:pQueueFamilyPropertyCount returned by
flink:vkGetPhysicalDeviceQueueFamilyProperties for the
pname:physicalDevice that was used to create pname:device
endif::VK_KHR_get_physical_device_properties2[]
ifdef::VK_KHR_get_physical_device_properties2[]
endif::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[]
ifdef::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[]
* [[VUID-VkSwapchainCreateInfoKHR-imageSharingMode-01428]]
If pname:imageSharingMode is ename:VK_SHARING_MODE_CONCURRENT, each
element of pname:pQueueFamilyIndices must: be unique and must: be less
than pname:pQueueFamilyPropertyCount returned by either
flink:vkGetPhysicalDeviceQueueFamilyProperties or
flink:vkGetPhysicalDeviceQueueFamilyProperties2KHR for the
flink:vkGetPhysicalDeviceQueueFamilyProperties2 for the
pname:physicalDevice that was used to create pname:device
endif::VK_KHR_get_physical_device_properties2[]
endif::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[]
* [[VUID-VkSwapchainCreateInfoKHR-preTransform-01279]]
pname:preTransform must: be one of the bits present in the
pname:supportedTransforms member of the sname:VkSurfaceCapabilitiesKHR
@ -331,13 +331,13 @@ endif::VK_KHR_get_physical_device_properties2[]
pname:presentMode must: be one of the elink:VkPresentModeKHR values
returned by fname:vkGetPhysicalDeviceSurfacePresentModesKHR for the
surface
ifdef::VK_KHX_device_group[]
ifdef::VK_VERSION_1_1,VK_KHR_device_group[]
* [[VUID-VkSwapchainCreateInfoKHR-physicalDeviceCount-01429]]
If the logical device was created with
slink:VkDeviceGroupDeviceCreateInfoKHX::pname:physicalDeviceCount equal
to 1, pname:flags must: not contain
ename:VK_SWAPCHAIN_CREATE_BIND_SFR_BIT_KHX
endif::VK_KHX_device_group[]
slink:VkDeviceGroupDeviceCreateInfo::pname:physicalDeviceCount equal to
1, pname:flags must: not contain
ename:VK_SWAPCHAIN_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT_KHR
endif::VK_VERSION_1_1,VK_KHR_device_group[]
* [[VUID-VkSwapchainCreateInfoKHR-oldSwapchain-01674]]
pname:oldSwapchain must: not be in the retired state
* [[VUID-VkSwapchainCreateInfoKHR-imageFormat-01778]]
@ -345,7 +345,6 @@ endif::VK_KHX_device_group[]
pname:imageArrayLayers must: be supported for ename:VK_IMAGE_TYPE_2D
ename:VK_IMAGE_TILING_OPTIMAL images as reported by
flink:vkGetPhysicalDeviceImageFormatProperties.
****
include::../../validity/structs/VkSwapchainCreateInfoKHR.txt[]
@ -359,12 +358,16 @@ specifying parameters of swapchain creation, are:
include::../../api/enums/VkSwapchainCreateFlagBitsKHR.txt[]
ifdef::VK_KHX_device_group[]
* ename:VK_SWAPCHAIN_CREATE_BIND_SFR_BIT_KHX specifies that images created
from the swapchain (i.e. with the pname:swapchain member of
slink:VkImageSwapchainCreateInfoKHX set to this swapchain's handle)
must: use ename:VK_IMAGE_CREATE_BIND_SFR_BIT_KHX.
endif::VK_KHX_device_group[]
ifdef::VK_VERSION_1_1,VK_KHR_device_group[]
* ename:VK_SWAPCHAIN_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT_KHR specifies
that images created from the swapchain (i.e. with the pname:swapchain
member of slink:VkImageSwapchainCreateInfoKHR set to this swapchain's
handle) must: use ename:VK_IMAGE_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT.
endif::VK_VERSION_1_1,VK_KHR_device_group[]
ifdef::VK_VERSION_1_1[]
* ename:VK_SWAPCHAIN_CREATE_PROTECTED_BIT_KHR specifies that images
created from the swapchain are protected images.
endif::VK_VERSION_1_1[]
--
@ -376,31 +379,31 @@ sname:VkSwapchainCreateFlagsKHR is a bitmask type for setting a mask of zero
or more slink:VkSwapchainCreateFlagBitsKHR.
--
ifdef::VK_KHX_device_group[]
ifdef::VK_VERSION_1_1,VK_KHR_device_group[]
[open,refpage='VkDeviceGroupSwapchainCreateInfoKHX',desc='Structure specifying parameters of a newly created swapchain object',type='structs']
[open,refpage='VkDeviceGroupSwapchainCreateInfoKHR',desc='Structure specifying parameters of a newly created swapchain object',type='structs']
--
If the pname:pNext chain of slink:VkSwapchainCreateInfoKHR includes a
sname:VkDeviceGroupSwapchainCreateInfoKHX structure, then that structure
sname:VkDeviceGroupSwapchainCreateInfoKHR structure, then that structure
includes a set of device group present modes that the swapchain can: be used
with.
The sname:VkDeviceGroupSwapchainCreateInfoKHX structure is defined as:
The sname:VkDeviceGroupSwapchainCreateInfoKHR structure is defined as:
include::../../api/structs/VkDeviceGroupSwapchainCreateInfoKHX.txt[]
include::../../api/structs/VkDeviceGroupSwapchainCreateInfoKHR.txt[]
* pname:sType is the type of this structure.
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
* pname:modes is a bitfield of modes that the swapchain can: be used with.
If this structure is not present, pname:modes is considered to be
ename:VK_DEVICE_GROUP_PRESENT_MODE_LOCAL_BIT_KHX.
ename:VK_DEVICE_GROUP_PRESENT_MODE_LOCAL_BIT_KHR.
include::../../validity/structs/VkDeviceGroupSwapchainCreateInfoKHX.txt[]
include::../../validity/structs/VkDeviceGroupSwapchainCreateInfoKHR.txt[]
--
endif::VK_KHX_device_group[]
endif::VK_VERSION_1_1,VK_KHR_device_group[]
ifdef::VK_EXT_display_control[]
include::../VK_EXT_display_control/swapchain_counters.txt[]
@ -419,12 +422,21 @@ the following sname:VkImageCreateInfo parameters:
[options="header"]
|====
| sname:VkImageCreateInfo Field | Value
ifndef::VK_KHX_device_group[]
ifndef::VK_VERSION_1_1,VK_KHR_device_group[]
| pname:flags | 0
endif::VK_KHX_device_group[]
ifdef::VK_KHX_device_group[]
| pname:flags | ename:VK_IMAGE_CREATE_BIND_SFR_BIT_KHX if ename:VK_SWAPCHAIN_CREATE_BIND_SFR_BIT_KHX is set, else 0
endif::VK_KHX_device_group[]
endif::VK_VERSION_1_1,VK_KHR_device_group[]
ifdef::VK_VERSION_1_1,VK_KHR_device_group[]
| pname:flags |
ifdef::VK_VERSION_1_1,VK_KHR_device_group[]
ename:VK_IMAGE_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT is set if ename:VK_SWAPCHAIN_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT_KHR is set
endif::VK_VERSION_1_1,VK_KHR_device_group[]
ifdef::VK_VERSION_1_1[]
ename:VK_IMAGE_CREATE_PROTECTED_BIT is set if ename:VK_SWAPCHAIN_CREATE_PROTECTED_BIT_KHR is set
endif::VK_VERSION_1_1[]
all other bits are unset
endif::VK_VERSION_1_1,VK_KHR_device_group[]
| pname:imageType | ename:VK_IMAGE_TYPE_2D
| pname:format | `pCreateInfo->imageFormat`
| pname:extent | `{pCreateInfo->imageExtent.width, pCreateInfo->imageExtent.height, 1}`
@ -579,11 +591,11 @@ results in undefined behavior.
See flink:vkDestroySwapchainKHR for further details on the lifetime of
presentable images.
ifdef::VK_KHX_device_group[]
ifdef::VK_VERSION_1_1,VK_KHR_device_group[]
Images can: also be created by using flink:vkCreateImage with
slink:VkImageSwapchainCreateInfoKHX and bound to swapchain memory using
flink:vkBindImageMemory2KHR with slink:VkBindImageMemorySwapchainInfoKHX.
slink:VkImageSwapchainCreateInfoKHR and bound to swapchain memory using
flink:vkBindImageMemory2KHR with slink:VkBindImageMemorySwapchainInfoKHR.
These images can: be used anywhere swapchain images are used, and are useful
in logical devices with multiple physical devices to create peer memory
bindings of swapchain memory.
@ -591,7 +603,7 @@ These images and bindings have no effect on what memory is presented.
Unlike images retrieved from fname:vkGetSwapchainImagesKHR, these images
must: be destroyed with flink:vkDestroyImage.
endif::VK_KHX_device_group[]
endif::VK_VERSION_1_1,VK_KHR_device_group[]
[open,refpage='vkAcquireNextImageKHR',desc='Retrieve the index of the next available presentable image',type='protos']
--
@ -755,22 +767,88 @@ the presentable images remain owned by the queue family the image was
previously presented on.
====
ifdef::VK_KHX_device_group[]
The possible return values for fname:vkAcquireNextImageKHR depend on the
pname:timeout provided:
[open,refpage='vkAcquireNextImage2KHX',desc='Retrieve the index of the next available presentable image',type='protos']
* ename:VK_SUCCESS is returned if an image became available.
* ename:VK_ERROR_SURFACE_LOST_KHR if the surface becomes no longer
available.
* ename:VK_NOT_READY is returned if pname:timeout is zero and no image was
available.
* ename:VK_TIMEOUT is returned if pname:timeout is greater than zero and
less than `UINT64_MAX`, and no image became available within the time
allowed.
* ename:VK_SUBOPTIMAL_KHR is returned if an image became available, and
the swapchain no longer matches the surface properties exactly, but can:
still be used to present to the surface successfully.
[NOTE]
.Note
====
This may: happen, for example, if the platform surface has been resized but
the platform is able to scale the presented images to the new size to
produce valid surface updates.
It is up to the application to decide whether it prefers to continue using
the current swapchain indefinitely or temporarily in this state, or to
re-create the swapchain to better match the platform surface properties.
====
* ename:VK_ERROR_OUT_OF_DATE_KHR is returned if the surface has changed in
such a way that it is no longer compatible with the swapchain, and
further presentation requests using the swapchain will fail.
Applications must: query the new surface properties and recreate their
swapchain if they wish to continue presenting to the surface.
If the native surface and presented image sizes no longer match,
presentation may: fail.
If presentation does succeed, parts of the native surface may: be undefined,
parts of the presented image may: have been clipped before presentation,
and/or the image may: have been scaled (uniformly or not uniformly) before
presentation.
It is the application's responsibility to detect surface size changes and
react appropriately.
If presentation fails because of a mismatch in the surface and presented
image sizes, a ename:VK_ERROR_OUT_OF_DATE_KHR error will be returned.
Before an application can: present an image, the image's layout must: be
transitioned to the ename:VK_IMAGE_LAYOUT_PRESENT_SRC_KHR
ifdef::VK_KHR_shared_presentable_image[]
layout, or for a shared presentable image the
ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR
endif::VK_KHR_shared_presentable_image[]
layout.
.Note
[NOTE]
====
When transitioning the image to
ifdef::VK_KHR_shared_presentable_image[]
ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR or
endif::VK_KHR_shared_presentable_image[]
ename:VK_IMAGE_LAYOUT_PRESENT_SRC_KHR, there is no need to delay subsequent
processing, or perform any visibility operations (as flink:vkQueuePresentKHR
performs automatic visibility operations).
To achieve this, the pname:dstAccessMask member of the
slink:VkImageMemoryBarrier should: be set to `0`, and the pname:dstStageMask
parameter should: be set to ename:VK_PIPELINE_STAGE_BOTTOM_OF_PIPE_BIT.
====
ifdef::VK_VERSION_1_1,VK_KHR_device_group[]
[open,refpage='vkAcquireNextImage2KHR',desc='Retrieve the index of the next available presentable image',type='protos']
--
To acquire an available presentable image to use, and retrieve the index of
that image, call:
include::../../api/protos/vkAcquireNextImage2KHX.txt[]
include::../../api/protos/vkAcquireNextImage2KHR.txt[]
* pname:device is the device associated with pname:swapchain.
* pname:pAcquireInfo is a pointer to a structure of type
slink:VkAcquireNextImageInfoKHX containing parameters of the acquire.
slink:VkAcquireNextImageInfoKHR containing parameters of the acquire.
* pname:pImageIndex is a pointer to a code:uint32_t that is set to the
index of the next image to use.
.Valid Usage
****
* [[VUID-vkAcquireNextImage2KHX-swapchain-01803]]
@ -783,15 +861,15 @@ include::../../api/protos/vkAcquireNextImage2KHX.txt[]
of pname:pAcquireInfo must: not be ename:UINT64_MAX
****
include::../../validity/protos/vkAcquireNextImage2KHX.txt[]
include::../../validity/protos/vkAcquireNextImage2KHR.txt[]
--
[open,refpage='VkAcquireNextImageInfoKHX',desc='Structure specifying parameters of the acquire',type='structs']
[open,refpage='VkAcquireNextImageInfoKHR',desc='Structure specifying parameters of the acquire',type='structs']
--
The sname:VkAcquireNextImageInfoKHX structure is defined as:
The sname:VkAcquireNextImageInfoKHR structure is defined as:
include::../../api/structs/VkAcquireNextImageInfoKHX.txt[]
include::../../api/structs/VkAcquireNextImageInfoKHR.txt[]
* pname:sType is the type of this structure.
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
@ -810,7 +888,7 @@ include all physical devices in the logical device.
[NOTE]
.Note
====
flink:vkAcquireNextImage2KHX signals at most one semaphore, even if the
flink:vkAcquireNextImage2KHR signals at most one semaphore, even if the
application requests waiting for multiple physical devices to be ready via
the pname:deviceMask.
However, only a single physical device can: wait on that semaphore, since
@ -823,33 +901,33 @@ succeeds, which the other physical device(s) can: wait upon.
.Valid Usage
****
* [[VUID-VkAcquireNextImageInfoKHX-swapchain-01675]]
* [[VUID-VkAcquireNextImageInfoKHR-swapchain-01675]]
pname:swapchain must: not be in the retired state
* [[VUID-VkAcquireNextImageInfoKHX-semaphore-01288]]
* [[VUID-VkAcquireNextImageInfoKHR-semaphore-01288]]
If pname:semaphore is not dlink:VK_NULL_HANDLE it must: be unsignaled
* [[VUID-VkAcquireNextImageInfoKHX-semaphore-01781]]
If pname:semaphore is not dlink:VK_NULL_HANDLE it must: not have any
uncompleted signal or wait operations pending
* [[VUID-VkAcquireNextImageInfoKHX-fence-01289]]
* [[VUID-VkAcquireNextImageInfoKHR-fence-01289]]
If pname:fence is not dlink:VK_NULL_HANDLE it must: be unsignaled and
must: not be associated with any other queue command that has not yet
completed execution on that queue
* [[VUID-VkAcquireNextImageInfoKHX-semaphore-01782]]
pname:semaphore and pname:fence must: not both be equal to
dlink:VK_NULL_HANDLE
* [[VUID-VkAcquireNextImageInfoKHX-deviceMask-01290]]
* [[VUID-VkAcquireNextImageInfoKHR-deviceMask-01290]]
pname:deviceMask must: be a valid device mask
* [[VUID-VkAcquireNextImageInfoKHX-deviceMask-01291]]
* [[VUID-VkAcquireNextImageInfoKHR-deviceMask-01291]]
pname:deviceMask must: not be zero
* [[VUID-VkAcquireNextImageInfoKHX-semaphore-01804]]
pname:semaphore and pname:fence must: not both be equal to
dlink:VK_NULL_HANDLE.
****
include::../../validity/structs/VkAcquireNextImageInfoKHX.txt[]
include::../../validity/structs/VkAcquireNextImageInfoKHR.txt[]
--
endif::VK_KHX_device_group[]
endif::VK_VERSION_1_1,VK_KHR_device_group[]
[open,refpage='vkQueuePresentKHR',desc='Queue an image for presentation',type='protos']
--
@ -1019,18 +1097,18 @@ ifdef::VK_KHR_display_swapchain[]
include::../VK_KHR_display_swapchain/display_swapchain_present.txt[]
endif::VK_KHR_display_swapchain[]
ifdef::VK_KHX_device_group[]
ifdef::VK_VERSION_1_1,VK_KHR_device_group[]
[open,refpage='VkDeviceGroupPresentInfoKHX',desc='Mode and mask controlling which physical devices\' images are presented',type='structs']
[open,refpage='VkDeviceGroupPresentInfoKHR',desc='Mode and mask controlling which physical devices\' images are presented',type='structs']
--
If the pname:pNext chain of slink:VkPresentInfoKHR includes a
sname:VkDeviceGroupPresentInfoKHX structure, then that structure includes an
sname:VkDeviceGroupPresentInfoKHR structure, then that structure includes an
array of device masks and a device group present mode.
The sname:VkDeviceGroupPresentInfoKHX structure is defined as:
The sname:VkDeviceGroupPresentInfoKHR structure is defined as:
include::../../api/structs/VkDeviceGroupPresentInfoKHX.txt[]
include::../../api/structs/VkDeviceGroupPresentInfoKHR.txt[]
* pname:sType is the type of this structure.
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
@ -1041,82 +1119,82 @@ include::../../api/structs/VkDeviceGroupPresentInfoKHX.txt[]
* pname:mode is the device group present mode that will be used for this
present.
If pname:mode is ename:VK_DEVICE_GROUP_PRESENT_MODE_LOCAL_BIT_KHX, then each
If pname:mode is ename:VK_DEVICE_GROUP_PRESENT_MODE_LOCAL_BIT_KHR, then each
element of pname:pDeviceMasks selects which instance of the swapchain image
is presented.
Each element of pname:pDeviceMasks must: have exactly one bit set, and the
corresponding physical device must: have a presentation engine as reported
by slink:VkDeviceGroupPresentCapabilitiesKHX.
by slink:VkDeviceGroupPresentCapabilitiesKHR.
If pname:mode is ename:VK_DEVICE_GROUP_PRESENT_MODE_REMOTE_BIT_KHX, then
If pname:mode is ename:VK_DEVICE_GROUP_PRESENT_MODE_REMOTE_BIT_KHR, then
each element of pname:pDeviceMasks selects which instance of the swapchain
image is presented.
Each element of pname:pDeviceMasks must: have exactly one bit set, and some
physical device in the logical device must: include that bit in its
slink:VkDeviceGroupPresentCapabilitiesKHX::pname:presentMask.
slink:VkDeviceGroupPresentCapabilitiesKHR::pname:presentMask.
If pname:mode is ename:VK_DEVICE_GROUP_PRESENT_MODE_SUM_BIT_KHX, then each
If pname:mode is ename:VK_DEVICE_GROUP_PRESENT_MODE_SUM_BIT_KHR, then each
element of pname:pDeviceMasks selects which instances of the swapchain image
are component-wise summed and the sum of those images is presented.
If the sum in any component is outside the representable range, the value of
that component is undefined.
Each element of pname:pDeviceMasks must: have a value for which all set bits
are set in one of the elements of
slink:VkDeviceGroupPresentCapabilitiesKHX::pname:presentMask.
slink:VkDeviceGroupPresentCapabilitiesKHR::pname:presentMask.
If pname:mode is
ename:VK_DEVICE_GROUP_PRESENT_MODE_LOCAL_MULTI_DEVICE_BIT_KHX, then each
ename:VK_DEVICE_GROUP_PRESENT_MODE_LOCAL_MULTI_DEVICE_BIT_KHR, then each
element of pname:pDeviceMasks selects which instance(s) of the swapchain
images are presented.
For each bit set in each element of pname:pDeviceMasks, the corresponding
physical device must: have a presentation engine as reported by
slink:VkDeviceGroupPresentCapabilitiesKHX.
slink:VkDeviceGroupPresentCapabilitiesKHR.
If sname:VkDeviceGroupPresentInfoKHX is not provided or pname:swapchainCount
If sname:VkDeviceGroupPresentInfoKHR is not provided or pname:swapchainCount
is zero then the masks are considered to be `1`.
If sname:VkDeviceGroupPresentInfoKHX is not provided, pname:mode is
considered to be ename:VK_DEVICE_GROUP_PRESENT_MODE_LOCAL_BIT_KHX.
If sname:VkDeviceGroupPresentInfoKHR is not provided, pname:mode is
considered to be ename:VK_DEVICE_GROUP_PRESENT_MODE_LOCAL_BIT_KHR.
.Valid Usage
****
* [[VUID-VkDeviceGroupPresentInfoKHX-swapchainCount-01297]]
* [[VUID-VkDeviceGroupPresentInfoKHR-swapchainCount-01297]]
pname:swapchainCount must: equal `0` or
slink:VkPresentInfoKHR::pname:swapchainCount
* [[VUID-VkDeviceGroupPresentInfoKHX-mode-01298]]
If pname:mode is ename:VK_DEVICE_GROUP_PRESENT_MODE_LOCAL_BIT_KHX, then
* [[VUID-VkDeviceGroupPresentInfoKHR-mode-01298]]
If pname:mode is ename:VK_DEVICE_GROUP_PRESENT_MODE_LOCAL_BIT_KHR, then
each element of pname:pDeviceMasks must: have exactly one bit set, and
the corresponding element of
slink:VkDeviceGroupPresentCapabilitiesKHX::pname:presentMask must: be
slink:VkDeviceGroupPresentCapabilitiesKHR::pname:presentMask must: be
non-zero
* [[VUID-VkDeviceGroupPresentInfoKHX-mode-01299]]
If pname:mode is ename:VK_DEVICE_GROUP_PRESENT_MODE_REMOTE_BIT_KHX, then
* [[VUID-VkDeviceGroupPresentInfoKHR-mode-01299]]
If pname:mode is ename:VK_DEVICE_GROUP_PRESENT_MODE_REMOTE_BIT_KHR, then
each element of pname:pDeviceMasks must: have exactly one bit set, and
some physical device in the logical device must: include that bit in its
slink:VkDeviceGroupPresentCapabilitiesKHX::pname:presentMask.
* [[VUID-VkDeviceGroupPresentInfoKHX-mode-01300]]
If pname:mode is ename:VK_DEVICE_GROUP_PRESENT_MODE_SUM_BIT_KHX, then
slink:VkDeviceGroupPresentCapabilitiesKHR::pname:presentMask.
* [[VUID-VkDeviceGroupPresentInfoKHR-mode-01300]]
If pname:mode is ename:VK_DEVICE_GROUP_PRESENT_MODE_SUM_BIT_KHR, then
each element of pname:pDeviceMasks must: have a value for which all set
bits are set in one of the elements of
slink:VkDeviceGroupPresentCapabilitiesKHX::pname:presentMask
* [[VUID-VkDeviceGroupPresentInfoKHX-mode-01301]]
slink:VkDeviceGroupPresentCapabilitiesKHR::pname:presentMask
* [[VUID-VkDeviceGroupPresentInfoKHR-mode-01301]]
If pname:mode is
ename:VK_DEVICE_GROUP_PRESENT_MODE_LOCAL_MULTI_DEVICE_BIT_KHX, then for
ename:VK_DEVICE_GROUP_PRESENT_MODE_LOCAL_MULTI_DEVICE_BIT_KHR, then for
each bit set in each element of pname:pDeviceMasks, the corresponding
element of slink:VkDeviceGroupPresentCapabilitiesKHX::pname:presentMask
element of slink:VkDeviceGroupPresentCapabilitiesKHR::pname:presentMask
must: be non-zero
* [[VUID-VkDeviceGroupPresentInfoKHX-pDeviceMasks-01302]]
* [[VUID-VkDeviceGroupPresentInfoKHR-pDeviceMasks-01302]]
The value of each element of pname:pDeviceMasks must: be equal to the
device mask passed in slink:VkAcquireNextImageInfoKHX::pname:deviceMask
device mask passed in slink:VkAcquireNextImageInfoKHR::pname:deviceMask
when the image index was last acquired
* [[VUID-VkDeviceGroupPresentInfoKHX-mode-01303]]
* [[VUID-VkDeviceGroupPresentInfoKHR-mode-01303]]
pname:mode must: have exactly one bit set, and that bit must: have been
included in slink:VkDeviceGroupSwapchainCreateInfoKHX::pname:modes
included in slink:VkDeviceGroupSwapchainCreateInfoKHR::pname:modes
****
include::../../validity/structs/VkDeviceGroupPresentInfoKHX.txt[]
include::../../validity/structs/VkDeviceGroupPresentInfoKHR.txt[]
--
endif::VK_KHX_device_group[]
endif::VK_VERSION_1_1,VK_KHR_device_group[]
ifdef::VK_GOOGLE_display_timing[]
include::../VK_GOOGLE_display_timing/PresentTimeInfo.txt[]

1
doc/specs/vulkan/chapters/VK_NVX_device_generated_commands/objecttable.txt
View File

@ -272,7 +272,6 @@ include::../../validity/structs/VkObjectTablePipelineEntryNVX.txt[]
[open,refpage='VkObjectTableDescriptorSetEntryNVX',desc='Parameters of an object table descriptor set entry',type='structs']
--
include::../../api/structs/VkObjectTableDescriptorSetEntryNVX.txt[]
* pname:pipelineLayout specifies the sname:VkPipelineLayout that the

4
doc/specs/vulkan/chapters/VK_NV_external_memory_win32/import_memory_win32.txt
View File

@ -56,12 +56,12 @@ include::../../api/enums/VkExternalMemoryHandleTypeFlagBitsNV.txt[]
ifdef::editing-notes[]
[NOTE]
.editing-note
==================
====
(Jon) If additional (non-Win32) bits are added to the possible memory types,
this type should move to the `<<VK_NV_external_memory_capabilities>>`
section, and each bit would then be protected by ifdefs for the extension
it's defined by.
==================
====
endif::editing-notes[]
--

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

@ -48,23 +48,23 @@ pname:pColor.
.Valid Usage
****
ifdef::VK_KHR_maintenance1[]
ifdef::VK_VERSION_1_1,VK_KHR_maintenance1[]
* [[VUID-vkCmdClearColorImage-image-00001]]
pname:image must: use a format that supports
ename:VK_FORMAT_FEATURE_TRANSFER_DST_BIT_KHR, which is indicated by
ename:VK_FORMAT_FEATURE_TRANSFER_DST_BIT, which is indicated by
sname:VkFormatProperties::pname:linearTilingFeatures (for linearly tiled
images) or sname:VkFormatProperties::pname:optimalTilingFeatures (for
optimally tiled images) - as returned by
fname:vkGetPhysicalDeviceFormatProperties
endif::VK_KHR_maintenance1[]
endif::VK_VERSION_1_1,VK_KHR_maintenance1[]
* [[VUID-vkCmdClearColorImage-image-00002]]
pname:image must: have been created with
ename:VK_IMAGE_USAGE_TRANSFER_DST_BIT usage flag
ifdef::VK_KHR_sampler_ycbcr_conversion[]
ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
* [[VUID-vkCmdClearColorImage-image-01545]]
pname:image must: not use a format listed in
<<features-formats-requiring-sampler-ycbcr-conversion>>
endif::VK_KHR_sampler_ycbcr_conversion[]
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
* [[VUID-vkCmdClearColorImage-image-00003]]
If pname:image is non-sparse then it must: be bound completely and
contiguously to a single sname:VkDeviceMemory object
@ -107,6 +107,12 @@ endif::VK_KHR_shared_presentable_image[]
pname:image was created
* [[VUID-vkCmdClearColorImage-image-00007]]
pname:image must: not have a compressed or depth/stencil format
ifdef::VK_VERSION_1_1[]
* If pname:commandBuffer is an unprotected command buffer, then
pname:image must: not be a protected image
* If pname:commandBuffer is a protected command buffer, then pname:image
must: not be an unprotected image
endif::VK_VERSION_1_1[]
****
include::../validity/protos/vkCmdClearColorImage.txt[]
@ -144,15 +150,15 @@ include::../api/protos/vkCmdClearDepthStencilImage.txt[]
.Valid Usage
****
ifdef::VK_KHR_maintenance1[]
ifdef::VK_VERSION_1_1,VK_KHR_maintenance1[]
* [[VUID-vkCmdClearDepthStencilImage-image-00008]]
pname:image must: use a format that supports
ename:VK_FORMAT_FEATURE_TRANSFER_DST_BIT_KHR, which is indicated by
ename:VK_FORMAT_FEATURE_TRANSFER_DST_BIT, which is indicated by
sname:VkFormatProperties::pname:linearTilingFeatures (for linearly tiled
images) or sname:VkFormatProperties::pname:optimalTilingFeatures (for
optimally tiled images) - as returned by
fname:vkGetPhysicalDeviceFormatProperties
endif::VK_KHR_maintenance1[]
endif::VK_VERSION_1_1,VK_KHR_maintenance1[]
* [[VUID-vkCmdClearDepthStencilImage-image-00009]]
pname:image must: have been created with
ename:VK_IMAGE_USAGE_TRANSFER_DST_BIT usage flag
@ -191,6 +197,13 @@ endif::VK_KHR_maintenance1[]
pname:image was created
* [[VUID-vkCmdClearDepthStencilImage-image-00014]]
pname:image must: have a depth/stencil format
ifdef::VK_VERSION_1_1[]
* If pname:commandBuffer is an unprotected command buffer, then
pname:image must: not be a protected image
* If pname:commandBuffer is a protected command buffer, then pname:image
must: not be an unprotected image
endif::VK_VERSION_1_1[]
****
include::../validity/protos/vkCmdClearDepthStencilImage.txt[]
@ -241,11 +254,11 @@ attachments and the command parameters.
* [[VUID-vkCmdClearAttachments-pRects-00017]]
The layers specified by each element of pname:pRects must: be contained
within every attachment that pname:pAttachments refers to
ifdef::VK_KHX_multiview[]
ifdef::VK_VERSION_1_1,VK_KHR_multiview[]
* [[VUID-vkCmdClearAttachments-baseArrayLayer-00018]]
If the render pass instance this is recorded in uses multiview, then
pname:baseArrayLayer must: be zero and pname:layerCount must: be one.
endif::VK_KHX_multiview[]
endif::VK_VERSION_1_1,VK_KHR_multiview[]
****
include::../validity/protos/vkCmdClearAttachments.txt[]
@ -317,6 +330,12 @@ described for flink:vkCreateRenderPass.
pname:aspectMask must: not include ename:VK_IMAGE_ASPECT_METADATA_BIT
* [[VUID-VkClearAttachment-clearValue-00021]]
pname:clearValue must: be a valid sname:VkClearValue union
ifdef::VK_VERSION_1_1[]
* If pname:commandBuffer is an unprotected command buffer, then the
attachment to be cleared must: not be a protected image.
* If pname:commandBuffer is a protected command buffer, then the
attachment to be cleared must: not be an unprotected image.
endif::VK_VERSION_1_1[]
****
include::../validity/structs/VkClearAttachment.txt[]
@ -471,14 +490,20 @@ fname:vkCmdFillBuffer.
* [[VUID-vkCmdFillBuffer-dstBuffer-00029]]
pname:dstBuffer must: have been created with
ename:VK_BUFFER_USAGE_TRANSFER_DST_BIT usage flag
ifndef::VK_KHR_maintenance1[]
ifndef::VK_VERSION_1_1,VK_KHR_maintenance1[]
* [[VUID-vkCmdFillBuffer-commandBuffer-00030]]
The sname:VkCommandPool that pname:commandBuffer was allocated from
must: support graphics or compute operations
endif::VK_KHR_maintenance1[]
endif::VK_VERSION_1_1,VK_KHR_maintenance1[]
* [[VUID-vkCmdFillBuffer-dstBuffer-00031]]
If pname:dstBuffer is non-sparse then it must: be bound completely and
contiguously to a single sname:VkDeviceMemory object
ifdef::VK_VERSION_1_1[]
* If pname:commandBuffer is an unprotected command buffer, then
pname:dstBuffer must: not be a protected buffer
* If pname:commandBuffer is a protected command buffer, then
pname:dstBuffer must: not be an unprotected buffer
endif::VK_VERSION_1_1[]
****
include::../validity/protos/vkCmdFillBuffer.txt[]
@ -556,6 +581,12 @@ fname:vkCmdUpdateBuffer.
pname:dataSize must: be less than or equal to `65536`
* [[VUID-vkCmdUpdateBuffer-dataSize-00038]]
pname:dataSize must: be a multiple of `4`
ifdef::VK_VERSION_1_1[]
* If pname:commandBuffer is an unprotected command buffer, then
pname:dstBuffer must: not be a protected buffer
* If pname:commandBuffer is a protected command buffer, then
pname:dstBuffer must: not be an unprotected buffer
endif::VK_VERSION_1_1[]
****
include::../validity/protos/vkCmdUpdateBuffer.txt[]
@ -566,6 +597,6 @@ include::../validity/protos/vkCmdUpdateBuffer.txt[]
====
The pname:pData parameter was of type code:uint32_t* instead of code:void*
prior to revision 1.0.19 of the Specification and dlink:VK_HEADER_VERSION 19
of `vulkan.h`.
of the <<boilerplate-headers,Vulkan Header Files>>.
This was a historical anomaly, as the source data may be of other types.
====

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

@ -86,18 +86,22 @@ Pending::
changes the state of a command buffer from the executable state to the
_pending state_.
Whilst in the pending state, applications must: not attempt to modify
the command buffer in any way - the device may: be processing the
the command buffer in any way - as the device may: be processing the
commands recorded to it.
Once execution of a command buffer completes, the command buffer reverts
back to the executable state.
back to either the _executable state_, or the _invalid state_ if it was
recorded with ename:VK_COMMAND_BUFFER_USAGE_ONE_TIME_SUBMIT_BIT.
A <<synchronization, synchronization>> command should: be used to detect
when this occurs.
Invalid::
Some operations, such as modifying or deleting a resource that was used
in a command recorded to a command buffer, will transition the state of
a command buffer into the _invalid state_.
Command buffers in the invalid state can: only be reset, moved to the
_recording state_, or freed.
Some operations, such as <<fundamentals-objectmodel-lifetime-cmdbuffers,
modifying or deleting a resource>> that was used in a command recorded
to a command buffer, will transition the state of that command buffer
into the _invalid state_.
Command buffers in the invalid state can: only be reset or freed.
[[commandbuffer-lifecycle-diagram]]
image::images/commandbuffer_lifecycle.svg[title="Lifecycle of a command buffer",{fullimagewidth},align="center"]
Any given command that operates on a command buffer has its own requirements
on what state a command buffer must: be in, which are detailed in the valid
@ -209,6 +213,13 @@ include::../api/enums/VkCommandPoolCreateFlagBits.txt[]
flink:vkBeginCommandBuffer.
If this flag is not set on a pool, then fname:vkResetCommandBuffer must:
not be called for any command buffer allocated from that pool.
ifdef::VK_VERSION_1_1[]
* ename:VK_COMMAND_POOL_CREATE_PROTECTED_BIT indicates that command
buffers allocated from the pool are protected command buffers.
If the protected memory feature is not enabled, the
ename:VK_COMMAND_POOL_CREATE_PROTECTED_BIT bit of pname:flags must: not
be set.
endif::VK_VERSION_1_1[]
--
@ -220,14 +231,22 @@ sname:VkCommandPoolCreateFlags is a bitmask type for setting a mask of zero
or more slink:VkCommandPoolCreateFlagBits.
--
ifdef::VK_KHR_maintenance1[]
ifdef::VK_VERSION_1_1,VK_KHR_maintenance1[]
[open,refpage='vkTrimCommandPoolKHR',desc='Trim a command pool',type='protos']
[open,refpage='vkTrimCommandPool',desc='Trim a command pool',type='protos']
--
To trim a command pool, call:
ifdef::VK_VERSION_1_1[]
include::../api/protos/vkTrimCommandPool.txt[]
endif::VK_VERSION_1_1[]
ifdef::VK_VERSION_1_1+VK_KHR_maintenance1[or the equivalent command]
ifdef::VK_KHR_maintenance1[]
include::../api/protos/vkTrimCommandPoolKHR.txt[]
endif::VK_KHR_maintenance1[]
* pname:device is the logical device that owns the command pool.
* pname:commandPool is the command pool to trim.
@ -276,11 +295,25 @@ application-known points when there exists enough unused memory that the
cost of trimming is "`worth`" it.
====
include::../validity/protos/vkTrimCommandPoolKHR.txt[]
include::../validity/protos/vkTrimCommandPool.txt[]
--
[open,refpage='VkCommandPoolTrimFlags',desc='Reserved for future use',type='enums']
--
include::../api/flags/VkCommandPoolTrimFlags.txt[]
ifdef::VK_KHR_maintenance1[]
or the equivalent
include::../api/flags/VkCommandPoolTrimFlagsKHR.txt[]
endif::VK_KHR_maintenance1[]
sname:VkCommandPoolTrimFlags is a bitmask type for setting a mask, but is
currently reserved for future use.
--
endif::VK_VERSION_1_1,VK_KHR_maintenance1[]
[open,refpage='vkResetCommandPool',desc='Reset a command pool',type='protos']
--
@ -392,14 +425,14 @@ include::../api/protos/vkAllocateCommandBuffers.txt[]
pname:commandBufferCount member of pname:pAllocateInfo.
Each allocated command buffer begins in the initial state.
ifdef::VK_KHR_maintenance1[]
ifdef::VK_VERSION_1_1,VK_KHR_maintenance1[]
fname:vkAllocateCommandBuffers can: be used to create multiple command
buffers.
If the creation of any of those command buffers fails, the implementation
must: destroy all successfully created command buffer objects from this
command, set all entries of the pname:pCommandBuffers array to `NULL` and
return the error.
endif::VK_KHR_maintenance1[]
endif::VK_VERSION_1_1,VK_KHR_maintenance1[]
When command buffers are first allocated, they are in the
<<commandbuffers-lifecycle, initial state>>.
@ -786,6 +819,12 @@ executable state>>.
* [[VUID-vkEndCommandBuffer-commandBuffer-00061]]
All queries made <<queries-operation-active,active>> during the
recording of pname:commandBuffer must: have been made inactive
ifdef::VK_EXT_debug_utils[]
* If pname:commandBuffer is a secondary command buffer, there must: not be
an outstanding flink:vkCmdBeginUtilsLabelEXT command recorded to
pname:commandBuffer that has not previously been ended by a call to
flink:vkCmdEndDebugUtilsLabelEXT.
endif::VK_EXT_debug_utils[]
ifdef::VK_EXT_debug_marker[]
* [[VUID-vkEndCommandBuffer-commandBuffer-00062]]
If pname:commandBuffer is a secondary command buffer, there must: not be
@ -1098,8 +1137,8 @@ include::../api/structs/VkWin32KeyedMutexAcquireReleaseInfoKHR.txt[]
Each member of pname:pAcquireSyncs and pname:pReleaseSyncs must: be a
device memory object imported by setting
slink:VkImportMemoryWin32HandleInfoKHR::pname:handleType to
ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_BIT_KHR or
ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_KMT_BIT_KHR.
ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_BIT or
ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_KMT_BIT.
****
include::../validity/structs/VkWin32KeyedMutexAcquireReleaseInfoKHR.txt[]
@ -1111,19 +1150,63 @@ ifdef::VK_NV_win32_keyed_mutex[]
include::VK_NV_win32_keyed_mutex/keyed_mutex_submit.txt[]
endif::VK_NV_win32_keyed_mutex[]
ifdef::VK_KHX_device_group[]
ifdef::VK_VERSION_1_1[]
[open,refpage='VkDeviceGroupSubmitInfoKHX',desc='Structure indicating which physical devices execute semaphore operations and command buffers',type='structs']
[open,refpage='VkProtectedSubmitInfo',desc='Structure indicating whether the submission is protected',type='structs']
--
If the ename:pNext chain of slink:VkSubmitInfo includes a
sname:VkProtectedSubmitInfo structure, then the structure indicates whether
the batch is protected.
The sname:VkProtectedSubmitInfo structure is defined as:
include::../api/structs/VkProtectedSubmitInfo.txt[]
* pname:protectedSubmit indicates whether the batch is protected.
If pname:protectedSubmit is ename:VK_TRUE, the batch is protected.
If pname:protectedSubmit is ename:VK_FALSE, the batch is unprotected.
If the sname:VkSubmitInfo::pname:pNext chain does not contain this
structure, the batch is unprotected.
.Valid Usage
****
* If the protected memory feature is not enabled, pname:protectedSubmit
must: not be ename:VK_TRUE.
* If pname:protectedSubmit is ename:VK_TRUE, then each element of the
pname:pCommandBuffers array must: be a protected command buffer.
* If pname:protectedSubmit is ename:VK_FALSE, then each element of the
pname:pCommandBuffers array must: be an unprotected command buffer.
* If the sname:VkSubmitInfo::pname:pNext chain does not include a
sname:VkProtectedSubmitInfo structure, then each element of the command
buffer of the pname:pCommandBuffers array must: be an unprotected
command buffer.
****
include::../validity/structs/VkProtectedSubmitInfo.txt[]
--
endif::VK_VERSION_1_1[]
ifdef::VK_VERSION_1_1,VK_KHR_device_group[]
[open,refpage='VkDeviceGroupSubmitInfo',desc='Structure indicating which physical devices execute semaphore operations and command buffers',type='structs']
--
If the pname:pNext chain of slink:VkSubmitInfo includes a
sname:VkDeviceGroupSubmitInfoKHX structure, then that structure includes
device indices and masks specifying which physical devices execute semaphore
sname:VkDeviceGroupSubmitInfo structure, then that structure includes device
indices and masks specifying which physical devices execute semaphore
operations and command buffers.
The sname:VkDeviceGroupSubmitInfoKHX structure is defined as:
The sname:VkDeviceGroupSubmitInfo structure is defined as:
include::../api/structs/VkDeviceGroupSubmitInfoKHX.txt[]
include::../api/structs/VkDeviceGroupSubmitInfo.txt[]
ifdef::VK_KHR_device_group[]
or the equivalent
include::../api/structs/VkDeviceGroupSubmitInfoKHR.txt[]
endif::VK_KHR_device_group[]
* pname:sType is the type of this structure.
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
@ -1152,28 +1235,28 @@ execute on device index zero.
.Valid Usage
****
* [[VUID-VkDeviceGroupSubmitInfoKHX-waitSemaphoreCount-00082]]
* [[VUID-VkDeviceGroupSubmitInfo-waitSemaphoreCount-00082]]
pname:waitSemaphoreCount must: equal
slink:VkSubmitInfo::pname:waitSemaphoreCount
* [[VUID-VkDeviceGroupSubmitInfoKHX-commandBufferCount-00083]]
* [[VUID-VkDeviceGroupSubmitInfo-commandBufferCount-00083]]
pname:commandBufferCount must: equal
slink:VkSubmitInfo::pname:commandBufferCount
* [[VUID-VkDeviceGroupSubmitInfoKHX-signalSemaphoreCount-00084]]
* [[VUID-VkDeviceGroupSubmitInfo-signalSemaphoreCount-00084]]
pname:signalSemaphoreCount must: equal
slink:VkSubmitInfo::pname:signalSemaphoreCount
* [[VUID-VkDeviceGroupSubmitInfoKHX-pWaitSemaphoreDeviceIndices-00085]]
* [[VUID-VkDeviceGroupSubmitInfo-pWaitSemaphoreDeviceIndices-00085]]
All elements of pname:pWaitSemaphoreDeviceIndices and
pname:pSignalSemaphoreDeviceIndices must: be valid device indices
* [[VUID-VkDeviceGroupSubmitInfoKHX-pCommandBufferDeviceMasks-00086]]
* [[VUID-VkDeviceGroupSubmitInfo-pCommandBufferDeviceMasks-00086]]
All elements of pname:pCommandBufferDeviceMasks must: be valid device
masks
****
include::../validity/structs/VkDeviceGroupSubmitInfoKHX.txt[]
include::../validity/structs/VkDeviceGroupSubmitInfo.txt[]
--
endif::VK_KHX_device_group[]
endif::VK_VERSION_1_1,VK_KHR_device_group[]
[[commandbuffers-submission-progress]]
@ -1311,12 +1394,18 @@ command buffer becomes <<commandbuffers-lifecycle, invalid>>.
* [[VUID-vkCmdExecuteCommands-pCommandBuffers-00105]]
Each element of pname:pCommandBuffers must: not begin any query types
that are <<queries-operation-active,active>> in pname:commandBuffer
ifdef::VK_VERSION_1_1[]
* If pname:commandBuffer is a protected command buffer, then each element
of pname:pCommandBuffers must: be a protected command buffer.
* If pname:commandBuffer is an unprotected command buffer, then each
element of pname:pCommandBuffers must: be an unprotected command buffer.
endif::VK_VERSION_1_1[]
****
include::../validity/protos/vkCmdExecuteCommands.txt[]
--
ifdef::VK_KHX_device_group[]
ifdef::VK_VERSION_1_1,VK_KHR_device_group[]
[[commandbuffers-devicemask]]
== Command Buffer Device Mask
@ -1337,20 +1426,26 @@ most recent command that set that state must: have included all physical
devices that execute the action command in its current device mask.
The command buffer's device mask is orthogonal to the
pname:pCommandBufferDeviceMasks member of slink:VkDeviceGroupSubmitInfoKHX.
pname:pCommandBufferDeviceMasks member of slink:VkDeviceGroupSubmitInfo.
Commands only execute on a physical device if the device index is set in
both device masks.
[open,refpage='VkDeviceGroupCommandBufferBeginInfoKHX',desc='Set the initial device mask for a command buffer',type='structs']
[open,refpage='VkDeviceGroupCommandBufferBeginInfo',desc='Set the initial device mask for a command buffer',type='structs']
--
If the pname:pNext chain of slink:VkCommandBufferBeginInfo includes a
sname:VkDeviceGroupCommandBufferBeginInfoKHX structure, then that structure
sname:VkDeviceGroupCommandBufferBeginInfo structure, then that structure
includes an initial device mask for the command buffer.
The sname:VkDeviceGroupCommandBufferBeginInfoKHX structure is defined as:
The sname:VkDeviceGroupCommandBufferBeginInfo structure is defined as:
include::../api/structs/VkDeviceGroupCommandBufferBeginInfoKHX.txt[]
include::../api/structs/VkDeviceGroupCommandBufferBeginInfo.txt[]
ifdef::VK_KHR_device_group[]
or the equivalent
include::../api/structs/VkDeviceGroupCommandBufferBeginInfoKHR.txt[]
endif::VK_KHR_device_group[]
* pname:sType is the type of this structure.
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
@ -1366,22 +1461,30 @@ when the command buffer begins recording.
.Valid Usage
****
* [[VUID-VkDeviceGroupCommandBufferBeginInfoKHX-deviceMask-00106]]
* [[VUID-VkDeviceGroupCommandBufferBeginInfo-deviceMask-00106]]
pname:deviceMask must: be a valid device mask value
* [[VUID-VkDeviceGroupCommandBufferBeginInfoKHX-deviceMask-00107]]
* [[VUID-VkDeviceGroupCommandBufferBeginInfo-deviceMask-00107]]
pname:deviceMask must: not be zero
****
include::../validity/structs/VkDeviceGroupCommandBufferBeginInfoKHX.txt[]
include::../validity/structs/VkDeviceGroupCommandBufferBeginInfo.txt[]
--
[open,refpage='vkCmdSetDeviceMaskKHX',desc='Modify device mask of a command buffer',type='protos']
[open,refpage='vkCmdSetDeviceMask',desc='Modify device mask of a command buffer',type='protos']
--
To update the current device mask of a command buffer, call:
include::../api/protos/vkCmdSetDeviceMaskKHX.txt[]
ifdef::VK_VERSION_1_1[]
include::../api/protos/vkCmdSetDeviceMask.txt[]
endif::VK_VERSION_1_1[]
ifdef::VK_VERSION_1_1+VK_KHR_device_group[or the equivalent command]
ifdef::VK_KHR_device_group[]
include::../api/protos/vkCmdSetDeviceMaskKHR.txt[]
endif::VK_KHR_device_group[]
* pname:commandBuffer is command buffer whose current device mask is
modified.
@ -1392,22 +1495,22 @@ all physical devices whose bit indices are not set in the mask.
.Valid Usage
****
* [[VUID-vkCmdSetDeviceMaskKHX-deviceMask-00108]]
* [[VUID-vkCmdSetDeviceMask-deviceMask-00108]]
pname:deviceMask must: be a valid device mask value
* [[VUID-vkCmdSetDeviceMaskKHX-deviceMask-00109]]
* [[VUID-vkCmdSetDeviceMask-deviceMask-00109]]
pname:deviceMask must: not be zero
* [[VUID-vkCmdSetDeviceMaskKHX-deviceMask-00110]]
* [[VUID-vkCmdSetDeviceMask-deviceMask-00110]]
pname:deviceMask must: not include any set bits that were not in the
slink:VkDeviceGroupCommandBufferBeginInfoKHX::pname:deviceMask value
when the command buffer began recording.
* [[VUID-vkCmdSetDeviceMaskKHX-deviceMask-00111]]
If fname:vkCmdSetDeviceMaskKHX is called inside a render pass instance,
slink:VkDeviceGroupCommandBufferBeginInfo::pname:deviceMask value when
the command buffer began recording.
* [[VUID-vkCmdSetDeviceMask-deviceMask-00111]]
If fname:vkCmdSetDeviceMask is called inside a render pass instance,
pname:deviceMask must: not include any set bits that were not in the
slink:VkDeviceGroupRenderPassBeginInfoKHX::pname:deviceMask value when
the render pass instance began recording.
slink:VkDeviceGroupRenderPassBeginInfo::pname:deviceMask value when the
render pass instance began recording.
****
include::../validity/protos/vkCmdSetDeviceMaskKHX.txt[]
include::../validity/protos/vkCmdSetDeviceMask.txt[]
--
endif::VK_KHX_device_group[]
endif::VK_VERSION_1_1,VK_KHR_device_group[]

337
doc/specs/vulkan/chapters/copies.txt
View File

@ -44,20 +44,20 @@ endif::VK_KHR_shared_presentable_image[]
As a consequence, if an image subresource is used as both source and
destination of a copy, it must: be in the ename:VK_IMAGE_LAYOUT_GENERAL
layout.
ifdef::VK_KHR_maintenance1[]
ifdef::VK_VERSION_1_1,VK_KHR_maintenance1[]
* Source images must: use a format that supports
ename:VK_FORMAT_FEATURE_TRANSFER_SRC_BIT_KHR, which is indicated by
ename:VK_FORMAT_FEATURE_TRANSFER_SRC_BIT, which is indicated by
sname:VkFormatProperties::pname:linearTilingFeatures (for linearly tiled
images) or sname:VkFormatProperties::pname:optimalTilingFeatures (for
optimally tiled images) - as returned by
flink:vkGetPhysicalDeviceFormatProperties.
* Destination images must: use a format that supports
ename:VK_FORMAT_FEATURE_TRANSFER_DST_BIT_KHR, which is indicated by
ename:VK_FORMAT_FEATURE_TRANSFER_DST_BIT, which is indicated by
sname:VkFormatProperties::pname:linearTilingFeatures (for linearly tiled
images) or sname:VkFormatProperties::pname:optimalTilingFeatures (for
optimally tiled images) - as returned by
flink:vkGetPhysicalDeviceFormatProperties.
endif::VK_KHR_maintenance1[]
endif::VK_VERSION_1_1,VK_KHR_maintenance1[]
* Source images must: have been created with the
ename:VK_IMAGE_USAGE_TRANSFER_SRC_BIT usage bit enabled and destination
images must: have been created with the
@ -128,6 +128,14 @@ memory.
* [[VUID-vkCmdCopyBuffer-dstBuffer-00121]]
If pname:dstBuffer is non-sparse then it must: be bound completely and
contiguously to a single sname:VkDeviceMemory object
ifdef::VK_VERSION_1_1[]
* If pname:commandBuffer is an unprotected command buffer, then
pname:srcBuffer must: not be a protected buffer
* If pname:commandBuffer is an unprotected command buffer, then
pname:dstBuffer must: not be a protected buffer
* If pname:commandBuffer is a protected command buffer, then
pname:dstBuffer must: not be an unprotected buffer
endif::VK_VERSION_1_1[]
****
include::../validity/protos/vkCmdCopyBuffer.txt[]
@ -193,7 +201,7 @@ For example, ename:VK_FORMAT_R8G8B8A8_UNORM is compatible with
ename:VK_FORMAT_R32_UINT because both texels are 4 bytes in size.
Depth/stencil formats must: match exactly.
ifdef::VK_KHR_sampler_ycbcr_conversion[]
ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
If the format of pname:srcImage or pname:dstImage is a
<<features-formats-requiring-sampler-ycbcr-conversion,_multi-planar_ image
format>>, regions of each plane to be copied must: be specified separately
@ -201,9 +209,8 @@ using the pname:srcSubresource and pname:dstSubresource members of the
slink:VkImageCopy structure.
In this case, the pname:aspectMask of the pname:srcSubresource or
pname:dstSubresource that refers to the multi-planar image must: be
ename:VK_IMAGE_ASPECT_PLANE_0_BIT_KHR,
ename:VK_IMAGE_ASPECT_PLANE_1_BIT_KHR, or
ename:VK_IMAGE_ASPECT_PLANE_2_BIT_KHR.
ename:VK_IMAGE_ASPECT_PLANE_0_BIT, ename:VK_IMAGE_ASPECT_PLANE_1_BIT, or
ename:VK_IMAGE_ASPECT_PLANE_2_BIT.
For the purposes of fname:vkCmdCopyImage, each plane of a multi-planar image
is treated as having the format listed in
<<features-formats-compatible-planes>> for the plane identified by the
@ -215,14 +222,14 @@ to coordinates in the image as a whole.
[NOTE]
.Note
====
For example, the ename:VK_IMAGE_ASPECT_PLANE_1_BIT_KHR plane of a
ename:VK_FORMAT_G8_B8R8_2PLANE_420_UNORM_KHR image is compatible with an
image of format ename:VK_FORMAT_R8G8_UNORM and (less usefully) with the
ename:VK_IMAGE_ASPECT_PLANE_0_BIT_KHR plane of an image of format
ename:VK_FORMAT_G10X6_B10X6_R10X6_3PLANE_420_UNORM_3PACK16_KHR, as each
texel is 2 bytes in size.
For example, the ename:VK_IMAGE_ASPECT_PLANE_1_BIT plane of a
ename:VK_FORMAT_G8_B8R8_2PLANE_420_UNORM image is compatible with an image
of format ename:VK_FORMAT_R8G8_UNORM and (less usefully) with the
ename:VK_IMAGE_ASPECT_PLANE_0_BIT plane of an image of format
ename:VK_FORMAT_G10X6_B10X6_R10X6_3PLANE_420_UNORM_3PACK16, as each texel is
2 bytes in size.
====
endif::VK_KHR_sampler_ycbcr_conversion[]
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
fname:vkCmdCopyImage allows copying between size-compatible compressed and
uncompressed internal formats.
@ -289,12 +296,12 @@ This allows the last compressed texel block of the image in each
non-multiple dimension to be included as a source or destination of the
copy.
ifdef::VK_KHR_sampler_ycbcr_conversion[]
ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
"`etext:_422`" image formats that are not
<<features-formats-requiring-sampler-ycbcr-conversion,_multi-planar_>> are
treated as having a 2{times}1 compressed texel block for the purposes of
these rules.
endif::VK_KHR_sampler_ycbcr_conversion[]
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
fname:vkCmdCopyImage can: be used to copy image data between multisample
images, but both images must: have the same number of samples.
@ -304,49 +311,49 @@ images, but both images must: have the same number of samples.
* [[VUID-vkCmdCopyImage-pRegions-00122]]
The source region specified by each element of pname:pRegions must: be a
region that is contained within pname:srcImage
ifdef::VK_KHR_sampler_ycbcr_conversion[]
ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
if the pname:srcImage's elink:VkFormat is not a
<<features-formats-requiring-sampler-ycbcr-conversion,multi-planar
format>>, and must: be a region that is contained within the plane being
copied if the pname:srcImage's elink:VkFormat is a multi-planar format
endif::VK_KHR_sampler_ycbcr_conversion[]
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
* [[VUID-vkCmdCopyImage-pRegions-00123]]
The destination region specified by each element of pname:pRegions must:
be a region that is contained within pname:dstImage
ifdef::VK_KHR_sampler_ycbcr_conversion[]
ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
if the pname:dstImage's elink:VkFormat is not a
<<features-formats-requiring-sampler-ycbcr-conversion,multi-planar
format>>, and must: be a region that is contained within the plane being
copied to if the pname:dstImage's elink:VkFormat is a multi-planar
format
endif::VK_KHR_sampler_ycbcr_conversion[]
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
* [[VUID-vkCmdCopyImage-pRegions-00124]]
The union of all source regions, and the union of all destination
regions, specified by the elements of pname:pRegions, must: not overlap
in memory
ifdef::VK_KHR_maintenance1[]
ifdef::VK_VERSION_1_1,VK_KHR_maintenance1[]
* [[VUID-vkCmdCopyImage-srcImage-00125]]
pname:srcImage must: use a format that supports
ename:VK_FORMAT_FEATURE_TRANSFER_SRC_BIT_KHR, which is indicated by
ename:VK_FORMAT_FEATURE_TRANSFER_SRC_BIT, which is indicated by
sname:VkFormatProperties::pname:linearTilingFeatures (for linearly tiled
images) or sname:VkFormatProperties::pname:optimalTilingFeatures (for
optimally tiled images) - as returned by
flink:vkGetPhysicalDeviceFormatProperties
endif::VK_KHR_maintenance1[]
endif::VK_VERSION_1_1,VK_KHR_maintenance1[]
* [[VUID-vkCmdCopyImage-srcImage-00126]]
pname:srcImage must: have been created with
ename:VK_IMAGE_USAGE_TRANSFER_SRC_BIT usage flag
ifndef::VK_KHR_sampler_ycbcr_conversion[]
ifndef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
* [[VUID-vkCmdCopyImage-srcImage-00127]]
If pname:srcImage is non-sparse then it must: be bound completely and
contiguously to a single sname:VkDeviceMemory object
endif::VK_KHR_sampler_ycbcr_conversion[]
ifdef::VK_KHR_sampler_ycbcr_conversion[]
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
* [[VUID-vkCmdCopyImage-srcImage-01546]]
If pname:srcImage is non-sparse then the image or _disjoint_ plane to be
copied must: be bound completely and contiguously to a single
sname:VkDeviceMemory object
endif::VK_KHR_sampler_ycbcr_conversion[]
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
* [[VUID-vkCmdCopyImage-srcImageLayout-00128]]
pname:srcImageLayout must: specify the layout of the image subresources
of pname:srcImage specified in pname:pRegions at the time this command
@ -362,29 +369,29 @@ ifdef::VK_KHR_shared_presentable_image[]
ename:VK_IMAGE_LAYOUT_GENERAL, or
ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR
endif::VK_KHR_shared_presentable_image[]
ifdef::VK_KHR_maintenance1[]
ifdef::VK_VERSION_1_1,VK_KHR_maintenance1[]
* [[VUID-vkCmdCopyImage-dstImage-00130]]
pname:dstImage must: use a format that supports
ename:VK_FORMAT_FEATURE_TRANSFER_DST_BIT_KHR, which is indicated by
ename:VK_FORMAT_FEATURE_TRANSFER_DST_BIT, which is indicated by
sname:VkFormatProperties::pname:linearTilingFeatures (for linearly tiled
images) or sname:VkFormatProperties::pname:optimalTilingFeatures (for
optimally tiled images) - as returned by
flink:vkGetPhysicalDeviceFormatProperties
endif::VK_KHR_maintenance1[]
endif::VK_VERSION_1_1,VK_KHR_maintenance1[]
* [[VUID-vkCmdCopyImage-dstImage-00131]]
pname:dstImage must: have been created with
ename:VK_IMAGE_USAGE_TRANSFER_DST_BIT usage flag
ifndef::VK_KHR_sampler_ycbcr_conversion[]
ifndef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
* [[VUID-vkCmdCopyImage-dstImage-00132]]
If pname:dstImage is non-sparse then it must: be bound completely and
contiguously to a single sname:VkDeviceMemory object
endif::VK_KHR_sampler_ycbcr_conversion[]
ifdef::VK_KHR_sampler_ycbcr_conversion[]
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
* [[VUID-vkCmdCopyImage-dstImage-01547]]
If pname:dstImage is non-sparse then the image or _disjoint_ plane that
is the destination of the copy must: be bound completely and
contiguously to a single sname:VkDeviceMemory object
endif::VK_KHR_sampler_ycbcr_conversion[]
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
* [[VUID-vkCmdCopyImage-dstImageLayout-00133]]
pname:dstImageLayout must: specify the layout of the image subresources
of pname:dstImage specified in pname:pRegions at the time this command
@ -401,12 +408,12 @@ ifdef::VK_KHR_shared_presentable_image[]
ename:VK_IMAGE_LAYOUT_GENERAL, or
ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR
endif::VK_KHR_shared_presentable_image[]
ifndef::VK_KHR_sampler_ycbcr_conversion[]
ifndef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
* [[VUID-vkCmdCopyImage-srcImage-00135]]
The elink:VkFormat of each of pname:srcImage and pname:dstImage must: be
compatible, as defined <<copies-images-format-compatibility, below>>
endif::VK_KHR_sampler_ycbcr_conversion[]
ifdef::VK_KHR_sampler_ycbcr_conversion[]
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
* [[VUID-vkCmdCopyImage-srcImage-01548]]
If the elink:VkFormat of each of pname:srcImage and pname:dstImage is
not a
@ -425,14 +432,21 @@ ifdef::VK_KHR_sampler_ycbcr_conversion[]
<<features-formats-requiring-sampler-ycbcr-conversion,multi-planar
format>>, the pname:aspectMask of the pname:srcSubresource and/or
pname:dstSubresource that refers to the multi-planar image must: be
ename:VK_IMAGE_ASPECT_PLANE_0_BIT_KHR,
ename:VK_IMAGE_ASPECT_PLANE_1_BIT_KHR, or
ename:VK_IMAGE_ASPECT_PLANE_2_BIT_KHR (with
ename:VK_IMAGE_ASPECT_PLANE_2_BIT_KHR valid only for a elink:VkFormat
with three planes)
endif::VK_KHR_sampler_ycbcr_conversion[]
ename:VK_IMAGE_ASPECT_PLANE_0_BIT, ename:VK_IMAGE_ASPECT_PLANE_1_BIT, or
ename:VK_IMAGE_ASPECT_PLANE_2_BIT (with
ename:VK_IMAGE_ASPECT_PLANE_2_BIT valid only for a elink:VkFormat with
three planes)
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
* [[VUID-vkCmdCopyImage-srcImage-00136]]
The sample count of pname:srcImage and pname:dstImage must: match
ifdef::VK_VERSION_1_1[]
* If pname:commandBuffer is an unprotected command buffer, then
pname:srcImage must: not be a protected image
* If pname:commandBuffer is an unprotected command buffer, then
pname:dstImage must: not be a protected image
* If pname:commandBuffer is a protected command buffer, then
pname:dstImage must: not be an unprotected image
endif::VK_VERSION_1_1[]
* [[VUID-vkCmdCopyImage-srcSubresource-01696]]
The pname:srcSubresource.mipLevel member of each element of
pname:pRegions must: be less than the pname:mipLevels specified in
@ -483,7 +497,7 @@ include::../api/structs/VkImageCopy.txt[]
* pname:extent is the size in texels of the image to copy in pname:width,
pname:height and pname:depth.
ifdef::VK_KHR_maintenance1[]
ifdef::VK_VERSION_1_1,VK_KHR_maintenance1[]
For ename:VK_IMAGE_TYPE_3D images, copies are performed slice by slice
starting with the pname:z member of the pname:srcOffset or pname:dstOffset,
and copying pname:depth slices.
@ -494,15 +508,15 @@ Image data can: be copied between images with different image types.
If one image is ename:VK_IMAGE_TYPE_3D and the other image is
ename:VK_IMAGE_TYPE_2D with multiple layers, then each slice is copied to or
from a different layer.
endif::VK_KHR_maintenance1[]
ifndef::VK_KHR_maintenance1[]
endif::VK_VERSION_1_1,VK_KHR_maintenance1[]
ifndef::VK_VERSION_1_1,VK_KHR_maintenance1[]
Copies are done layer by layer starting with pname:baseArrayLayer member of
pname:srcSubresource for the source and pname:dstSubresource for the
destination.
pname:layerCount layers are copied to the destination image.
endif::VK_KHR_maintenance1[]
endif::VK_VERSION_1_1,VK_KHR_maintenance1[]
ifdef::VK_KHR_sampler_ycbcr_conversion[]
ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
Copies involving a <<features-formats-requiring-sampler-ycbcr-conversion,
multi-planar image format>> specify the region to be copied in terms of the
_plane_ to be copied, not the coordinates of the multi-planar image.
@ -511,16 +525,16 @@ images must: fit the copied region within half the pname:width of the parent
image, and that copies accessing the R/B planes of "`etext:_420`" format
images must: fit the copied region within half the pname:width and
pname:height of the parent image.
endif::VK_KHR_sampler_ycbcr_conversion[]
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
.Valid Usage
****
ifndef::VK_KHR_sampler_ycbcr_conversion[]
ifndef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
* [[VUID-VkImageCopy-aspectMask-00137]]
The pname:aspectMask member of pname:srcSubresource and
pname:dstSubresource must: match
endif::VK_KHR_sampler_ycbcr_conversion[]
ifdef::VK_KHR_sampler_ycbcr_conversion[]
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
* [[VUID-VkImageCopy-srcImage-01551]]
If neither the calling command's pname:srcImage nor the calling
command's pname:dstImage has a
@ -531,28 +545,24 @@ ifdef::VK_KHR_sampler_ycbcr_conversion[]
If the calling command's pname:srcImage has a elink:VkFormat with
<<features-formats-requiring-sampler-ycbcr-conversion,two planes>> then
the pname:srcSubresource pname:aspectMask must: be
ename:VK_IMAGE_ASPECT_PLANE_0_BIT_KHR or
ename:VK_IMAGE_ASPECT_PLANE_1_BIT_KHR
ename:VK_IMAGE_ASPECT_PLANE_0_BIT or ename:VK_IMAGE_ASPECT_PLANE_1_BIT
* [[VUID-VkImageCopy-srcImage-01553]]
If the calling command's pname:srcImage has a elink:VkFormat with
<<features-formats-requiring-sampler-ycbcr-conversion,three planes>>
then the pname:srcSubresource pname:aspectMask must: be
ename:VK_IMAGE_ASPECT_PLANE_0_BIT_KHR,
ename:VK_IMAGE_ASPECT_PLANE_1_BIT_KHR, or
ename:VK_IMAGE_ASPECT_PLANE_2_BIT_KHR
ename:VK_IMAGE_ASPECT_PLANE_0_BIT, ename:VK_IMAGE_ASPECT_PLANE_1_BIT, or
ename:VK_IMAGE_ASPECT_PLANE_2_BIT
* [[VUID-VkImageCopy-dstImage-01554]]
If the calling command's pname:dstImage has a elink:VkFormat with
<<features-formats-requiring-sampler-ycbcr-conversion,two planes>> then
the pname:dstSubresource pname:aspectMask must: be
ename:VK_IMAGE_ASPECT_PLANE_0_BIT_KHR or
ename:VK_IMAGE_ASPECT_PLANE_1_BIT_KHR
ename:VK_IMAGE_ASPECT_PLANE_0_BIT or ename:VK_IMAGE_ASPECT_PLANE_1_BIT
* [[VUID-VkImageCopy-dstImage-01555]]
If the calling command's pname:dstImage has a elink:VkFormat with
<<features-formats-requiring-sampler-ycbcr-conversion,three planes>>
then the pname:dstSubresource pname:aspectMask must: be
ename:VK_IMAGE_ASPECT_PLANE_0_BIT_KHR,
ename:VK_IMAGE_ASPECT_PLANE_1_BIT_KHR, or
ename:VK_IMAGE_ASPECT_PLANE_2_BIT_KHR
ename:VK_IMAGE_ASPECT_PLANE_0_BIT, ename:VK_IMAGE_ASPECT_PLANE_1_BIT, or
ename:VK_IMAGE_ASPECT_PLANE_2_BIT
* [[VUID-VkImageCopy-srcImage-01556]]
If the calling command's pname:srcImage has a
<<features-formats-requiring-sampler-ycbcr-conversion,multi-planar image
@ -565,8 +575,8 @@ ifdef::VK_KHR_sampler_ycbcr_conversion[]
format>> and the pname:srcImage does not have a multi-planar image
format, the pname:srcSubresource pname:aspectMask must: be
ename:VK_IMAGE_ASPECT_COLOR_BIT
endif::VK_KHR_sampler_ycbcr_conversion[]
ifndef::VK_KHR_maintenance1[]
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
ifndef::VK_VERSION_1_1,VK_KHR_maintenance1[]
* [[VUID-VkImageCopy-layerCount-00138]]
The pname:layerCount member of pname:srcSubresource and
pname:dstSubresource must: match
@ -576,8 +586,8 @@ ifndef::VK_KHR_maintenance1[]
pname:baseArrayLayer and pname:layerCount members of both
pname:srcSubresource and pname:dstSubresource must: be `0` and `1`,
respectively
endif::VK_KHR_maintenance1[]
ifdef::VK_KHR_maintenance1[]
endif::VK_VERSION_1_1,VK_KHR_maintenance1[]
ifdef::VK_VERSION_1_1,VK_KHR_maintenance1[]
* [[VUID-VkImageCopy-extent-00140]]
The number of slices of the pname:extent (for 3D) or layers of the
pname:srcSubresource (for non-3D) must: match the number of slices of
@ -588,7 +598,7 @@ ifdef::VK_KHR_maintenance1[]
parameters are of elink:VkImageType ename:VK_IMAGE_TYPE_3D, the
pname:baseArrayLayer and pname:layerCount members of the corresponding
subresource must: be `0` and `1`, respectively
endif::VK_KHR_maintenance1[]
endif::VK_VERSION_1_1,VK_KHR_maintenance1[]
* [[VUID-VkImageCopy-aspectMask-00142]]
The pname:aspectMask member of pname:srcSubresource must: specify
aspects present in the calling command's pname:srcImage
@ -625,12 +635,12 @@ endif::VK_KHR_maintenance1[]
* [[VUID-VkImageCopy-dstImage-01788]]
If the calling command's pname:dstImage is of type
ename:VK_IMAGE_TYPE_2D, then pname:dstOffset.z must: be `0`.
ifndef::VK_KHR_maintenance1[]
ifndef::VK_VERSION_1_1,VK_KHR_maintenance1[]
* [[VUID-VkImageCopy-srcImage-01789]]
If the calling command's pname:srcImage or pname:dstImage is of type
ename:VK_IMAGE_TYPE_2D, then pname:extent.depth must: be `1`.
endif::VK_KHR_maintenance1[]
ifdef::VK_KHR_maintenance1[]
endif::VK_VERSION_1_1,VK_KHR_maintenance1[]
ifdef::VK_VERSION_1_1,VK_KHR_maintenance1[]
* [[VUID-VkImageCopy-srcImage-01790]]
If both pname:srcImage and pname:dstImage are of type
ename:VK_IMAGE_TYPE_2D then then pname:extent.depth must: be `1`.
@ -644,7 +654,7 @@ ifdef::VK_KHR_maintenance1[]
ename:VK_IMAGE_TYPE_2D, and the pname:srcImage is of type
ename:VK_IMAGE_TYPE_3D, then pname:extent.depth must: equal to the
pname:layerCount member of pname:dstSubresource.
endif::VK_KHR_maintenance1[]
endif::VK_VERSION_1_1,VK_KHR_maintenance1[]
* [[VUID-VkImageCopy-dstOffset-00150]]
pname:dstOffset.x and [eq]#(pname:extent.width {plus}
pname:dstOffset.x)# must: both be greater than or equal to `0` and less
@ -663,7 +673,7 @@ endif::VK_KHR_maintenance1[]
than or equal to the destination image subresource depth
// The block of VU below come in alternate versions when the extension is
// enabled.
ifndef::VK_KHR_sampler_ycbcr_conversion[]
ifndef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
* [[VUID-VkImageCopy-srcOffset-00157]]
If the calling command's pname:srcImage is a compressed image, all
members of pname:srcOffset must: be a multiple of the corresponding
@ -702,74 +712,74 @@ ifndef::VK_KHR_sampler_ycbcr_conversion[]
pname:extent.depth must: be a multiple of the compressed texel block
depth or [eq]#(pname:extent.depth {plus} pname:dstOffset.z)# must: equal
the destination image subresource depth
endif::VK_KHR_sampler_ycbcr_conversion[]
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
// The nested ifdefs are there in anticipation of the hoped-for day when the
// VU extractor and validation layers can handle VU with imbedded
// conditionals.
ifdef::VK_KHR_sampler_ycbcr_conversion[]
ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
* [[VUID-VkImageCopy-srcImage-01727]]
If the calling command's pname:srcImage is a compressed image,
// ifdef::VK_KHR_sampler_ycbcr_conversion[]
// ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
or a _single-plane_, "`etext:_422`" image format,
// endif::VK_KHR_sampler_ycbcr_conversion[]
// endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
all members of pname:srcOffset must: be a multiple of the corresponding
dimensions of the compressed texel block
* [[VUID-VkImageCopy-srcImage-01728]]
If the calling command's pname:srcImage is a compressed image,
// ifdef::VK_KHR_sampler_ycbcr_conversion[]
// ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
or a _single-plane_, "`etext:_422`" image format,
// endif::VK_KHR_sampler_ycbcr_conversion[]
// endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
pname:extent.width must: be a multiple of the compressed texel block
width or [eq]#(pname:extent.width {plus} pname:srcOffset.x)# must: equal
the source image subresource width
* [[VUID-VkImageCopy-srcImage-01729]]
If the calling command's pname:srcImage is a compressed image,
// ifdef::VK_KHR_sampler_ycbcr_conversion[]
// ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
or a _single-plane_, "`etext:_422`" image format,
// endif::VK_KHR_sampler_ycbcr_conversion[]
// endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
pname:extent.height must: be a multiple of the compressed texel block
height or [eq]#(pname:extent.height {plus} pname:srcOffset.y)# must:
equal the source image subresource height
* [[VUID-VkImageCopy-srcImage-01730]]
If the calling command's pname:srcImage is a compressed image,
// ifdef::VK_KHR_sampler_ycbcr_conversion[]
// ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
or a _single-plane_, "`etext:_422`" image format,
// endif::VK_KHR_sampler_ycbcr_conversion[]
// endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
pname:extent.depth must: be a multiple of the compressed texel block
depth or [eq]#(pname:extent.depth {plus} pname:srcOffset.z)# must: equal
the source image subresource depth
* [[VUID-VkImageCopy-dstImage-01731]]
If the calling command's pname:dstImage is a compressed format image,
// ifdef::VK_KHR_sampler_ycbcr_conversion[]
// ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
or a _single-plane_, "`etext:_422`" image format,
// endif::VK_KHR_sampler_ycbcr_conversion[]
// endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
all members of pname:dstOffset must: be a multiple of the corresponding
dimensions of the compressed texel block
* [[VUID-VkImageCopy-dstImage-01732]]
If the calling command's pname:dstImage is a compressed format image,
// ifdef::VK_KHR_sampler_ycbcr_conversion[]
// ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
or a _single-plane_, "`etext:_422`" image format,
// endif::VK_KHR_sampler_ycbcr_conversion[]
// endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
pname:extent.width must: be a multiple of the compressed texel block
width or [eq]#(pname:extent.width {plus} pname:dstOffset.x)# must: equal
the destination image subresource width
* [[VUID-VkImageCopy-dstImage-01733]]
If the calling command's pname:dstImage is a compressed format image,
// ifdef::VK_KHR_sampler_ycbcr_conversion[]
// ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
or a _single-plane_, "`etext:_422`" image format,
// endif::VK_KHR_sampler_ycbcr_conversion[]
// endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
pname:extent.height must: be a multiple of the compressed texel block
height or [eq]#(pname:extent.height {plus} pname:dstOffset.y)# must:
equal the destination image subresource height
* [[VUID-VkImageCopy-dstImage-01734]]
If the calling command's pname:dstImage is a compressed format image,
// ifdef::VK_KHR_sampler_ycbcr_conversion[]
// ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
or a _single-plane_, "`etext:_422`" image format,
// endif::VK_KHR_sampler_ycbcr_conversion[]
// endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
pname:extent.depth must: be a multiple of the compressed texel block
depth or [eq]#(pname:extent.depth {plus} pname:dstOffset.z)# must: equal
the destination image subresource depth
endif::VK_KHR_sampler_ycbcr_conversion[]
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
****
include::../validity/structs/VkImageCopy.txt[]
@ -827,16 +837,15 @@ include::../api/protos/vkCmdCopyBufferToImage.txt[]
Each region in pname:pRegions is copied from the specified region of the
source buffer to the specified region of the destination image.
ifdef::VK_KHR_sampler_ycbcr_conversion[]
ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
If the format of pname:dstImage is a
<<features-formats-requiring-sampler-ycbcr-conversion,multi-planar image
format>>), regions of each plane to be a target of a copy must: be specified
separately using the pname:pRegions member of the slink:VkBufferImageCopy
structure.
In this case, the pname:aspectMask of pname:imageSubresource must: be
ename:VK_IMAGE_ASPECT_PLANE_0_BIT_KHR,
ename:VK_IMAGE_ASPECT_PLANE_1_BIT_KHR, or
ename:VK_IMAGE_ASPECT_PLANE_2_BIT_KHR.
ename:VK_IMAGE_ASPECT_PLANE_0_BIT, ename:VK_IMAGE_ASPECT_PLANE_1_BIT, or
ename:VK_IMAGE_ASPECT_PLANE_2_BIT.
For the purposes of fname:vkCmdCopyBufferToImage, each plane of a
multi-planar image is treated as having the format listed in
<<features-formats-compatible-planes>> for the plane identified by the
@ -844,7 +853,7 @@ pname:aspectMask of the corresponding subresource.
This applies both to elink:VkFormat and to coordinates used in the copy,
which correspond to texels in the _plane_ rather than how these texels map
to coordinates in the image as a whole.
endif::VK_KHR_sampler_ycbcr_conversion[]
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
.Valid Usage
****
@ -854,13 +863,13 @@ endif::VK_KHR_sampler_ycbcr_conversion[]
* [[VUID-vkCmdCopyBufferToImage-pRegions-00172]]
The image region specified by each element of pname:pRegions must: be a
region that is contained within pname:dstImage
ifdef::VK_KHR_sampler_ycbcr_conversion[]
ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
if the pname:dstImage's elink:VkFormat is not a
<<features-formats-requiring-sampler-ycbcr-conversion,multi-planar
format>>, and must: be a region that is contained within the plane being
copied to if the pname:dstImage's elink:VkFormat is a multi-planar
format
endif::VK_KHR_sampler_ycbcr_conversion[]
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
* [[VUID-vkCmdCopyBufferToImage-pRegions-00173]]
The union of all source regions, and the union of all destination
regions, specified by the elements of pname:pRegions, must: not overlap
@ -868,15 +877,15 @@ endif::VK_KHR_sampler_ycbcr_conversion[]
* [[VUID-vkCmdCopyBufferToImage-srcBuffer-00174]]
pname:srcBuffer must: have been created with
ename:VK_BUFFER_USAGE_TRANSFER_SRC_BIT usage flag
ifdef::VK_KHR_maintenance1[]
ifdef::VK_VERSION_1_1,VK_KHR_maintenance1[]
* [[VUID-vkCmdCopyBufferToImage-dstImage-00175]]
pname:dstImage must: use a format that supports
ename:VK_FORMAT_FEATURE_TRANSFER_DST_BIT_KHR, which is indicated by
ename:VK_FORMAT_FEATURE_TRANSFER_DST_BIT, which is indicated by
sname:VkFormatProperties::pname:linearTilingFeatures (for linearly tiled
images) or sname:VkFormatProperties::pname:optimalTilingFeatures (for
optimally tiled images) - as returned by
flink:vkGetPhysicalDeviceFormatProperties
endif::VK_KHR_maintenance1[]
endif::VK_VERSION_1_1,VK_KHR_maintenance1[]
* [[VUID-vkCmdCopyBufferToImage-srcBuffer-00176]]
If pname:srcBuffer is non-sparse then it must: be bound completely and
contiguously to a single sname:VkDeviceMemory object
@ -905,6 +914,14 @@ ifdef::VK_KHR_shared_presentable_image[]
ename:VK_IMAGE_LAYOUT_GENERAL, or
ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR
endif::VK_KHR_shared_presentable_image[]
ifdef::VK_VERSION_1_1[]
* If pname:commandBuffer is an unprotected command buffer, then
pname:srcBuffer must: not be a protected buffer
* If pname:commandBuffer is an unprotected command buffer, then
pname:dstImage must: not be a protected image
* If pname:commandBuffer is a protected command buffer, then
pname:dstImage must: not be an unprotected image
endif::VK_VERSION_1_1[]
* [[VUID-vkCmdCopyBufferToImage-imageSubresource-01701]]
The pname:imageSubresource.mipLevel member of each element of
pname:pRegions must: be less than the pname:mipLevels specified in
@ -944,16 +961,15 @@ include::../api/protos/vkCmdCopyImageToBuffer.txt[]
Each region in pname:pRegions is copied from the specified region of the
source image to the specified region of the destination buffer.
ifdef::VK_KHR_sampler_ycbcr_conversion[]
ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
If the elink:VkFormat of pname:srcImage is a
<<features-formats-requiring-sampler-ycbcr-conversion,multi-planar image
format>>, regions of each plane to be a source of a copy must: be specified
separately using the pname:pRegions member of the slink:VkBufferImageCopy
structure.
In this case, the pname:aspectMask of pname:imageSubresource must: be
ename:VK_IMAGE_ASPECT_PLANE_0_BIT_KHR,
ename:VK_IMAGE_ASPECT_PLANE_1_BIT_KHR, or
ename:VK_IMAGE_ASPECT_PLANE_2_BIT_KHR.
ename:VK_IMAGE_ASPECT_PLANE_0_BIT, ename:VK_IMAGE_ASPECT_PLANE_1_BIT, or
ename:VK_IMAGE_ASPECT_PLANE_2_BIT.
For the purposes of fname:vkCmdCopyBufferToImage, each plane of a
multi-planar image is treated as having the format listed in
<<features-formats-compatible-planes>> for the plane identified by the
@ -961,19 +977,19 @@ pname:aspectMask of the corresponding subresource.
This applies both to elink:VkFormat and to coordinates used in the copy,
which correspond to texels in the _plane_ rather than how these texels map
to coordinates in the image as a whole.
endif::VK_KHR_sampler_ycbcr_conversion[]
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
.Valid Usage
****
* [[VUID-vkCmdCopyImageToBuffer-pRegions-00182]]
The image region specified by each element of pname:pRegions must: be a
region that is contained within pname:srcImage
ifdef::VK_KHR_sampler_ycbcr_conversion[]
ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
if the pname:srcImage's elink:VkFormat is not a
<<features-formats-requiring-sampler-ycbcr-conversion,multi-planar
format>>, and must: be a region that is contained within the plane being
copied if the pname:srcImage's elink:VkFormat is a multi-planar format
endif::VK_KHR_sampler_ycbcr_conversion[]
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
* [[VUID-vkCmdCopyImageToBuffer-pRegions-00183]]
The buffer region specified by each element of pname:pRegions must: be a
region that is contained within pname:dstBuffer
@ -981,15 +997,15 @@ endif::VK_KHR_sampler_ycbcr_conversion[]
The union of all source regions, and the union of all destination
regions, specified by the elements of pname:pRegions, must: not overlap
in memory
ifdef::VK_KHR_maintenance1[]
ifdef::VK_VERSION_1_1,VK_KHR_maintenance1[]
* [[VUID-vkCmdCopyImageToBuffer-srcImage-00185]]
pname:srcImage must: use a format that supports
ename:VK_FORMAT_FEATURE_TRANSFER_SRC_BIT_KHR, which is indicated by
ename:VK_FORMAT_FEATURE_TRANSFER_SRC_BIT, which is indicated by
sname:VkFormatProperties::pname:linearTilingFeatures (for linearly tiled
images) or sname:VkFormatProperties::pname:optimalTilingFeatures (for
optimally tiled images) - as returned by
flink:vkGetPhysicalDeviceFormatProperties
endif::VK_KHR_maintenance1[]
endif::VK_VERSION_1_1,VK_KHR_maintenance1[]
* [[VUID-vkCmdCopyImageToBuffer-srcImage-00186]]
pname:srcImage must: have been created with
ename:VK_IMAGE_USAGE_TRANSFER_SRC_BIT usage flag
@ -1020,6 +1036,14 @@ endif::VK_KHR_shared_presentable_image[]
* [[VUID-vkCmdCopyImageToBuffer-dstBuffer-00192]]
If pname:dstBuffer is non-sparse then it must: be bound completely and
contiguously to a single sname:VkDeviceMemory object
ifdef::VK_VERSION_1_1[]
* If pname:commandBuffer is an unprotected command buffer, then
pname:srcImage must: not be a protected image
* If pname:commandBuffer is an unprotected command buffer, then
pname:dstBuffer must: not be a protected buffer
* If pname:commandBuffer is a protected command buffer, then
pname:dstBuffer must: not be an unprotected buffer
endif::VK_VERSION_1_1[]
* [[VUID-vkCmdCopyImageToBuffer-imageSubresource-01703]]
The pname:imageSubresource.mipLevel member of each element of
pname:pRegions must: be less than the pname:mipLevels specified in
@ -1101,13 +1125,13 @@ destination image.
.Valid Usage
****
ifndef::VK_KHR_sampler_ycbcr_conversion[]
ifndef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
* [[VUID-VkBufferImageCopy-bufferOffset-00193]]
If the calling command's sname:VkImage parameter's format is not a
depth/stencil format, then pname:bufferOffset must: be a multiple of the
format's element size
endif::VK_KHR_sampler_ycbcr_conversion[]
ifdef::VK_KHR_sampler_ycbcr_conversion[]
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
* [[VUID-VkBufferImageCopy-bufferOffset-01558]]
If the calling command's sname:VkImage parameter's format is not a
depth/stencil format or a
@ -1121,7 +1145,7 @@ ifdef::VK_KHR_sampler_ycbcr_conversion[]
size of the compatible format for the format and the pname:aspectMask of
the pname:imageSubresource as defined in
<<features-formats-compatible-planes>>
endif::VK_KHR_sampler_ycbcr_conversion[]
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
* [[VUID-VkBufferImageCopy-bufferOffset-00194]]
pname:bufferOffset must: be a multiple of `4`
* [[VUID-VkBufferImageCopy-bufferRowLength-00195]]
@ -1134,22 +1158,22 @@ endif::VK_KHR_sampler_ycbcr_conversion[]
pname:imageOffset.x and [eq]#(pname:imageExtent.width {plus}
pname:imageOffset.x)# must: both be greater than or equal to `0` and
less than or equal to the image subresource width
ifdef::VK_KHR_sampler_ycbcr_conversion[]
ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
where this refers to the width of the _plane_ of the image involved in
the copy in the case of a
<<features-formats-requiring-sampler-ycbcr-conversion,multi-planar
format>>
endif::VK_KHR_sampler_ycbcr_conversion[]
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
* [[VUID-VkBufferImageCopy-imageOffset-00198]]
pname:imageOffset.y and [eq]#(imageExtent.height {plus}
pname:imageOffset.y)# must: both be greater than or equal to `0` and
less than or equal to the image subresource height
ifdef::VK_KHR_sampler_ycbcr_conversion[]
ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
where this refers to the height of the _plane_ of the image involved in
the copy in the case of a
<<features-formats-requiring-sampler-ycbcr-conversion,multi-planar
format>>
endif::VK_KHR_sampler_ycbcr_conversion[]
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
* [[VUID-VkBufferImageCopy-srcImage-00199]]
If the calling command's pname:srcImage (flink:vkCmdCopyImageToBuffer)
or pname:dstImage (flink:vkCmdCopyBufferToImage) is of type
@ -1167,7 +1191,7 @@ endif::VK_KHR_sampler_ycbcr_conversion[]
`1`
// The block of VU below come in alternate versions when the extension is
// enabled.
ifndef::VK_KHR_sampler_ycbcr_conversion[]
ifndef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
* [[VUID-VkBufferImageCopy-bufferRowLength-00203]]
If the calling command's sname:VkImage parameter is a compressed image,
pname:bufferRowLength must: be a multiple of the compressed texel block
@ -1199,78 +1223,77 @@ ifndef::VK_KHR_sampler_ycbcr_conversion[]
pname:imageExtent.depth must: be a multiple of the compressed texel
block depth or [eq]#(pname:imageExtent.depth {plus}
pname:imageOffset.z)# must: equal the image subresource depth
endif::VK_KHR_sampler_ycbcr_conversion[]
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
// The nested ifdefs are there in anticipation of the hoped-for day when the
// VU extractor and validation layers can handle VU with imbedded
// conditionals.
ifdef::VK_KHR_sampler_ycbcr_conversion[]
ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
* [[VUID-VkBufferImageCopy-None-01735]]
If the calling command's sname:VkImage parameter is a compressed image,
// ifdef::VK_KHR_sampler_ycbcr_conversion[]
// ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
or a _single-plane_, "`etext:_422`" image format,
// endif::VK_KHR_sampler_ycbcr_conversion[]
// endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
pname:bufferRowLength must: be a multiple of the compressed texel block
width
* [[VUID-VkBufferImageCopy-None-01736]]
If the calling command's sname:VkImage parameter is a compressed image,
// ifdef::VK_KHR_sampler_ycbcr_conversion[]
// ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
or a _single-plane_, "`etext:_422`" image format,
// endif::VK_KHR_sampler_ycbcr_conversion[]
// endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
pname:bufferImageHeight must: be a multiple of the compressed texel
block height
* [[VUID-VkBufferImageCopy-None-01737]]
If the calling command's sname:VkImage parameter is a compressed image,
// ifdef::VK_KHR_sampler_ycbcr_conversion[]
// ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
or a _single-plane_, "`etext:_422`" image format,
// endif::VK_KHR_sampler_ycbcr_conversion[]
// endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
all members of pname:imageOffset must: be a multiple of the
corresponding dimensions of the compressed texel block
* [[VUID-VkBufferImageCopy-None-01738]]
If the calling command's sname:VkImage parameter is a compressed image,
// ifdef::VK_KHR_sampler_ycbcr_conversion[]
// ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
or a _single-plane_, "`etext:_422`" image format,
// endif::VK_KHR_sampler_ycbcr_conversion[]
// endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
pname:bufferOffset must: be a multiple of the compressed texel block
size in bytes
* [[VUID-VkBufferImageCopy-None-01739]]
If the calling command's sname:VkImage parameter is a compressed image,
// ifdef::VK_KHR_sampler_ycbcr_conversion[]
// ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
or a _single-plane_, "`etext:_422`" image format,
// endif::VK_KHR_sampler_ycbcr_conversion[]
// endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
pname:imageExtent.width must: be a multiple of the compressed texel
block width or [eq]#(pname:imageExtent.width {plus}
pname:imageOffset.x)# must: equal the image subresource width
* [[VUID-VkBufferImageCopy-None-01740]]
If the calling command's sname:VkImage parameter is a compressed image,
// ifdef::VK_KHR_sampler_ycbcr_conversion[]
// ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
or a _single-plane_, "`etext:_422`" image format,
// endif::VK_KHR_sampler_ycbcr_conversion[]
// endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
pname:imageExtent.height must: be a multiple of the compressed texel
block height or [eq]#(pname:imageExtent.height {plus}
pname:imageOffset.y)# must: equal the image subresource height
* [[VUID-VkBufferImageCopy-None-01741]]
If the calling command's sname:VkImage parameter is a compressed image,
// ifdef::VK_KHR_sampler_ycbcr_conversion[]
// ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
or a _single-plane_, "`etext:_422`" image format,
// endif::VK_KHR_sampler_ycbcr_conversion[]
// endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
pname:imageExtent.depth must: be a multiple of the compressed texel
block depth or [eq]#(pname:imageExtent.depth {plus}
pname:imageOffset.z)# must: equal the image subresource depth
endif::VK_KHR_sampler_ycbcr_conversion[]
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
* [[VUID-VkBufferImageCopy-aspectMask-00211]]
The pname:aspectMask member of pname:imageSubresource must: specify
aspects present in the calling command's sname:VkImage parameter
ifdef::VK_KHR_sampler_ycbcr_conversion[]
ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
* [[VUID-VkBufferImageCopy-aspectMask-01560]]
If the calling command's sname:VkImage parameter's format is a
<<features-formats-requiring-sampler-ycbcr-conversion,multi-planar
format>>, then the pname:aspectMask member of pname:imageSubresource
must: be ename:VK_IMAGE_ASPECT_PLANE_0_BIT_KHR,
ename:VK_IMAGE_ASPECT_PLANE_1_BIT_KHR, or
ename:VK_IMAGE_ASPECT_PLANE_2_BIT_KHR (with
ename:VK_IMAGE_ASPECT_PLANE_2_BIT_KHR valid only for image formats with
three planes)
endif::VK_KHR_sampler_ycbcr_conversion[]
must: be ename:VK_IMAGE_ASPECT_PLANE_0_BIT,
ename:VK_IMAGE_ASPECT_PLANE_1_BIT, or ename:VK_IMAGE_ASPECT_PLANE_2_BIT
(with ename:VK_IMAGE_ASPECT_PLANE_2_BIT valid only for image formats
with three planes)
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
* [[VUID-VkBufferImageCopy-aspectMask-00212]]
The pname:aspectMask member of pname:imageSubresource must: only have a
single bit set
@ -1495,11 +1518,11 @@ representable range of the destination format, then casting the value.
images) or sname:VkFormatProperties::pname:optimalTilingFeatures (for
optimally tiled images) - as returned by
fname:vkGetPhysicalDeviceFormatProperties
ifdef::VK_KHR_sampler_ycbcr_conversion[]
ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
* [[VUID-vkCmdBlitImage-srcImage-01561]]
pname:srcImage must: not use a format listed in
<<features-formats-requiring-sampler-ycbcr-conversion>>
endif::VK_KHR_sampler_ycbcr_conversion[]
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
* [[VUID-vkCmdBlitImage-srcImage-00219]]
pname:srcImage must: have been created with
ename:VK_IMAGE_USAGE_TRANSFER_SRC_BIT usage flag
@ -1528,11 +1551,11 @@ endif::VK_KHR_shared_presentable_image[]
images) or sname:VkFormatProperties::pname:optimalTilingFeatures (for
optimally tiled images) - as returned by
fname:vkGetPhysicalDeviceFormatProperties
ifdef::VK_KHR_sampler_ycbcr_conversion[]
ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
* [[VUID-vkCmdBlitImage-dstImage-01562]]
pname:dstImage must: not use a format listed in
<<features-formats-requiring-sampler-ycbcr-conversion>>
endif::VK_KHR_sampler_ycbcr_conversion[]
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
* [[VUID-vkCmdBlitImage-dstImage-00224]]
pname:dstImage must: have been created with
ename:VK_IMAGE_USAGE_TRANSFER_DST_BIT usage flag
@ -1598,6 +1621,14 @@ ifdef::VK_IMG_filter_cubic[]
If pname:filter is ename:VK_FILTER_CUBIC_IMG, pname:srcImage must: have
a elink:VkImageType of ename:VK_IMAGE_TYPE_3D
endif::VK_IMG_filter_cubic[]
ifdef::VK_VERSION_1_1[]
* If pname:commandBuffer is an unprotected command buffer, then
pname:srcImage must: not be a protected image
* If pname:commandBuffer is an unprotected command buffer, then
pname:dstImage must: not be a protected image
* If pname:commandBuffer is a protected command buffer, then
pname:dstImage must: not be an unprotected image
endif::VK_VERSION_1_1[]
* [[VUID-vkCmdBlitImage-srcSubresource-01705]]
The pname:srcSubresource.mipLevel member of each element of
pname:pRegions must: be less than the pname:mipLevels specified in
@ -1817,6 +1848,14 @@ endif::VK_KHR_shared_presentable_image[]
* [[VUID-vkCmdResolveImage-srcImage-01386]]
pname:srcImage and pname:dstImage must: have been created with the same
image format
ifdef::VK_VERSION_1_1[]
* If pname:commandBuffer is an unprotected command buffer, then
pname:srcImage must: not be a protected image
* If pname:commandBuffer is an unprotected command buffer, then
pname:dstImage must: not be a protected image
* If pname:commandBuffer is a protected command buffer, then
pname:dstImage must: not be an unprotected image
endif::VK_VERSION_1_1[]
* [[VUID-vkCmdResolveImage-srcSubresource-01709]]
The pname:srcSubresource.mipLevel member of each element of
pname:pRegions must: be less than the pname:mipLevels specified in

10
doc/specs/vulkan/chapters/debugging.txt
View File

@ -58,9 +58,9 @@ endif::VK_KHR_display[]
ifdef::VK_EXT_debug_report[]
| ename:VK_OBJECT_TYPE_DEBUG_REPORT_CALLBACK_EXT | slink:VkDebugReportCallbackEXT
endif::VK_EXT_debug_report[]
ifdef::VK_KHR_descriptor_update_template[]
| ename:VK_OBJECT_TYPE_DESCRIPTOR_UPDATE_TEMPLATE_KHR | slink:VkDescriptorUpdateTemplateKHR
endif::VK_KHR_descriptor_update_template[]
ifdef::VK_VERSION_1_1,VK_KHR_descriptor_update_template[]
| ename:VK_OBJECT_TYPE_DESCRIPTOR_UPDATE_TEMPLATE | slink:VkDescriptorUpdateTemplate
endif::VK_VERSION_1_1,VK_KHR_descriptor_update_template[]
ifdef::VK_NVX_device_generated_commands[]
| ename:VK_OBJECT_TYPE_OBJECT_TABLE_NVX | slink:VkObjectTableNVX
| ename:VK_OBJECT_TYPE_INDIRECT_COMMANDS_LAYOUT_NVX | slink:VkIndirectCommandsLayoutNVX
@ -75,6 +75,10 @@ endif::VK_EXT_validation_cache[]
If this Specification was generated with any such extensions included, they
will be described in the remainder of this chapter.
ifdef::VK_EXT_debug_utils[]
include::VK_EXT_debug_utils.txt[]
endif::VK_EXT_debug_utils[]
ifdef::VK_EXT_debug_marker[]
include::VK_EXT_debug_marker.txt[]
endif::VK_EXT_debug_marker[]

1029
doc/specs/vulkan/chapters/descriptorsets.txt
View File

File diff suppressed because it is too large Load Diff

469
doc/specs/vulkan/chapters/devsandqueues.txt
View File

@ -12,10 +12,11 @@ to interact with a Vulkan implementation.
--
Vulkan separates the concept of _physical_ and _logical_ devices.
A physical device usually represents a single device in a system (perhaps
made up of several individual hardware devices working together), of which
there are a finite number.
A logical device represents an application's view of the device.
A physical device usually represents a single complete implementation of
Vulkan (excluding instance-level functionality) available to the host, of
which there are a finite number.
A logical device represents an instance of that implementation with its own
state and resources independent of other logical devices.
Physical devices are represented by sname:VkPhysicalDevice handles:
@ -103,47 +104,75 @@ include::../api/structs/VkPhysicalDeviceProperties.txt[]
physical device.
See <<sparsememory-physicalprops,Sparse Properties>> for details.
ifdef::VK_VERSION_1_1[]
[NOTE]
.Note
====
The value of pname:apiVersion may: be different than the version returned by
flink:vkEnumerateInstanceVersion; either higher or lower.
In such cases, the application must: not use functionality that exceeds the
version of Vulkan associated with a given object.
The pname:pApiVersion parameter returned by flink:vkEnumerateInstanceVersion
is the version associated with a slink:VkInstance and its children, except
for a slink:VkPhysicalDevice and its children.
sname:VkPhysicalDeviceProperties::pname:apiVersion is the version associated
with a slink:VkPhysicalDevice and its children.
====
endif::VK_VERSION_1_1[]
The pname:vendorID and pname:deviceID fields are provided to allow
applications to adapt to device characteristics that are not adequately
exposed by other Vulkan queries.
[NOTE]
.Note
====
These may: include performance profiles, hardware errata, or other
characteristics.
In PCI-based implementations, the low sixteen bits of pname:vendorID and
pname:deviceID must: contain (respectively) the PCI vendor and device IDs
associated with the hardware device, and the remaining bits must: be set to
zero.
In non-PCI implementations, the choice of what values to return may: be
dictated by operating system or platform policies.
It is otherwise at the discretion of the implementer, subject to the
following constraints and guidelines:
====
* For purposes of physical device identification, the _vendor_ of a
physical device is the entity responsible for the most salient
characteristics of the hardware represented by the physical device
handle.
In the case of a discrete GPU, this should: be the GPU chipset vendor.
In the case of a GPU or other accelerator integrated into a
system-on-chip (SoC), this should: be the supplier of the silicon IP
used to create the GPU or other accelerator.
* If the vendor of the physical device has a valid PCI vendor ID issued by
https://pcisig.com/[PCI-SIG], that ID should: be used to construct
pname:vendorID as described above for PCI-based implementations.
Implementations that do not return a PCI vendor ID in pname:vendorID
must: return a valid Khronos vendor ID, obtained as described in the
<<vulkan-styleguide,Vulkan Documentation and Extensions>> document in
the section "`Registering a Vendor ID with Khronos`".
Khronos vendor IDs are allocated starting at 0x10000, to distinguish
them from the PCI vendor ID namespace.
* The vendor of the physical device is responsible for selecting
pname:deviceID.
The value selected should: uniquely identify both the device version and
any major configuration options (for example, core count in the case of
multicore devices).
The same device ID should: be used for all physical implementations of
that device version and configuration.
For example, all uses of a specific silicon IP GPU version and
configuration should: use the same device ID, even if those uses occur
in different SoCs.
The _vendor_ identified by pname:vendorID is the entity responsible for the
most salient characteristics of the underlying implementation of the
slink:VkPhysicalDevice being queried.
[NOTE]
.Note
====
For example, in the case of a discrete GPU implementation, this should: be
the GPU chipset vendor.
In the case of a hardware accelerator integrated into a system-on-chip
(SoC), this should: be the supplier of the silicon IP used to create the
accelerator.
====
If the vendor has a https://pcisig.com/membership/member-companies[PCI
vendor ID], the low 16 bits of pname:vendorID must: contain that PCI vendor
ID, and the remaining bits must: be set to zero.
Otherwise, the value returned must: be a valid Khronos vendor ID, obtained
as described in the <<vulkan-styleguide,Vulkan Documentation and
Extensions>> document in the section "`Registering a Vendor ID with
Khronos`".
Khronos vendor IDs are allocated starting at 0x10000, to distinguish them
from the PCI vendor ID namespace.
The vendor is also responsible for the value returned in pname:deviceID.
If the implementation is driven primarily by a https://pcisig.com/[PCI
device] with a https://pcisig.com/[PCI device ID], the low 16 bits of
pname:deviceID must: contain that PCI device ID, and the remaining bits
must: be set to zero.
Otherwise, the choice of what values to return may: be dictated by operating
system or platform policies - but should: uniquely identify both the device
version and any major configuration options (for example, core count in the
case of multicore devices).
[NOTE]
.Note
====
The same device ID should: be used for all physical implementations of that
device version and configuration.
For example, all uses of a specific silicon IP GPU version and configuration
should: use the same device ID, even if those uses occur in different SoCs.
====
include::../validity/structs/VkPhysicalDeviceProperties.txt[]
--
@ -174,35 +203,49 @@ capabilities of the system, such as how many memory heaps there are.
--
ifdef::VK_KHR_get_physical_device_properties2[]
ifdef::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[]
[open,refpage='vkGetPhysicalDeviceProperties2KHR',desc='Returns properties of a physical device',type='protos']
[open,refpage='vkGetPhysicalDeviceProperties2',desc='Returns properties of a physical device',type='protos']
--
To query general properties of physical devices once enumerated, call:
ifdef::VK_VERSION_1_1[]
include::../api/protos/vkGetPhysicalDeviceProperties2.txt[]
endif::VK_VERSION_1_1[]
ifdef::VK_VERSION_1_1+VK_KHR_get_physical_device_properties2[or the equivalent command]
ifdef::VK_KHR_get_physical_device_properties2[]
include::../api/protos/vkGetPhysicalDeviceProperties2KHR.txt[]
endif::VK_KHR_get_physical_device_properties2[]
* pname:physicalDevice is the handle to the physical device whose
properties will be queried.
* pname:pProperties points to an instance of the
slink:VkPhysicalDeviceProperties2KHR structure, that will be filled with
slink:VkPhysicalDeviceProperties2 structure, that will be filled with
returned information.
Each structure in pname:pProperties and its pname:pNext chain contain
members corresponding to properties or implementation-dependent limits.
fname:vkGetPhysicalDeviceProperties2KHR writes each member to a value
fname:vkGetPhysicalDeviceProperties2 writes each member to a value
indicating the value of that property or limit.
include::../validity/protos/vkGetPhysicalDeviceProperties2KHR.txt[]
include::../validity/protos/vkGetPhysicalDeviceProperties2.txt[]
--
[open,refpage='VkPhysicalDeviceProperties2KHR',desc='Structure specifying physical device properties',type='structs']
[open,refpage='VkPhysicalDeviceProperties2',desc='Structure specifying physical device properties',type='structs']
--
The sname:VkPhysicalDeviceProperties2KHR structure is defined as:
The sname:VkPhysicalDeviceProperties2 structure is defined as:
include::../api/structs/VkPhysicalDeviceProperties2.txt[]
ifdef::VK_KHR_get_physical_device_properties2[]
or the equivalent
include::../api/structs/VkPhysicalDeviceProperties2KHR.txt[]
endif::VK_KHR_get_physical_device_properties2[]
* pname:sType is the type of this structure.
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
@ -214,20 +257,26 @@ include::../api/structs/VkPhysicalDeviceProperties2KHR.txt[]
The pname:pNext chain of this structure is used to extend the structure with
properties defined by extensions.
include::../validity/structs/VkPhysicalDeviceProperties2KHR.txt[]
include::../validity/structs/VkPhysicalDeviceProperties2.txt[]
--
ifdef::VK_KHR_external_memory_capabilities,VK_KHR_external_semaphore_capabilities,VK_KHR_external_fence_capabilities[]
ifdef::VK_VERSION_1_1,VK_KHR_external_memory_capabilities,VK_KHR_external_semaphore_capabilities,VK_KHR_external_fence_capabilities[]
[open,refpage='VkPhysicalDeviceIDPropertiesKHR',desc='Structure specifying IDs related to the physical device',type='structs']
[open,refpage='VkPhysicalDeviceIDProperties',desc='Structure specifying IDs related to the physical device',type='structs']
--
To query the UUID and LUID of a device, add
slink:VkPhysicalDeviceIDPropertiesKHR to the pname:pNext chain of the
slink:VkPhysicalDeviceProperties2KHR structure.
The sname:VkPhysicalDeviceIDPropertiesKHR structure is defined as:
slink:VkPhysicalDeviceIDProperties to the pname:pNext chain of the
slink:VkPhysicalDeviceProperties2 structure.
The sname:VkPhysicalDeviceIDProperties structure is defined as:
include::../api/structs/VkPhysicalDeviceIDProperties.txt[]
ifdef::VK_KHR_external_memory_capabilities[]
or the equivalent
include::../api/structs/VkPhysicalDeviceIDPropertiesKHR.txt[]
endif::VK_KHR_external_memory_capabilities[]
* pname:sType is the type of this structure.
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
@ -237,7 +286,7 @@ include::../api/structs/VkPhysicalDeviceIDPropertiesKHR.txt[]
* pname:driverUUID is an array of size ename:VK_UUID_SIZE, containing
8-bit values that represent a universally unique identifier for the
driver build in use by the device.
* pname:deviceLUID is an array of size ename:VK_LUID_SIZE_KHR, containing
* pname:deviceLUID is an array of size ename:VK_LUID_SIZE, containing
8-bit values that represent a locally unique identifier for the device.
* pname:deviceNodeMask is a bitfield identifying the node within a linked
device adapter corresponding to the device.
@ -258,18 +307,18 @@ a particular external object can be shared between driver components, where
such a restriction exists as defined in the compatibility table for the
particular object type:
ifdef::VK_KHR_external_memory_capabilities[]
ifdef::VK_VERSION_1_1,VK_KHR_external_memory_capabilities[]
* <<external-memory-handle-types-compatibility,External memory handle
types compatibility>>
endif::VK_KHR_external_memory_capabilities[]
ifdef::VK_KHR_external_semaphore_capabilities[]
endif::VK_VERSION_1_1,VK_KHR_external_memory_capabilities[]
ifdef::VK_VERSION_1_1,VK_KHR_external_semaphore_capabilities[]
* <<external-semaphore-handle-types-compatibility,External semaphore
handle types compatibility>>
endif::VK_KHR_external_semaphore_capabilities[]
ifdef::VK_KHR_external_fence_capabilities[]
endif::VK_VERSION_1_1,VK_KHR_external_semaphore_capabilities[]
ifdef::VK_VERSION_1_1,VK_KHR_external_fence_capabilities[]
* <<external-fence-handle-types-compatibility,External fence handle types
compatibility>>
endif::VK_KHR_external_fence_capabilities[]
endif::VK_VERSION_1_1,VK_KHR_external_fence_capabilities[]
If pname:deviceLUIDValid is ename:VK_FALSE, the contents of pname:deviceLUID
and pname:deviceNodeMask are undefined.
@ -289,8 +338,8 @@ Otherwise, pname:deviceNodeMask must: be `1`.
.Note
====
Although they have identical descriptions,
slink:VkPhysicalDeviceIDPropertiesKHR::pname:deviceUUID may differ from
slink:VkPhysicalDeviceProperties2KHR::pname:pipelineCacheUUID.
slink:VkPhysicalDeviceIDProperties::pname:deviceUUID may differ from
slink:VkPhysicalDeviceProperties2::pname:pipelineCacheUUID.
The former is intended to identify and correlate devices across API and
driver boundaries, while the latter is used to identify a compatible device
and driver combination to use when serializing and de-serializing pipeline
@ -300,8 +349,8 @@ state.
[NOTE]
.Note
====
While slink:VkPhysicalDeviceIDPropertiesKHR::pname:deviceUUID is specified
to remain consistent across driver versions and system reboots, it is not
While slink:VkPhysicalDeviceIDProperties::pname:deviceUUID is specified to
remain consistent across driver versions and system reboots, it is not
intended to be usable as a serializable persistent identifier for a device.
It may change when a device is physically added to, removed from, or moved
to a different connector in a system while that system is powered down.
@ -314,12 +363,12 @@ persistence of this value for uses other than identifying compatible devices
for external object sharing purposes.
====
include::../validity/structs/VkPhysicalDeviceIDPropertiesKHR.txt[]
include::../validity/structs/VkPhysicalDeviceIDProperties.txt[]
--
endif::VK_KHR_external_memory_capabilities,VK_KHR_external_semaphore_capabilities,VK_KHR_external_fence_capabilities[]
endif::VK_VERSION_1_1,VK_KHR_external_memory_capabilities,VK_KHR_external_semaphore_capabilities,VK_KHR_external_fence_capabilities[]
endif::VK_KHR_get_physical_device_properties2[]
endif::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[]
[open,refpage='vkGetPhysicalDeviceQueueFamilyProperties',desc='Reports properties of the queues of the specified physical device',type='protos']
--
@ -446,12 +495,27 @@ include::../api/enums/VkQueueFlagBits.txt[]
<<sparsememory,Sparse Resources>>).
If any of the sparse resource features are enabled, then at least one
queue family must: support this bit.
ifdef::VK_VERSION_1_1[]
* if ename:VK_QUEUE_PROTECTED_BIT is set, then the queues in this queue
family support the ename:VK_DEVICE_QUEUE_CREATE_PROTECTED_BIT bit.
(see <<memory-protected-memory,Protected Memory>>).
If the protected memory physical device feature is supported, then at
least one queue family of at least one physical device exposed by the
implementation must: support this bit.
endif::VK_VERSION_1_1[]
If an implementation exposes any queue family that supports graphics
operations, at least one queue family of at least one physical device
exposed by the implementation must: support both graphics and compute
operations.
ifdef::VK_VERSION_1_1[]
Furthermore, if the protected memory physical device feature is supported,
then at least one queue family of at least one physical device exposed by
the implementation must: support graphics operations, compute operations,
and protected memory operations.
endif::VK_VERSION_1_1[]
[NOTE]
.Note
====
@ -476,14 +540,22 @@ sname:VkQueueFlags is a bitmask type for setting a mask of zero or more
slink:VkQueueFlagBits.
--
ifdef::VK_KHR_get_physical_device_properties2[]
ifdef::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[]
[open,refpage='vkGetPhysicalDeviceQueueFamilyProperties2KHR',desc='Reports properties of the queues of the specified physical device',type='protos']
[open,refpage='vkGetPhysicalDeviceQueueFamilyProperties2',desc='Reports properties of the queues of the specified physical device',type='protos']
--
To query properties of queues available on a physical device, call:
ifdef::VK_VERSION_1_1[]
include::../api/protos/vkGetPhysicalDeviceQueueFamilyProperties2.txt[]
endif::VK_VERSION_1_1[]
ifdef::VK_VERSION_1_1+VK_KHR_get_physical_device_properties2[or the equivalent command]
ifdef::VK_KHR_get_physical_device_properties2[]
include::../api/protos/vkGetPhysicalDeviceQueueFamilyProperties2KHR.txt[]
endif::VK_KHR_get_physical_device_properties2[]
* pname:physicalDevice is the handle to the physical device whose
properties will be queried.
@ -491,21 +563,27 @@ include::../api/protos/vkGetPhysicalDeviceQueueFamilyProperties2KHR.txt[]
the number of queue families available or queried, as described in
flink:vkGetPhysicalDeviceQueueFamilyProperties.
* pname:pQueueFamilyProperties is either `NULL` or a pointer to an array
of slink:VkQueueFamilyProperties2KHR structures.
of slink:VkQueueFamilyProperties2 structures.
fname:vkGetPhysicalDeviceQueueFamilyProperties2KHR behaves similarly to
fname:vkGetPhysicalDeviceQueueFamilyProperties2 behaves similarly to
flink:vkGetPhysicalDeviceQueueFamilyProperties, with the ability to return
extended information in a pname:pNext chain of output structures.
include::../validity/protos/vkGetPhysicalDeviceQueueFamilyProperties2KHR.txt[]
include::../validity/protos/vkGetPhysicalDeviceQueueFamilyProperties2.txt[]
--
[open,refpage='VkQueueFamilyProperties2KHR',desc='Structure providing information about a queue family',type='structs']
[open,refpage='VkQueueFamilyProperties2',desc='Structure providing information about a queue family',type='structs']
--
The sname:VkQueueFamilyProperties2KHR structure is defined as:
The sname:VkQueueFamilyProperties2 structure is defined as:
include::../api/structs/VkQueueFamilyProperties2.txt[]
ifdef::VK_KHR_get_physical_device_properties2[]
or the equivalent
include::../api/structs/VkQueueFamilyProperties2KHR.txt[]
endif::VK_KHR_get_physical_device_properties2[]
* pname:sType is the type of this structure.
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
@ -513,10 +591,10 @@ include::../api/structs/VkQueueFamilyProperties2KHR.txt[]
slink:VkQueueFamilyProperties which is populated with the same values as
in flink:vkGetPhysicalDeviceQueueFamilyProperties.
include::../validity/structs/VkQueueFamilyProperties2KHR.txt[]
include::../validity/structs/VkQueueFamilyProperties2.txt[]
--
endif::VK_KHR_get_physical_device_properties2[]
endif::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[]
[[devsandqueues-devices]]
@ -544,7 +622,7 @@ devices for their queue family properties is described in the
<<devsandqueues-physical-device-enumeration, Physical Device Enumeration>>
section above.
ifdef::VK_KHX_device_group_creation[]
ifdef::VK_VERSION_1_1,VK_KHR_device_group_creation[]
A single logical device can: also be created from multiple physical devices,
if those physical devices belong to the same device group.
@ -552,23 +630,31 @@ A _device group_ is a set of physical devices that support accessing each
other's memory and recording a single command buffer that can: be executed
on all the physical devices.
Device groups are enumerated by calling
flink:vkEnumeratePhysicalDeviceGroupsKHX, and a logical device is created
from a subset of the physical devices in a device group by passing the
physical devices through slink:VkDeviceGroupDeviceCreateInfoKHX.
flink:vkEnumeratePhysicalDeviceGroups, and a logical device is created from
a subset of the physical devices in a device group by passing the physical
devices through slink:VkDeviceGroupDeviceCreateInfo.
[open,refpage='vkEnumeratePhysicalDeviceGroupsKHX',desc='Enumerates groups of physical devices that can be used to create a single logical device',type='protos']
[open,refpage='vkEnumeratePhysicalDeviceGroups',desc='Enumerates groups of physical devices that can be used to create a single logical device',type='protos']
--
To retrieve a list of the device groups present in the system, call:
include::../api/protos/vkEnumeratePhysicalDeviceGroupsKHX.txt[]
ifdef::VK_VERSION_1_1[]
include::../api/protos/vkEnumeratePhysicalDeviceGroups.txt[]
endif::VK_VERSION_1_1[]
ifdef::VK_VERSION_1_1+VK_KHR_device_group_creation[or the equivalent command]
ifdef::VK_KHR_device_group_creation[]
include::../api/protos/vkEnumeratePhysicalDeviceGroupsKHR.txt[]
endif::VK_KHR_device_group_creation[]
* pname:instance is a handle to a Vulkan instance previously created with
flink:vkCreateInstance.
* pname:pPhysicalDeviceGroupCount is a pointer to an integer related to
the number of device groups available or queried, as described below.
* pname:pPhysicalDeviceGroupProperties is either `NULL` or a pointer to an
array of slink:VkPhysicalDeviceGroupPropertiesKHX structures.
array of slink:VkPhysicalDeviceGroupProperties structures.
If pname:pPhysicalDeviceGroupProperties is `NULL`, then the number of device
groups available is returned in pname:pPhysicalDeviceGroupCount.
@ -587,15 +673,21 @@ returned.
Every physical device must: be in exactly one device group.
include::../validity/protos/vkEnumeratePhysicalDeviceGroupsKHX.txt[]
include::../validity/protos/vkEnumeratePhysicalDeviceGroups.txt[]
--
[open,refpage='VkPhysicalDeviceGroupPropertiesKHX',desc='Structure specifying physical device group properties',type='structs']
[open,refpage='VkPhysicalDeviceGroupProperties',desc='Structure specifying physical device group properties',type='structs']
--
The sname:VkPhysicalDeviceGroupPropertiesKHX structure is defined as:
The sname:VkPhysicalDeviceGroupProperties structure is defined as:
include::../api/structs/VkPhysicalDeviceGroupPropertiesKHX.txt[]
include::../api/structs/VkPhysicalDeviceGroupProperties.txt[]
ifdef::VK_KHR_device_group_creation[]
or the equivalent
include::../api/structs/VkPhysicalDeviceGroupPropertiesKHR.txt[]
endif::VK_KHR_device_group_creation[]
* pname:sType is the type of this structure.
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
@ -606,7 +698,7 @@ include::../api/structs/VkPhysicalDeviceGroupPropertiesKHX.txt[]
The first pname:physicalDeviceCount elements of the array will be valid.
* pname:subsetAllocation indicates whether logical devices created from
the group support allocating device memory on a subset of devices, via
the pname:deviceMask member of the slink:VkMemoryAllocateFlagsInfoKHX.
the pname:deviceMask member of the slink:VkMemoryAllocateFlagsInfo.
If this is ename:VK_FALSE, then all device memory allocations are made
across all physical devices in the group.
If pname:physicalDeviceCount is `1`, then pname:subsetAllocation must:
@ -614,7 +706,7 @@ include::../api/structs/VkPhysicalDeviceGroupPropertiesKHX.txt[]
--
endif::VK_KHX_device_group_creation[]
endif::VK_VERSION_1_1,VK_KHR_device_group_creation[]
[[devsandqueues-device-creation]]
@ -722,20 +814,34 @@ include::../api/structs/VkDeviceCreateInfo.txt[]
.Valid Usage
****
* [[VUID-VkDeviceCreateInfo-queueFamilyIndex-00372]]
ifndef::VK_VERSION_1_1[]
The pname:queueFamilyIndex member of each element of
pname:pQueueCreateInfos must: be unique within pname:pQueueCreateInfos
ifdef::VK_KHR_get_physical_device_properties2[]
endif::VK_VERSION_1_1[]
ifdef::VK_VERSION_1_1[]
The pname:queueFamilyIndex member of each element of
pname:pQueueCreateInfos must: be unique within pname:pQueueCreateInfos,
except that two members can share the same pname:queueFamilyIndex if one
is a protected-capable queue and one is not a protected-capable queue.
endif::VK_VERSION_1_1[]
ifdef::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[]
* [[VUID-VkDeviceCreateInfo-pNext-00373]]
If the pname:pNext chain includes a slink:VkPhysicalDeviceFeatures2KHR
If the pname:pNext chain includes a slink:VkPhysicalDeviceFeatures2
structure, then pname:pEnabledFeatures must: be `NULL`
endif::VK_KHR_get_physical_device_properties2[]
ifdef::VK_KHR_maintenance1[]
endif::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[]
ifdef::VK_AMD_negative_viewport_height[]
ifdef::VK_VERSION_1_1[]
* pname:ppEnabledExtensionNames must: not contain
code:VK_AMD_negative_viewport_height
endif::VK_VERSION_1_1[]
ifndef::VK_VERSION_1_1[]
ifdef::VK_VERSION_1_1,VK_KHR_maintenance1[]
* [[VUID-VkDeviceCreateInfo-ppEnabledExtensionNames-00374]]
pname:ppEnabledExtensionNames must: not contain both
`<<VK_KHR_maintenance1>>` and `<<VK_AMD_negative_viewport_height>>`
endif::VK_VERSION_1_1,VK_KHR_maintenance1[]
endif::VK_VERSION_1_1[]
endif::VK_AMD_negative_viewport_height[]
endif::VK_KHR_maintenance1[]
****
include::../validity/structs/VkDeviceCreateInfo.txt[]
@ -749,17 +855,23 @@ sname:VkDeviceCreateFlags is a bitmask type for setting a mask, but is
currently reserved for future use.
--
ifdef::VK_KHX_device_group_creation[]
ifdef::VK_VERSION_1_1,VK_KHR_device_group_creation[]
[open,refpage='VkDeviceGroupDeviceCreateInfoKHX',desc='Create a logical device from multiple physical devices',type='structs']
[open,refpage='VkDeviceGroupDeviceCreateInfo',desc='Create a logical device from multiple physical devices',type='structs']
--
A logical device can: be created that connects to one or more physical
devices by including a sname:VkDeviceGroupDeviceCreateInfoKHX structure in
the pname:pNext chain of slink:VkDeviceCreateInfo.
The sname:VkDeviceGroupDeviceCreateInfoKHX structure is defined as:
devices by including a sname:VkDeviceGroupDeviceCreateInfo structure in the
pname:pNext chain of slink:VkDeviceCreateInfo.
The sname:VkDeviceGroupDeviceCreateInfo structure is defined as:
include::../api/structs/VkDeviceGroupDeviceCreateInfoKHX.txt[]
include::../api/structs/VkDeviceGroupDeviceCreateInfo.txt[]
ifdef::VK_KHR_device_group_creation[]
or the equivalent
include::../api/structs/VkDeviceGroupDeviceCreateInfoKHR.txt[]
endif::VK_KHR_device_group_creation[]
* pname:sType is the type of this structure.
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
@ -778,31 +890,30 @@ being assigned a device index of [eq]#i#.
Certain commands and structures refer to one or more physical devices by
using device indices or _device masks_ formed using device indices.
A logical device created without using
sname:VkDeviceGroupDeviceCreateInfoKHX, or with pname:physicalDeviceCount
equal to zero, is equivalent to a pname:physicalDeviceCount of one and
pname:pPhysicalDevices pointing to the pname:physicalDevice parameter to
flink:vkCreateDevice.
A logical device created without using sname:VkDeviceGroupDeviceCreateInfo,
or with pname:physicalDeviceCount equal to zero, is equivalent to a
pname:physicalDeviceCount of one and pname:pPhysicalDevices pointing to the
pname:physicalDevice parameter to flink:vkCreateDevice.
In particular, the device index of that physical device is zero.
.Valid Usage
****
* [[VUID-VkDeviceGroupDeviceCreateInfoKHX-pPhysicalDevices-00375]]
* [[VUID-VkDeviceGroupDeviceCreateInfo-pPhysicalDevices-00375]]
Each element of pname:pPhysicalDevices must: be unique
* [[VUID-VkDeviceGroupDeviceCreateInfoKHX-pPhysicalDevices-00376]]
* [[VUID-VkDeviceGroupDeviceCreateInfo-pPhysicalDevices-00376]]
All elements of pname:pPhysicalDevices must: be in the same device group
as enumerated by flink:vkEnumeratePhysicalDeviceGroupsKHX
* [[VUID-VkDeviceGroupDeviceCreateInfoKHX-physicalDeviceCount-00377]]
as enumerated by flink:vkEnumeratePhysicalDeviceGroups
* [[VUID-VkDeviceGroupDeviceCreateInfo-physicalDeviceCount-00377]]
If pname:physicalDeviceCount is not `0`, the pname:physicalDevice
parameter of flink:vkCreateDevice must: be an element of
pname:pPhysicalDevices.
****
include::../validity/structs/VkDeviceGroupDeviceCreateInfoKHX.txt[]
include::../validity/structs/VkDeviceGroupDeviceCreateInfo.txt[]
--
endif::VK_KHX_device_group_creation[]
endif::VK_VERSION_1_1,VK_KHR_device_group_creation[]
[[devsandqueues-use]]
@ -830,10 +941,18 @@ references on where to find more information:
[[devsandqueues-lost-device]]
=== Lost Device
A logical device may: become _lost_ because of hardware errors, execution
timeouts, power management events and/or platform-specific events.
This may: cause pending and future command execution to fail and cause
hardware resources to be corrupted.
A logical device may: become _lost_ for a number of implementation-specific
reasons, indicating that pending and future command execution may: fail and
cause resources and backing memory to become undefined.
[NOTE]
.Note
====
Typical reasons for device loss will include things like execution timing
out (to prevent denial of service), power management events, platform
resource management, or implementation errors.
====
When this happens, certain commands will return ename:VK_ERROR_DEVICE_LOST
(see <<fundamentals-errorcodes,Error Codes>> for a list of such commands).
After any such event, the logical device is considered _lost_.
@ -841,10 +960,11 @@ It is not possible to reset the logical device to a non-lost state, however
the lost state is specific to a logical device (sname:VkDevice), and the
corresponding physical device (sname:VkPhysicalDevice) may: be otherwise
unaffected.
In some cases, the physical device may: also be lost, and attempting to
create a new logical device will fail, returning ename:VK_ERROR_DEVICE_LOST.
This is usually indicative of a problem with the underlying hardware, or its
connection to the host.
This is usually indicative of a problem with the underlying implementation,
or its connection to the host.
If the physical device has not been lost, and a new logical device is
successfully created from that physical device, it must: be in the non-lost
state.
@ -856,8 +976,9 @@ Whilst logical device loss may: be recoverable, in the case of physical
device loss, it is unlikely that an application will be able to recover
unless additional, unaffected physical devices exist on the system.
The error is largely informational and intended only to inform the user that
their hardware has probably developed a fault or become physically
disconnected, and should: be investigated further.
a platform issue has occurred, and should: be investigated further.
For example, underlying hardware may: have developed a fault or become
physically disconnected from the rest of the system.
In many cases, physical device loss may: cause other more serious issues
such as the operating system crashing; in which case it may: not be reported
via the Vulkan API.
@ -904,7 +1025,7 @@ of determining whether a command buffer is in the
considered in-use by the device, a return value of
ename:VK_ERROR_DEVICE_LOST is equivalent to ename:VK_SUCCESS.
ifdef::VK_KHR_external_memory[]
ifdef::VK_VERSION_1_1,VK_KHR_external_memory[]
The content of any external memory objects that have been exported from or
imported to a lost device become undefined.
@ -916,9 +1037,9 @@ to sname:VkDeviceMemory objects associated with the same underlying memory
resources as external memory objects on the lost device becomes
ename:VK_IMAGE_LAYOUT_UNDEFINED.
endif::VK_KHR_external_memory[]
endif::VK_VERSION_1_1,VK_KHR_external_memory[]
ifdef::VK_KHR_external_semaphore[]
ifdef::VK_VERSION_1_1,VK_KHR_external_semaphore[]
The state of sname:VkSemaphore objects on other logical devices created by
<<synchronization-semaphores-importing,importing a semaphore payload>> with
@ -933,7 +1054,7 @@ operations on such semaphores behave as defined in
Wait Operations>> for external semaphores not in a valid state for a wait
operation.
endif::VK_KHR_external_semaphore[]
endif::VK_VERSION_1_1,VK_KHR_external_semaphore[]
ifdef::editing-notes[]
[NOTE]
@ -1059,7 +1180,12 @@ include::../api/structs/VkDeviceQueueCreateInfo.txt[]
* pname:sType is the type of this structure.
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
ifndef::VK_VERSION_1_1[]
* pname:flags is reserved for future use.
endif::VK_VERSION_1_1[]
ifdef::VK_VERSION_1_1[]
* pname:flags is a bitmask indicating behavior of the queue.
endif::VK_VERSION_1_1[]
* pname:queueFamilyIndex is an unsigned integer indicating the index of
the queue family to create on this device.
This index corresponds to the index of an element of the
@ -1091,12 +1217,32 @@ include::../api/structs/VkDeviceQueueCreateInfo.txt[]
include::../validity/structs/VkDeviceQueueCreateInfo.txt[]
--
[open,refpage='VkDeviceQueueCreateFlags',desc='Reserved for future use',type='enums']
ifdef::VK_VERSION_1_1[]
[open,refpage='VkDeviceQueueCreateFlagBits',desc='Bitmask specifying behavior of the queue',type='enums']
--
Bits which can: be set in slink:VkDeviceQueueCreateInfo::pname:flags to
specify usage behavior of the queue are:
include::../api/enums/VkDeviceQueueCreateFlagBits.txt[]
* ename:VK_DEVICE_QUEUE_CREATE_PROTECTED_BIT indicates that the device
queue is a protected-capable queue.
If the protected memory feature is not enabled, the
ename:VK_DEVICE_QUEUE_CREATE_PROTECTED_BIT bit of pname:flags must: not
be set.
--
endif::VK_VERSION_1_1[]
[open,refpage='VkDeviceQueueCreateFlags',desc='Bitmask of VkDeviceQueueCreateFlagBits',type='enums']
--
include::../api/flags/VkDeviceQueueCreateFlags.txt[]
sname:VkDeviceQueueCreateFlags is a bitmask type for setting a mask, but is
currently reserved for future use.
sname:VkDeviceQueueCreateFlags is a bitmask type for setting a mask of zero
or more slink:VkDeviceQueueCreateFlagBits.
--
ifdef::VK_EXT_global_priority[]
@ -1160,8 +1306,8 @@ processing time or better quality of service than lower priority queues.
The global priority level of a queue takes precedence over the per-process
queue priority (sname:VkDeviceQueueCreateInfo::pname:pQueuePriorities).
Abuse of this feature may result in starving the rest of the system from
hardware resources.
Abuse of this feature may: result in starving the rest of the system of
implementation resources.
Therefore, the driver implementation may: deny requests to acquire a
priority above the default priority
(ename:VK_QUEUE_GLOBAL_PRIORITY_MEDIUM_EXT) if the caller does not have
@ -1190,6 +1336,13 @@ include::../api/protos/vkGetDeviceQueue.txt[]
* pname:pQueue is a pointer to a sname:VkQueue object that will be filled
with the handle for the requested queue.
ifdef::VK_VERSION_1_1[]
fname:vkGetDeviceQueue must: only be used to get queues that were created
with the pname:flags parameter of sname:VkDeviceQueueCreateInfo set to zero.
To get queues that were created with a non-zero pname:flags parameter use
flink:vkGetDeviceQueue2.
endif::VK_VERSION_1_1[]
.Valid Usage
****
* [[VUID-vkGetDeviceQueue-queueFamilyIndex-00384]]
@ -1200,11 +1353,73 @@ include::../api/protos/vkGetDeviceQueue.txt[]
pname:queueIndex must: be less than the number of queues created for the
specified queue family index when pname:device was created, via the
pname:queueCount member of the sname:VkDeviceQueueCreateInfo structure
* slink:VkDeviceQueueCreateInfo::pname:flags must: have been set to zero
when pname:device was created
****
include::../validity/protos/vkGetDeviceQueue.txt[]
--
ifdef::VK_VERSION_1_1[]
[open,refpage='vkGetDeviceQueue2',desc='Get a queue handle from a device',type='protos']
--
To retrieve a handle to a VkQueue object with specific
pname:VkDeviceQueueCreateFlags creation flags, call:
include::../api/protos/vkGetDeviceQueue2.txt[]
* pname:device is the logical device that owns the queue.
* pname:pQueueInfo points to an instance of the slink:VkDeviceQueueInfo2
structure, describing the parameters used to create the device queue.
* pname:pQueue is a pointer to a sname:VkQueue object that will be filled
with the handle for the requested queue.
include::../validity/protos/vkGetDeviceQueue2.txt[]
--
[open,refpage='VkDeviceQueueInfo2',desc='Structure specifying the parameters used for device queue creation',type='structs']
--
The sname:VkDeviceQueueInfo2 structure is defined as:
include::../api/structs/VkDeviceQueueInfo2.txt[]
* pname:sType is the type of this structure.
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
The pname:pNext chain of sname:VkDeviceQueueInfo2 is used to provide
additional image parameters to fname:vkGetDeviceQueue2.
* pname:flags is a elink:VkDeviceQueueCreateFlags value indicating the
flags used to create the device queue.
* pname:queueFamilyIndex is the index of the queue family to which the
queue belongs.
* pname:queueIndex is the index within this queue family of the queue to
retrieve.
The queue returned by fname:vkGetDeviceQueue2 must: have the same
pname:flags value from this structure as that used at device creation time
in a sname:VkDeviceQueueCreateInfo instance.
If no matching pname:flags were specified at device creation time then
pname:pQueue will return code:VK_NULL_HANDLE.
.Valid Usage
****
* pname:queueFamilyIndex must: be one of the queue family indices
specified when pname:device was created, via the
sname:VkDeviceQueueCreateInfo structure
* pname:queueIndex must: be less than the number of queues created for the
specified queue family index and sname:VkDeviceQueueCreateFlags member
pname:flags equal to this pname:flags value when pname:device was
created, via the pname:queueCount member of the
sname:VkDeviceQueueCreateInfo structure
****
include::../validity/structs/VkDeviceQueueInfo2.txt[]
--
endif::VK_VERSION_1_1[]
[[devsandqueues-index]]
=== Queue Family Index

72
doc/specs/vulkan/chapters/dispatch.txt
View File

@ -125,6 +125,22 @@ ifdef::VK_IMG_filter_cubic[]
ename:VK_IMAGE_VIEW_TYPE_3D, ename:VK_IMAGE_VIEW_TYPE_CUBE, or
ename:VK_IMAGE_VIEW_TYPE_CUBE_ARRAY
endif::VK_IMG_filter_cubic[]
ifdef::VK_VERSION_1_1[]
* If pname:commandBuffer is an unprotected command buffer, and any
pipeline stage in the sname:VkPipeline object currently bound to
ename:VK_PIPELINE_BIND_POINT_COMPUTE reads from or writes to any image
or buffer, that image or buffer must: not be a protected image or
protected buffer.
* If pname:commandBuffer is a protected command buffer, and any pipeline
stage in the sname:VkPipeline object currently bound to
ename:VK_PIPELINE_POINT_COMPUTE writes to any image or buffer, that
image or buffer must: not be an unprotected image or unprotected buffer.
* If pname:commandBuffer is a protected command buffer, and any pipeline
stage other than the compute pipeline stage in the sname:VkPipeline
object currently bound to ename:VK_PIPELINE_POINT_COMPUTE reads from any
image or buffer, the image or buffer must: not be a protected image or
protected buffer.
endif::VK_VERSION_1_1[]
****
include::../validity/protos/vkCmdDispatch.txt[]
@ -243,6 +259,22 @@ ifdef::VK_IMG_filter_cubic[]
ename:VK_IMAGE_VIEW_TYPE_3D, ename:VK_IMAGE_VIEW_TYPE_CUBE, or
ename:VK_IMAGE_VIEW_TYPE_CUBE_ARRAY
endif::VK_IMG_filter_cubic[]
ifdef::VK_VERSION_1_1[]
* If pname:commandBuffer is an unprotected command buffer, and any
pipeline stage in the sname:VkPipeline object currently bound to
ename:VK_PIPELINE_BIND_POINT_COMPUTE reads from or writes to any image
or buffer, that image or buffer must: not be a protected image or
protected buffer.
* If pname:commandBuffer is a protected command buffer, and any pipeline
stage in the sname:VkPipeline object currently bound to
ename:VK_PIPELINE_POINT_COMPUTE writes to any image or buffer, that
image or buffer must: not be an unprotected image or unprotected buffer.
* If pname:commandBuffer is a protected command buffer, and any pipeline
stage other than the compute pipeline stage in the sname:VkPipeline
object currently bound to ename:VK_PIPELINE_POINT_COMPUTE reads from any
image or buffer, the image or buffer must: not be a protected image or
protected buffer.
endif::VK_VERSION_1_1[]
****
include::../validity/protos/vkCmdDispatchIndirect.txt[]
@ -282,15 +314,23 @@ include::../validity/structs/VkDispatchIndirectCommand.txt[]
--
ifdef::VK_KHX_device_group[]
ifdef::VK_VERSION_1_1,VK_KHR_device_group[]
[open,refpage='vkCmdDispatchBaseKHX',desc='Dispatch compute work items',type='protos']
[open,refpage='vkCmdDispatchBase',desc='Dispatch compute work items',type='protos']
--
To record a dispatch using non-zero base values for the components of
code:WorkgroupId, call:
include::../api/protos/vkCmdDispatchBaseKHX.txt[]
ifdef::VK_VERSION_1_1[]
include::../api/protos/vkCmdDispatchBase.txt[]
endif::VK_VERSION_1_1[]
ifdef::VK_VERSION_1_1+VK_KHR_device_group[or the equivalent command]
ifdef::VK_KHR_device_group[]
include::../api/protos/vkCmdDispatchBaseKHR.txt[]
endif::VK_KHR_device_group[]
* pname:commandBuffer is the command buffer into which the command will be
recorded.
@ -312,40 +352,40 @@ When the command is executed, a global workgroup consisting of
is assembled, with code:WorkgroupId values ranging from [eq]#[baseGroup,
baseGroup {plus} groupCount)# in each component.
flink:vkCmdDispatch is equivalent to
vkCmdDispatchBaseKHX(0,0,0,groupCountX,groupCountY,groupCountZ).
vkCmdDispatchBase(0,0,0,groupCountX,groupCountY,groupCountZ).
.Valid Usage
****
* [[VUID-vkCmdDispatchBaseKHX-None-00420]]
* [[VUID-vkCmdDispatchBase-None-00420]]
All valid usage rules from flink:vkCmdDispatch apply
* [[VUID-vkCmdDispatchBaseKHX-baseGroupX-00421]]
* [[VUID-vkCmdDispatchBase-baseGroupX-00421]]
pname:baseGroupX must: be less than
sname:VkPhysicalDeviceLimits::pname:maxComputeWorkGroupCount[0]
* [[VUID-vkCmdDispatchBaseKHX-baseGroupX-00422]]
* [[VUID-vkCmdDispatchBase-baseGroupX-00422]]
pname:baseGroupX must: be less than
sname:VkPhysicaYDeviceLimits::pname:maxComputeWorkGroupCount[1]
* [[VUID-vkCmdDispatchBaseKHX-baseGroupZ-00423]]
sname:VkPhysicalDeviceLimits::pname:maxComputeWorkGroupCount[1]
* [[VUID-vkCmdDispatchBase-baseGroupZ-00423]]
pname:baseGroupZ must: be less than
sname:VkPhysicalDeviceLimits::pname:maxComputeWorkGroupCount[2]
* [[VUID-vkCmdDispatchBaseKHX-groupCountX-00424]]
* [[VUID-vkCmdDispatchBase-groupCountX-00424]]
pname:groupCountX must: be less than or equal to
sname:VkPhysicalDeviceLimits::pname:maxComputeWorkGroupCount[0] minus
pname:baseGroupX
* [[VUID-vkCmdDispatchBaseKHX-groupCountY-00425]]
* [[VUID-vkCmdDispatchBase-groupCountY-00425]]
pname:groupCountY must: be less than or equal to
sname:VkPhysicalDeviceLimits::pname:maxComputeWorkGroupCount[1] minus
pname:baseGroupY
* [[VUID-vkCmdDispatchBaseKHX-groupCountZ-00426]]
* [[VUID-vkCmdDispatchBase-groupCountZ-00426]]
pname:groupCountZ must: be less than or equal to
sname:VkPhysicalDeviceLimits::pname:maxComputeWorkGroupCount[2] minus
pname:baseGroupZ
* [[VUID-vkCmdDispatchBaseKHX-baseGroupX-00427]]
* [[VUID-vkCmdDispatchBase-baseGroupX-00427]]
If any of pname:baseGroupX, pname:baseGroupY, or pname:baseGroupZ are
not zero, then the currently bound compute pipeline must: have been
created with the ename:VK_PIPELINE_CREATE_DISPATCH_BASE_KHX flag.
created with the ename:VK_PIPELINE_CREATE_DISPATCH_BASE flag.
****
include::../validity/protos/vkCmdDispatchBaseKHX.txt[]
include::../validity/protos/vkCmdDispatchBase.txt[]
--
endif::VK_KHX_device_group[]
endif::VK_VERSION_1_1,VK_KHR_device_group[]

144
doc/specs/vulkan/chapters/drawing.txt
View File

@ -653,12 +653,30 @@ ifdef::VK_IMG_filter_cubic[]
ename:VK_IMAGE_VIEW_TYPE_3D, ename:VK_IMAGE_VIEW_TYPE_CUBE, or
ename:VK_IMAGE_VIEW_TYPE_CUBE_ARRAY
endif::VK_IMG_filter_cubic[]
ifdef::VK_KHX_multiview[]
ifdef::VK_VERSION_1_1,VK_KHR_multiview[]
* [[VUID-vkCmdDraw-maxMultiviewInstanceIndex-00453]]
If the draw is recorded in a render pass instance with multiview
enabled, the maximum instance index must: be less than or equal to
slink:VkPhysicalDeviceMultiviewPropertiesKHX::pname:maxMultiviewInstanceIndex.
endif::VK_KHX_multiview[]
slink:VkPhysicalDeviceMultiviewProperties::pname:maxMultiviewInstanceIndex.
endif::VK_VERSION_1_1,VK_KHR_multiview[]
ifdef::VK_VERSION_1_1[]
* If pname:commandBuffer is an unprotected command buffer, and any
pipeline stage in the sname:VkPipeline object currently bound to
ename:VK_PIPELINE_BIND_POINT_GRAPHICS reads from or writes to any image
or buffer, that image or buffer must: not be a protected image or
protected buffer.
* If pname:commandBuffer is a protected command buffer, and any pipeline
stage in the sname:VkPipeline object currently bound to
ename:VK_PIPELINE_BIND_POINT_GRAPHICS writes to any image or buffer,
that image or buffer must: not be an unprotected image or unprotected
buffer.
* If pname:commandBuffer is a protected command buffer, and any pipeline
stage other than the framebuffer-space pipeline stages in the
sname:VkPipeline object currently bound to
ename:VK_PIPELINE_BIND_POINT_GRAPHICS reads from or writes to any image
or buffer, the image or buffer must: not be a protected image or
protected buffer.
endif::VK_VERSION_1_1[]
ifdef::VK_EXT_sample_locations[]
* [[VUID-vkCmdDraw-sampleLocationsEnable-01512]]
If the currently bound graphics pipeline was created with
@ -832,12 +850,30 @@ ifdef::VK_IMG_filter_cubic[]
ename:VK_IMAGE_VIEW_TYPE_3D, ename:VK_IMAGE_VIEW_TYPE_CUBE, or
ename:VK_IMAGE_VIEW_TYPE_CUBE_ARRAY
endif::VK_IMG_filter_cubic[]
ifdef::VK_KHX_multiview[]
ifdef::VK_VERSION_1_1,VK_KHR_multiview[]
* [[VUID-vkCmdDrawIndexed-maxMultiviewInstanceIndex-00473]]
If the draw is recorded in a render pass instance with multiview
enabled, the maximum instance index must: be less than or equal to
slink:VkPhysicalDeviceMultiviewPropertiesKHX::pname:maxMultiviewInstanceIndex.
endif::VK_KHX_multiview[]
slink:VkPhysicalDeviceMultiviewProperties::pname:maxMultiviewInstanceIndex.
endif::VK_VERSION_1_1,VK_KHR_multiview[]
ifdef::VK_VERSION_1_1[]
* If pname:commandBuffer is an unprotected command buffer, and any
pipeline stage in the sname:VkPipeline object currently bound to
ename:VK_PIPELINE_BIND_POINT_GRAPHICS reads from or writes to any image
or buffer, that image or buffer must: not be a protected image or
protected buffer.
* If pname:commandBuffer is a protected command buffer, and any pipeline
stage in the sname:VkPipeline object currently bound to
ename:VK_PIPELINE_BIND_POINT_GRAPHICS writes to any image or buffer,
that image or buffer must: not be an unprotected image or unprotected
buffer.
* If pname:commandBuffer is a protected command buffer, and any pipeline
stage other than the framebuffer-space pipeline stages in the
sname:VkPipeline object currently bound to
ename:VK_PIPELINE_BIND_POINT_GRAPHICS reads from or writes to any image
or buffer, the image or buffer must: not be a protected image or
protected buffer.
endif::VK_VERSION_1_1[]
ifdef::VK_EXT_sample_locations[]
* [[VUID-vkCmdDrawIndexed-sampleLocationsEnable-01513]]
If the currently bound graphics pipeline was created with
@ -1020,12 +1056,30 @@ ifdef::VK_IMG_filter_cubic[]
ename:VK_IMAGE_VIEW_TYPE_3D, ename:VK_IMAGE_VIEW_TYPE_CUBE, or
ename:VK_IMAGE_VIEW_TYPE_CUBE_ARRAY
endif::VK_IMG_filter_cubic[]
ifdef::VK_KHX_multiview[]
ifdef::VK_VERSION_1_1,VK_KHR_multiview[]
* [[VUID-vkCmdDrawIndirect-maxMultiviewInstanceIndex-00499]]
If the draw is recorded in a render pass instance with multiview
enabled, the maximum instance index must: be less than or equal to
slink:VkPhysicalDeviceMultiviewPropertiesKHX::pname:maxMultiviewInstanceIndex.
endif::VK_KHX_multiview[]
slink:VkPhysicalDeviceMultiviewProperties::pname:maxMultiviewInstanceIndex.
endif::VK_VERSION_1_1,VK_KHR_multiview[]
ifdef::VK_VERSION_1_1[]
* If pname:commandBuffer is an unprotected command buffer, and any
pipeline stage in the sname:VkPipeline object currently bound to
ename:VK_PIPELINE_BIND_POINT_GRAPHICS reads from or writes to any image
or buffer, that image or buffer must: not be a protected image or
protected buffer.
* If pname:commandBuffer is a protected command buffer, and any pipeline
stage in the sname:VkPipeline object currently bound to
ename:VK_PIPELINE_BIND_POINT_GRAPHICS writes to any image or buffer,
that image or buffer must: not be an unprotected image or unprotected
buffer.
* If pname:commandBuffer is a protected command buffer, and any pipeline
stage other than the framebuffer-space pipeline stages in the
sname:VkPipeline object currently bound to
ename:VK_PIPELINE_BIND_POINT_GRAPHICS reads from or writes to any image
or buffer, the image or buffer must: not be a protected image or
protected buffer.
endif::VK_VERSION_1_1[]
ifdef::VK_EXT_sample_locations[]
* [[VUID-vkCmdDrawIndirect-sampleLocationsEnable-01514]]
If the currently bound graphics pipeline was created with
@ -1237,12 +1291,30 @@ located at pname:countBufferOffset and use this as the draw count.
* [[VUID-vkCmdDrawIndirectCountAMD-None-01502]]
Image subresources used as attachments in the current render pass must:
not be accessed in any way other than as an attachment by this command.
ifdef::VK_KHX_multiview[]
ifdef::VK_VERSION_1_1,VK_KHR_multiview[]
* [[VUID-vkCmdDrawIndirectCountAMD-maxMultiviewInstanceIndex-00525]]
If the draw is recorded in a render pass instance with multiview
enabled, the maximum instance index must: be less than or equal to
slink:VkPhysicalDeviceMultiviewPropertiesKHX::pname:maxMultiviewInstanceIndex.
endif::VK_KHX_multiview[]
slink:VkPhysicalDeviceMultiviewProperties::pname:maxMultiviewInstanceIndex.
endif::VK_VERSION_1_1,VK_KHR_multiview[]
ifdef::VK_VERSION_1_1[]
* If pname:commandBuffer is an unprotected command buffer, and any
pipeline stage in the sname:VkPipeline object currently bound to
ename:VK_PIPELINE_BIND_POINT_GRAPHICS reads from or writes to any image
or buffer, that image or buffer must: not be a protected image or
protected buffer.
* If pname:commandBuffer is a protected command buffer, and any pipeline
stage in the sname:VkPipeline object currently bound to
ename:VK_PIPELINE_BIND_POINT_GRAPHICS writes to any image or buffer,
that image or buffer must: not be an unprotected image or unprotected
buffer.
* If pname:commandBuffer is a protected command buffer, and any pipeline
stage other than the framebuffer-space pipeline stages in the
sname:VkPipeline object currently bound to
ename:VK_PIPELINE_BIND_POINT_GRAPHICS reads from or writes to any image
or buffer, the image or buffer must: not be a protected image or
protected buffer.
endif::VK_VERSION_1_1[]
ifdef::VK_EXT_sample_locations[]
* [[VUID-vkCmdDrawIndirectCountAMD-sampleLocationsEnable-01515]]
If the currently bound graphics pipeline was created with
@ -1428,12 +1500,30 @@ ifdef::VK_IMG_filter_cubic[]
ename:VK_IMAGE_VIEW_TYPE_3D, ename:VK_IMAGE_VIEW_TYPE_CUBE, or
ename:VK_IMAGE_VIEW_TYPE_CUBE_ARRAY
endif::VK_IMG_filter_cubic[]
ifdef::VK_KHX_multiview[]
ifdef::VK_VERSION_1_1,VK_KHR_multiview[]
* [[VUID-vkCmdDrawIndexedIndirect-maxMultiviewInstanceIndex-00551]]
If the draw is recorded in a render pass instance with multiview
enabled, the maximum instance index must: be less than or equal to
slink:VkPhysicalDeviceMultiviewPropertiesKHX::pname:maxMultiviewInstanceIndex.
endif::VK_KHX_multiview[]
slink:VkPhysicalDeviceMultiviewProperties::pname:maxMultiviewInstanceIndex.
endif::VK_VERSION_1_1,VK_KHR_multiview[]
ifdef::VK_VERSION_1_1[]
* If pname:commandBuffer is an unprotected command buffer, and any
pipeline stage in the sname:VkPipeline object currently bound to
ename:VK_PIPELINE_BIND_POINT_GRAPHICS reads from or writes to any image
or buffer, that image or buffer must: not be a protected image or
protected buffer.
* If pname:commandBuffer is a protected command buffer, and any pipeline
stage in the sname:VkPipeline object currently bound to
ename:VK_PIPELINE_BIND_POINT_GRAPHICS writes to any image or buffer,
that image or buffer must: not be an unprotected image or unprotected
buffer.
* If pname:commandBuffer is a protected command buffer, and any pipeline
stage other than the framebuffer-space pipeline stages in the
sname:VkPipeline object currently bound to
ename:VK_PIPELINE_BIND_POINT_GRAPHICS reads from or writes to any image
or buffer, the image or buffer must: not be a protected image or
protected buffer.
endif::VK_VERSION_1_1[]
ifdef::VK_EXT_sample_locations[]
* [[VUID-vkCmdDrawIndexedIndirect-sampleLocationsEnable-01516]]
If the currently bound graphics pipeline was created with
@ -1654,12 +1744,30 @@ located at pname:countBufferOffset and use this as the draw count.
* [[VUID-vkCmdDrawIndexedIndirectCountAMD-None-01504]]
Image subresources used as attachments in the current render pass must:
not be accessed in any way other than as an attachment by this command.
ifdef::VK_KHX_multiview[]
ifdef::VK_VERSION_1_1,VK_KHR_multiview[]
* [[VUID-vkCmdDrawIndexedIndirectCountAMD-maxMultiviewInstanceIndex-00578]]
If the draw is recorded in a render pass instance with multiview
enabled, the maximum instance index must: be less than or equal to
slink:VkPhysicalDeviceMultiviewPropertiesKHX::pname:maxMultiviewInstanceIndex.
endif::VK_KHX_multiview[]
slink:VkPhysicalDeviceMultiviewProperties::pname:maxMultiviewInstanceIndex.
endif::VK_VERSION_1_1,VK_KHR_multiview[]
ifdef::VK_VERSION_1_1[]
* If pname:commandBuffer is an unprotected command buffer, and any
pipeline stage in the sname:VkPipeline object currently bound to
ename:VK_PIPELINE_BIND_POINT_GRAPHICS reads from or writes to any image
or buffer, that image or buffer must: not be a protected image or
protected buffer.
* If pname:commandBuffer is a protected command buffer, and any pipeline
stage in the sname:VkPipeline object currently bound to
ename:VK_PIPELINE_BIND_POINT_GRAPHICS writes to any image or buffer,
that image or buffer must: not be an unprotected image or unprotected
buffer.
* If pname:commandBuffer is a protected command buffer, and any pipeline
stage other than the framebuffer-space pipeline stages in the
sname:VkPipeline object currently bound to
ename:VK_PIPELINE_BIND_POINT_GRAPHICS reads from or writes to any image
or buffer, the image or buffer must: not be a protected image or
protected buffer.
endif::VK_VERSION_1_1[]
ifdef::VK_EXT_sample_locations[]
* [[VUID-vkCmdDrawIndexedIndirectCountAMD-sampleLocationsEnable-01517]]
If the currently bound graphics pipeline was created with

46
doc/specs/vulkan/chapters/extensions.txt
View File

@ -19,15 +19,20 @@ and any of its child objects, while device extensions may: only be available
on a subset of physical devices, must: be individually enabled per-device,
and only affect the operation of the devices where they are enabled.
[NOTE]
.Note
====
Examples of these might be:
* Whole API validation is an example of a layer.
* Debug capabilities might make a good instance extension.
* A layer that provides hardware-specific performance telemetry and
* A layer that provides implementation-specific performance telemetry and
analysis could be a layer that is only active for devices created from
compatible physical devices.
* Functions to allow an application to use additional hardware features
beyond the core would be a good candidate for a device extension.
* Functions to allow an application to use additional implementation
features beyond the core would be a good candidate for a device
extension.
====
[[extended-functionality-layers]]
== Layers
@ -203,8 +208,8 @@ layers enabled when the parent instance was created.
Extensions may: define new Vulkan commands, structures, and enumerants.
For compilation purposes, the interfaces defined by registered extensions,
including new structures and enumerants as well as function pointer types
for new commands, are defined in the Khronos-supplied +vulkan.h+ together
with the core API.
for new commands, are defined in the Khronos-supplied `vulkan_core.h`
together with the core API.
However, commands defined by extensions may: not be available for static
linking - in which case function pointers to these commands should: be
queried at runtime as described in <<initialization-functionpointers>>.
@ -320,34 +325,19 @@ it extends instance-level or device-level functionality.
All Vulkan commands, structures, and enumerants are considered either
instance-level, physical-device-level, or device-level.
Commands that are dispatched from instances (sname:VkInstance) are
considered instance-level commands.
Any structure, enumerated type, and enumerant that is used with
instance-level commands are considered instance-level objects.
New instance-level extension functionality must: be structured within an
instance extension.
Any command or object that must: be used after calling flink:vkCreateDevice
is a device-level command or object.
These objects include all children of sname:VkDevice objects, such as queues
(sname:VkQueue) and command buffers (sname:VkCommandBuffer).
New device-level extension functionality may: be structured within a device
extension.
Commands that are dispatched from physical devices (sname:VkPhysicalDevice)
are considered physical-device-level commands.
Any structure, enumerated type, and enumerant that is used with
physical-device-level commands, and not used with instance-level commands,
are considered physical-device-level objects.
Vulkan 1.0 requires all new physical-device-level extension functionality to
be structured within an instance extension.
ifdef::VK_KHR_get_physical_device_properties2[]
Vulkan 1.0 initially required all new physical-device-level extension
functionality to be structured within an instance extension.
ifdef::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[]
In order to avoid using an instance extension, which often requires loader
support, the `<<VK_KHR_get_physical_device_properties2>>` extension allows
physical-device-level extension functionality to be implemented within
device extensions (which must: depend on the
`<<VK_KHR_get_physical_device_properties2>>` extension).
endif::VK_KHR_get_physical_device_properties2[]
support, physical-device-level extension functionality may: be implemented
within device extensions (which must: depend on the
`<<VK_KHR_get_physical_device_properties2>>` extension, or on Vulkan 1.1 or
later).
endif::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[]
[[extended-functionality-extensions-dependencies]]

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

File diff suppressed because it is too large Load Diff

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

@ -302,8 +302,9 @@ Blend factors that use the secondary color input
[eq]#(R~s1~,G~s1~,B~s1~,A~s1~)# (ename:VK_BLEND_FACTOR_SRC1_COLOR,
ename:VK_BLEND_FACTOR_ONE_MINUS_SRC1_COLOR,
ename:VK_BLEND_FACTOR_SRC1_ALPHA, and
ename:VK_BLEND_FACTOR_ONE_MINUS_SRC1_ALPHA) may: consume hardware resources
that could otherwise be used for rendering to multiple color attachments.
ename:VK_BLEND_FACTOR_ONE_MINUS_SRC1_ALPHA) may: consume implementation
resources that could otherwise be used for rendering to multiple color
attachments.
Therefore, the number of color attachments that can: be used in a
framebuffer may: be lower when using dual-source blending.

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

@ -13,28 +13,29 @@ It provides a framework for interpreting more specific descriptions of
commands and behavior in the remainder of the Specification.
[[fundamentals-architecture-model]]
== Architecture Model
[[fundamentals-host-environment]]
== Host and Device Environment
Vulkan is designed for, and the API is written for, CPU, GPU, and other
hardware accelerator architectures with the following properties:
The Vulkan Specification assumes and requires: the following properties of
the host environment with respect to Vulkan implementations:
* Runtime support for 8, 16, 32 and 64-bit signed and unsigned
twos-complement integers, all addressable at the granularity of their
size in bytes.
* Runtime support for 32- and 64-bit floating-point types satisfying the
range and precision constraints in the
* The host must: have runtime support for 8, 16, 32 and 64-bit signed and
unsigned twos-complement integers, all addressable at the granularity of
their size in bytes.
* The host must: have runtime support for 32- and 64-bit floating-point
types satisfying the range and precision constraints in the
<<fundamentals-floatingpoint,Floating Point Computation>> section.
* The representation and endianness of these types must: be identical for
the host and the physical devices.
* The representation and endianness of these types on the host must: match
the representation and endianness of the same types on every physical
device supported.
[NOTE]
.Note
====
Since a variety of data types and structures in Vulkan may: be mapped back
and forth between host and physical device memory, host and device
architectures must: both be able to access such data efficiently in order to
write portable and performant applications.
Since a variety of data types and structures in Vulkan may: be accessible by
both host and physical device operations, the implementation should: be able
to access such data efficiently in both paths in order to facilitate writing
portable and performant applications.
====
[[fundamentals-execmodel]]
@ -50,7 +51,7 @@ multiple queues with similar characteristics.
Queues within a single family are considered _compatible_ with one another,
and work produced for a family of queues can: be executed on any queue
within that family.
This specification defines four types of functionality that queues may:
This Specification defines four types of functionality that queues may:
support: graphics, compute, transfer, and sparse memory management.
[NOTE]
@ -84,8 +85,8 @@ for any purpose.
A Vulkan application controls a set of devices through the submission of
command buffers which have recorded device commands issued via Vulkan
library calls.
The content of command buffers is specific to the underlying hardware and is
opaque to the application.
The content of command buffers is specific to the underlying implementation
and is opaque to the application.
Once constructed, a command buffer can: be submitted once or many times to a
queue for execution.
Multiple command buffers can: be built in parallel by employing multiple
@ -232,7 +233,7 @@ its lifetime.
_Non-dispatchable_ handle types are a 64-bit integer type whose meaning is
implementation-dependent, and may: encode object information directly in the
handle rather than pointing to a software structure.
handle rather than acting as a reference to an underlying object.
Objects of a non-dispatchable type may: not have unique handle values within
a type or across types.
If handle values are not unique, then destroying one such handle must: not
@ -299,13 +300,15 @@ sname:VkDescriptorSetLayout objects may: be accessed by commands that
operate on descriptor sets allocated using that layout, and those descriptor
sets must: not be updated with flink:vkUpdateDescriptorSets after the
descriptor set layout has been destroyed.
Otherwise, descriptor set layouts can: be destroyed any time they are not in
use by an API command.
Otherwise, a sname:VkDescriptorSetLayout object passed as a parameter to
create another object is not further accessed by that object after the
duration of the command it is passed into.
The application must: not destroy any other type of Vulkan object until all
uses of that object by the device (such as via command buffer execution)
have completed.
[[fundamentals-objectmodel-lifetime-cmdbuffers]]
The following Vulkan objects must: not be destroyed while any command
buffers using the object are in the <<commandbuffers-lifecycle, pending
state>>:
@ -318,9 +321,9 @@ state>>:
* sname:VkImageView
* sname:VkPipeline
* sname:VkSampler
ifdef::VK_KHR_sampler_ycbcr_conversion[]
* basetype:VkSamplerYcbcrConversionKHR
endif::VK_KHR_sampler_ycbcr_conversion[]
ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
* basetype:VkSamplerYcbcrConversion
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
* sname:VkDescriptorPool
* sname:VkFramebuffer
* sname:VkRenderPass
@ -394,9 +397,9 @@ be destroyed:
** sname:VkPipeline
** sname:VkPipelineLayout
** sname:VkSampler
ifdef::VK_KHR_sampler_ycbcr_conversion[]
** basetype:VkSamplerYcbcrConversionKHR
endif::VK_KHR_sampler_ycbcr_conversion[]
ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
** basetype:VkSamplerYcbcrConversion
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
** sname:VkDescriptorSetLayout
** sname:VkDescriptorPool
** sname:VkFramebuffer
@ -415,7 +418,7 @@ endif::VK_EXT_validation_cache[]
destroyed.
ifdef::VK_KHR_external_memory_capabilities,VK_KHR_external_semaphore_capabilities,VK_KHR_external_fence_capabilities[]
ifdef::VK_VERSION_1_1,VK_KHR_external_memory_capabilities,VK_KHR_external_semaphore_capabilities,VK_KHR_external_fence_capabilities[]
[[fundamentals-objectmodel-external]]
=== External Object Handles
@ -432,7 +435,7 @@ The scope of external handles and their associated resources may: vary
according to their type, but they can: generally be shared across process
and API boundaries.
====
endif::VK_KHR_external_memory_capabilities,VK_KHR_external_semaphore_capabilities,VK_KHR_external_fence_capabilities[]
endif::VK_VERSION_1_1,VK_KHR_external_memory_capabilities,VK_KHR_external_semaphore_capabilities,VK_KHR_external_fence_capabilities[]
[[fundamentals-abi]]
@ -455,7 +458,7 @@ types; the procedure calling convention; and the naming convention for
shared library symbols corresponding to C functions.
Customizing the calling convention for a platform is usually accomplished by
defining <<boilerplate-platform-specific-calling-conventions,calling
convention macros>> appropriately in +vk_platform.h+.
convention macros>> appropriately in `vk_platform.h`.
On platforms where Vulkan is provided as a shared library, library symbols
beginning with "`vk`" and followed by a digit or uppercase letter are
@ -483,6 +486,12 @@ libraries between platforms.
Platform vendors, or providers of the _de facto_ standard Vulkan shared
library for a platform, are encouraged to document what symbols the shared
library provides and how it will be versioned when new symbols are added.
Applications should: only rely on shared library symbols for commands in the
minimum core version required by the application.
flink:vkGetInstanceProcAddr and flink:vkGetDeviceProcAddr should: be used to
obtain function pointers for commands in core versions beyond the
application's minimum required version.
====
@ -495,8 +504,8 @@ Language bindings for other languages such as C++ and JavaScript may: allow
for stricter parameter passing, or object-oriented interfaces.
Vulkan uses the standard C types for the base type of scalar parameters
(e.g. types from +stdint.h+), with exceptions described below, or elsewhere
in the text when appropriate:
(e.g. types from `<stdint.h>`), with exceptions described below, or
elsewhere in the text when appropriate:
[open,refpage='VkBool32',desc='Vulkan boolean type',type='basetypes']
--
@ -581,10 +590,10 @@ _externally synchronized_.
This means that the caller must: guarantee that no more than one thread is
using such a parameter at a given time.
More precisely, Vulkan commands use simple stores to update software
structures representing Vulkan objects.
A parameter declared as externally synchronized may: have its software
structures updated at any time during the host execution of the command.
More precisely, Vulkan commands use simple stores to update the state of
Vulkan objects.
A parameter declared as externally synchronized may: have its contents
updated at any time during the host execution of the command.
If two commands operate on the same object and at least one of the commands
declares the object to be externally synchronized, then the caller must:
guarantee not only that the commands do not execute simultaneously, but also
@ -594,9 +603,9 @@ needed).
[NOTE]
.Note
====
Memory barriers are particularly relevant on the ARM CPU architecture which
is more weakly ordered than many developers are accustomed to from x86/x64
programming.
Memory barriers are particularly relevant for hosts based on the ARM CPU
architecture, which is more weakly ordered than many developers are
accustomed to from x86/x64 programming.
Fortunately, most higher-level synchronization primitives (like the pthread
library) perform memory barriers as a part of mutual exclusion, so mutexing
Vulkan objects via these primitives will have the desired effect.
@ -610,14 +619,14 @@ While the ownership of application-owned memory remains acquired by a
command the implementation may: read the memory at any point, and it may:
write non-code:const qualified memory at any point.
Parameters referring to non-code:const qualified application-owned memory
are not marked explicitly as _externally synchronized_ in the specification.
are not marked explicitly as _externally synchronized_ in the Specification.
Many object types are _immutable_, meaning the objects cannot: change once
they have been created.
These types of objects never need external synchronization, except that they
must: not be destroyed while they are in use on another thread.
In certain special cases, mutable object parameters are internally
synchronized such that they do not require external synchronization.
In certain special cases mutable object parameters are internally
synchronized, making external synchronization unnecessary.
One example of this is the use of a sname:VkPipelineCache in
fname:vkCreateGraphicsPipelines and fname:vkCreateComputePipelines, where
external synchronization around such a heavyweight command would be
@ -764,15 +773,15 @@ An object handle is valid if:
* It has been created or allocated by a previous, successful call to the
API.
Such calls are noted in the specification.
Such calls are noted in the Specification.
* It has not been deleted or freed by a previous call to the API.
Such calls are noted in the specification.
Such calls are noted in the Specification.
* Any objects used by that object, either as part of creation or
execution, must: also be valid.
The reserved values dlink:VK_NULL_HANDLE and `NULL` can: be used in place of
valid non-dispatchable handles and dispatchable handles, respectively, when
_explicitly called out in the specification_.
_explicitly called out in the Specification_.
Any command that creates an object successfully must: not return these
values.
It is valid to pass these values to ftext:vkDestroy* or ftext:vkFree*
@ -795,7 +804,7 @@ a structure) satisfy the alignment requirements of the host processor.
Any parameter that is a pointer to `char` must: be a finite sequence of
values terminated by a null character, or if _explicitly called out in the
specification_, can: be `NULL`.
Specification_, can: be `NULL`.
[[fundamentals-validusage-enums]]
@ -902,7 +911,7 @@ its pname:sType member must: equal that when it is passed to the API.
The values ename:VK_STRUCTURE_TYPE_LOADER_INSTANCE_CREATE_INFO and
ename:VK_STRUCTURE_TYPE_LOADER_DEVICE_CREATE_INFO are reserved for internal
use by the loader, and do not have corresponding Vulkan structures in this
specification.
Specification.
--
@ -928,8 +937,8 @@ drivers) must: skip over, without processing (other than reading the
pname:sType and pname:pNext members) any structures in the chain with
pname:sType values not defined by extensions supported by that component.
Extension structures are not described in the base Vulkan specification, but
either in layered specifications incorporating those extensions, or in
Extension structures are not described in the base Vulkan Specification, but
either in layered Specifications incorporating those extensions, or in
separate vendor-provided documents.
@ -944,6 +953,48 @@ Specifics on valid usage of each command are covered in their individual
sections.
[[fundamentals-validusage-extensions]]
==== Valid Usage for Extensions
Instance-level functionality or behavior added by an <<extensions, instance
extension>> to the API must: not be used unless that extension is supported
by the instance as determined by
flink:vkEnumerateInstanceExtensionProperties, and that extension is enabled
in slink:VkInstanceCreateInfo.
Physical-device-level functionality or behavior added by an <<extensions,
instance extension>> to the API must: not be used unless that extension is
supported by the instance as determined by
flink:vkEnumerateInstanceExtensionProperties, and that extension is enabled
in slink:VkInstanceCreateInfo.
Physical-device-level functionality or behavior added by a <<extensions,
device extension>> to the API must: not be used unless the conditions
described in <<initialization-phys-dev-extensions, Extending Physical Device
Core Functionality>> are met.
Device functionality or behavior added by a <<extensions, device extension>>
to the API must: not be used unless that extension is supported by the
device as determined by flink:vkEnumerateDeviceExtensionProperties, and that
extension is enabled in slink:VkDeviceCreateInfo.
[[fundamentals-validusage-versions]]
==== Valid Usage for Newer Core Versions
Instance-level functionality or behavior added by a <<versions, new core
version>> of the API must: not be used unless it is supported by the
instance as determined by flink:vkEnumerateInstanceVersion.
Physical-device-level functionality or behavior added by a <<versions, new
core version>> of the API must: not be used unless it is supported by the
physical device as determined by flink:vkGetPhysicalDeviceProperties.
Device-level functionality or behavior added by a <<versions, new core
version>> of the API must: not be used unless it is supported by the device
as determined by flink:vkGetPhysicalDeviceProperties.
[[fundamentals-returncodes]]
=== Return Codes
@ -1008,11 +1059,11 @@ endif::VK_KHR_swapchain[]
fragmentation of the pool's memory.
This must: only be returned if no attempt to allocate host or device
memory was made to accomodate the new allocation.
ifdef::VK_KHR_maintenance1[]
ifdef::VK_VERSION_1_1,VK_KHR_maintenance1[]
This should: be returned in preference to
ename:VK_ERROR_OUT_OF_POOL_MEMORY_KHR, but only if the implementation is
ename:VK_ERROR_OUT_OF_POOL_MEMORY, but only if the implementation is
certain that the pool allocation failure was due to fragmentation.
endif::VK_KHR_maintenance1[]
endif::VK_VERSION_1_1,VK_KHR_maintenance1[]
ifdef::VK_KHR_surface[]
* ename:VK_ERROR_SURFACE_LOST_KHR A surface is no longer available.
* ename:VK_ERROR_NATIVE_WINDOW_IN_USE_KHR The requested window is already
@ -1037,18 +1088,17 @@ ifdef::VK_NV_glsl_shader[]
More details are reported back to the application via
`<<VK_EXT_debug_report>>` if enabled.
endif::VK_NV_glsl_shader[]
ifdef::VK_KHR_maintenance1[]
* ename:VK_ERROR_OUT_OF_POOL_MEMORY_KHR A pool memory allocation has
failed.
ifdef::VK_VERSION_1_1,VK_KHR_maintenance1[]
* ename:VK_ERROR_OUT_OF_POOL_MEMORY A pool memory allocation has failed.
This must: only be returned if no attempt to allocate host or device
memory was made to accomodate the new allocation.
If the failure was definitely due to fragmentation of the pool,
ename:VK_ERROR_FRAGMENTED_POOL should: be returned instead.
endif::VK_KHR_maintenance1[]
ifdef::VK_KHR_external_memory,VK_KHR_external_semaphore,VK_KHR_external_fence[]
* ename:VK_ERROR_INVALID_EXTERNAL_HANDLE_KHR An external handle is not a
valid handle of the specified type.
endif::VK_KHR_external_memory,VK_KHR_external_semaphore,VK_KHR_external_fence[]
endif::VK_VERSION_1_1,VK_KHR_maintenance1[]
ifdef::VK_VERSION_1_1,VK_KHR_external_memory,VK_KHR_external_semaphore,VK_KHR_external_fence[]
* ename:VK_ERROR_INVALID_EXTERNAL_HANDLE An external handle is not a valid
handle of the specified type.
endif::VK_VERSION_1_1,VK_KHR_external_memory,VK_KHR_external_semaphore,VK_KHR_external_fence[]
If a command returns a run time error, unless otherwise specified any output
parameters will have undefined contents, except that if the output parameter
@ -1342,7 +1392,7 @@ API in some way, with each part of the version number indicating a different
scope of changes.
A difference in patch version numbers indicates that some usually small part
of the specification or header has been modified, typically to fix a bug,
of the Specification or header has been modified, typically to fix a bug,
and may: have an impact on the behavior of existing functionality.
Differences in this version number should: not affect either _full
compatibility_ or _backwards compatibility_ between two versions, or add
@ -1354,10 +1404,14 @@ This will usually include new interfaces in the header, and may: also
include behavior changes and bug fixes.
Functionality may: be deprecated in a minor revision, but will not be
removed.
When a new minor version is introduced, the patch version is reset to 0, and
each minor revision maintains its own set of patch versions.
Differences in this version should: not affect backwards compatibility, but
will affect full compatibility.
The patch version will continue to increment through minor version number
changes since all minor versions are generated from the same source files,
and changes to the source files may affect all minor versions within a major
version.
Differences in the patch version should: not affect backwards compatibility,
but will affect full compatibility.
The patch version of the Specification is taken from
dlink:VK_HEADER_VERSION.
A difference in major version numbers indicates a large set of changes to
the API, potentially including new functionality and header interfaces,

82
doc/specs/vulkan/chapters/fxvertex.txt
View File

@ -5,11 +5,8 @@
[[fxvertex]]
= Fixed-Function Vertex Processing
Some implementations have specialized fixed-function hardware for fetching
and format-converting vertex input data from buffers, rather than performing
the fetch as part of the vertex shader.
Vulkan includes a vertex attribute fetch stage in the graphics pipeline in
order to take advantage of this.
Vertex fetching is controlled via configurable state, as a logically
distinct graphics pipeline stage.
[[fxvertex-attrib]]
@ -456,6 +453,66 @@ commands.
include::../validity/protos/vkCmdBindVertexBuffers.txt[]
--
ifdef::VK_EXT_vertex_attribute_divisor[]
== Vertex Attribute Divisor in Instanced Rendering
If the pname:pNext chain of slink:VkPipelineVertexInputStateCreateInfo
includes a sname:VkPipelineVertexInputDivisorStateCreateInfoEXT structure, then
that structure controls how vertex attributes are assigned to an instance
when instanced rendering is enabled.
The sname:VkPipelineVertexInputDivisorStateCreateInfoEXT structure is defined
as:
include::../api/structs/VkPipelineVertexInputDivisorStateCreateInfoEXT.txt[]
* pname:sType is the type of this structure
* pname:pNext is `NULL` or a pointer to an extension-specific structure
* pname:vertexBindingDivisorCount is the number of elements in the
pname:pVertexBindingDivisors array.
* pname:pVertexBindingDivisors is a pointer to an array of
sname:VkVertexInputBindingDivisorDescriptionEXT structures, which specifies the
divisor value for each binding.
include::../validity/structs/VkPipelineVertexInputDivisorStateCreateInfoEXT.txt[]
--
The individual divisor values per binding are specified using the
sname:VkVertexInputBindingDivisorDescriptionEXT structure which is defined as:
include::../api/structs/VkVertexInputBindingDivisorDescriptionEXT.txt[]
* pname:binding is the binding number for which the divisor is specified.
* pname:divisor is the the number of successive instances that will use the
same value of the vertex attribute when instanced rendering is enabled.
For example, if the divisor is N, the same vertex attribute will applied to N
successive instances before moving on to the next vertex attribute.
If a value of 0 is used for the divisor, then the first vertex attribute
will be applied to all instances.
The maximum value of divisor is implementation dependent and can be queried
using sname:VkPhysicalDeviceVertexAttributeDivisorPropertiesEXT::pname:maxVertexAttribDivisor.
.Valid Usage
****
* pname:binding must: be less than
sname:VkPhysicalDeviceLimits::pname:maxVertexInputBindings
* pname:divisor must: be a value between `0` and
sname:VkPhysicalDeviceVertexAttributeDivisorPropertiesEXT::pname:maxVertexAttribDivisor,
inclusive.
* slink:VkVertexInputBindingDescription::pname:inputRate must: be of type
ename:VK_VERTEX_INPUT_RATE_INSTANCE for this pname:binding.
****
include::../validity/structs/VkVertexInputBindingDivisorDescriptionEXT.txt[]
--
If this structure is not used to define a divisor value for an attribute then
the divisor has a logical default value of 1.
endif::VK_EXT_vertex_attribute_divisor[]
The address of each attribute for each code:vertexIndex and
code:instanceIndex is calculated as follows:
@ -473,6 +530,12 @@ code:instanceIndex is calculated as follows:
fname:vkCmdDrawIndexed), and let code:instanceIndex be the instance
number of the draw (a value between pname:firstInstance and
pname:firstInstance+pname:instanceCount).
ifdef::VK_EXT_vertex_attribute_divisor[]
* Let code:divisor be the member of
sname:VkPipelineVertexInputDivisorStateCreateInfoEXT::pname:pVertexBindingDivisors
with sname:VkVertexInputBindingDivisorDescriptionEXT::pname:binding equal to
code:attribDesc.binding.
endif::VK_EXT_vertex_attribute_divisor[]
[source,c]
---------------------------------------------------
@ -481,7 +544,15 @@ bufferBindingAddress = buffer[binding].baseAddress + offset[binding];
if (bindingDesc.inputRate == VK_VERTEX_INPUT_RATE_VERTEX)
vertexOffset = vertexIndex * bindingDesc.stride;
else
ifndef::VK_EXT_vertex_attribute_divisor[]
vertexOffset = instanceIndex * bindingDesc.stride;
endif::VK_EXT_vertex_attribute_divisor[]
ifdef::VK_EXT_vertex_attribute_divisor[]
if (divisor == 0)
vertexOffset = 0;
else
vertexOffset = (instanceIndex / divisor) * bindingDesc.stride;
endif::VK_EXT_vertex_attribute_divisor[]
attribAddress = bufferBindingAddress + vertexOffset + attribDesc.offset;
---------------------------------------------------
@ -505,7 +576,6 @@ exactly match the number of components in the format.
If the vertex shader has fewer components, the extra components are
discarded.
[[fxvertex-example]]
== Example

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

@ -8,6 +8,7 @@
Before using Vulkan, an application must: initialize it by loading the
Vulkan commands, and creating a sname:VkInstance object.
[[initialization-functionpointers]]
== Command Function Pointers
@ -42,6 +43,9 @@ be cast to the type of the command being queried.
| pname:instance | pname:pName | return value
| * | `NULL` | undefined
| invalid instance | * | undefined
ifdef::VK_VERSION_1_1[]
| `NULL` | flink:vkEnumerateInstanceVersion | fp
endif::VK_VERSION_1_1[]
| `NULL` | flink:vkEnumerateInstanceExtensionProperties | fp
| `NULL` | flink:vkEnumerateInstanceLayerProperties | fp
| `NULL` | flink:vkCreateInstance | fp
@ -55,7 +59,8 @@ be cast to the type of the command being queried.
1::
The returned function pointer must: only be called with a dispatchable
object (the first parameter) that is pname:instance or a child of
pname:instance.
pname:instance, e.g. slink:VkInstance, slink:VkPhysicalDevice,
slink:VkDevice, slink:VkQueue, or slink:VkCommandBuffer.
2::
An "`available device extension`" is a device extension supported by any
@ -67,14 +72,13 @@ include::../validity/protos/vkGetInstanceProcAddr.txt[]
[open,refpage='vkGetDeviceProcAddr',desc='Return a function pointer for a command',type='protos',xrefs='PFN_vkVoidFunction']
--
In order to support systems with multiple Vulkan implementations comprising
heterogeneous collections of hardware and software, the function pointers
returned by fname:vkGetInstanceProcAddr may: point to dispatch code, which
calls a different real implementation for different sname:VkDevice objects
or their child objects.
The overhead of this internal dispatch can: be avoided for commands that
dispatch from device-level objects by calling device-specific function
pointers.
In order to support systems with multiple Vulkan implementations, the
function pointers returned by fname:vkGetInstanceProcAddr may: point to
dispatch code that calls a different real implementation for different
slink:VkDevice objects or their child objects.
The overhead of the internal dispatch for slink:VkDevice objects can be
avoided by obtaining device-specific function pointers for any commands that
use a device or device-child object as their dispatchable object.
Such function pointers can: be obtained with the command:
include::../api/protos/vkGetDeviceProcAddr.txt[]
@ -112,29 +116,48 @@ include::../api/funcpointers/PFN_vkVoidFunction.txt[]
--
ifdef::VK_KHR_get_physical_device_properties2[]
ifdef::VK_VERSION_1_1[]
=== Extending Physical Device Core Functionality
New core physical-device-level functionality can: be used when the
physical-device version is greater than or equal to the version of Vulkan
that added the new functionality.
The Vulkan version supported by a physical device can: be obtained by
calling flink:vkGetPhysicalDeviceProperties.
endif::VK_VERSION_1_1[]
ifdef::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[]
[[initialization-phys-dev-extensions]]
=== Extending Physical Device From Device Extensions
When the `<<VK_KHR_get_physical_device_properties2>>` extension is enabled,
physical device extension commands and structures can: be used with a
physical device if the corresponding extension is enumerated by
ifdef::VK_VERSION_1_1[]
or when both the instance and the physical-device versions are at least 1.1,
endif::VK_VERSION_1_1[]
physical-device-level functionality of a device extension can: be used with
a physical device if the corresponding extension is enumerated by
flink:vkEnumerateDeviceExtensionProperties for that physical device, even
before a logical device has been created.
To obtain a function pointer for a physical-device command from a device
extension, an application can: use fname:vkGetInstanceProcAddr.
To obtain a function pointer for a physical-device-level command from a
device extension, an application can: use flink:vkGetInstanceProcAddr.
This function pointer may: point to dispatch code, which calls a different
real implementation for different sname:VkPhysicalDevice objects.
Behavior is undefined if an extension physical-device command is called on a
physical device that does not support the extension.
Device extensions may: define structures that can: be added to the
ptext:pNext chain of physical-device commands.
Behavior is undefined if such an extension structure is passed to a physical
device command for a physical device that does not support the extension.
ptext:pNext chain of physical-device-level commands.
Behavior is undefined if such an extension structure is passed to a
physical-device-level command for a physical device that does not support
the extension.
endif::VK_KHR_get_physical_device_properties2[]
endif::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[]
[[initialization-instances]]
@ -154,6 +177,27 @@ include::../api/handles/VkInstance.txt[]
--
ifdef::VK_VERSION_1_1[]
[open,refpage='vkEnumerateInstanceVersion',desc='Query instance-level version before instance creation',type='protos']
--
The version of Vulkan that is supported by an instance may: be different
than the version of Vulkan supported by a device or physical device.
To query properties that can: be used in creating an instance, call:
include::../api/protos/vkEnumerateInstanceVersion.txt[]
* pname:pApiVersion points to a code:uint32_t, which is is the version of
Vulkan supported by instance-level functionality, encoded as described
in the <<fundamentals-versionnum,API Version Numbers and Semantics>>
section.
include::../validity/protos/vkEnumerateInstanceVersion.txt[]
--
endif::VK_VERSION_1_1[]
[open,refpage='vkCreateInstance',desc='Create a new Vulkan instance',type='protos']
--
@ -254,6 +298,7 @@ include::../api/structs/VkApplicationInfo.txt[]
* pname:engineVersion is an unsigned integer variable containing the
developer-supplied version number of the engine used to create the
application.
ifndef::VK_VERSION_1_1[]
* pname:apiVersion is the version of the Vulkan API against which the
application expects to run, encoded as described in the
<<fundamentals-versionnum,API Version Numbers and Semantics>> section.
@ -261,11 +306,49 @@ include::../api/structs/VkApplicationInfo.txt[]
if the implementation does not support the requested pname:apiVersion,
or an effective substitute for pname:apiVersion, it must: return
ename:VK_ERROR_INCOMPATIBLE_DRIVER.
endif::VK_VERSION_1_1[]
ifdef::VK_VERSION_1_1[]
* pname:apiVersion must: be the highest version of Vulkan that the
application is designed to use, encoded as described in the
<<fundamentals-versionnum,API Version Numbers and Semantics>> section.
endif::VK_VERSION_1_1[]
The patch version number specified in pname:apiVersion is ignored when
creating an instance object.
Only the major and minor versions of the instance must: match those
requested in pname:apiVersion.
ifdef::VK_VERSION_1_1[]
Vulkan 1.0 implementations were required to return
ename:VK_ERROR_INCOMPATIBLE_DRIVER if pname:apiVersion was larger than 1.0.
Implementations that support Vulkan 1.1 or later must: not return
ename:VK_ERROR_INCOMPATIBLE_DRIVER for any value of pname:apiVersion.
[NOTE]
.Note
====
Because Vulkan 1.0 implementations may: fail with
ename:VK_ERROR_INCOMPATIBLE_DRIVER, applications should: determine the
version of Vulkan available before calling flink:vkCreateInstance.
If the flink:vkGetInstanceProcAddr returns `NULL` for
flink:vkEnumerateInstanceVersion, it is a Vulkan 1.0 implementation.
Otherwise, the application can: call flink:vkEnumerateInstanceVersion to
determine the version of Vulkan.
====
Implicit layers must: be disabled if they do not support a version at least
as high as pname:apiVersion.
See the <<LoaderAndValidationLayers, "Vulkan Loader Specification and
Architecture Overview">> document for additional information.
[NOTE]
.Note
====
Providing a `NULL` sname:VkInstanceCreateInfo::pname:pApplicationInfo or
providing an pname:apiVersion of 0 is equivalent to providing an
pname:apiVersion of VK_MAKE_VERSION(1,0,0).
====
endif::VK_VERSION_1_1[]
include::../validity/structs/VkApplicationInfo.txt[]
--

249
doc/specs/vulkan/chapters/interfaces.txt
View File

@ -84,13 +84,13 @@ interface.
The remaining variables listed by code:OpEntryPoint with the code:Input or
code:Output storage class form the _user-defined variable interface_.
ifdef::VK_KHR_16bit_storage[]
ifdef::VK_VERSION_1_1,VK_KHR_16bit_storage[]
By default such variables have a type with a width of 32 or 64.
If an implementation supports
<<features-features-storageInputOutput16,storageInputOutput16>>,
user-defined variables in the code:Input and code:Output storage classes
can: also have types with a width of 16.
endif::VK_KHR_16bit_storage[]
endif::VK_VERSION_1_1,VK_KHR_16bit_storage[]
These variables must: be identified with a code:Location decoration and can:
also be identified with a code:Component decoration.
@ -149,9 +149,9 @@ corresponding output satisfying all of the following conditions:
* the output is a vector with the same basic type and has at least as many
components as the input, and
* the common component type of the input and output is
ifdef::VK_KHR_16bit_storage[]
ifdef::VK_VERSION_1_1,VK_KHR_16bit_storage[]
16-bit integer or floating-point, or
endif::VK_KHR_16bit_storage[]
endif::VK_VERSION_1_1,VK_KHR_16bit_storage[]
32-bit integer or floating-point (64-bit component types are excluded).
In this case, the components of the input will be taken from the first
@ -175,17 +175,17 @@ The code:Component specifies
<<interfaces-iointerfaces-components,components>> within these vector
locations.
Only types with widths of
ifdef::VK_KHR_16bit_storage[]
ifdef::VK_VERSION_1_1,VK_KHR_16bit_storage[]
16,
endif::VK_KHR_16bit_storage[]
endif::VK_VERSION_1_1,VK_KHR_16bit_storage[]
32 or 64 are supported in shader interfaces.
Inputs and outputs of the following types consume a single interface
location:
ifdef::VK_KHR_16bit_storage[]
ifdef::VK_VERSION_1_1,VK_KHR_16bit_storage[]
* 16-bit scalar and vector types, and
endif::VK_KHR_16bit_storage[]
endif::VK_VERSION_1_1,VK_KHR_16bit_storage[]
* 32-bit scalar and vector types, and
* 64-bit scalar and 2-component vector types.
@ -196,9 +196,9 @@ _m_ locations, it will be assigned _m_ {times} _n_ consecutive locations
starting with the location specified.
If the declared input or output is an _n_ {times} _m_
ifdef::VK_KHR_16bit_storage[]
ifdef::VK_VERSION_1_1,VK_KHR_16bit_storage[]
16-,
endif::VK_KHR_16bit_storage[]
endif::VK_VERSION_1_1,VK_KHR_16bit_storage[]
32- or 64-bit matrix, it will be assigned multiple locations starting with
the location specified.
The number of locations assigned for each matrix will be the same as for an
@ -268,12 +268,12 @@ The components within a location are 0, 1, 2, and 3.
A variable or block member starting at component N will consume components
N, N+1, N+2, ...
up through its size.
ifdef::VK_KHR_16bit_storage[]
ifdef::VK_VERSION_1_1,VK_KHR_16bit_storage[]
For 16-, and 32-bit types,
endif::VK_KHR_16bit_storage[]
ifndef::VK_KHR_16bit_storage[]
endif::VK_VERSION_1_1,VK_KHR_16bit_storage[]
ifndef::VK_VERSION_1_1,VK_KHR_16bit_storage[]
For single precision types,
endif::VK_KHR_16bit_storage[]
endif::VK_VERSION_1_1,VK_KHR_16bit_storage[]
it is invalid if this sequence of components gets larger than 3.
A scalar 64-bit type will consume two of these components in sequence, and a
two-component 64-bit vector type will consume all four components available
@ -372,11 +372,11 @@ index, either explicitly declared or implied.
Output values written by a fragment shader must: be declared with either
code:OpTypeFloat or code:OpTypeInt, and a Width of 32.
ifdef::VK_KHR_16bit_storage[]
ifdef::VK_VERSION_1_1,VK_KHR_16bit_storage[]
If pname:storageInputOutput16 is supported, output values written by a
fragment shader can: be also declared with either code:OpTypeFloat or
code:OpTypeInt and a Width of 16.
endif::VK_KHR_16bit_storage[]
endif::VK_VERSION_1_1,VK_KHR_16bit_storage[]
Composites of these types are also permitted.
If the color attachment has a signed or unsigned normalized fixed-point
format, color values are assumed to be floating-point and are converted to
@ -514,27 +514,32 @@ expressions, except under the following conditions:
shader module declares the code:SampledImageArrayDynamicIndexing
capability, the array must: only be indexed by dynamically uniform
expressions.
ifdef::VK_KHR_sampler_ycbcr_conversion[]
ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
* If sampler Y'C~B~C~R~ conversion is enabled, the combined image sampler
must: be indexed only by constant integral expressions when aggregated
into arrays in shader code, irrespective of the
pname:shaderSampledImageArrayDynamicIndexing feature.
endif::VK_KHR_sampler_ycbcr_conversion[]
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
The code:Sampled code:Type of an code:OpTypeImage declaration must: match
the same basic data type as the corresponding resource, or the values
obtained by reading or sampling from this image are undefined.
The code:Image code:Format of an code:OpTypeImage declaration must: not be
*Unknown*, for variables which are used for code:OpImageRead or
code:OpImageWrite operations, except under the following conditions:
*Unknown*, for variables which are used for code:OpImageRead,
code:OpImageSparseRead, or code:OpImageWrite operations, except under the
following conditions:
* For code:OpImageWrite, if the pname:shaderStorageImageWriteWithoutFormat
feature is enabled and the shader module declares the
code:StorageImageWriteWithoutFormat capability.
* For code:OpImageRead, if the pname:shaderStorageImageReadWithoutFormat
feature is enabled and the shader module declares the
code:StorageImageReadWithoutFormat capability.
* For code:OpImageRead or code:OpImageSparseRead, if the
pname:shaderStorageImageReadWithoutFormat feature is enabled and the
shader module declares the code:StorageImageReadWithoutFormat
capability.
The code:Image code:Format of an code:OpTypeImage declaration must: not be
*Unknown*, for variables which are used for code:OpAtomic* operations.
Variables identified with the code:Uniform storage class are used to access
transparent buffer backed resources.
@ -546,7 +551,7 @@ Such variables must: be:
code:MatrixStride decorations as specified in
<<interfaces-resources-layout,Offset and Stride Assignment>>.
ifdef::VK_KHR_storage_buffer_storage_class[]
ifdef::VK_VERSION_1_1,VK_KHR_storage_buffer_storage_class[]
Variables identified with the code:StorageBuffer storage class are used to
access transparent buffer backed resources.
Such variables must: be:
@ -556,7 +561,7 @@ Such variables must: be:
* laid out explicitly using the code:Offset, code:ArrayStride, and
code:MatrixStride decorations as specified in
<<interfaces-resources-layout,Offset and Stride Assignment>>.
endif::VK_KHR_storage_buffer_storage_class[]
endif::VK_VERSION_1_1,VK_KHR_storage_buffer_storage_class[]
Any array of these types must: only be indexed with constant integral
expressions, except under the following conditions.
@ -568,25 +573,25 @@ expressions, except under the following conditions.
expressions.
* For arrays of code:BufferBlock variables in the code:Uniform storage
class
ifdef::VK_KHR_storage_buffer_storage_class[]
ifdef::VK_VERSION_1_1,VK_KHR_storage_buffer_storage_class[]
or arrays of code:Block variables in the code:StorageBuffer storage
class
endif::VK_KHR_storage_buffer_storage_class[]
endif::VK_VERSION_1_1,VK_KHR_storage_buffer_storage_class[]
, if the pname:shaderStorageBufferArrayDynamicIndexing feature is
enabled and the shader module declares the
code:StorageBufferArrayDynamicIndexing capability, the array must: only
be indexed by dynamically uniform expressions.
ifndef::VK_KHR_storage_buffer_storage_class[]
ifndef::VK_VERSION_1_1,VK_KHR_storage_buffer_storage_class[]
The code:Offset decoration for any variable in a code:Block must: not cause
the space required for that variable to extend outside the range [eq]#[0,
pname:maxUniformBufferRange)#.
The code:Offset decoration for any variable in a code:BufferBlock must: not
cause the space required for that variable to extend outside the range
[eq]#[0, pname:maxStorageBufferRange)#.
endif::VK_KHR_storage_buffer_storage_class[]
endif::VK_VERSION_1_1,VK_KHR_storage_buffer_storage_class[]
ifdef::VK_KHR_storage_buffer_storage_class[]
ifdef::VK_VERSION_1_1,VK_KHR_storage_buffer_storage_class[]
The code:Offset decoration for any member of a code:Block-decorated variable
in the code:Uniform storage class must: not cause the space required for
that variable to extend outside the range [eq]#[0,
@ -595,7 +600,7 @@ The code:Offset decoration for any member of a code:Block-decorated variable
in the code:StorageBuffer storage class must: not cause the space required
for that variable to extend outside the range [eq]#[0,
pname:maxStorageBufferRange)#.
endif::VK_KHR_storage_buffer_storage_class[]
endif::VK_VERSION_1_1,VK_KHR_storage_buffer_storage_class[]
Variables identified with a storage class of code:UniformConstant and a
decoration of code:InputAttachmentIndex must: be declared as described in
@ -610,6 +615,11 @@ See <<interfaces-resources-correspondence,Shader Resource and Descriptor
Type Correspondence>> for the relationship between shader types and
descriptor types.
SPIR-V variables decorated with a descriptor set and binding that identify a
<<descriptorsets-combinedimagesampler, combined image sampler descriptor>>
can: have a type of code:OpTypeImage, code:OpTypeSampler (code:Sampled=1),
or code:OpTypeSampledImage.
[[interfaces-resources-correspondence]]
.Shader Resource and Descriptor Type Correspondence
[width="90%",cols="<1,<2",options="header"]
@ -641,7 +651,9 @@ descriptor types.
| storage image
| code:UniformConstant | code:OpTypeImage (code:Sampled=2) |
| combined image sampler
| code:UniformConstant | code:OpTypeSampledImage |
| code:UniformConstant | code:OpTypeSampledImage +
code:OpTypeImage (code:Sampled=1) +
code:OpTypeSampler |
| uniform texel buffer
| code:UniformConstant | code:OpTypeImage (code:Dim=code:Buffer, code:Sampled=1) |
| storage texel buffer
@ -649,17 +661,17 @@ descriptor types.
| uniform buffer
| code:Uniform | code:OpTypeStruct
| code:Block, code:Offset, (code:ArrayStride), (code:MatrixStride)
ifndef::VK_KHR_storage_buffer_storage_class[]
ifndef::VK_VERSION_1_1,VK_KHR_storage_buffer_storage_class[]
| storage buffer
| code:Uniform | code:OpTypeStruct
| code:BufferBlock, code:Offset, (code:ArrayStride), (code:MatrixStride)
endif::VK_KHR_storage_buffer_storage_class[]
ifdef::VK_KHR_storage_buffer_storage_class[]
endif::VK_VERSION_1_1,VK_KHR_storage_buffer_storage_class[]
ifdef::VK_VERSION_1_1,VK_KHR_storage_buffer_storage_class[]
.2+<.^| storage buffer
| code:Uniform .2+<.^| code:OpTypeStruct
| code:BufferBlock, code:Offset, (code:ArrayStride), (code:MatrixStride)
| code:StorageBuffer | code:Block, code:Offset, (code:ArrayStride), (code:MatrixStride)
endif::VK_KHR_storage_buffer_storage_class[]
endif::VK_VERSION_1_1,VK_KHR_storage_buffer_storage_class[]
| input attachment
| code:UniformConstant | code:OpTypeImage (code:Dim=code:SubpassData, code:Sampled=2)
| code:InputAttachmentIndex
@ -769,7 +781,7 @@ defined recursively as follows:
* A column-major matrix has a base alignment equal to the base alignment
of the matrix column type.
ifdef::VK_KHR_relaxed_block_layout[]
ifdef::VK_VERSION_1_1,VK_KHR_relaxed_block_layout[]
A member is defined to _improperly straddle_ if either of the following are
true:
@ -781,19 +793,19 @@ true:
code:Offset decorations placing its first byte at a non-integer multiple
of 16.
endif::VK_KHR_relaxed_block_layout[]
endif::VK_VERSION_1_1,VK_KHR_relaxed_block_layout[]
Every member of an code:OpTypeStruct with storage class of code:Uniform and
a decoration of code:Block (uniform buffers) must: be laid out according to
the following rules:
ifndef::VK_KHR_relaxed_block_layout[]
ifndef::VK_VERSION_1_1,VK_KHR_relaxed_block_layout[]
* The code:Offset decoration must: be a multiple of its base alignment.
endif::VK_KHR_relaxed_block_layout[]
endif::VK_VERSION_1_1,VK_KHR_relaxed_block_layout[]
ifdef::VK_KHR_relaxed_block_layout[]
ifdef::VK_VERSION_1_1,VK_KHR_relaxed_block_layout[]
* The code:Offset decoration of a scalar, an array, a structure, or a
matrix must: be a multiple of its base alignment.
@ -801,7 +813,7 @@ ifdef::VK_KHR_relaxed_block_layout[]
the base alignment of its scalar component type, and must: not
improperly straddle, as defined above.
endif::VK_KHR_relaxed_block_layout[]
endif::VK_VERSION_1_1,VK_KHR_relaxed_block_layout[]
* Any code:ArrayStride or code:MatrixStride decoration must: be an integer
multiple of the base alignment of the array or matrix from above.
@ -823,9 +835,9 @@ The *std140 layout* in GLSL satisfies these rules.
Member variables of an code:OpTypeStruct with a storage class of
code:PushConstant (push constants), or a storage class of code:Uniform with
a decoration of code:BufferBlock (storage buffers)
ifdef::VK_KHR_storage_buffer_storage_class[]
ifdef::VK_VERSION_1_1,VK_KHR_storage_buffer_storage_class[]
, or a storage class of code:StorageBuffer with a decoration of code:Block
endif::VK_KHR_storage_buffer_storage_class[]
endif::VK_VERSION_1_1,VK_KHR_storage_buffer_storage_class[]
must: be laid out as <<interfaces-resources-layout-std140,above>>, except
for array and structure base alignment which do not need to be rounded up to
a multiple of [eq]#16#.
@ -920,7 +932,7 @@ identity I + J + K = 1.0.
endif::VK_AMD_shader_explicit_vertex_parameter[]
ifdef::VK_KHR_shader_draw_parameters[]
ifdef::VK_VERSION_1_1,VK_KHR_shader_draw_parameters[]
[[interfaces-builtin-variables-baseinstance]]
code:BaseInstance::
@ -962,7 +974,7 @@ input storage class.
The variable decorated with codeBaseVertex must: be declared as a scalar
32-bit integer.
endif::VK_KHR_shader_draw_parameters[]
endif::VK_VERSION_1_1,VK_KHR_shader_draw_parameters[]
code:ClipDistance::
@ -1047,7 +1059,7 @@ the corresponding value from the code:CullDistance decorated output variable
from the previous shader stage.
====
ifdef::VK_KHX_device_group[]
ifdef::VK_VERSION_1_1,VK_KHR_device_group[]
[[interfaces-builtin-variables-deviceindex]]
code:DeviceIndex::
@ -1057,7 +1069,7 @@ be filled with the device index of the physical device that is executing the
current shader invocation.
This value will be in the range latexmath:[[0,max(1,physicalDeviceCount))],
where physicalDeviceCount is the pname:physicalDeviceCount member of
slink:VkDeviceGroupDeviceCreateInfoKHX.
slink:VkDeviceGroupDeviceCreateInfo.
+
The code:DeviceIndex decoration can: be used in any shader.
+
@ -1067,9 +1079,9 @@ code:Input storage class.
The variable decorated with code:DeviceIndex must: be declared as a scalar
32-bit integer.
endif::VK_KHX_device_group[]
endif::VK_VERSION_1_1,VK_KHR_device_group[]
ifdef::VK_KHR_shader_draw_parameters[]
ifdef::VK_VERSION_1_1,VK_KHR_shader_draw_parameters[]
[[interfaces-builtin-variables-drawindex]]
code:DrawIndex::
@ -1091,7 +1103,7 @@ storage class.
The variable decorated with code:DrawIndex must: be declared as a scalar
32-bit integer.
endif::VK_KHR_shader_draw_parameters[]
endif::VK_VERSION_1_1,VK_KHR_shader_draw_parameters[]
code:FragCoord::
@ -1407,6 +1419,23 @@ If the workgroup is effectively one-dimensional, then both
code:LocalInvocationId.y and code:LocalInvocationId.z will be zero.
====
ifdef::VK_VERSION_1_1[]
code:NumSubgroups::
Decorating a variable with the code:NumSubgroups built-in decoration will
make that variable contain the number of subgroups in the local workgroup.
+
The code:NumSubgroups decoration must: be used only within compute shaders.
+
The variable decorated with code:NumSubgroups must: be declared using the
code:Input storage class.
+
The object decorated with code:NumSubgroups must: be declared as a scalar
32-bit integer.
endif::VK_VERSION_1_1[]
code:NumWorkgroups::
Decorating a variable with the code:NumWorkgroups built-in decoration will
@ -1607,7 +1636,7 @@ The code:PrimitiveId decoration must: be used only within fragment,
tessellation control, tessellation evaluation, and geometry shaders.
+
In a tessellation control or tessellation evaluation shader, any variable
decorated with code:PrimitiveId must: be declared using the code:Output
decorated with code:PrimitiveId must: be declared using the code:Input
storage class.
+
In a geometry shader, any variable decorated with code:PrimitiveId must: be
@ -1745,91 +1774,119 @@ endif::VK_EXT_sample_locations[]
The variable decorated with code:SamplePosition must: be declared as a
two-component vector of 32-bit floating-point values.
ifdef::VK_EXT_shader_subgroup_ballot[]
ifdef::VK_VERSION_1_1[]
code:SubgroupId::
+
Decorating a variable with the code:SubgroupId built-in decoration will make
that variable contain the index of the subgroup within the local workgroup.
This variable is in range [0, code:NumSubgroups-1].
+
The code:SubgroupId decoration must: be used only within compute shaders.
+
The variable decorated with code:SubgroupId must: be declared using the
code:Input storage class.
+
The variable decorated with code:SubgroupId must: be declared as a scalar
32-bit integer.
endif::VK_VERSION_1_1[]
ifdef::VK_VERSION_1_1,VK_EXT_shader_subgroup_ballot[]
[[interfaces-builtin-variables-sgeq]]
code:SubgroupEqMaskKHR::
code:SubgroupEqMask::
+
Decorating a variable with the code:SubgroupEqMaskKHR builtin decoration
will make that variable contain the _subgroup mask_ of the current subgroup
Decorating a variable with the code:SubgroupEqMask builtin decoration will
make that variable contain the _subgroup mask_ of the current subgroup
invocation.
The bit corresponding to the code:SubgroupLocalInvocationId is set in the
variable decorated with code:SubgroupEqMaskKHR.
variable decorated with code:SubgroupEqMask.
All other bits are set to zero.
+
The variable decorated with code:SubgroupEqMaskKHR must: be declared using
the code:Input storage class.
The variable decorated with code:SubgroupEqMask must: be declared using the
code:Input storage class.
+
The variable decorated with code:SubgroupEqMaskKHR must: be declared as a
The variable decorated with code:SubgroupEqMask must: be declared as a
four-component vector of 32-bit integer values.
+
code:SubgroupEqMaskKHR is an alias of code:SubgroupEqMask.
[[interfaces-builtin-variables-sgge]]
code:SubgroupGeMaskKHR::
code:SubgroupGeMask::
+
Decorating a variable with the code:SubgroupGeMaskKHR builtin decoration
will make that variable contain the _subgroup mask_ of the invocations
greater than or equal to the current subgroup invocation.
The bits corresponding to the invocations greather than or equal to
Decorating a variable with the code:SubgroupGeMask builtin decoration will
make that variable contain the _subgroup mask_ of the current subgroup
invocation.
The bits corresponding to the invocations greater than or equal to
code:SubgroupLocalInvocationId through code:SubgroupSize-1 are set in the
variable decorated with code:SubgroupGeMaskKHR.
variable decorated with code:SubgroupGeMask.
All other bits are set to zero.
+
The variable decorated with code:SubgroupGeMaskKHR must: be declared using
the code:Input storage class.
The variable decorated with code:SubgroupGeMask must: be declared using the
code:Input storage class.
+
The variable decorated with code:SubgroupGeMaskKHR must: be declared as a
The variable decorated with code:SubgroupGeMask must: be declared as a
four-component vector of 32-bit integer values.
+
code:SubgroupGeMaskKHR is an alias of code:SubgroupGeMask.
[[interfaces-builtin-variables-sggt]]
code:SubgroupGtMaskKHR::
code:SubgroupGtMask::
+
Decorating a variable with the code:SubgroupGtMaskKHR builtin decoration
will make that variable contain the _subgroup mask_ of the invocations
greater than the current subgroup invocation.
Decorating a variable with the code:SubgroupGtMask builtin decoration will
make that variable contain the _subgroup mask_ of the current subgroup
invocation.
The bits corresponding to the invocations greater than
code:SubgroupLocalInvocationId through code:SubgroupSize-1 are set in the
variable decorated with code:SubgroupGtMaskKHR.
variable decorated with code:SubgroupGtMask.
All other bits are set to zero.
+
The variable decorated with code:SubgroupGtMaskKHR must: be declared using
the code:Input storage class.
The variable decorated with code:SubgroupGtMask must: be declared using the
code:Input storage class.
+
The variable decorated with code:SubgroupGtMaskKHR must: be declared as a
The variable decorated with code:SubgroupGtMask must: be declared as a
four-component vector of 32-bit integer values.
+
code:SubgroupGtMaskKHR is an alias of code:SubgroupGtMask.
[[interfaces-builtin-variables-sgle]]
code:SubgroupLeMaskKHR::
code:SubgroupLeMask::
+
Decorating a variable with the code:SubgroupLeMaskKHR builtin decoration
will make that variable contain the _subgroup mask_ of the invocations less
than or equal to the current subgroup invocation.
Decorating a variable with the code:SubgroupLeMask builtin decoration will
make that variable contain the _subgroup mask_ of the current subgroup
invocation.
The bits corresponding to the invocations less than or equal to
code:SubgroupLocalInvocationId are set in the variable decorated with
code:SubgroupLeMaskKHR.
code:SubgroupLeMask.
All other bits are set to zero.
+
The variable decorated with code:SubgroupLeMaskKHR must: be declared using
the code:Input storage class.
The variable decorated with code:SubgroupLeMask must: be declared using the
code:Input storage class.
+
The variable decorated with code:SubgroupLeMaskKHR must: be declared as a
The variable decorated with code:SubgroupLeMask must: be declared as a
four-component vector of 32-bit integer values.
+
code:SubgroupLeMaskKHR is an alias of code:SubgroupLeMask.
[[interfaces-builtin-variables-sglt]]
code:SubgroupLtMaskKHR::
code:SubgroupLtMask::
+
Decorating a variable with the code:SubgroupLtMaskKHR builtin decoration
will make that variable contain the _subgroup mask_ of the invocations less
than the current subgroup invocation.
Decorating a variable with the code:SubgroupLtMask builtin decoration will
make that variable contain the _subgroup mask_ of the current subgroup
invocation.
The bits corresponding to the invocations less than
code:SubgroupLocalInvocationId are set in the variable decorated with
code:SubgroupLtMaskKHR.
code:SubgroupLtMask.
All other bits are set to zero.
+
The variable decorated with code:SubgroupLtMaskKHR must: be declared using
the code:Input storage class.
The variable decorated with code:SubgroupLtMask must: be declared using the
code:Input storage class.
+
The variable decorated with code:SubgroupLtMaskKHR must: be declared as a
The variable decorated with code:SubgroupLtMask must: be declared as a
four-component vector of 32-bit integer values.
+
code:SubgroupLtMaskKHR is an alias of code:SubgroupLtMask.
[[interfaces-builtin-variables-sgli]]
code:SubgroupLocalInvocationId::
@ -1860,7 +1917,7 @@ code:Input storage class.
The variable decorated with code:SubgroupSize must: be declared as a scalar
32-bit integer.
endif::VK_EXT_shader_subgroup_ballot[]
endif::VK_VERSION_1_1,VK_EXT_shader_subgroup_ballot[]
code:TessCoord::
@ -1965,7 +2022,7 @@ The variable decorated with code:VertexIndex must: be declared as a scalar
code:VertexIndex starts at the same starting value for each instance.
====
ifdef::VK_KHX_multiview[]
ifdef::VK_VERSION_1_1,VK_KHR_multiview[]
[[interfaces-builtin-variables-viewindex]]
code:ViewIndex::
@ -1986,7 +2043,7 @@ code:Input storage class.
The variable decorated with code:ViewIndex must: be declared as a scalar
32-bit integer.
endif::VK_KHX_multiview[]
endif::VK_VERSION_1_1,VK_KHR_multiview[]
[[interfaces-builtin-variables-viewportindex]]
code:ViewportIndex::

255
doc/specs/vulkan/chapters/introduction.txt
View File

@ -2,165 +2,84 @@
// Creative Commons Attribution 4.0 International License; see
// http://creativecommons.org/licenses/by/4.0/
[[introduction]]
= Introduction
This chapter is Informative except for the sections on Terminology and
Normative References.
This document, referred to as the "`Vulkan Specification`" or just the
"`Specification`" hereafter, describes the Vulkan graphics system: what it
is, how it acts, and what is required to implement it.
We assume that the reader has at least a rudimentary understanding of
computer graphics.
This means familiarity with the essentials of computer graphics algorithms
and terminology as well as with modern GPUs (Graphic Processing Units).
"`Specification`" hereafter, describes the Vulkan Application Programming
Interface (API).
Vulkan is a http://www.open-std.org/jtc1/sc22/wg14/www/standards[C99] API
designed for explicit control of low-level graphics and compute
functionality.
The canonical version of the Specification is available in the official
Vulkan Registry, located at URL
http://www.khronos.org/registry/vulkan/
http://www.khronos.org/registry/vulkan/[Vulkan Registry]
(http://www.khronos.org/registry/vulkan/).
The source files used to generate the Vulkan specification are stored in the
https://github.com/KhronosGroup/Vulkan-Docs[Vulkan Documentation Repository]
(https://github.com/KhronosGroup/Vulkan-Docs).
The source repository additionally has a public issue tracker and allows the
submission of pull requests that improve the specification.
[[introduction-whatis]]
== What is the Vulkan Graphics System?
[[introduction-conventions]]
== Document Conventions
Vulkan is an API (Application Programming Interface) for graphics and
compute hardware.
The API consists of many commands that allow a programmer to specify shader
programs, compute kernels, objects, and operations involved in producing
high-quality graphical images, specifically color images of
three-dimensional objects.
[[introduction-programmer]]
=== The Programmer's View of Vulkan
To the programmer, Vulkan is a set of commands that allow the specification
of _shader programs_ or _shaders_, _kernels_, data used by kernels or
shaders, and state controlling aspects of Vulkan outside of shader
execution.
Typically, the data represents geometry in two or three dimensions and
texture images, while the shaders and kernels control the processing of the
data, rasterization of the geometry, and the lighting and shading of
_fragments_ generated by rasterization, resulting in the rendering of
geometry into the framebuffer.
A typical Vulkan program begins with platform-specific calls to open a
window or otherwise prepare a display device onto which the program will
draw.
Then, calls are made to open _queues_ to which _command buffers_ are
submitted.
The command buffers contain lists of commands which will be executed by the
underlying hardware.
The application can: also allocate device memory, associate _resources_ with
memory and refer to these resources from within command buffers.
Drawing commands cause application-defined shader programs to be invoked,
which can: then consume the data in the resources and use them to produce
graphical images.
To display the resulting images, further platform-specific commands are made
to transfer the resulting image to a display device or window.
[[introduction-implementor]]
=== The Implementor's View of Vulkan
To the implementor, Vulkan is a set of commands that allow the construction
and submission of command buffers to a device.
Modern devices accelerate virtually all Vulkan operations, storing data and
framebuffer images in high-speed memory and executing shaders in dedicated
GPU processing resources.
The implementor's task is to provide a software library on the host which
implements the Vulkan API, while mapping the work for each Vulkan command to
the graphics hardware as appropriate for the capabilities of the device.
[[introduction-ourview]]
=== Our View of Vulkan
We view Vulkan as a pipeline having some programmable stages and some
state-driven fixed-function stages that are invoked by a set of specific
drawing operations.
We expect this model to result in a specification that satisfies the needs
of both programmers and implementors.
It does not, however, necessarily provide a model for implementation.
An implementation must: produce results conforming to those produced by the
specified methods, but may: carry out particular computations in ways that
are more efficient than the one specified.
[[introduction-bugs]]
== Filing Bug Reports
Issues with and bug reports on the Vulkan Specification and the API Registry
can: be filed in the Khronos Vulkan GitHub repository, located at URL
https://github.com/KhronosGroup/Vulkan-Docs
Please tag issues with appropriate labels, such as "`Specification`", "`Ref
Pages`" or "`Registry`", to help us triage and assign them appropriately.
Unfortunately, GitHub does not currently let users who do not have write
access to the repository set GitHub labels on issues.
In the meantime, they can: be added to the title line of the issue set in
brackets, e.g. "`[Specification]`".
[[introduction-terminology]]
== Terminology
The key words *must*, *required*, *should*, *recommend*, *may*, and
*optional* in this document are to be interpreted as described in RFC 2119:
http://www.ietf.org/rfc/rfc2119.txt
*must*::
When used alone, this word, or the term *required*, means that the
definition is an absolute requirement of the specification.
When followed by *not* ("`must: not`" ), the phrase means that the
definition is an absolute prohibition of the specification.
*should*::
When used alone, this word means that there may exist valid reasons in
particular circumstances to ignore a particular item, but the full
implications must be understood and carefully weighed before choosing a
different course.
When followed by *not* ("`should: not`"), the phrase means that there may
exist valid reasons in particular circumstances when the particular behavior
is acceptable or even useful, but the full implications should: be
understood and the case carefully weighed before implementing any behavior
described with this label.
In cases where grammatically appropriate, the terms *recommend* or
*recommendation* may be used instead of *should*.
*may*::
This word, or the adjective *optional*, means that an item is truly
optional.
One vendor may choose to include the item because a particular marketplace
requires it or because the vendor feels that it enhances the product while
another vendor may omit the same item.
An implementation which does not include a particular option must be
prepared to interoperate with another implementation which does include the
option, though perhaps with reduced functionality.
In the same vein an implementation which does include a particular option
must be prepared to interoperate with another implementation which does not
include the option (except, of course, for the feature the option provides).
The additional terms *can* and *cannot* are to be interpreted as follows:
*can*::
This word means that the particular behavior described is a valid choice for
an application, and is never used to refer to implementation behavior.
*cannot*::
This word means that the particular behavior described is not achievable by
an application.
For example, an entry point does not exist, or shader code is not capable of
expressing an operation.
The Vulkan specification is intended for use by both implementors of the API
and application developers seeking to make use of the API, forming a
contract between these parties.
Specification text may address either party; typically the intended audience
can be inferred from context, though some sections are defined to address
only one of these parties.
(For example, <<fundamentals-validusage>> sections only address application
developers).
Any requirements, prohibitions, recommendations or options defined by
<<introduction-normative-terminology, normative terminology>> are imposed
only on the audience of that text.
[NOTE]
.Note
====
Structure and enumerated types defined in extensions that were promoted to
core in Vulkan 1.1 are now defined in terms of the equivalent Vulkan 1.1
interfaces.
This affects the Vulkan Specification, the Vulkan header files, and the
corresponding XML Registry.
====
[[introduction-normative-terminology]]
=== Normative Terminology
Within this specification, the key words *must*, *required*, *should*,
*recommended*, *may*, and *optional* are to be interpreted as described in
http://www.ietf.org/rfc/rfc2119.txt[RFC 2119 - Key words for use in RFCs to
Indicate Requirement Levels] (http://www.ietf.org/rfc/rfc2119.txt).
These key words are highlighted in the specification for clarity.
In text addressing application developers, their use expresses requirements
that apply to application behavior.
In text addressing implementors, their use expresses requirements that apply
to implementations.
In text addressing application developers, the additional key words *can*
and *cannot* are to be interpreted as describing the capabilities of an
application, as follows:
*can*::
This word means that the application is able to perform the action
described.
*cannot*::
This word means that the API and/or the execution environment provide no
mechanism through which the application can express or accomplish the action
described.
These key words are never used in text addressing implementors.
[NOTE]
.Note
==================
There is an important distinction between *cannot* and *must not*, as used
in this Specification.
*Cannot* means something the application literally is unable to express or
@ -168,25 +87,38 @@ accomplish through the API, while *must not* means something that the
application is capable of expressing through the API, but that the
consequences of doing so are undefined and potentially unrecoverable for the
implementation.
====
==================
ifdef::editing-notes[]
[NOTE]
.editing-note
====
TODO (Jon) - We might need to augment the RFC 2119 definition of *must not*
to include some of the previous note, since at present it is defined solely
in terms of implementation behavior.
See Gitlab issue #9.
====
endif::editing-notes[]
Unless otherwise noted in the section heading, all sections and appendices
in this document are normative.
[[introduction-normative]]
== Normative References
[[introduction-technical-terminology]]
=== Technical Terminology
Normative references are references to external documents or resources to
which implementers of Vulkan must: comply.
The Vulkan Specification makes use of common engineering and graphics terms
such as *Pipeline*, *Shader*, and *Host* to identify and describe Vulkan API
constructs and their attributes, states, and behaviors.
The <<glossary,Glossary>> defines the basic meanings of these terms in the
context of the Specification.
The Specification text provides fuller definitions of the terms and may
elaborate, extend, or clarify the <<glossary,Glossary>> definitions.
When a term defined in the <<glossary,Glossary>> is used in normative
language within the Specification, the definitions within the Specification
govern and supersede any meanings the terms may have in other technical
contexts (i.e. outside the Specification).
[[introduction-normative-references]]
=== Normative References
References to external documents are considered normative references if the
Specification uses any of the normative terms defined in
<<introduction-normative-terminology>> to refer to them or their
requirements, either as a whole or in part.
The following documents are referenced by normative sections of the
specification:
[[ieee-754]]
_IEEE Standard for Floating-Point Arithmetic_, IEEE Std 754-2008,
@ -216,3 +148,4 @@ https://www.khronos.org/registry/vulkan/, July 11, 2016
_Vulkan Loader Specification and Architecture Overview_,
https://github.com/KhronosGroup/Vulkan-LoaderAndValidationLayers/blob/master/loader/LoaderAndLayerInterface.md,
August, 2016.

491
doc/specs/vulkan/chapters/memory.txt
View File

@ -14,7 +14,13 @@ memory_.
Host memory is memory needed by the Vulkan implementation for
non-device-visible storage.
This storage may: be used for e.g. internal software structures.
[NOTE]
.Note
====
This memory may: be used to store the implementation's representation and
state of Vulkan objects.
====
[[memory-allocation]]
Vulkan provides applications the opportunity to perform host memory
@ -543,6 +549,11 @@ have its pname:propertyFlags set to one of the following values:
ename:VK_MEMORY_PROPERTY_HOST_COHERENT_BIT
* ename:VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT | +
ename:VK_MEMORY_PROPERTY_LAZILY_ALLOCATED_BIT
ifdef::VK_VERSION_1_1[]
* ename:VK_MEMORY_PROPERTY_PROTECTED_BIT
* ename:VK_MEMORY_PROPERTY_PROTECTED_BIT |
ename:VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT
endif::VK_VERSION_1_1[]
There must: be at least one memory type with both the
ename:VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT and
@ -623,33 +634,47 @@ if (memoryType == -1) // not found; try fallback properties
include::../validity/structs/VkPhysicalDeviceMemoryProperties.txt[]
--
ifdef::VK_KHR_get_physical_device_properties2[]
ifdef::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[]
[open,refpage='vkGetPhysicalDeviceMemoryProperties2KHR',desc='Reports memory information for the specified physical device',type='protos']
[open,refpage='vkGetPhysicalDeviceMemoryProperties2',desc='Reports memory information for the specified physical device',type='protos']
--
To query memory properties, call:
ifdef::VK_VERSION_1_1[]
include::../api/protos/vkGetPhysicalDeviceMemoryProperties2.txt[]
endif::VK_VERSION_1_1[]
ifdef::VK_VERSION_1_1+VK_KHR_get_physical_device_properties2[or the equivalent command]
ifdef::VK_KHR_get_physical_device_properties2[]
include::../api/protos/vkGetPhysicalDeviceMemoryProperties2KHR.txt[]
endif::VK_KHR_get_physical_device_properties2[]
* pname:physicalDevice is the handle to the device to query.
* pname:pMemoryProperties points to an instance of
sname:VkPhysicalDeviceMemoryProperties2KHR structure in which the
sname:VkPhysicalDeviceMemoryProperties2 structure in which the
properties are returned.
fname:vkGetPhysicalDeviceMemoryProperties2KHR behaves similarly to
fname:vkGetPhysicalDeviceMemoryProperties2 behaves similarly to
flink:vkGetPhysicalDeviceMemoryProperties, with the ability to return
extended information in a pname:pNext chain of output structures.
include::../validity/protos/vkGetPhysicalDeviceMemoryProperties2KHR.txt[]
include::../validity/protos/vkGetPhysicalDeviceMemoryProperties2.txt[]
--
[open,refpage='VkPhysicalDeviceMemoryProperties2KHR',desc='Structure specifying physical device memory properties',type='structs']
[open,refpage='VkPhysicalDeviceMemoryProperties2',desc='Structure specifying physical device memory properties',type='structs']
--
The sname:VkPhysicalDeviceMemoryProperties2KHR structure is defined as:
The sname:VkPhysicalDeviceMemoryProperties2 structure is defined as:
include::../api/structs/VkPhysicalDeviceMemoryProperties2.txt[]
ifdef::VK_KHR_get_physical_device_properties2[]
or the equivalent
include::../api/structs/VkPhysicalDeviceMemoryProperties2KHR.txt[]
endif::VK_KHR_get_physical_device_properties2[]
* pname:sType is the type of this structure.
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
@ -657,10 +682,11 @@ include::../api/structs/VkPhysicalDeviceMemoryProperties2KHR.txt[]
slink:VkPhysicalDeviceMemoryProperties which is populated with the same
values as in flink:vkGetPhysicalDeviceMemoryProperties.
include::../validity/structs/VkPhysicalDeviceMemoryProperties2KHR.txt[]
include::../validity/structs/VkPhysicalDeviceMemoryProperties2.txt[]
--
endif::VK_KHR_get_physical_device_properties2[]
endif::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[]
[open,refpage='VkMemoryHeap',desc='Structure specifying a memory heap',type='structs']
--
@ -688,13 +714,13 @@ include::../api/enums/VkMemoryHeapFlagBits.txt[]
corresponds to device local memory.
Device local memory may: have different performance characteristics than
host local memory, and may: support different memory property flags.
ifdef::VK_KHX_device_group_creation[]
* ename:VK_MEMORY_HEAP_MULTI_INSTANCE_BIT_KHX indicates that in a logical
ifdef::VK_KHR_device_group_creation[]
* ename:VK_MEMORY_HEAP_MULTI_INSTANCE_BIT indicates that in a logical
device representing more than one physical device, there is a
per-physical device instance of the heap memory.
By default, an allocation from such a heap will be replicated to each
physical device's instance of the heap.
endif::VK_KHX_device_group_creation[]
endif::VK_KHR_device_group_creation[]
--
@ -753,6 +779,15 @@ include::../api/enums/VkMemoryPropertyFlagBits.txt[]
Additionally, the object's backing memory may: be provided by the
implementation lazily as specified in <<memory-device-lazy_allocation,
Lazily Allocated Memory>>.
ifdef::VK_VERSION_1_1[]
* ename:VK_MEMORY_PROPERTY_PROTECTED_BIT bit indicates that the memory
type only allows device access to the memory, and allows protected queue
operations to access the memory.
Memory types must: not have ename:VK_MEMORY_PROPERTY_PROTECTED_BIT set
and any of ename:VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT set, or
ename:VK_MEMORY_PROPERTY_HOST_COHERENT_BIT set, or
ename:VK_MEMORY_PROPERTY_HOST_CACHED_BIT set.
endif::VK_VERSION_1_1[]
--
@ -774,7 +809,7 @@ include::../api/handles/VkDeviceMemory.txt[]
--
[open,refpage='vkAllocateMemory',desc='Allocate GPU memory',type='protos']
[open,refpage='vkAllocateMemory',desc='Allocate device memory',type='protos']
--
To allocate memory objects, call:
@ -801,7 +836,25 @@ This ensures that applications can: correctly suballocate objects of
different types (with potentially different alignment requirements) in the
same memory object.
ifndef::VK_VERSION_1_1[]
When memory is allocated, its contents are undefined.
endif::VK_VERSION_1_1[]
ifdef::VK_VERSION_1_1[]
When memory is allocated, its contents are undefined with the following
constraint:
* The contents of unprotected memory must: not be a function of data
protected memory objects, even if those memory objects were previously
freed.
[NOTE]
.Note
====
The contents of memory allocated by one application should: not be a
function of data from protected memory objects of another application, even
if those memory objects were previously freed.
====
endif::VK_VERSION_1_1[]
The maximum number of valid memory allocations that can: exist
simultaneously within a slink:VkDevice may: be restricted by implementation-
@ -819,6 +872,10 @@ For example, certain systems may: fail to create allocations with a size
greater than or equal to 4GB.
Such a limit is implementation-dependent, and if such a failure occurs then
the error ename:VK_ERROR_OUT_OF_DEVICE_MEMORY must: be returned.
ifdef::VK_KHR_maintenance3[]
This limit is advertised in
slink:VkPhysicalDeviceMaintenance3Properties::pname:maxMemoryAllocationSize.
endif::VK_KHR_maintenance3[]
.Valid Usage
****
@ -896,7 +953,7 @@ of other resources when used as allowed according to its allocation
parameters.
If the external handle provided does not meet these requirements, the
implementation must: fail the memory import operation with the error code
ename:VK_ERROR_INVALID_EXTERNAL_HANDLE_KHR.
ename:VK_ERROR_INVALID_EXTERNAL_HANDLE.
endif::VK_KHR_external_memory_win32,VK_KHR_external_memory_fd,VK_EXT_external_memory_host[]
@ -908,28 +965,32 @@ ifdef::VK_KHR_external_memory[]
ifdef::VK_KHR_dedicated_allocation,VK_NV_dedicated_allocation[]
* [[VUID-VkMemoryAllocateInfo-pNext-00639]]
If the pname:pNext chain contains an instance of
sname:VkExportMemoryAllocateInfoKHR, and any of the handle types
specified in sname:VkExportMemoryAllocateInfoKHR::pname:handleTypes
require a dedicated allocation, as reported by
flink:vkGetPhysicalDeviceImageFormatProperties2KHR in
sname:VkExternalImageFormatPropertiesKHR::pname:externalMemoryProperties::pname:externalMemoryFeatures
sname:VkExportMemoryAllocateInfo, and any of the handle types specified
in sname:VkExportMemoryAllocateInfo::pname:handleTypes require a
dedicated allocation, as reported by
flink:vkGetPhysicalDeviceImageFormatProperties2 in
sname:VkExternalImageFormatProperties::pname:externalMemoryProperties::pname:externalMemoryFeatures
or
sname:VkExternalBufferPropertiesKHR::pname:externalMemoryProperties::pname:externalMemoryFeatures,
sname:VkExternalBufferProperties::pname:externalMemoryProperties::pname:externalMemoryFeatures,
the pname:pNext chain must contain an instance of
ifdef::VK_KHR_dedicated_allocation[slink:VkMemoryDedicatedAllocateInfoKHR]
ifdef::VK_KHR_dedicated_allocation+VK_NV_dedicated_allocation[or]
ifdef::VK_KHR_dedicated_allocation[slink:VkMemoryDedicatedAllocateInfo]
ifdef::VK_KHR_dedicated_allocation[]
ifdef::VK_NV_dedicated_allocation[or]
endif::VK_KHR_dedicated_allocation[]
ifdef::VK_NV_dedicated_allocation[slink:VkDedicatedAllocationMemoryAllocateInfoNV]
with either its pname:image or pname:buffer field set to a value other
than ename:VK_NULL_HANDLE.
endif::VK_KHR_dedicated_allocation,VK_NV_dedicated_allocation[]
endif::VK_KHR_external_memory[]
ifdef::VK_KHR_external_memory+VK_NV_external_memory[]
ifdef::VK_KHR_external_memory[]
ifdef::VK_NV_external_memory[]
* [[VUID-VkMemoryAllocateInfo-pNext-00640]]
If the pname:pNext chain contains an instance of
slink:VkExportMemoryAllocateInfoKHR, it must: not contain an instance of
slink:VkExportMemoryAllocateInfo, it must: not contain an instance of
slink:VkExportMemoryAllocateInfoNV or
slink:VkExportMemoryWin32HandleInfoNV.
endif::VK_KHR_external_memory+VK_NV_external_memory[]
endif::VK_NV_external_memory[]
endif::VK_KHR_external_memory[]
ifdef::VK_KHR_external_memory_win32+VK_NV_external_memory_win32[]
* [[VUID-VkMemoryAllocateInfo-pNext-00641]]
If the pname:pNext chain contains an instance of
@ -944,11 +1005,11 @@ ifdef::VK_KHR_external_memory_fd[]
of pname:allocationSize and pname:memoryTypeIndex must: match those
specified when the memory object being imported was created.
endif::VK_KHR_external_memory_fd[]
ifdef::VK_KHR_external_memory+VK_KHX_device_group[]
ifdef::VK_KHR_external_memory+VK_KHR_device_group[]
* [[VUID-VkMemoryAllocateInfo-None-00643]]
If the parameters define an import operation and the external handle
specified was created by the Vulkan API, the device mask specified by
slink:VkMemoryAllocateFlagsInfoKHX must: match that specified when the
slink:VkMemoryAllocateFlagsInfo must: match that specified when the
memory object being imported was allocated.
* [[VUID-VkMemoryAllocateInfo-None-00644]]
If the parameters define an import operation and the external handle
@ -956,7 +1017,7 @@ ifdef::VK_KHR_external_memory+VK_KHX_device_group[]
that comprise the logical device passed to flink:vkAllocateMemory must:
match the list of physical devices that comprise the logical device on
which the memory was originally allocated.
endif::VK_KHR_external_memory+VK_KHX_device_group[]
endif::VK_KHR_external_memory+VK_KHR_device_group[]
ifdef::VK_KHR_external_memory_win32[]
* [[VUID-VkMemoryAllocateInfo-memoryTypeIndex-00645]]
If the parameters define an import operation and the external handle is
@ -972,16 +1033,16 @@ ifdef::VK_KHR_external_memory_win32[]
those specified when the memory object being imported was created.
* [[VUID-VkMemoryAllocateInfo-allocationSize-00646]]
If the parameters define an import operation and the external handle
type is ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_BIT_KHR,
ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_KMT_BIT_KHR, or
ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_RESOURCE_BIT_KHR,
type is ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_BIT,
ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_KMT_BIT, or
ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_RESOURCE_BIT,
pname:allocationSize must: match the size reported in the memory
requirements of the pname:image or pname:buffer member of the instance
of sname:VkDedicatedAllocationMemoryAllocateInfoNV included in the
pname:pNext chain.
* [[VUID-VkMemoryAllocateInfo-allocationSize-00647]]
If the parameters define an import operation and the external handle
type is ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_HEAP_BIT_KHR,
type is ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_HEAP_BIT,
pname:allocationSize must: match the size specified when creating the
Direct3D 12 heap from which the external handle was extracted.
endif::VK_KHR_external_memory_win32[]
@ -992,6 +1053,11 @@ ifdef::VK_KHR_external_memory_fd[]
pname:memoryTypeIndex must: be one of those returned by
flink:vkGetMemoryFdPropertiesKHR.
endif::VK_KHR_external_memory_fd[]
ifdef::VK_VERSION_1_1[]
* If the protected memory feature is not enabled, the
sname:VkMemoryAllocateInfo::pname:memoryTypeIndex must: not indicate a
memory type that reports ename:VK_MEMORY_PROPERTY_PROTECTED_BIT.
endif::VK_VERSION_1_1[]
ifdef::VK_EXT_external_memory_host[]
* [[VUID-VkMemoryAllocateInfo-memoryTypeIndex-01744]]
If the parameters define an import operation and the external handle is
@ -1007,18 +1073,24 @@ endif::VK_EXT_external_memory_host[]
include::../validity/structs/VkMemoryAllocateInfo.txt[]
--
ifdef::VK_KHR_dedicated_allocation[]
ifdef::VK_VERSION_1_1,VK_KHR_dedicated_allocation[]
[open,refpage='VkMemoryDedicatedAllocateInfoKHR',desc='Specify a dedicated memory allocation resource',type='structs']
[open,refpage='VkMemoryDedicatedAllocateInfo',desc='Specify a dedicated memory allocation resource',type='structs']
--
If the pname:pNext chain includes a sname:VkMemoryDedicatedAllocateInfoKHR
If the pname:pNext chain includes a sname:VkMemoryDedicatedAllocateInfo
structure, then that structure includes a handle of the sole buffer or image
resource that the memory can: be bound to.
The sname:VkMemoryDedicatedAllocateInfoKHR structure is defined as:
The sname:VkMemoryDedicatedAllocateInfo structure is defined as:
include::../api/structs/VkMemoryDedicatedAllocateInfo.txt[]
ifdef::VK_KHR_dedicated_allocation[]
or the equivalent
include::../api/structs/VkMemoryDedicatedAllocateInfoKHR.txt[]
endif::VK_KHR_dedicated_allocation[]
* pname:sType is the type of this structure.
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
@ -1029,33 +1101,33 @@ include::../api/structs/VkMemoryDedicatedAllocateInfoKHR.txt[]
.Valid Usage
****
* [[VUID-VkMemoryDedicatedAllocateInfoKHR-image-01432]]
* [[VUID-VkMemoryDedicatedAllocateInfo-image-01432]]
At least one of pname:image and pname:buffer must: be
dlink:VK_NULL_HANDLE
* [[VUID-VkMemoryDedicatedAllocateInfoKHR-image-01433]]
* [[VUID-VkMemoryDedicatedAllocateInfo-image-01433]]
If pname:image is not dlink:VK_NULL_HANDLE,
sname:VkMemoryAllocateInfo::pname:allocationSize must: equal the
sname:VkMemoryRequirements::pname:size of the image
* [[VUID-VkMemoryDedicatedAllocateInfoKHR-image-01434]]
* [[VUID-VkMemoryDedicatedAllocateInfo-image-01434]]
If pname:image is not dlink:VK_NULL_HANDLE, pname:image must: have been
created without ename:VK_IMAGE_CREATE_SPARSE_BINDING_BIT set in
slink:VkImageCreateInfo::pname:flags
* [[VUID-VkMemoryDedicatedAllocateInfoKHR-buffer-01435]]
sname:VkImageCreateInfo::pname:flags
* [[VUID-VkMemoryDedicatedAllocateInfo-buffer-01435]]
If pname:buffer is not dlink:VK_NULL_HANDLE,
sname:VkMemoryAllocateInfo::pname:allocationSize must: equal the
sname:VkMemoryRequirements::pname:size of the buffer
* [[VUID-VkMemoryDedicatedAllocateInfoKHR-buffer-01436]]
* [[VUID-VkMemoryDedicatedAllocateInfo-buffer-01436]]
If pname:buffer is not dlink:VK_NULL_HANDLE, pname:buffer must: have
been created without ename:VK_BUFFER_CREATE_SPARSE_BINDING_BIT set in
slink:VkBufferCreateInfo::pname:flags
ifdef::VK_KHR_external_memory_win32,VK_KHR_external_memory_fd[]
* [[VUID-VkMemoryDedicatedAllocateInfoKHR-image-01437]]
* [[VUID-VkMemoryDedicatedAllocateInfo-image-01437]]
If pname:image is not dlink:VK_NULL_HANDLE and
slink:VkMemoryAllocateInfo defines a memory import operation, the memory
being imported must: also be a dedicated image allocation and
pname:image must be identical to the image associated with the imported
memory.
* [[VUID-VkMemoryDedicatedAllocateInfoKHR-buffer-01438]]
* [[VUID-VkMemoryDedicatedAllocateInfo-buffer-01438]]
If pname:buffer is not dlink:VK_NULL_HANDLE and
slink:VkMemoryAllocateInfo defines a memory import operation, the memory
being imported must: also be a dedicated buffer allocation and
@ -1070,10 +1142,10 @@ ifdef::VK_KHR_sampler_ycbcr_conversion[]
endif::VK_KHR_sampler_ycbcr_conversion[]
****
include::../validity/structs/VkMemoryDedicatedAllocateInfoKHR.txt[]
include::../validity/structs/VkMemoryDedicatedAllocateInfo.txt[]
--
endif::VK_KHR_dedicated_allocation[]
endif::VK_VERSION_1_1,VK_KHR_dedicated_allocation[]
ifdef::VK_NV_dedicated_allocation[]
@ -1140,41 +1212,46 @@ include::../validity/structs/VkDedicatedAllocationMemoryAllocateInfoNV.txt[]
endif::VK_NV_dedicated_allocation[]
ifdef::VK_KHR_external_memory[]
ifdef::VK_VERSION_1_1,VK_KHR_external_memory[]
[open,refpage='VkExportMemoryAllocateInfoKHR',desc='Specify exportable handle types for a device memory object',type='structs']
[open,refpage='VkExportMemoryAllocateInfo',desc='Specify exportable handle types for a device memory object',type='structs']
--
When allocating memory that may: be exported to another process or Vulkan
instance, add a slink:VkExportMemoryAllocateInfoKHR structure to the
instance, add a slink:VkExportMemoryAllocateInfo structure to the
pname:pNext chain of the slink:VkMemoryAllocateInfo structure, specifying
the handle types that may: be exported.
The slink:VkExportMemoryAllocateInfoKHR structure is defined as:
The slink:VkExportMemoryAllocateInfo structure is defined as:
include::../api/structs/VkExportMemoryAllocateInfo.txt[]
ifdef::VK_KHR_external_memory[]
or the equivalent
include::../api/structs/VkExportMemoryAllocateInfoKHR.txt[]
endif::VK_KHR_external_memory[]
* pname:sType is the type of this structure.
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
* pname:handleTypes is a bitmask of
elink:VkExternalMemoryHandleTypeFlagBitsKHR specifying one or more
memory handle types the application can: export from the resulting
allocation.
elink:VkExternalMemoryHandleTypeFlagBits specifying one or more memory
handle types the application can: export from the resulting allocation.
The application can: request multiple handle types for the same
allocation.
.Valid Usage
****
* [[VUID-VkExportMemoryAllocateInfoKHR-handleTypes-00656]]
* [[VUID-VkExportMemoryAllocateInfo-handleTypes-00656]]
The bits in pname:handleTypes must: be supported and compatible, as
reported by slink:VkExternalImageFormatPropertiesKHR or
slink:VkExternalBufferPropertiesKHR.
reported by slink:VkExternalImageFormatProperties or
slink:VkExternalBufferProperties.
****
include::../validity/structs/VkExportMemoryAllocateInfoKHR.txt[]
include::../validity/structs/VkExportMemoryAllocateInfo.txt[]
--
endif::VK_KHR_external_memory[]
endif::VK_VERSION_1_1,VK_KHR_external_memory[]
ifdef::VK_KHR_external_memory_win32[]
@ -1207,8 +1284,8 @@ code:DXGI_SHARED_RESOURCE_READ | code:DXGI_SHARED_RESOURCE_WRITE
for handles of the following types:
ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_BIT_KHR
ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_BIT_KHR
ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_BIT
ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_BIT
And
@ -1216,8 +1293,8 @@ code:GENERIC_ALL
for handles of the following types:
ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_HEAP_BIT_KHR
ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_RESOURCE_BIT_KHR
ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_HEAP_BIT
ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_RESOURCE_BIT
1::
https://msdn.microsoft.com/en-us/library/windows/desktop/ms686670.aspx
@ -1225,11 +1302,11 @@ ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_RESOURCE_BIT_KHR
.Valid Usage
****
* [[VUID-VkExportMemoryWin32HandleInfoKHR-handleTypes-00657]]
If slink:VkExportMemoryAllocateInfoKHR::pname:handleTypes does not
include ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_BIT_KHR,
ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_BIT_KHR,
ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_HEAP_BIT_KHR, or
ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_RESOURCE_BIT_KHR,
If slink:VkExportMemoryAllocateInfo::pname:handleTypes does not include
ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_BIT,
ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_BIT,
ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_HEAP_BIT, or
ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_RESOURCE_BIT,
VkExportMemoryWin32HandleInfoKHR must: not be in the pname:pNext chain
of slink:VkMemoryAllocateInfo.
****
@ -1271,8 +1348,8 @@ sname:VkDeviceMemory object.
****
* [[VUID-VkImportMemoryWin32HandleInfoKHR-handleType-00658]]
If pname:handleType is not `0`, it must: be supported for import, as
reported by slink:VkExternalImageFormatPropertiesKHR or
slink:VkExternalBufferPropertiesKHR.
reported by slink:VkExternalImageFormatProperties or
slink:VkExternalBufferProperties.
* [[VUID-VkImportMemoryWin32HandleInfoKHR-handle-00659]]
The memory from which pname:handle was exported, or the memory named by
pname:name must: have been created on the same underlying physical
@ -1282,10 +1359,10 @@ sname:VkDeviceMemory object.
global share handle.
* [[VUID-VkImportMemoryWin32HandleInfoKHR-handleType-01439]]
If pname:handleType is not
ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_BIT_KHR,
ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_BIT_KHR,
ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_HEAP_BIT_KHR, or
ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_RESOURCE_BIT_KHR, pname:name
ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_BIT,
ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_BIT,
ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_HEAP_BIT, or
ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_RESOURCE_BIT, pname:name
must: be `NULL`.
* [[VUID-VkImportMemoryWin32HandleInfoKHR-handleType-01440]]
If pname:handleType is not `0` and pname:handle is `NULL`, pname:name
@ -1350,14 +1427,14 @@ include::../api/structs/VkMemoryGetWin32HandleInfoKHR.txt[]
The properties of the handle returned depend on the value of
pname:handleType.
See elink:VkExternalMemoryHandleTypeFlagBitsKHR for a description of the
See elink:VkExternalMemoryHandleTypeFlagBits for a description of the
properties of the defined external memory handle types.
.Valid Usage
****
* [[VUID-VkMemoryGetWin32HandleInfoKHR-handleType-00662]]
pname:handleType must: have been included in
slink:VkExportMemoryAllocateInfoKHR::pname:handleTypes when pname:memory
slink:VkExportMemoryAllocateInfo::pname:handleTypes when pname:memory
was created.
* [[VUID-VkMemoryGetWin32HandleInfoKHR-handleType-00663]]
If pname:handleType is defined as an NT handle,
@ -1448,8 +1525,11 @@ sname:VkDeviceMemory object.
****
* [[VUID-VkImportMemoryFdInfoKHR-handleType-00667]]
If pname:handleType is not `0`, it must: be supported for import, as
reported by slink:VkExternalImageFormatPropertiesKHR or
slink:VkExternalBufferPropertiesKHR.
reported by slink:VkExternalImageFormatProperties or
slink:VkExternalBufferProperties.
* [[VUID-VkImportMemoryFdInfoKHR-fd-00668]]
The memory from which pname:fd was exported must: have been created on
the same underlying physical device as pname:device.
* [[VUID-VkImportMemoryFdInfoKHR-handleType-00669]]
If pname:handleType is not `0`, it must: be defined as a POSIX file
descriptor handle.
@ -1513,7 +1593,7 @@ include::../api/structs/VkMemoryGetFdInfoKHR.txt[]
The properties of the file descriptor exported depend on the value of
pname:handleType.
See elink:VkExternalMemoryHandleTypeFlagBitsKHR for a description of the
See elink:VkExternalMemoryHandleTypeFlagBits for a description of the
properties of the defined external memory handle types.
ifdef::VK_EXT_external_memory_dma_buf[]
@ -1532,7 +1612,7 @@ endif::VK_EXT_external_memory_dma_buf[]
****
* [[VUID-VkMemoryGetFdInfoKHR-handleType-00671]]
pname:handleType must: have been included in
slink:VkExportMemoryAllocateInfoKHR::pname:handleTypes when pname:memory
slink:VkExportMemoryAllocateInfo::pname:handleTypes when pname:memory
was created.
* [[VUID-VkMemoryGetFdInfoKHR-handleType-00672]]
pname:handleType must: be defined as a POSIX file descriptor handle.
@ -1723,41 +1803,47 @@ include::VK_NV_external_memory_win32/get_handle_win32.txt[]
endif::VK_NV_external_memory_win32[]
ifdef::VK_KHX_device_group[]
ifdef::VK_VERSION_1_1,VK_KHR_device_group[]
[open,refpage='VkMemoryAllocateFlagsInfoKHX',desc='Structure controlling how many instances of memory will be allocated',type='structs']
[open,refpage='VkMemoryAllocateFlagsInfo',desc='Structure controlling how many instances of memory will be allocated',type='structs']
--
If the pname:pNext chain of slink:VkMemoryAllocateInfo includes a
sname:VkMemoryAllocateFlagsInfoKHX structure, then that structure includes
sname:VkMemoryAllocateFlagsInfo structure, then that structure includes
flags and a device mask controlling how many instances of the memory will be
allocated.
The sname:VkMemoryAllocateFlagsInfoKHX structure is defined as:
The sname:VkMemoryAllocateFlagsInfo structure is defined as:
include::../api/structs/VkMemoryAllocateFlagsInfoKHX.txt[]
include::../api/structs/VkMemoryAllocateFlagsInfo.txt[]
ifdef::VK_KHR_device_group[]
or the equivalent
include::../api/structs/VkMemoryAllocateFlagsInfoKHR.txt[]
endif::VK_KHR_device_group[]
* pname:sType is the type of this structure.
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
* pname:flags is a bitmask of elink:VkMemoryAllocateFlagBitsKHX
controlling the allocation.
* pname:flags is a bitmask of elink:VkMemoryAllocateFlagBits controlling
the allocation.
* pname:deviceMask is a mask of physical devices in the logical device,
indicating that memory must: be allocated on each device in the mask, if
ename:VK_MEMORY_ALLOCATE_DEVICE_MASK_BIT_KHX is set in pname:flags.
ename:VK_MEMORY_ALLOCATE_DEVICE_MASK_BIT is set in pname:flags.
If ename:VK_MEMORY_ALLOCATE_DEVICE_MASK_BIT_KHX is not set, the number of
If ename:VK_MEMORY_ALLOCATE_DEVICE_MASK_BIT is not set, the number of
instances allocated depends on whether
ename:VK_MEMORY_HEAP_MULTI_INSTANCE_BIT_KHX is set in the memory heap.
If ename:VK_MEMORY_HEAP_MULTI_INSTANCE_BIT_KHX is set, then memory is
allocated for every physical device in the logical device (as if
pname:deviceMask has bits set for all device indices).
If ename:VK_MEMORY_HEAP_MULTI_INSTANCE_BIT_KHX is not set, then a single
ename:VK_MEMORY_HEAP_MULTI_INSTANCE_BIT is set in the memory heap.
If ename:VK_MEMORY_HEAP_MULTI_INSTANCE_BIT is set, then memory is allocated
for every physical device in the logical device (as if pname:deviceMask has
bits set for all device indices).
If ename:VK_MEMORY_HEAP_MULTI_INSTANCE_BIT is not set, then a single
instance of memory is allocated (as if pname:deviceMask is set to one).
On some implementations, allocations from a multi-instance heap may: consume
memory on all physical devices even if the pname:deviceMask excludes some
devices.
If slink:VkPhysicalDeviceGroupPropertiesKHX::pname:subsetAllocation is
If slink:VkPhysicalDeviceGroupProperties::pname:subsetAllocation is
ename:VK_TRUE, then memory is only consumed for the devices in the device
mask.
@ -1772,42 +1858,54 @@ allocations.
.Valid Usage
****
* [[VUID-VkMemoryAllocateFlagsInfoKHX-deviceMask-00675]]
If ename:VK_MEMORY_ALLOCATE_DEVICE_MASK_BIT_KHX is set, pname:deviceMask
* [[VUID-VkMemoryAllocateFlagsInfo-deviceMask-00675]]
If ename:VK_MEMORY_ALLOCATE_DEVICE_MASK_BIT is set, pname:deviceMask
must: be a valid device mask.
* [[VUID-VkMemoryAllocateFlagsInfoKHX-deviceMask-00676]]
If ename:VK_MEMORY_ALLOCATE_DEVICE_MASK_BIT_KHX is set, pname:deviceMask
* [[VUID-VkMemoryAllocateFlagsInfo-deviceMask-00676]]
If ename:VK_MEMORY_ALLOCATE_DEVICE_MASK_BIT is set, pname:deviceMask
must: not be zero
****
include::../validity/structs/VkMemoryAllocateFlagsInfoKHX.txt[]
include::../validity/structs/VkMemoryAllocateFlagsInfo.txt[]
--
[open,refpage='VkMemoryAllocateFlagBitsKHX',desc='Bitmask specifying flags for a device memory allocation',type='enums']
[open,refpage='VkMemoryAllocateFlagBits',desc='Bitmask specifying flags for a device memory allocation',type='enums']
--
Bits which can: be set in slink:VkMemoryAllocateFlagsInfoKHX::pname:flags,
Bits which can: be set in slink:VkMemoryAllocateFlagsInfo::pname:flags,
controlling device memory allocation, are:
include::../api/enums/VkMemoryAllocateFlagBitsKHX.txt[]
include::../api/enums/VkMemoryAllocateFlagBits.txt[]
* ename:VK_MEMORY_ALLOCATE_DEVICE_MASK_BIT_KHX specifies that memory will
be allocated for the devices in
slink:VkMemoryAllocateFlagsInfoKHX::pname:deviceMask.
ifdef::VK_KHR_device_group[]
or the equivalent
include::../api/enums/VkMemoryAllocateFlagBitsKHR.txt[]
endif::VK_KHR_device_group[]
* ename:VK_MEMORY_ALLOCATE_DEVICE_MASK_BIT specifies that memory will be
allocated for the devices in
slink:VkMemoryAllocateFlagsInfo::pname:deviceMask.
--
[open,refpage='VkMemoryAllocateFlagsKHX',desc='Bitmask of VkMemoryAllocateFlagBitsKHX',type='enums']
[open,refpage='VkMemoryAllocateFlags',desc='Bitmask of VkMemoryAllocateFlagBits',type='enums']
--
include::../api/flags/VkMemoryAllocateFlagsKHX.txt[]
include::../api/flags/VkMemoryAllocateFlags.txt[]
sname:VkMemoryAllocateFlagsKHX is a bitmask type for setting a mask of zero
or more slink:VkMemoryAllocateFlagBitsKHX.
ifdef::VK_KHR_device_group[]
or the equivalent
include::../api/flags/VkMemoryAllocateFlagsKHR.txt[]
endif::VK_KHR_device_group[]
sname:VkMemoryAllocateFlags is a bitmask type for setting a mask of zero or
more slink:VkMemoryAllocateFlagBits.
--
endif::VK_KHX_device_group[]
endif::VK_VERSION_1_1,VK_KHR_device_group[]
[open,refpage='vkFreeMemory',desc='Free GPU memory',type='protos']
[open,refpage='vkFreeMemory',desc='Free device memory',type='protos']
--
To free a memory object, call:
@ -1951,10 +2049,10 @@ to maintaining memory access ordering.
* [[VUID-vkMapMemory-memory-00682]]
pname:memory must: have been created with a memory type that reports
ename:VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT
ifdef::VK_KHX_device_group[]
ifdef::VK_KHR_device_group[]
* [[VUID-vkMapMemory-memory-00683]]
pname:memory must: not have been allocated with multiple instances.
endif::VK_KHX_device_group[]
endif::VK_KHR_device_group[]
****
include::../validity/protos/vkMapMemory.txt[]
@ -2004,6 +2102,14 @@ access, via <<synchronization-dependencies-available-and-visible,
availability operations>> from the ename:VK_ACCESS_HOST_WRITE_BIT
<<synchronization-access-types,access type>>.
Within each range described by pname:pMemoryRanges, each set of
pname:nonCoherentAtomSize bytes in that range is flushed if any byte in that
set has been written by the host since it was first mapped, or the last time
it was flushed.
If pname:pMemoryRanges includes sets of pname:nonCoherentAtomSize bytes
where no bytes have been written by the host, those bytes must: not be
flushed.
[[memory-device-unmap-does-not-flush]]
Unmapping non-coherent memory does not implicitly flush the mapped memory,
and host writes that have not been flushed may: not ever be visible to the
@ -2044,6 +2150,11 @@ host.
If a range of non-coherent memory is written by the host and then
invalidated without first being flushed, its contents are undefined.
Within each range described by pname:pMemoryRanges, each set of
pname:nonCoherentAtomSize bytes in that range is invalidated if any byte in
that set has been written by the device since it was first mapped, or the
last time it was invalidated.
[NOTE]
.Note
====
@ -2175,12 +2286,82 @@ with.
include::../validity/protos/vkGetDeviceMemoryCommitment.txt[]
--
ifdef::VK_KHX_device_group[]
ifdef::VK_VERSION_1_1[]
[[memory-protected-memory]]
=== Protected Memory
_Protected memory_ divides device memory into protected device memory and
unprotected device memory.
Protected memory adds the following concepts:
* Memory:
** Unprotected device memory, which can: be visible to the device and can:
be visible to the host
** Protected device memory, which can: be visible to the device but must:
not be visible to the host
* Resources:
** Unprotected images and unprotected buffers, to which unprotected memory
can: be bound
** Protected images and protected buffers, to which protected memory can:
be bound
* Command buffers:
** Unprotected command buffers, which can: be submitted to a device queue
to execute unprotected queue operations
** Protected command buffers, which can: be submitted to a
protected-capable device queue to execute protected queue operations
* Device queues:
** Unprotected device queues, to which unprotected command buffers can: be
submitted
** Protected-capable device queues, to which unprotected command buffers
or protected command buffers can: be submitted
* Queue submissions
** Unprotected queue submissions, through which unprotected command
buffers can: be submitted
** Protected queue submissions, through which protected command buffers
can: be submitted
* Queue operations
** Unprotected queue operations
*** Any read from or write to protected memory during unprotected queue
operations results in undefined behavior but is subject to the
inviolable rules below.
** Protected queue operations
*** Any write to unprotected memory during protected queue operations
results in undefined behavior but is subject to the inviolable rules
below.
*** Except for framebuffer-space pipeline stages, compute shader stage,
and transfer stage, any read from or write to protected memory during
protected queue operations results in undefined behavior but is
subject to the inviolable rules below.
*** Any queries during protected queue operations results in undefined
behavior but is subject to the inviolable rules below.
[[memory-protected-memory-undefined]]
==== Protected memory inviolable rules
Implementations must: ensure that correct usage or incorrect usage by an
application does not affect the integrity of the memory protection system.
The implementation must: guarantee that:
* Protected device memory must: not be visible to the host.
* Values written to unprotected device memory must: not be a function of
data from protected memory.
Incorrect usage by an application of the memory protection system results in
undefined behavior which may: include process termination or device loss.
endif::VK_VERSION_1_1[]
ifdef::VK_VERSION_1_1,VK_KHR_device_group[]
[[memory-peer-memory-features]]
=== Peer Memory Features
[open,refpage='vkGetDeviceGroupPeerMemoryFeaturesKHX',desc='Query supported peer memory features of a device',type='protos']
[open,refpage='vkGetDeviceGroupPeerMemoryFeatures',desc='Query supported peer memory features of a device',type='protos']
--
_Peer memory_ is memory that is allocated for a given physical device and
@ -2191,7 +2372,15 @@ device.
To determine how peer memory can: be accessed, call:
include::../api/protos/vkGetDeviceGroupPeerMemoryFeaturesKHX.txt[]
ifdef::VK_VERSION_1_1[]
include::../api/protos/vkGetDeviceGroupPeerMemoryFeatures.txt[]
endif::VK_VERSION_1_1[]
ifdef::VK_VERSION_1_1+VK_KHR_device_group[or the equivalent command]
ifdef::VK_KHR_device_group[]
include::../api/protos/vkGetDeviceGroupPeerMemoryFeaturesKHR.txt[]
endif::VK_KHR_device_group[]
* pname:device is the logical device that owns the memory.
* pname:heapIndex is the index of the memory heap from which the memory is
@ -2201,51 +2390,65 @@ include::../api/protos/vkGetDeviceGroupPeerMemoryFeaturesKHX.txt[]
* pname:remoteDeviceIndex is the device index of the physical device that
the memory is allocated for.
* pname:pPeerMemoryFeatures is a pointer to a bitmask of
elink:VkPeerMemoryFeatureFlagBitsKHX indicating which types of memory
elink:VkPeerMemoryFeatureFlagBits indicating which types of memory
accesses are supported for the combination of heap, local, and remote
devices.
.Valid Usage
****
* [[VUID-vkGetDeviceGroupPeerMemoryFeaturesKHX-heapIndex-00691]]
* [[VUID-vkGetDeviceGroupPeerMemoryFeatures-heapIndex-00691]]
pname:heapIndex must: be less than pname:memoryHeapCount
* [[VUID-vkGetDeviceGroupPeerMemoryFeaturesKHX-localDeviceIndex-00692]]
* [[VUID-vkGetDeviceGroupPeerMemoryFeatures-localDeviceIndex-00692]]
pname:localDeviceIndex must: be a valid device index
* [[VUID-vkGetDeviceGroupPeerMemoryFeaturesKHX-remoteDeviceIndex-00693]]
* [[VUID-vkGetDeviceGroupPeerMemoryFeatures-remoteDeviceIndex-00693]]
pname:remoteDeviceIndex must: be a valid device index
* [[VUID-vkGetDeviceGroupPeerMemoryFeaturesKHX-localDeviceIndex-00694]]
* [[VUID-vkGetDeviceGroupPeerMemoryFeatures-localDeviceIndex-00694]]
pname:localDeviceIndex must: not equal remoteDeviceIndex
****
include::../validity/protos/vkGetDeviceGroupPeerMemoryFeaturesKHX.txt[]
include::../validity/protos/vkGetDeviceGroupPeerMemoryFeatures.txt[]
--
[open,refpage='VkPeerMemoryFeatureFlagBitsKHX',desc='Bitmask specifying supported peer memory features',type='enums']
[open,refpage='VkPeerMemoryFeatureFlagBits',desc='Bitmask specifying supported peer memory features',type='enums']
--
Bits which may: be set in the value returned for
flink:vkGetDeviceGroupPeerMemoryFeaturesKHX::pname:pPeerMemoryFeatures,
flink:vkGetDeviceGroupPeerMemoryFeatures::pname:pPeerMemoryFeatures,
indicating the supported peer memory features, are:
include::../api/enums/VkPeerMemoryFeatureFlagBitsKHX.txt[]
include::../api/enums/VkPeerMemoryFeatureFlagBits.txt[]
* ename:VK_PEER_MEMORY_FEATURE_COPY_SRC_BIT_KHX indicates that the memory
can: be accessed as the source of a ftext:vkCmdCopyBuffer,
ifdef::VK_KHR_device_group[]
or the equivalent
include::../api/enums/VkPeerMemoryFeatureFlagBitsKHR.txt[]
endif::VK_KHR_device_group[]
* ename:VK_PEER_MEMORY_FEATURE_COPY_SRC_BIT indicates that the memory can:
be accessed as the source of a ftext:vkCmdCopyBuffer,
ftext:vkCmdCopyImage, ftext:vkCmdCopyBufferToImage, or
ftext:vkCmdCopyImageToBuffer command.
* ename:VK_PEER_MEMORY_FEATURE_COPY_DST_BIT_KHX indicates that the memory
can: be accessed as the destination of a ftext:vkCmdCopyBuffer,
* ename:VK_PEER_MEMORY_FEATURE_COPY_DST_BIT indicates that the memory can:
be accessed as the destination of a ftext:vkCmdCopyBuffer,
ftext:vkCmdCopyImage, ftext:vkCmdCopyBufferToImage, or
ftext:vkCmdCopyImageToBuffer command.
* ename:VK_PEER_MEMORY_FEATURE_GENERIC_SRC_BIT_KHX indicates that the
memory can: be read as any memory access type.
* ename:VK_PEER_MEMORY_FEATURE_GENERIC_DST_BIT_KHX indicates that the
memory can: be written as any memory access type.
* ename:VK_PEER_MEMORY_FEATURE_GENERIC_SRC_BIT indicates that the memory
can: be read as any memory access type.
* ename:VK_PEER_MEMORY_FEATURE_GENERIC_DST_BIT indicates that the memory
can: be written as any memory access type.
Shader atomics are considered to be writes.
ename:VK_PEER_MEMORY_FEATURE_COPY_DST_BIT_KHX must: be supported for all
host local heaps and for at least one device local heap.
[NOTE]
.Note
====
The peer memory features of a memory heap also apply to any accesses that
may: be performed during <<synchronization-image-layout-transitions, image
layout transitions>>.
====
ename:VK_PEER_MEMORY_FEATURE_COPY_DST_BIT must: be supported for all host
local heaps and for at least one device local heap.
If a device does not support a peer memory feature, it is still valid to use
a resource that includes both local and peer memory bindings with the
@ -2257,12 +2460,18 @@ but would scissor the rendering to only update local memory.
--
[open,refpage='VkPeerMemoryFeatureFlagsKHX',desc='Bitmask of VkPeerMemoryFeatureFlagBitsKHX',type='enums']
[open,refpage='VkPeerMemoryFeatureFlags',desc='Bitmask of VkPeerMemoryFeatureFlagBits',type='enums']
--
include::../api/flags/VkPeerMemoryFeatureFlagsKHX.txt[]
include::../api/flags/VkPeerMemoryFeatureFlags.txt[]
sname:VkPeerMemoryFeatureFlagsKHX is a bitmask type for setting a mask of
zero or more slink:VkPeerMemoryFeatureFlagBitsKHX.
ifdef::VK_KHR_device_group[]
or the equivalent
include::../api/flags/VkPeerMemoryFeatureFlagsKHR.txt[]
endif::VK_KHR_device_group[]
sname:VkPeerMemoryFeatureFlags is a bitmask type for setting a mask of zero
or more slink:VkPeerMemoryFeatureFlagBits.
--
endif::VK_KHX_device_group[]
endif::VK_VERSION_1_1,VK_KHR_device_group[]

58
doc/specs/vulkan/chapters/pipelines.txt
View File

@ -596,7 +596,7 @@ endif::VK_NV_glsl_shader[]
chapter
// The block of VU below come in alternate versions when the extension is
// enabled.
ifndef::VK_KHR_maintenance2[]
ifndef::VK_VERSION_1_1,VK_KHR_maintenance2[]
* [[VUID-VkGraphicsPipelineCreateInfo-subpass-00743]]
If rasterization is not disabled and pname:subpass uses a depth/stencil
attachment in pname:renderPass that has a layout of
@ -612,18 +612,18 @@ ifndef::VK_KHR_maintenance2[]
pname:passOp and pname:depthFailOp members of each of the pname:front
and pname:back members of pname:pDepthStencilState must: be
ename:VK_STENCIL_OP_KEEP
endif::VK_KHR_maintenance2[]
endif::VK_VERSION_1_1,VK_KHR_maintenance2[]
// The nested ifdefs are there in anticipation of the hoped-for day when the
// VU extractor and validation layers can handle VU with imbedded
// conditionals.
ifdef::VK_KHR_maintenance2[]
ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[]
* [[VUID-VkGraphicsPipelineCreateInfo-subpass-01756]]
If rasterization is not disabled and pname:subpass uses a depth/stencil
attachment in pname:renderPass that has a layout of
ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL
// ifdef::VK_KHR_maintenance2[]
or ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL_KHR
// endif::VK_KHR_maintenance2[]
// ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[]
or ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL
// endif::VK_VERSION_1_1,VK_KHR_maintenance2[]
in the sname:VkAttachmentReference defined by pname:subpass, the
pname:depthWriteEnable member of pname:pDepthStencilState must: be
ename:VK_FALSE
@ -631,14 +631,14 @@ ifdef::VK_KHR_maintenance2[]
If rasterization is not disabled and pname:subpass uses a depth/stencil
attachment in pname:renderPass that has a layout of
ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL
// ifdef::VK_KHR_maintenance2[]
or ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL_KHR
// endif::VK_KHR_maintenance2[]
// ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[]
or ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL
// endif::VK_VERSION_1_1,VK_KHR_maintenance2[]
in the sname:VkAttachmentReference defined by pname:subpass, the
pname:failOp, pname:passOp and pname:depthFailOp members of each of the
pname:front and pname:back members of pname:pDepthStencilState must: be
ename:VK_STENCIL_OP_KEEP
endif::VK_KHR_maintenance2[]
endif::VK_VERSION_1_1,VK_KHR_maintenance2[]
* [[VUID-VkGraphicsPipelineCreateInfo-subpass-00745]]
If rasterization is not disabled and the subpass uses color attachments,
then for each color attachment in the subpass the pname:blendEnable
@ -783,7 +783,7 @@ endif::VK_NV_framebuffer_mixed_samples[]
<<renderpass-noattachments, zero-attachment subpass>>
* [[VUID-VkGraphicsPipelineCreateInfo-subpass-00759]]
pname:subpass must: be a valid subpass within pname:renderPass
ifdef::VK_KHX_multiview[]
ifdef::VK_VERSION_1_1,VK_KHR_multiview[]
* [[VUID-VkGraphicsPipelineCreateInfo-renderPass-00760]]
If the pname:renderPass has multiview enabled and pname:subpass has more
than one bit set in the view mask and pname:multiviewTessellationShader
@ -801,21 +801,21 @@ ifdef::VK_KHX_multiview[]
If the pname:renderPass has multiview enabled, then all shaders must:
not include variables decorated with the code:Layer built-in decoration
in their interfaces.
endif::VK_KHX_multiview[]
ifdef::VK_KHX_device_group[]
endif::VK_VERSION_1_1,VK_KHR_multiview[]
ifdef::VK_VERSION_1_1,VK_KHR_device_group[]
* [[VUID-VkGraphicsPipelineCreateInfo-flags-00764]]
pname:flags must: not contain the
ename:VK_PIPELINE_CREATE_DISPATCH_BASE_KHX flag.
endif::VK_KHX_device_group[]
ifdef::VK_KHR_maintenance2[]
pname:flags must: not contain the ename:VK_PIPELINE_CREATE_DISPATCH_BASE
flag.
endif::VK_VERSION_1_1,VK_KHR_device_group[]
ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[]
* [[VUID-VkGraphicsPipelineCreateInfo-pStages-01565]]
If pname:pStages includes a fragment shader stage and an input
attachment was referenced by the
slink:VkRenderPassInputAttachmentAspectCreateInfoKHR at pname:renderPass
slink:VkRenderPassInputAttachmentAspectCreateInfo at pname:renderPass
create time, its shader code must: not read from any aspect that was not
specified in the pname:aspectMask of the corresponding
slink:VkInputAttachmentAspectReferenceKHR structure.
endif::VK_KHR_maintenance2[]
slink:VkInputAttachmentAspectReference structure.
endif::VK_VERSION_1_1,VK_KHR_maintenance2[]
* [[VUID-VkGraphicsPipelineCreateInfo-layout-01688]]
The number of resources in pname:layout accessible to each shader stage
that is used by the pipeline must: be less than or equal to
@ -856,16 +856,16 @@ include::../api/enums/VkPipelineCreateFlagBits.txt[]
or flink:vkCreateComputePipelines.
* ename:VK_PIPELINE_CREATE_DERIVATIVE_BIT specifies that the pipeline to
be created will be a child of a previously created parent pipeline.
ifdef::VK_KHX_device_group[]
ifdef::VK_KHX_multiview[]
* ename:VK_PIPELINE_CREATE_VIEW_INDEX_FROM_DEVICE_INDEX_BIT_KHX specifies
that any shader input variables decorated as code:DeviceIndex will be
ifdef::VK_VERSION_1_1,VK_KHR_device_group[]
ifdef::VK_VERSION_1_1,VK_KHR_multiview[]
* ename:VK_PIPELINE_CREATE_VIEW_INDEX_FROM_DEVICE_INDEX_BIT specifies that
any shader input variables decorated as code:DeviceIndex will be
assigned values as if they were decorated as code:ViewIndex.
endif::VK_KHX_multiview[]
* ename:VK_PIPELINE_CREATE_DISPATCH_BASE_KHX specifies that a compute
pipeline can: be used with flink:vkCmdDispatchBaseKHX with a non-zero
base workgroup.
endif::VK_KHX_device_group[]
endif::VK_VERSION_1_1,VK_KHR_multiview[]
* ename:VK_PIPELINE_CREATE_DISPATCH_BASE specifies that a compute pipeline
can: be used with flink:vkCmdDispatchBase with a non-zero base
workgroup.
endif::VK_VERSION_1_1,VK_KHR_device_group[]
It is valid to set both ename:VK_PIPELINE_CREATE_ALLOW_DERIVATIVES_BIT and
ename:VK_PIPELINE_CREATE_DERIVATIVE_BIT.

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

@ -420,7 +420,7 @@ instructions enabling the application to get direct access to the fragment
mask and the individual color fragment values.
[[vk-amd-shader-fragment-mask-diagram]]
image::images/fragment_mask.png[align="center",title="Fragment Mask",{fullimagewidth},align="center"]
image::images/fragment_mask.svg[align="center",title="Fragment Mask",{fullimagewidth},align="center"]
endif::VK_AMD_shader_fragment_mask[]
@ -525,7 +525,7 @@ clamped to the implementation-dependent sample location coordinate range
[eq]#[pname:sampleLocationCoordinateRange[0],pname:sampleLocationCoordinateRange[1]]#
that can: be queried by chaining the
slink:VkPhysicalDeviceSampleLocationsPropertiesEXT structure to the
pname:pNext chain of slink:VkPhysicalDeviceProperties2KHR.
pname:pNext chain of slink:VkPhysicalDeviceProperties2.
include::../validity/structs/VkSampleLocationEXT.txt[]
--

30
doc/specs/vulkan/chapters/queries.txt
View File

@ -183,14 +183,14 @@ reset prior to use.
Queries must: also be reset between uses.
Using a query that has not been reset will result in undefined behavior.
ifdef::VK_KHX_device_group[]
ifdef::VK_VERSION_1_1,VK_KHR_device_group[]
If a logical device includes multiple physical devices, then each command
that writes a query must: execute on a single physical device, and any call
to flink:vkCmdBeginQuery must: execute the corresponding flink:vkCmdEndQuery
command on the same physical device.
endif::VK_KHX_device_group[]
endif::VK_VERSION_1_1,VK_KHR_device_group[]
[open,refpage='vkCmdResetQueryPool',desc='Reset queries in a query pool',type='protos']
--
@ -245,7 +245,7 @@ A query must: either begin and end inside the same subpass of a render pass
instance, or must: both begin and end outside of a render pass instance
(i.e. contain entire render pass instances).
ifdef::VK_KHX_multiview[]
ifdef::VK_VERSION_1_1,VK_KHR_multiview[]
If queries are used while executing a render pass instance that has
multiview enabled, the query uses [eq]#N# consecutive query indices in the
@ -264,7 +264,7 @@ result.
Queries used with multiview rendering must: not span subpasses, i.e. they
must: begin and end in the same subpass.
endif::VK_KHX_multiview[]
endif::VK_VERSION_1_1,VK_KHR_multiview[]
[open,refpage='vkCmdBeginQuery',desc='Begin a query',type='protos']
--
@ -329,7 +329,10 @@ are executed are considered active for those secondary command buffers.
pname:pipelineStatistics indicate compute operations, the
sname:VkCommandPool that pname:commandBuffer was allocated from must:
support compute operations
ifdef::VK_KHX_multiview[]
ifdef::VK_VERSION_1_1[]
* pname:commandBuffer must: not be a protected command buffer
endif::VK_VERSION_1_1[]
ifdef::VK_VERSION_1_1,VK_KHR_multiview[]
* [[VUID-vkCmdBeginQuery-None-00806]]
All queries used by the command must: not be active
* [[VUID-vkCmdBeginQuery-None-00807]]
@ -339,7 +342,7 @@ ifdef::VK_KHX_multiview[]
sum of pname:query and the number of bits set in the current subpass's
view mask must: be less than or equal to the number of queries in
pname:queryPool
endif::VK_KHX_multiview[]
endif::VK_VERSION_1_1,VK_KHR_multiview[]
****
include::../validity/protos/vkCmdBeginQuery.txt[]
@ -400,7 +403,10 @@ of the query.
be <<queries-operation-active,active>>
* [[VUID-vkCmdEndQuery-query-00810]]
pname:query must: be less than the number of queries in pname:queryPool
ifdef::VK_KHX_multiview[]
ifdef::VK_VERSION_1_1[]
* pname:commandBuffer must: not be a protected command buffer
endif::VK_VERSION_1_1[]
ifdef::VK_VERSION_1_1,VK_KHR_multiview[]
* [[VUID-vkCmdEndQuery-None-00811]]
All queries used by the command must: be active
* [[VUID-vkCmdEndQuery-query-00812]]
@ -408,7 +414,7 @@ ifdef::VK_KHX_multiview[]
of pname:query and the number of bits set in the current subpass's view
mask must: be less than or equal to the number of queries in
pname:queryPool
endif::VK_KHX_multiview[]
endif::VK_VERSION_1_1,VK_KHR_multiview[]
****
include::../validity/protos/vkCmdEndQuery.txt[]
@ -999,7 +1005,7 @@ An example of such a comparison is determining the execution time of a
sequence of commands.
====
ifdef::VK_KHX_multiview[]
ifdef::VK_VERSION_1_1,VK_KHR_multiview[]
If fname:vkCmdWriteTimestamp is called while executing a render pass
instance that has multiview enabled, the timestamp uses [eq]#N# consecutive
@ -1024,7 +1030,7 @@ choice of one of the following behaviors:
In either case, the application can: sum the differences between all [eq]#N#
queries to determine the total execution time.
endif::VK_KHX_multiview[]
endif::VK_VERSION_1_1,VK_KHR_multiview[]
.Valid Usage
****
@ -1037,7 +1043,7 @@ endif::VK_KHX_multiview[]
* [[VUID-vkCmdWriteTimestamp-timestampValidBits-00829]]
The command pool's queue family must: support a non-zero
pname:timestampValidBits
ifdef::VK_KHX_multiview[]
ifdef::VK_VERSION_1_1,VK_KHR_multiview[]
* [[VUID-vkCmdWriteTimestamp-None-00830]]
All queries used by the command must: be unavailable
* [[VUID-vkCmdWriteTimestamp-query-00831]]
@ -1045,7 +1051,7 @@ ifdef::VK_KHX_multiview[]
the sum of pname:query and the number of bits set in the current
subpass's view mask must: be less than or equal to the number of queries
in pname:queryPool
endif::VK_KHX_multiview[]
endif::VK_VERSION_1_1,VK_KHR_multiview[]
****
include::../validity/protos/vkCmdWriteTimestamp.txt[]

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

@ -190,18 +190,18 @@ include::../api/structs/VkRenderPassCreateInfo.txt[]
must: not specify a pname:layout equal to
pname:VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL or
pname:VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL.
ifdef::VK_KHR_maintenance2[]
ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[]
* [[VUID-VkRenderPassCreateInfo-pAttachments-01566]]
For any member of pname:pAttachments with a pname:loadOp equal to
ename:VK_ATTACHMENT_LOAD_OP_CLEAR, the first use of that attachment
must: not specify a pname:layout equal to
pname:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL_KHR.
pname:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL.
* [[VUID-VkRenderPassCreateInfo-pAttachments-01567]]
For any member of pname:pAttachments with a pname:stencilLoadOp equal to
ename:VK_ATTACHMENT_LOAD_OP_CLEAR, the first use of that attachment
must: not specify a pname:layout equal to
pname:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL_KHR.
endif::VK_KHR_maintenance2[]
pname:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL.
endif::VK_VERSION_1_1,VK_KHR_maintenance2[]
* [[VUID-VkRenderPassCreateInfo-pDependencies-00837]]
For any element of pname:pDependencies, if the pname:srcSubpass is not
ename:VK_SUBPASS_EXTERNAL, all stage flags included in the
@ -227,20 +227,26 @@ sname:VkRenderPassCreateFlags is a bitmask type for setting a mask, but is
currently reserved for future use.
--
ifdef::VK_KHX_multiview[]
ifdef::VK_VERSION_1_1,VK_KHR_multiview[]
[[renderpass-multiview]]
[open,refpage='VkRenderPassMultiviewCreateInfoKHX',desc='Structure containing multiview info for all subpasses',type='structs']
[open,refpage='VkRenderPassMultiviewCreateInfo',desc='Structure containing multiview info for all subpasses',type='structs']
--
If the sname:VkRenderPassCreateInfo::pname:pNext chain includes a
sname:VkRenderPassMultiviewCreateInfoKHX structure, then that structure
sname:VkRenderPassMultiviewCreateInfo structure, then that structure
includes an array of view masks, view offsets, and correlation masks for the
render pass.
The sname:VkRenderPassMultiviewCreateInfoKHX structure is defined as:
The sname:VkRenderPassMultiviewCreateInfo structure is defined as:
include::../api/structs/VkRenderPassMultiviewCreateInfoKHX.txt[]
include::../api/structs/VkRenderPassMultiviewCreateInfo.txt[]
ifdef::VK_KHR_multiview[]
or the equivalent
include::../api/structs/VkRenderPassMultiviewCreateInfoKHR.txt[]
endif::VK_KHR_multiview[]
* pname:sType is the type of this structure.
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
@ -286,8 +292,8 @@ Some implementations may: not support multiview in conjunction with
<<features-features-multiview-tess,tessellation shaders>>.
[[renderpass-multiview-view-local]]
When multiview is enabled, the ename:VK_DEPENDENCY_VIEW_LOCAL_BIT_KHX bit in
a dependency can: be used to express a view-local dependency, meaning that
When multiview is enabled, the ename:VK_DEPENDENCY_VIEW_LOCAL_BIT bit in a
dependency can: be used to express a view-local dependency, meaning that
each view in the destination subpass depends on a single view in the source
subpass.
Unlike pipeline barriers, a subpass dependency can: potentially have a
@ -359,27 +365,27 @@ endif::VK_NVX_multiview_per_view_attributes[]
.Valid Usage
****
* [[VUID-VkRenderPassMultiviewCreateInfoKHX-subpassCount-00839]]
* [[VUID-VkRenderPassMultiviewCreateInfo-subpassCount-00839]]
If pname:subpassCount is not zero, pname:subpassCount must: be equal to
the pname:subpassCount in the sname:VkRenderPassCreateInfo structure at
the start of the chain
* [[VUID-VkRenderPassMultiviewCreateInfoKHX-dependencyCount-00840]]
* [[VUID-VkRenderPassMultiviewCreateInfo-dependencyCount-00840]]
If pname:dependencyCount is not zero, pname:dependencyCount must: be
equal to the pname:dependencyCount in the sname:VkRenderPassCreateInfo
structure at the start of the chain
* [[VUID-VkRenderPassMultiviewCreateInfoKHX-pCorrelationMasks-00841]]
* [[VUID-VkRenderPassMultiviewCreateInfo-pCorrelationMasks-00841]]
Each view index must: not be set in more than one element of
pname:pCorrelationMasks
* [[VUID-VkRenderPassMultiviewCreateInfoKHX-pViewOffsets-00842]]
* [[VUID-VkRenderPassMultiviewCreateInfo-pViewOffsets-00842]]
If an element of pname:pViewOffsets is non-zero, the corresponding
slink:VkSubpassDependency structure must: have different values of
pname:srcSubpass and pname:dstSubpass.
****
include::../validity/structs/VkRenderPassMultiviewCreateInfoKHX.txt[]
include::../validity/structs/VkRenderPassMultiviewCreateInfo.txt[]
--
endif::VK_KHX_multiview[]
endif::VK_VERSION_1_1,VK_KHR_multiview[]
[open,refpage='VkAttachmentDescription',desc='Structure specifying an attachment description',type='structs']
--
@ -445,7 +451,7 @@ pname:storeOp, pname:stencilStoreOp, and pname:stencilLoadOp are ignored,
and the attachment's memory contents will not be modified by execution of a
render pass instance.
ifdef::VK_KHX_multiview[]
ifdef::VK_VERSION_1_1,VK_KHR_multiview[]
The load and store operations apply on the first and last use of each view
in the render pass, respectively.
@ -454,7 +460,7 @@ subpass that uses it, then the load and store operations are ignored, and
the attachment's memory contents will not be modified by execution of a
render pass instance.
endif::VK_KHX_multiview[]
endif::VK_VERSION_1_1,VK_KHR_multiview[]
[[renderpass-precision]]
During a render pass instance, input/color attachments with color formats
@ -492,36 +498,42 @@ This is described in more detail below.
include::../validity/structs/VkAttachmentDescription.txt[]
--
ifdef::VK_KHR_maintenance2[]
ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[]
[open,refpage='VkRenderPassInputAttachmentAspectCreateInfoKHR',desc='Structure specifying, for a given subpass/input attachment pair, which aspect can: be read.',type='structs']
[open,refpage='VkRenderPassInputAttachmentAspectCreateInfo',desc='Structure specifying, for a given subpass/input attachment pair, which aspect can: be read.',type='structs']
--
To specify which aspects of an input attachment can: be read add a
slink:VkRenderPassInputAttachmentAspectCreateInfoKHR structure to the
slink:VkRenderPassInputAttachmentAspectCreateInfo structure to the
pname:pNext chain of the slink:VkRenderPassCreateInfo structure:
The sname:VkRenderPassInputAttachmentAspectCreateInfoKHR structure is
defined as:
The sname:VkRenderPassInputAttachmentAspectCreateInfo structure is defined
as:
include::../api/structs/VkRenderPassInputAttachmentAspectCreateInfo.txt[]
ifdef::VK_KHR_maintenance2[]
or the equivalent
include::../api/structs/VkRenderPassInputAttachmentAspectCreateInfoKHR.txt[]
endif::VK_KHR_maintenance2[]
* pname:sType is the type of this structure.
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
* pname:aspectReferenceCount is the number of elements in the
pAspectReferences array.
* pname:pAspectReferences points to an array of pname:aspectReferenceCount
number of slink:VkInputAttachmentAspectReferenceKHR structures
describing which aspect(s) can: be accessed for a given input attachment
within a given subpass.
number of slink:VkInputAttachmentAspectReference structures describing
which aspect(s) can: be accessed for a given input attachment within a
given subpass.
include::../validity/structs/VkRenderPassInputAttachmentAspectCreateInfoKHR.txt[]
include::../validity/structs/VkRenderPassInputAttachmentAspectCreateInfo.txt[]
--
[open,refpage='VkInputAttachmentAspectReferenceKHR',desc='Structure specifying a subpass/input attachment pair and an aspect mask that can: be read.',type='structs']
[open,refpage='VkInputAttachmentAspectReference',desc='Structure specifying a subpass/input attachment pair and an aspect mask that can: be read.',type='structs']
--
The sname:VkInputAttachmentAspectReferenceKHR structure specifies an aspect
The sname:VkInputAttachmentAspectReference structure specifies an aspect
mask for a specific input attachment of a specific subpass in the render
pass.
@ -529,7 +541,13 @@ The pname:subpass and pname:inputAttachment index into the render pass as:
pname:pCreateInfo::pname:pSubpasses[pname:subpass].pname:pInputAttachments[pname:inputAttachment]
include::../api/structs/VkInputAttachmentAspectReference.txt[]
ifdef::VK_KHR_maintenance2[]
or the equivalent
include::../api/structs/VkInputAttachmentAspectReferenceKHR.txt[]
endif::VK_KHR_maintenance2[]
* pname:subpass is an index into the pname:pSubpasses array of the parent
sname:VkRenderPassCreateInfo structure.
@ -550,7 +568,7 @@ include::../api/structs/VkInputAttachmentAspectReferenceKHR.txt[]
input attachment.
****
include::../validity/structs/VkInputAttachmentAspectReferenceKHR.txt[]
include::../validity/structs/VkInputAttachmentAspectReference.txt[]
--
ifdef::editing-notes[]
@ -570,7 +588,7 @@ An application must: only access the specified aspect(s).
An application can: access any aspect of an input attachment that does not
have a specified aspect mask.
endif::VK_KHR_maintenance2[]
endif::VK_VERSION_1_1,VK_KHR_maintenance2[]
[open,refpage='VkAttachmentDescriptionFlagBits',desc='Bitmask specifying additional properties of an attachment',type='enums']
--
@ -672,8 +690,8 @@ Attachments aliasing the same memory occurs in multiple ways:
* Attachments using views of distinct image subresources which are bound
to overlapping memory ranges.
.Note
[NOTE]
.Note
====
Render passes must: include subpass dependencies (either directly or via a
subpass dependency chain) between any two subpasses that operate on the same
@ -1003,8 +1021,8 @@ visibility operations>> defined by a subpass dependency affect the execution
of <<renderpass-layout-transitions, image layout transitions>> within the
render pass.
.Note
[NOTE]
.Note
====
For non-attachment resources, the memory dependency expressed by subpass
dependency is nearly identical to that of a slink:VkMemoryBarrier (with
@ -1093,26 +1111,25 @@ layouts as follows:
one of the pipeline stages in pname:dstStageMask, as specified in the
<<synchronization-access-types-supported, table of supported access
types>>.
ifdef::VK_KHX_multiview[]
ifdef::VK_VERSION_1_1,VK_KHR_multiview[]
* [[VUID-VkSubpassDependency-dependencyFlags-00870]]
If pname:dependencyFlags includes
ename:VK_DEPENDENCY_VIEW_LOCAL_BIT_KHX, then both pname:srcSubpass and
pname:dstSubpass must: not equal ename:VK_SUBPASS_EXTERNAL
If pname:dependencyFlags includes ename:VK_DEPENDENCY_VIEW_LOCAL_BIT,
then both pname:srcSubpass and pname:dstSubpass must: not equal
ename:VK_SUBPASS_EXTERNAL
* [[VUID-VkSubpassDependency-dependencyFlags-00871]]
If pname:dependencyFlags includes
ename:VK_DEPENDENCY_VIEW_LOCAL_BIT_KHX, then the render pass must: have
multiview enabled
If pname:dependencyFlags includes ename:VK_DEPENDENCY_VIEW_LOCAL_BIT,
then the render pass must: have multiview enabled
* [[VUID-VkSubpassDependency-srcSubpass-00872]]
If pname:srcSubpass equals pname:dstSubpass and that subpass has more
than one bit set in the view mask, then pname:dependencyFlags must:
include ename:VK_DEPENDENCY_VIEW_LOCAL_BIT_KHX
endif::VK_KHX_multiview[]
include ename:VK_DEPENDENCY_VIEW_LOCAL_BIT
endif::VK_VERSION_1_1,VK_KHR_multiview[]
****
include::../validity/structs/VkSubpassDependency.txt[]
--
ifdef::VK_KHX_multiview[]
ifdef::VK_VERSION_1_1,VK_KHR_multiview[]
When multiview is enabled, the execution of the multiple views of one
subpass may: not occur simultaneously or even back-to-back, and rather may:
@ -1142,7 +1159,7 @@ load op apply`" - it is on the first use of each view of an attachment, as
if each view were a separate attachment.
====
endif::VK_KHX_multiview[]
endif::VK_VERSION_1_1,VK_KHR_multiview[]
ifdef::editing-notes[]
[NOTE]
@ -1216,12 +1233,12 @@ subpass, and in the final layout at the end of the render pass.
Automatic layout transitions apply to the entire image subresource attached
to the framebuffer.
ifdef::VK_KHR_maintenance1[]
ifdef::VK_VERSION_1_1,VK_KHR_maintenance1[]
If the attachment view is a 2D or 2D array view of a 3D image, even if the
attachment view only refers to a subset of the slices of the selected mip
level of the 3D image, automatic layout transitions apply to the entire
subresource referenced which is the entire mip level in this case.
endif::VK_KHR_maintenance1[]
endif::VK_VERSION_1_1,VK_KHR_maintenance1[]
Automatic layout transitions away from the layout used in a subpass
happen-after the availability operations for all dependencies with that
@ -1356,10 +1373,10 @@ be in the
ifdef::VK_KHR_shared_presentable_image[]
ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR,
endif::VK_KHR_shared_presentable_image[]
ifdef::VK_KHR_maintenance2[]
ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL_KHR,
ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL_KHR,
endif::VK_KHR_maintenance2[]
ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[]
ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL,
ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL,
endif::VK_VERSION_1_1,VK_KHR_maintenance2[]
ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL, or
ename:VK_IMAGE_LAYOUT_GENERAL layout.
An attachment must: not be used as both a depth/stencil attachment and a
@ -1475,12 +1492,12 @@ include::../api/structs/VkFramebufferCreateInfo.txt[]
instance.
* pname:width, pname:height and pname:layers define the dimensions of the
framebuffer.
ifdef::VK_KHX_multiview[]
ifdef::VK_VERSION_1_1,VK_KHR_multiview[]
If the render pass uses multiview, then pname:layers must: be one and
each attachment requires a number of layers that is greater than the
maximum bit index set in the view mask in the subpasses in which it is
used.
endif::VK_KHX_multiview[]
endif::VK_VERSION_1_1,VK_KHR_multiview[]
Applications must: ensure that all accesses to memory that backs image
subresources used as attachments in a given renderpass instance either
@ -1488,30 +1505,30 @@ happen-before the <<renderpass-load-store-ops, load operations>> for those
attachments, or happen-after the <<renderpass-load-store-ops, store
operations>> for those attachments.
ifdef::VK_KHR_maintenance2[]
ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[]
For depth/stencil attachments, each aspect can: be used separately as
attachments and non-attachments as long as the non-attachment accesses are
also via an image subresource in either the
ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL_KHR layout
or the ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL_KHR
layout, and the attachment resource uses whichever of those two layouts the
image accesses do not.
ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL layout or
the ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL layout,
and the attachment resource uses whichever of those two layouts the image
accesses do not.
Use of non-attachment aspects in this case is only well defined if the
attachment is used in the subpass where the non-attachment access is being
made, or the layout of the image subresource is constant throughout the
entire render pass instance, including the pname:initialLayout and
pname:finalLayout.
endif::VK_KHR_maintenance2[]
endif::VK_VERSION_1_1,VK_KHR_maintenance2[]
[NOTE]
.Note
====
ifndef::VK_KHR_maintenance2[]
ifndef::VK_VERSION_1_1,VK_KHR_maintenance2[]
This restriction means
endif::VK_KHR_maintenance2[]
ifdef::VK_KHR_maintenance2[]
endif::VK_VERSION_1_1,VK_KHR_maintenance2[]
ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[]
These restrictions mean
endif::VK_KHR_maintenance2[]
endif::VK_VERSION_1_1,VK_KHR_maintenance2[]
that the render pass has full knowledge of all uses of all of the
attachments, so that the implementation is able to make correct decisions
about when and how to perform layout transitions, when to overlap execution
@ -1582,11 +1599,11 @@ slink:VkPipelineMultisampleStateCreateInfo::pname:rasterizationSamples.
* [[VUID-VkFramebufferCreateInfo-layers-00890]]
pname:layers must: be less than or equal to
sname:VkPhysicalDeviceLimits::pname:maxFramebufferLayers
ifdef::VK_KHR_maintenance1[]
ifdef::VK_VERSION_1_1,VK_KHR_maintenance1[]
* [[VUID-VkFramebufferCreateInfo-pAttachments-00891]]
Each element of pname:pAttachments that is a 2D or 2D array image view
taken from a 3D image must: not be a depth/stencil format
endif::VK_KHR_maintenance1[]
endif::VK_VERSION_1_1,VK_KHR_maintenance1[]
****
include::../validity/structs/VkFramebufferCreateInfo.txt[]
@ -1669,7 +1686,7 @@ record the commands for the first subpass of that render pass.
set
// The VU below comes in an alternate version when the extension is
// enabled.
ifndef::VK_KHR_maintenance2[]
ifndef::VK_VERSION_1_1,VK_KHR_maintenance2[]
* [[VUID-vkCmdBeginRenderPass-initialLayout-00896]]
If any of the pname:initialLayout or pname:finalLayout member of the
sname:VkAttachmentDescription structures or the pname:layout member of
@ -1681,27 +1698,27 @@ ifndef::VK_KHR_maintenance2[]
corresponding attachment image subresource of the framebuffer specified
in the pname:framebuffer member of pname:pRenderPassBegin must: have
been created with ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT set
endif::VK_KHR_maintenance2[]
endif::VK_VERSION_1_1,VK_KHR_maintenance2[]
// The nested ifdefs are there in anticipation of the hoped-for day when the
// VU extractor and validation layers can handle VU with imbedded
// conditionals.
ifdef::VK_KHR_maintenance2[]
ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[]
* [[VUID-vkCmdBeginRenderPass-initialLayout-01758]]
If any of the pname:initialLayout or pname:finalLayout member of the
sname:VkAttachmentDescription structures or the pname:layout member of
the sname:VkAttachmentReference structures specified when creating the
render pass specified in the pname:renderPass member of
pname:pRenderPassBegin is
// ifdef::VK_KHR_maintenance2[]
ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL_KHR,
ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL_KHR,
// endif::VK_KHR_maintenance2[]
// ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[]
ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL,
ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL,
// endif::VK_VERSION_1_1,VK_KHR_maintenance2[]
ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL, or
ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL then the
corresponding attachment image subresource of the framebuffer specified
in the pname:framebuffer member of pname:pRenderPassBegin must: have
been created with ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT set
endif::VK_KHR_maintenance2[]
endif::VK_VERSION_1_1,VK_KHR_maintenance2[]
* [[VUID-vkCmdBeginRenderPass-initialLayout-00897]]
If any of the pname:initialLayout or pname:finalLayout member of the
sname:VkAttachmentDescription structures or the pname:layout member of
@ -1786,12 +1803,12 @@ render area become undefined and shader side effects may: occur for
fragments outside the render area.
The render area must: be contained within the framebuffer dimensions.
ifdef::VK_KHX_multiview[]
ifdef::VK_VERSION_1_1,VK_KHR_multiview[]
When multiview is enabled, the resolve operation at the end of a subpass
applies to all views in the view mask.
endif::VK_KHX_multiview[]
endif::VK_VERSION_1_1,VK_KHR_multiview[]
[NOTE]
.Note
@ -1963,18 +1980,24 @@ include::../api/enums/VkSubpassContents.txt[]
--
ifdef::VK_KHX_device_group[]
ifdef::VK_VERSION_1_1,VK_KHR_device_group[]
[open,refpage='VkDeviceGroupRenderPassBeginInfoKHX',desc='Set the initial device mask and render areas for a render pass instance',type='structs']
[open,refpage='VkDeviceGroupRenderPassBeginInfo',desc='Set the initial device mask and render areas for a render pass instance',type='structs']
--
If the pname:pNext chain of slink:VkRenderPassBeginInfo includes a
sname:VkDeviceGroupRenderPassBeginInfoKHX structure, then that structure
sname:VkDeviceGroupRenderPassBeginInfo structure, then that structure
includes a device mask and set of render areas for the render pass instance.
The sname:VkDeviceGroupRenderPassBeginInfoKHX structure is defined as:
The sname:VkDeviceGroupRenderPassBeginInfo structure is defined as:
include::../api/structs/VkDeviceGroupRenderPassBeginInfoKHX.txt[]
include::../api/structs/VkDeviceGroupRenderPassBeginInfo.txt[]
ifdef::VK_KHR_device_group[]
or the equivalent
include::../api/structs/VkDeviceGroupRenderPassBeginInfoKHR.txt[]
endif::VK_KHR_device_group[]
* pname:sType is the type of this structure.
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
@ -2002,29 +2025,29 @@ region of attachments that are cleared by ename:VK_ATTACHMENT_LOAD_OP_CLEAR
and that are resolved into resolve attachments.
If this structure is not present, the render pass instance's device mask is
the value of slink:VkDeviceGroupCommandBufferBeginInfoKHX::pname:deviceMask.
the value of slink:VkDeviceGroupCommandBufferBeginInfo::pname:deviceMask.
If this structure is not present or if pname:deviceRenderAreaCount is zero,
slink:VkRenderPassBeginInfo::pname:renderArea is used for all physical
devices.
.Valid Usage
****
* [[VUID-VkDeviceGroupRenderPassBeginInfoKHX-deviceMask-00905]]
* [[VUID-VkDeviceGroupRenderPassBeginInfo-deviceMask-00905]]
pname:deviceMask must: be a valid device mask value
* [[VUID-VkDeviceGroupRenderPassBeginInfoKHX-deviceMask-00906]]
* [[VUID-VkDeviceGroupRenderPassBeginInfo-deviceMask-00906]]
pname:deviceMask must: not be zero
* [[VUID-VkDeviceGroupRenderPassBeginInfoKHX-deviceMask-00907]]
* [[VUID-VkDeviceGroupRenderPassBeginInfo-deviceMask-00907]]
pname:deviceMask must: be a subset of the command buffer's initial
device mask
* [[VUID-VkDeviceGroupRenderPassBeginInfoKHX-deviceRenderAreaCount-00908]]
* [[VUID-VkDeviceGroupRenderPassBeginInfo-deviceRenderAreaCount-00908]]
pname:deviceRenderAreaCount must: either be zero or equal to the number
of physical devices in the logical device.
****
include::../validity/structs/VkDeviceGroupRenderPassBeginInfoKHX.txt[]
include::../validity/structs/VkDeviceGroupRenderPassBeginInfo.txt[]
--
endif::VK_KHX_device_group[]
endif::VK_VERSION_1_1,VK_KHR_device_group[]
[open,refpage='vkGetRenderAreaGranularity',desc='Returns the granularity for optimal render area',type='protos']
--

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

File diff suppressed because it is too large Load Diff

195
doc/specs/vulkan/chapters/samplers.txt
View File

@ -103,9 +103,9 @@ include::../api/structs/VkSamplerCreateInfo.txt[]
ename:VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_BORDER.
** pname:anisotropyEnable must: be ename:VK_FALSE.
** pname:compareEnable must: be ename:VK_FALSE.
ifdef::VK_KHR_sampler_ycbcr_conversion[]
ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
** The sampler must: not enable sampler Y'C~B~C~R~ conversion.
endif::VK_KHR_sampler_ycbcr_conversion[]
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
* When pname:unnormalizedCoordinates is ename:VK_TRUE, images the sampler
is used with in the shader have the following requirements:
** The pname:viewType must: be either ename:VK_IMAGE_VIEW_TYPE_1D or
@ -170,14 +170,14 @@ pname:maxSamplerAllocationCount limit.
If pname:anisotropyEnable is ename:VK_TRUE, pname:maxAnisotropy must: be
between `1.0` and
sname:VkPhysicalDeviceLimits::pname:maxSamplerAnisotropy, inclusive
ifdef::VK_KHR_sampler_ycbcr_conversion[]
ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
* [[VUID-VkSamplerCreateInfo-minFilter-01645]]
If <<samplers-YCbCr-conversion,sampler Y'C~B~C~R~ conversion>> is
enabled and
ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_SEPARATE_RECONSTRUCTION_FILTER_BIT_KHR
ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_SEPARATE_RECONSTRUCTION_FILTER_BIT
is not set for the format, pname:minFilter and pname:magFilter must: be
equal to the sampler Y'C~B~C~R~ conversion's pname:chromaFilter
endif::VK_KHR_sampler_ycbcr_conversion[]
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
* [[VUID-VkSamplerCreateInfo-unnormalizedCoordinates-01072]]
If pname:unnormalizedCoordinates is ename:VK_TRUE, pname:minFilter and
pname:magFilter must: be equal
@ -202,7 +202,7 @@ endif::VK_KHR_sampler_ycbcr_conversion[]
If any of pname:addressModeU, pname:addressModeV or pname:addressModeW
are ename:VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_BORDER, pname:borderColor
must: be a valid elink:VkBorderColor value
ifdef::VK_KHR_sampler_ycbcr_conversion[]
ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
* [[VUID-VkSamplerCreateInfo-addressModeU-01646]]
If <<samplers-YCbCr-conversion,sampler Y'C~B~C~R~ conversion>> is
enabled, pname:addressModeU, pname:addressModeV, and pname:addressModeW
@ -215,7 +215,7 @@ ifdef::VK_EXT_sampler_filter_minmax[]
ename:VK_SAMPLER_REDUCTION_MODE_WEIGHTED_AVERAGE_EXT if
<<samplers-YCbCr-conversion,sampler Y'C~B~C~R~ conversion>> is enabled
endif::VK_EXT_sampler_filter_minmax[]
endif::VK_KHR_sampler_ycbcr_conversion[]
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
* [[VUID-VkSamplerCreateInfo-addressModeU-01079]]
If the `<<VK_KHR_sampler_mirror_clamp_to_edge>>` extension is not
enabled, pname:addressModeU, pname:addressModeV and pname:addressModeW
@ -415,16 +415,16 @@ include::../validity/protos/vkDestroySampler.txt[]
--
ifdef::VK_KHR_sampler_ycbcr_conversion[]
ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
[[samplers-YCbCr-conversion]]
== Sampler Y'C~B~C~R~ conversion
[open,refpage='VkSamplerYcbcrConversionInfoKHR',desc='Structure specifying Y\'CbCr conversion to a sampler or image view',type='structs']
[open,refpage='VkSamplerYcbcrConversionInfo',desc='Structure specifying Y\'CbCr conversion to a sampler or image view',type='structs']
--
To create a sampler with Y'C~B~C~R~ conversion enabled, add a
slink:VkSamplerYcbcrConversionInfoKHR to the pname:pNext chain of the
slink:VkSamplerYcbcrConversionInfo to the pname:pNext chain of the
slink:VkSamplerCreateInfo structure.
To create a sampler Y'C~B~C~R~ conversion, the
<<features-features-sampler-YCbCr-conversion,pname:samplerYcbcrConversion
@ -433,50 +433,70 @@ Conversion must: be fixed at pipeline creation time, through use of a
combined image sampler with an immutable sampler in
sname:VkDescriptorSetLayoutBinding.
A slink:VkSamplerYcbcrConversionInfoKHR must: be provided for samplers to be
A slink:VkSamplerYcbcrConversionInfo must: be provided for samplers to be
used with image views that access ename:VK_IMAGE_ASPECT_COLOR_BIT if the
format appears in <<features-formats-requiring-sampler-ycbcr-conversion>>.
The sname:VkSamplerYcbcrConversionInfoKHR structure is defined as:
The sname:VkSamplerYcbcrConversionInfo structure is defined as:
include::../api/structs/VkSamplerYcbcrConversionInfo.txt[]
ifdef::VK_KHR_sampler_ycbcr_conversion[]
or the equivalent
include::../api/structs/VkSamplerYcbcrConversionInfoKHR.txt[]
endif::VK_KHR_sampler_ycbcr_conversion[]
* pname:sType is the type of this structure.
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
* pname:conversion is a slink:VkSamplerYcbcrConversionKHR handle created
with flink:vkCreateSamplerYcbcrConversionKHR.
* pname:conversion is a slink:VkSamplerYcbcrConversion handle created with
flink:vkCreateSamplerYcbcrConversion.
include::../validity/structs/VkSamplerYcbcrConversionInfoKHR.txt[]
include::../validity/structs/VkSamplerYcbcrConversionInfo.txt[]
--
[open,refpage='VkSamplerYcbcrConversionKHR',desc='',type='handles']
[open,refpage='VkSamplerYcbcrConversion',desc='',type='handles']
--
A sampler Y'C~B~C~R~ conversion is an opaque representation of a
device-specific sampler Y'C~B~C~R~ conversion description, represented as a
sname:VkSamplerYcbcrConversionKHR handle:
sname:VkSamplerYcbcrConversion handle:
include::../api/handles/VkSamplerYcbcrConversion.txt[]
ifdef::VK_KHR_sampler_ycbcr_conversion[]
or the equivalent
include::../api/handles/VkSamplerYcbcrConversionKHR.txt[]
endif::VK_KHR_sampler_ycbcr_conversion[]
--
[open,refpage='vkCreateSamplerYcbcrConversionKHR',desc='Create a new Ycbcr conversion',type='protos']
[open,refpage='vkCreateSamplerYcbcrConversion',desc='Create a new Ycbcr conversion',type='protos']
--
To create a slink:VkSamplerYcbcrConversionKHR, call:
To create a slink:VkSamplerYcbcrConversion, call:
ifdef::VK_VERSION_1_1[]
include::../api/protos/vkCreateSamplerYcbcrConversion.txt[]
endif::VK_VERSION_1_1[]
ifdef::VK_VERSION_1_1+VK_KHR_sampler_ycbcr_conversion[or the equivalent command]
ifdef::VK_KHR_sampler_ycbcr_conversion[]
include::../api/protos/vkCreateSamplerYcbcrConversionKHR.txt[]
endif::VK_KHR_sampler_ycbcr_conversion[]
* pname:device is the logical device that creates the sampler Y'C~B~C~R~
conversion.
* pname:pCreateInfo is a pointer to an instance of the
slink:VkSamplerYcbcrConversionCreateInfoKHR specifying the requested
slink:VkSamplerYcbcrConversionCreateInfo specifying the requested
sampler Y'C~B~C~R~ conversion.
* pname:pAllocator controls host memory allocation as described in the
<<memory-allocation, Memory Allocation>> chapter.
* pname:pYcbcrConversion points to a slink:VkSamplerYcbcrConversionKHR
handle in which the resulting sampler Y'C~B~C~R~ conversion is returned.
* pname:pYcbcrConversion points to a slink:VkSamplerYcbcrConversion handle
in which the resulting sampler Y'C~B~C~R~ conversion is returned.
The interpretation of the configured sampler Y'C~B~C~R~ conversion is
described in more detail in <<textures-sampler-YCbCr-conversion,the
@ -490,16 +510,22 @@ Operations>> chapter.
conversion feature>> must: be enabled
****
include::../validity/protos/vkCreateSamplerYcbcrConversionKHR.txt[]
include::../validity/protos/vkCreateSamplerYcbcrConversion.txt[]
--
[open,refpage='VkSamplerYcbcrConversionCreateInfoKHR',desc='Structure specifying the parameters of the newly created conversion',type='structs']
[open,refpage='VkSamplerYcbcrConversionCreateInfo',desc='Structure specifying the parameters of the newly created conversion',type='structs']
--
The sname:VkSamplerYcbcrConversionCreateInfoKHR structure is defined as:
The sname:VkSamplerYcbcrConversionCreateInfo structure is defined as:
include::../api/structs/VkSamplerYcbcrConversionCreateInfo.txt[]
ifdef::VK_KHR_sampler_ycbcr_conversion[]
or the equivalent
include::../api/structs/VkSamplerYcbcrConversionCreateInfoKHR.txt[]
endif::VK_KHR_sampler_ycbcr_conversion[]
* pname:sType is the type of this structure.
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
@ -525,8 +551,8 @@ include::../api/structs/VkSamplerYcbcrConversionCreateInfoKHR.txt[]
* pname:forceExplicitReconstruction can: be used to ensure that
reconstruction is done explicitly, if supported.
.Note
[NOTE]
.Note
====
Setting pname:forceExplicitReconstruction to ename:VK_TRUE may: have a
performance penalty on implementations where explicit reconstruction is not
@ -539,18 +565,17 @@ the default mode of operation.
pname:format must: not be ename:VK_FORMAT_UNDEFINED
* [[VUID-VkSamplerYcbcrConversionCreateInfoKHR-format-01650]]
pname:format must: support
ename:VK_FORMAT_FEATURE_MIDPOINT_CHROMA_SAMPLES_BIT_KHR or
ename:VK_FORMAT_FEATURE_COSITED_CHROMA_SAMPLES_BIT_KHR
ename:VK_FORMAT_FEATURE_MIDPOINT_CHROMA_SAMPLES_BIT or
ename:VK_FORMAT_FEATURE_COSITED_CHROMA_SAMPLES_BIT
* [[VUID-VkSamplerYcbcrConversionCreateInfoKHR-xChromaOffset-01651]]
If the format does not support
ename:VK_FORMAT_FEATURE_COSITED_CHROMA_SAMPLES_BIT_KHR,
pname:xChromaOffset and pname:yChromaOffset must: not be
ename:VK_CHROMA_LOCATION_COSITED_EVEN_KHR
ename:VK_FORMAT_FEATURE_COSITED_CHROMA_SAMPLES_BIT, pname:xChromaOffset
and pname:yChromaOffset must: not be
ename:VK_CHROMA_LOCATION_COSITED_EVEN
* [[VUID-VkSamplerYcbcrConversionCreateInfoKHR-xChromaOffset-01652]]
If the format does not support
ename:VK_FORMAT_FEATURE_MIDPOINT_CHROMA_SAMPLES_BIT_KHR,
pname:xChromaOffset and pname:yChromaOffset must: not be
ename:VK_CHROMA_LOCATION_MIDPOINT_KHR
ename:VK_FORMAT_FEATURE_MIDPOINT_CHROMA_SAMPLES_BIT, pname:xChromaOffset
and pname:yChromaOffset must: not be ename:VK_CHROMA_LOCATION_MIDPOINT
* [[VUID-VkSamplerYcbcrConversionCreateInfoKHR-format-01653]]
pname:format must: represent unsigned normalized values (i.e. the format
must be a etext:UNORM format)
@ -568,7 +593,7 @@ the default mode of operation.
ename:VK_COMPONENT_SWIZZLE_IDENTITY
* [[VUID-VkSamplerYcbcrConversionCreateInfoKHR-ycbcrModel-01655]]
If pname:ycbcrModel is not
ename:VK_SAMPLER_YCBCR_MODEL_CONVERSION_RGB_IDENTITY_KHR, then
ename:VK_SAMPLER_YCBCR_MODEL_CONVERSION_RGB_IDENTITY, then
pname:components.r, pname:components.g, and pname:components.b must:
correspond to channels of the pname:format; that is, pname:components.r,
pname:components.g, and pname:components.b must: not be
@ -577,15 +602,15 @@ the default mode of operation.
consequence of <<textures-conversion-to-rgba,conversion to RGBA>>
* [[VUID-VkSamplerYcbcrConversionCreateInfoKHR-forceExplicitReconstruction-01656]]
If the format does not support
ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_CHROMA_RECONSTRUCTION_EXPLICIT_FORCEABLE_BIT_KHR,
ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_CHROMA_RECONSTRUCTION_EXPLICIT_FORCEABLE_BIT,
pname:forceExplicitReconstruction must: be FALSE
* [[VUID-VkSamplerYcbcrConversionCreateInfoKHR-chromaFilter-01657]]
If the format does not support
ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_LINEAR_FILTER_BIT_KHR,
ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_LINEAR_FILTER_BIT,
pname:chromaFilter must: be ename:VK_FILTER_NEAREST
****
include::../validity/structs/VkSamplerYcbcrConversionCreateInfoKHR.txt[]
include::../validity/structs/VkSamplerYcbcrConversionCreateInfo.txt[]
If pname:chromaFilter is ename:VK_FILTER_NEAREST, chroma samples are
reconstructed to luma channel resolution using nearest-neighbour sampling.
@ -596,29 +621,35 @@ Operations>> chapter.
--
[open,refpage='VkSamplerYcbcrModelConversionKHR',desc='Color model component of a color space',type='enums']
[open,refpage='VkSamplerYcbcrModelConversion',desc='Color model component of a color space',type='enums']
--
elink:VkSamplerYcbcrModelConversionKHR defines the conversion from the
source color model to the shader color model.
elink:VkSamplerYcbcrModelConversion defines the conversion from the source
color model to the shader color model.
Possible values are:
include::../api/enums/VkSamplerYcbcrModelConversionKHR.txt[]
include::../api/enums/VkSamplerYcbcrModelConversion.txt[]
* ename:VK_SAMPLER_YCBCR_MODEL_CONVERSION_RGB_IDENTITY_KHR specifies that
the input values to the conversion are unmodified.
* ename:VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_IDENTITY_KHR specifies no
ifdef::VK_KHR_sampler_ycbcr_conversion[]
or the equivalent
include::../api/enums/VkSamplerYcbcrModelConversionKHR.txt[]
endif::VK_KHR_sampler_ycbcr_conversion[]
* ename:VK_SAMPLER_YCBCR_MODEL_CONVERSION_RGB_IDENTITY specifies that the
input values to the conversion are unmodified.
* ename:VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_IDENTITY specifies no
model conversion but the inputs are range expanded as for Y'C~B~C~R~.
* ename:VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_709_KHR specifies the
color model conversion from Y'C~B~C~R~ to R'G'B' defined in BT.709 and
* ename:VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_709 specifies the color
model conversion from Y'C~B~C~R~ to R'G'B' defined in BT.709 and
described in the "`BT.709 Y’C~B~C~R~ conversion`" section of the
<<data-format,Khronos Data Format Specification>>.
* ename:VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_601_KHR specifies the
color model conversion from Y'C~B~C~R~ to R'G'B' defined in BT.601 and
* ename:VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_601 specifies the color
model conversion from Y'C~B~C~R~ to R'G'B' defined in BT.601 and
described in the "`BT.601 Y’C~B~C~R~ conversion`" section of the
<<data-format,Khronos Data Format Specification>>.
* ename:VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_2020_KHR specifies the
color model conversion from Y'C~B~C~R~ to R'G'B' defined in BT.2020 and
* ename:VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_2020 specifies the color
model conversion from Y'C~B~C~R~ to R'G'B' defined in BT.2020 and
described in the "`BT.2020 Y’C~B~C~R~ conversion`" section of the
<<data-format,Khronos Data Format Specification>>.
@ -635,7 +666,7 @@ the input to the sampler Y'C~B~C~R~ range expansion and model conversion:
These rules reflect the mapping of channels after the channel swizzle
operation (controlled by
slink:VkSamplerYcbcrConversionCreateInfoKHR::pname:components).
slink:VkSamplerYcbcrConversionCreateInfo::pname:components).
[NOTE]
.Note
@ -651,21 +682,27 @@ implemented as ename:VK_FORMAT_R8G8B8A8_UNORM with a component mapping:
--
[open,refpage='VkSamplerYcbcrRangeKHR',desc='Range of encoded values in a color space',type='enums']
[open,refpage='VkSamplerYcbcrRange',desc='Range of encoded values in a color space',type='enums']
--
The elink:VkSamplerYcbcrRangeKHR enum describes whether color channels are
The elink:VkSamplerYcbcrRange enum describes whether color channels are
encoded using the full range of numerical values or whether values are
reserved for headroom and foot room.
elink:VkSamplerYcbcrRangeKHR is defined as:
elink:VkSamplerYcbcrRange is defined as:
include::../api/enums/VkSamplerYcbcrRange.txt[]
ifdef::VK_KHR_sampler_ycbcr_conversion[]
or the equivalent
include::../api/enums/VkSamplerYcbcrRangeKHR.txt[]
endif::VK_KHR_sampler_ycbcr_conversion[]
* ename:VK_SAMPLER_YCBCR_RANGE_ITU_FULL_KHR indicates that the full range
of the encoded values are valid and interpreted according to the ITU
"`full range`" quantization rules.
* ename:VK_SAMPLER_YCBCR_RANGE_ITU_NARROW_KHR indicates that headroom and
foot room are reserved in the numerical range of encoded values, and the
* ename:VK_SAMPLER_YCBCR_RANGE_ITU_FULL indicates that the full range of
the encoded values are valid and interpreted according to the ITU "`full
range`" quantization rules.
* ename:VK_SAMPLER_YCBCR_RANGE_ITU_NARROW indicates that headroom and foot
room are reserved in the numerical range of encoded values, and the
remaining values are expanded according to the ITU "`narrow range`"
quantization rules.
@ -674,35 +711,47 @@ The formulae for these conversions is described in the
Expansion>> section of the <<textures,Image Operations>> chapter.
No range modification takes place if pname:ycbcrModel is
ename:VK_SAMPLER_YCBCR_MODEL_CONVERSION_RGB_IDENTITY_KHR; the
pname:ycbcrRange field of sname:VkSamplerYcbcrConversionCreateInfoKHR is
ignored in this case.
ename:VK_SAMPLER_YCBCR_MODEL_CONVERSION_RGB_IDENTITY; the pname:ycbcrRange
field of sname:VkSamplerYcbcrConversionCreateInfo is ignored in this case.
--
[open,refpage='VkChromaLocationKHR',desc='Position of downsampled chroma samples',type='enums']
[open,refpage='VkChromaLocation',desc='Position of downsampled chroma samples',type='enums']
--
The elink:VkChromaLocationKHR enum, which defines the location of
downsampled chroma channel samples relative to the luma samples, is defined
as:
The elink:VkChromaLocation enum, which defines the location of downsampled
chroma channel samples relative to the luma samples, is defined as:
include::../api/enums/VkChromaLocation.txt[]
ifdef::VK_KHR_sampler_ycbcr_conversion[]
or the equivalent
include::../api/enums/VkChromaLocationKHR.txt[]
endif::VK_KHR_sampler_ycbcr_conversion[]
* ename:VK_CHROMA_LOCATION_COSITED_EVEN_KHR indicates that downsampled
chroma samples are aligned with luma samples with even coordinates.
* ename:VK_CHROMA_LOCATION_MIDPOINT_KHR indicates that downsampled chroma
* ename:VK_CHROMA_LOCATION_COSITED_EVEN indicates that downsampled chroma
samples are aligned with luma samples with even coordinates.
* ename:VK_CHROMA_LOCATION_MIDPOINT indicates that downsampled chroma
samples are located half way between each even luma sample and the
nearest higher odd luma sample.
--
[open,refpage='vkDestroySamplerYcbcrConversionKHR',desc='Destroy a created Y\'CbCr conversion',type='protos']
[open,refpage='vkDestroySamplerYcbcrConversion',desc='Destroy a created Y\'CbCr conversion',type='protos']
--
To destroy a sampler Y'C~B~C~R~ conversion, call:
ifdef::VK_VERSION_1_1[]
include::../api/protos/vkDestroySamplerYcbcrConversion.txt[]
endif::VK_VERSION_1_1[]
ifdef::VK_VERSION_1_1+VK_KHR_sampler_ycbcr_conversion[or the equivalent command]
ifdef::VK_KHR_sampler_ycbcr_conversion[]
include::../api/protos/vkDestroySamplerYcbcrConversionKHR.txt[]
endif::VK_KHR_sampler_ycbcr_conversion[]
* pname:device is the logical device that destroys the Y'C~B~C~R~
conversion.
@ -710,8 +759,8 @@ include::../api/protos/vkDestroySamplerYcbcrConversionKHR.txt[]
* pname:pAllocator controls host memory allocation as described in the
<<memory-allocation, Memory Allocation>> chapter.
include::../validity/protos/vkDestroySamplerYcbcrConversionKHR.txt[]
include::../validity/protos/vkDestroySamplerYcbcrConversion.txt[]
--
endif::VK_KHR_sampler_ycbcr_conversion[]
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]

132
doc/specs/vulkan/chapters/shaders.txt
View File

@ -141,10 +141,9 @@ endif::VK_NV_glsl_shader[]
Capabilities>> section of the <<spirvenv-capabilities,SPIR-V
Environment>> appendix
* [[VUID-VkShaderModuleCreateInfo-pCode-01091]]
If pname:pCode declares any of the capabilities that are listed as not
required by the implementation, the relevant feature must: be enabled,
as listed in the <<spirvenv-capabilities-table,SPIR-V Environment>>
appendix
If pname:pCode declares any of the capabilities listed as optional: in
the <<spirvenv-capabilities-table,SPIR-V Environment>> appendix, the
corresponding feature(s) must: be enabled.
****
include::../validity/structs/VkShaderModuleCreateInfo.txt[]
@ -352,10 +351,10 @@ stage is always the first shader stage in the graphics pipeline.
A vertex shader must: be executed at least once for each vertex specified by
a draw command.
ifdef::VK_KHX_multiview[]
ifdef::VK_VERSION_1_1,VK_KHR_multiview[]
If the subpass includes multiple views in its view mask, the shader may: be
invoked separately for each view.
endif::VK_KHX_multiview[]
endif::VK_VERSION_1_1,VK_KHR_multiview[]
During execution, the shader is presented with the index of the vertex and
instance for which it has been invoked.
Input variables declared in the vertex shader are filled by the
@ -402,10 +401,10 @@ sname:VkPhysicalDeviceLimits::pname:maxTessellationPatchSize.
A tessellation control shader is invoked at least once for each _output_
vertex in a patch.
ifdef::VK_KHX_multiview[]
ifdef::VK_VERSION_1_1,VK_KHR_multiview[]
If the subpass includes multiple views in its view mask, the shader may: be
invoked separately for each view.
endif::VK_KHX_multiview[]
endif::VK_VERSION_1_1,VK_KHR_multiview[]
Inputs to the tessellation control shader are generated by the vertex
shader.
@ -437,10 +436,10 @@ and outputs a single vertex and its associated data.
A tessellation evaluation shader is invoked at least once for each unique
vertex generated by the tessellator.
ifdef::VK_KHX_multiview[]
ifdef::VK_VERSION_1_1,VK_KHR_multiview[]
If the subpass includes multiple views in its view mask, the shader may: be
invoked separately for each view.
endif::VK_KHX_multiview[]
endif::VK_VERSION_1_1,VK_KHR_multiview[]
[[shaders-geometry]]
@ -463,10 +462,10 @@ from the invocation count of the geometry shader specified by the
code:OpExecutionMode code:Invocations in the geometry shader.
If the invocation count is not specified, then a default of one invocation
is executed.
ifdef::VK_KHX_multiview[]
ifdef::VK_VERSION_1_1,VK_KHR_multiview[]
If the subpass includes multiple views in its view mask, the shader may: be
invoked separately for each view.
endif::VK_KHX_multiview[]
endif::VK_VERSION_1_1,VK_KHR_multiview[]
[[shaders-fragment]]
@ -488,10 +487,10 @@ For each fragment generated by rasterization, a fragment shader may: be
invoked.
A fragment shader must: not be invoked if the <<fragops-early,Early
Per-Fragment Tests>> cause it to have no coverage.
ifdef::VK_KHX_multiview[]
ifdef::VK_VERSION_1_1,VK_KHR_multiview[]
If the subpass includes multiple views in its view mask, the shader may: be
invoked separately for each view.
endif::VK_KHX_multiview[]
endif::VK_VERSION_1_1,VK_KHR_multiview[]
Furthermore, if it is determined that a fragment generated as the result of
rasterizing a first primitive will have its outputs entirely overwritten by
@ -690,6 +689,111 @@ including any helper invocations generated by that primitive.
Derivatives are undefined for a sampled image instruction if the instruction
is in flow control that is not uniform across the derivative group.
ifdef::VK_VERSION_1_1[]
[[shaders-subgroup]]
== Subgroups
A _subgroup_ (see the subsection ``Control Flow'' of section 2 of the SPIR-V
1.3 Revision 1 specification) is a set of invocations that can synchronize
and share data with each other efficiently.
An invocation group is partitioned into one or more subgroups.
Subgroup operations are divided into various categories as described in
elink:VkSubgroupFeatureFlagBits.
[[shaders-subgroup-basic]]
=== Basic Subgroup Operations
The basic subgroup operations allow two classes of functionality within
shaders
- elect and barrier.
Invocations within a subgroup can: choose a single invocation to perform
some task for the subgroup as a whole using elect.
Invocations within a subgroup can: perform a subgroup barrier to ensure the
ordering of execution or memory accesses within a subgroup.
Barriers can: be performed on buffer memory accesses, code:WorkgroupLocal
memory accesses, and image memory accesses to ensure that any results
written are visible by other invocations within the subgroup.
An code:OpControlBarrier can: also be used to perform a full execution
control barrier.
A full execution control barrier will ensure that each active invocation
within the subgroup reaches a point of execution before any are allowed to
continue.
[[shaders-subgroup-vote]]
=== Vote Subgroup Operations
The vote subgroup operations allow invocations within a subgroup to compare
values across a subgroup.
The types of votes enabled are:
* Do all active subgroup invocations agree that an expression is true?
* Do any active subgroup invocations evaluate an expression to true?
* Do all active subgroup invocations have the same value of an expression?
[NOTE]
.Note
====
These operations are useful in combination with control flow in that they
allow for developers to check whether conditions match across the subgroup
and choose potentially faster code-paths in these cases.
====
[[shaders-subgroup-arithmetic]]
=== Arithmetic Subgroup Operations
The arithmetic subgroup operations allow invocations to perform scan and
reduction operations across a subgroup.
For reduction operations, each invocation in a subgroup will obtain the same
result of these arithmetic operations applied across the subgroup.
For scan operations, each invocation in the subgroup will perform an
inclusive or exclusive scan, cumulatively applying the operation across the
invocations in a subgroup in linear order.
The operations supported are add, mul, min, max, and, or, xor.
[[shaders-subgroup-ballot]]
=== Ballot Subgroup Operations
The ballot subgroup operations allow invocations to perform more complex
votes across the subgroup.
The ballot functionality allows all invocations within a subgroup to provide
a boolean value and get as a result what each invocation provided as their
boolean value.
The broadcast functionality allows values to be broadcast from an invocation
to all other invocations within the subgroup, given that the invocation to
be broadcast from is known at pipeline creation time.
[[shaders-subgroup-shuffle]]
=== Shuffle Subgroup Operations
The shuffle subgroup operations allow invocations to read values from other
invocations within a subgroup.
[[shaders-subgroup-shuffle-relative]]
=== Shuffle Relative Subgroup Operations
The shuffle relative subgroup operations allow invocations to read values
from other invocations within the subgroup relative to the current
invocation in the group.
The relative operations supported allow data to be shifted up and down
through the invocations within a subgroup.
[[shaders-subgroup-clustered]]
=== Clustered Subgroup Operations
The clustered subgroup operations allow invocations to perform an operation
among partitions of a subgroup, such that the operation is only performed
within the subgroup invocations within a partition.
The operations supported are add, mul, min, max, and, or, xor.
[[shaders-subgroup-quad]]
=== Quad Subgroup Operations
The quad subgroup operations allow clusters of 4 invocations (a quad), to
share data efficiently with each other.
endif::VK_VERSION_1_1[]
ifdef::VK_EXT_validation_cache[]
[[shaders-validation-cache]]
== Validation Cache

197
doc/specs/vulkan/chapters/sparsemem.txt
View File

@ -98,7 +98,7 @@ slink:VkPhysicalDeviceFeatures.
+
Implementations supporting pname:sparseResidencyImage2D are only required:
to support sparse 2D, single-sampled images.
Support is not required: for sparse 3D and MSAA images and is enabled via
Support for sparse 3D and MSAA images is optional: and can: be enabled via
pname:sparseResidencyImage3D, pname:sparseResidency2Samples,
pname:sparseResidency4Samples, pname:sparseResidency8Samples, and
pname:sparseResidency16Samples.
@ -222,14 +222,14 @@ Enumeration>> for instructions for retrieving physical device properties.
ifdef::implementation-guide[]
.Implementor's Note
****
For hardware that cannot: natively handle access to unbound regions of a
resource, the implementation may: allocate and bind memory to the unbound
regions.
For implementations that cannot: natively handle access to unbound regions
of a resource, the implementation may: allocate and bind memory to the
unbound regions.
Reads and writes to unbound regions will access the implementation-managed
memory instead of causing a hardware fault.
memory instead.
Given that reads of unbound regions are undefined in this scenario,
implementations may: use the same physical memory for unbound regions of
implementations may: use the same physical memory for all unbound regions of
multiple resources within the same process.
****
endif::implementation-guide[]
@ -538,24 +538,23 @@ resource.
The <<features-features-sparseResidency,sparse residency>> features allow
sparse resources to be used even when not all pages are bound to memory.
Hardware that supports access to unbound pages without causing a fault may:
support pname:residencyNonResidentStrict.
Implementations that support access to unbound pages without causing a fault
may: support pname:residencyNonResidentStrict.
Not faulting on access to unbound pages is not enough to support
pname:residencyNonResidentStrict.
An implementation must: also guarantee that reads after writes to unbound
regions of the resource always return data for the read as if the memory
contains zeros.
Depending on the cache implementation of the hardware this may: not always
be possible.
Depending on any caching hierarchy of the implementation this may: not
always be possible.
Hardware that does not fault, but does not guarantee correct read values
will not require dummy pages, but also must: not support
pname:residencyNonResidentStrict.
Any implementation that does not fault, but does not guarantee correct read
values must: not support pname:residencyNonResidentStrict.
Hardware that cannot: access unbound pages without causing a fault will
require the implementation to bind the entire device virtual address range
to physical memory.
Any implementation that cannot: access unbound pages without causing a fault
will require the implementation to bind the entire device virtual address
range to physical memory.
Any pages that the application does not bind to memory may: be bound to one
(or more) "`dummy`" physical page(s) allocated by the implementation.
Given the following properties:
@ -574,8 +573,8 @@ resource).
The byte size reported in sname:VkMemoryRequirements::pname:size must: be
greater than or equal to the amount of physical memory required: to fully
populate the resource.
Some hardware requires "`holes`" in the device virtual address range that
are never accessed.
Some implementations require "`holes`" in the device virtual address range
that are never accessed.
These holes may: be included in the pname:size reported for the resource.
Including or not including the device virtual address holes in the resource
@ -597,9 +596,9 @@ endif::editing-notes[]
* If the holes are included in the size, this bind function becomes very
easy.
In most cases the pname:resourceOffset is simply a device virtual
address offset and the implementation does not require any sophisticated
logic to determine what device virtual address to bind.
The cost is that the application can: allocate more physical memory for
address offset and the implementation can easily determine what device
virtual address to bind.
The cost is that the application may: allocate more physical memory for
the resource than it needs.
* If the holes are not included in the size, the application can: allocate
less physical memory than otherwise for the resource.
@ -887,45 +886,59 @@ ename:VK_IMAGE_ASPECT_STENCIL_BIT.
include::../validity/protos/vkGetPhysicalDeviceSparseImageFormatProperties.txt[]
--
ifdef::VK_KHR_get_physical_device_properties2[]
ifdef::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[]
[open,refpage='vkGetPhysicalDeviceSparseImageFormatProperties2KHR',desc='Retrieve properties of an image format applied to sparse images',type='protos']
[open,refpage='vkGetPhysicalDeviceSparseImageFormatProperties2',desc='Retrieve properties of an image format applied to sparse images',type='protos']
--
fname:vkGetPhysicalDeviceSparseImageFormatProperties2KHR returns an array of
slink:VkSparseImageFormatProperties2KHR.
fname:vkGetPhysicalDeviceSparseImageFormatProperties2 returns an array of
slink:VkSparseImageFormatProperties2.
Each element will describe properties for one set of image aspects that are
bound simultaneously in the image.
This is usually one element for each aspect in the image, but for
interleaved depth/stencil images there is only one element describing the
combined aspects.
ifdef::VK_VERSION_1_1[]
include::../api/protos/vkGetPhysicalDeviceSparseImageFormatProperties2.txt[]
endif::VK_VERSION_1_1[]
ifdef::VK_VERSION_1_1+VK_KHR_get_physical_device_properties2[or the equivalent command]
ifdef::VK_KHR_get_physical_device_properties2[]
include::../api/protos/vkGetPhysicalDeviceSparseImageFormatProperties2KHR.txt[]
endif::VK_KHR_get_physical_device_properties2[]
* pname:physicalDevice is the physical device from which to query the
sparse image capabilities.
* pname:pFormatInfo is a pointer to a structure of type
slink:VkPhysicalDeviceSparseImageFormatInfo2KHR containing input
parameters to the command.
slink:VkPhysicalDeviceSparseImageFormatInfo2 containing input parameters
to the command.
* pname:pPropertyCount is a pointer to an integer related to the number of
sparse format properties available or queried, as described below.
* pname:pProperties is either `NULL` or a pointer to an array of
slink:VkSparseImageFormatProperties2KHR structures.
slink:VkSparseImageFormatProperties2 structures.
fname:vkGetPhysicalDeviceSparseImageFormatProperties2KHR behaves identically
to flink:vkGetPhysicalDeviceSparseImageFormatProperties, with the ability to
fname:vkGetPhysicalDeviceSparseImageFormatProperties2 behaves identically to
flink:vkGetPhysicalDeviceSparseImageFormatProperties, with the ability to
return extended information by adding extension structures to the
pname:pNext chain of its pname:pProperties parameter.
include::../validity/protos/vkGetPhysicalDeviceSparseImageFormatProperties2KHR.txt[]
include::../validity/protos/vkGetPhysicalDeviceSparseImageFormatProperties2.txt[]
--
[open,refpage='VkPhysicalDeviceSparseImageFormatInfo2KHR',desc='Structure specifying sparse image format inputs',type='structs']
[open,refpage='VkPhysicalDeviceSparseImageFormatInfo2',desc='Structure specifying sparse image format inputs',type='structs']
--
The sname:VkPhysicalDeviceSparseImageFormatInfo2KHR structure is defined as:
The sname:VkPhysicalDeviceSparseImageFormatInfo2 structure is defined as:
include::../api/structs/VkPhysicalDeviceSparseImageFormatInfo2.txt[]
ifdef::VK_KHR_get_physical_device_properties2[]
or the equivalent
include::../api/structs/VkPhysicalDeviceSparseImageFormatInfo2KHR.txt[]
endif::VK_KHR_get_physical_device_properties2[]
* pname:sType is the type of this structure.
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
@ -938,7 +951,7 @@ include::../api/structs/VkPhysicalDeviceSparseImageFormatInfo2KHR.txt[]
.Valid Usage
****
* [[VUID-VkPhysicalDeviceSparseImageFormatInfo2KHR-samples-01095]]
* [[VUID-VkPhysicalDeviceSparseImageFormatInfo2-samples-01095]]
pname:samples must: be a bit value that is set in
sname:VkImageFormatProperties::pname:sampleCounts returned by
fname:vkGetPhysicalDeviceImageFormatProperties with pname:format,
@ -947,15 +960,21 @@ include::../api/structs/VkPhysicalDeviceSparseImageFormatInfo2KHR.txt[]
sname:VkImageCreateInfo::pname:flags when the image is created
****
include::../validity/structs/VkPhysicalDeviceSparseImageFormatInfo2KHR.txt[]
include::../validity/structs/VkPhysicalDeviceSparseImageFormatInfo2.txt[]
--
[open,refpage='VkSparseImageFormatProperties2KHR',desc='Structure specifying sparse image format properties',type='structs']
[open,refpage='VkSparseImageFormatProperties2',desc='Structure specifying sparse image format properties',type='structs']
--
The sname:VkSparseImageFormatProperties2KHR structure is defined as:
The sname:VkSparseImageFormatProperties2 structure is defined as:
include::../api/structs/VkSparseImageFormatProperties2.txt[]
ifdef::VK_KHR_get_physical_device_properties2[]
or the equivalent
include::../api/structs/VkSparseImageFormatProperties2KHR.txt[]
endif::VK_KHR_get_physical_device_properties2[]
* pname:sType is the type of this structure.
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
@ -963,10 +982,10 @@ include::../api/structs/VkSparseImageFormatProperties2KHR.txt[]
slink:VkSparseImageFormatProperties which is populated with the same
values as in flink:vkGetPhysicalDeviceSparseImageFormatProperties.
include::../validity/structs/VkSparseImageFormatProperties2KHR.txt[]
include::../validity/structs/VkSparseImageFormatProperties2.txt[]
--
endif::VK_KHR_get_physical_device_properties2[]
endif::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[]
[[sparsememory-resource-creation]]
@ -1125,13 +1144,85 @@ It is legal for an implementation to report a larger value in
sname:VkMemoryRequirements::pname:size than would be obtained by adding
together memory sizes for all sname:VkSparseImageMemoryRequirements returned
by fname:vkGetImageSparseMemoryRequirements.
This may: occur when the hardware requires unused padding in the address
range describing the resource.
This may: occur when the implementation requires unused padding in the
address range describing the resource.
====
include::../validity/protos/vkGetImageSparseMemoryRequirements.txt[]
--
ifdef::VK_VERSION_1_1,VK_KHR_get_memory_requirements2[]
[open,refpage='vkGetImageSparseMemoryRequirements2',desc='Query the memory requirements for a sparse image',type='protos']
--
To query sparse memory requirements for an image, call:
ifdef::VK_VERSION_1_1[]
include::../api/protos/vkGetImageSparseMemoryRequirements2.txt[]
endif::VK_VERSION_1_1[]
ifdef::VK_VERSION_1_1+VK_KHR_get_memory_requirements2[or the equivalent command]
ifdef::VK_KHR_get_memory_requirements2[]
include::../api/protos/vkGetImageSparseMemoryRequirements2KHR.txt[]
endif::VK_KHR_get_memory_requirements2[]
* pname:device is the logical device that owns the image.
* pname:pInfo is a pointer to an instance of the
sname:VkImageSparseMemoryRequirementsInfo2 structure containing
parameters required for the memory requirements query.
* pname:pSparseMemoryRequirementCount is a pointer to an integer related
to the number of sparse memory requirements available or queried, as
described below.
* pname:pSparseMemoryRequirements is either `NULL` or a pointer to an
array of sname:VkSparseImageMemoryRequirements2 structures.
include::../validity/protos/vkGetImageSparseMemoryRequirements2.txt[]
--
[open,refpage='VkImageSparseMemoryRequirementsInfo2',desc='(None)',type='structs']
--
The sname:VkImageSparseMemoryRequirementsInfo2 structure is defined as:
include::../api/structs/VkImageSparseMemoryRequirementsInfo2.txt[]
ifdef::VK_KHR_get_memory_requirements2[]
or the equivalent
include::../api/structs/VkImageSparseMemoryRequirementsInfo2KHR.txt[]
endif::VK_KHR_get_memory_requirements2[]
* pname:sType is the type of this structure.
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
* pname:image is the image to query.
include::../validity/structs/VkImageSparseMemoryRequirementsInfo2.txt[]
--
[open,refpage='VkSparseImageMemoryRequirements2',desc='(None)',type='structs']
--
The sname:VkSparseImageMemoryRequirements2 structure is defined as:
include::../api/structs/VkSparseImageMemoryRequirements2.txt[]
ifdef::VK_KHR_get_memory_requirements2[]
or the equivalent
include::../api/structs/VkSparseImageMemoryRequirements2KHR.txt[]
endif::VK_KHR_get_memory_requirements2[]
* pname:sType is the type of this structure.
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
* pname:memoryRequirements is a structure of type
slink:VkSparseImageMemoryRequirements describing the memory requirements
of the sparse image.
include::../validity/structs/VkSparseImageMemoryRequirements2.txt[]
--
endif::VK_VERSION_1_1,VK_KHR_get_memory_requirements2[]
[[sparsememory-resource-binding]]
=== Binding Resource Memory
@ -1599,19 +1690,25 @@ include::../api/structs/VkBindSparseInfo.txt[]
include::../validity/structs/VkBindSparseInfo.txt[]
--
ifdef::VK_KHX_device_group[]
ifdef::VK_VERSION_1_1,VK_KHR_device_group[]
[open,refpage='VkDeviceGroupBindSparseInfoKHX',desc='Structure indicating which instances are bound',type='structs']
[open,refpage='VkDeviceGroupBindSparseInfo',desc='Structure indicating which instances are bound',type='structs']
--
If the pname:pNext chain of slink:VkBindSparseInfo includes a
sname:VkDeviceGroupBindSparseInfoKHX structure, then that structure includes
sname:VkDeviceGroupBindSparseInfo structure, then that structure includes
device indices specifying which instance of the resources and memory are
bound.
The sname:VkDeviceGroupBindSparseInfoKHX structure is defined as:
The sname:VkDeviceGroupBindSparseInfo structure is defined as:
include::../api/structs/VkDeviceGroupBindSparseInfoKHX.txt[]
include::../api/structs/VkDeviceGroupBindSparseInfo.txt[]
ifdef::VK_KHR_device_group[]
or the equivalent
include::../api/structs/VkDeviceGroupBindSparseInfoKHR.txt[]
endif::VK_KHR_device_group[]
* pname:sType is the type of this structure.
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
@ -1630,19 +1727,19 @@ pname:memoryDeviceIndex are assumed to be zero.
.Valid Usage
****
* [[VUID-VkDeviceGroupBindSparseInfoKHX-resourceDeviceIndex-01118]]
* [[VUID-VkDeviceGroupBindSparseInfo-resourceDeviceIndex-01118]]
pname:resourceDeviceIndex and pname:memoryDeviceIndex must: both be
valid device indices.
* [[VUID-VkDeviceGroupBindSparseInfoKHX-memoryDeviceIndex-01119]]
* [[VUID-VkDeviceGroupBindSparseInfo-memoryDeviceIndex-01119]]
Each memory allocation bound in this batch must: have allocated an
instance for pname:memoryDeviceIndex.
****
include::../validity/structs/VkDeviceGroupBindSparseInfoKHX.txt[]
include::../validity/structs/VkDeviceGroupBindSparseInfo.txt[]
--
endif::VK_KHX_device_group[]
endif::VK_VERSION_1_1,VK_KHR_device_group[]
[[sparsememory-examples]]

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

File diff suppressed because it is too large Load Diff

68
doc/specs/vulkan/chapters/tessellation.txt
View File

@ -76,25 +76,25 @@ invocations that share a line).
Each vertex produced by the tessellator has an associated (u,v,w) or (u,v)
position in a normalized parameter space, with parameter values in the range
[eq]#[0,1]#, as illustrated
ifdef::VK_KHR_maintenance2[]
ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[]
in figures <<img-tessellation-topology-ul>> and
<<img-tessellation-topology-ll>>.
The domain space can: have either an upper-left or lower-left origin,
selected by the pname:domainOrigin member of
slink:VkPipelineTessellationDomainOriginStateCreateInfoKHR.
endif::VK_KHR_maintenance2[]
ifndef::VK_KHR_maintenance2[]
slink:VkPipelineTessellationDomainOriginStateCreateInfo.
endif::VK_VERSION_1_1,VK_KHR_maintenance2[]
ifndef::VK_VERSION_1_1,VK_KHR_maintenance2[]
in figure <<img-tessellation-topology-ul>>.
The domain space has an upper-left origin.
endif::VK_KHR_maintenance2[]
endif::VK_VERSION_1_1,VK_KHR_maintenance2[]
[[img-tessellation-topology-ul]]
image::images/tessparamUL.svg[align="center",title="Domain parameterization for tessellation primitive modes (upper-left origin)",{fullimagewidth}]
ifdef::VK_KHR_maintenance2[]
ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[]
[[img-tessellation-topology-ll]]
image::images/tessparam.svg[align="center",title="Domain parameterization for tessellation primitive modes (lower-left origin)",{fullimagewidth}]
endif::VK_KHR_maintenance2[]
endif::VK_VERSION_1_1,VK_KHR_maintenance2[]
.Caption
****
@ -192,11 +192,11 @@ triangle have counter-clockwise ordering if
is negative, and clockwise ordering if [eq]#a# is positive.
[eq]#u~i~# and [eq]#v~i~# are the [eq]#u# and [eq]#v# coordinates in
normalized parameter space of the [eq]##i##th vertex of the triangle.
ifdef::VK_KHR_maintenance2[]
ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[]
If the tessellation domain has a lower-left origin, the vertices of a
triangle have counter-clockwise ordering if [eq]#a# is positive, and
clockwise ordering if [eq]#a# is negative.
endif::VK_KHR_maintenance2[]
endif::VK_VERSION_1_1,VK_KHR_maintenance2[]
[NOTE]
.Note
@ -412,8 +412,8 @@ image::images/innerquad.svg[align="center",title="Inner Quad Tessellation",{full
****
In the <<img-innerquad,Inner Quad Tessellation>> diagram, inner quad
tessellation levels of (a) [eq]#(4,2)# and (b) [eq]#(7,4)# are shown.
Gray regions in figure (b) depict the 10 inner rectangles, each of which
will be subdivided into two triangles.
The regions highlighted in red in figure (b) depict the 10 inner rectangles,
each of which will be subdivided into two triangles.
Solid black circles depict vertices on the boundary of the outer and inner
rectangles, where the inner rectangle on the top figure is degenerate (a
single line segment).
@ -523,45 +523,57 @@ sname:VkPipelineTessellationStateCreateFlags is a bitmask type for setting a
mask, but is currently reserved for future use.
--
ifdef::VK_KHR_maintenance2[]
ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[]
[open,refpage='VkPipelineTessellationDomainOriginStateCreateInfoKHR',desc='Structure specifying the orientation of the tessellation domain',type='structs']
[open,refpage='VkPipelineTessellationDomainOriginStateCreateInfo',desc='Structure specifying the orientation of the tessellation domain',type='structs']
--
The sname:VkPipelineTessellationDomainOriginStateCreateInfoKHR structure is
The sname:VkPipelineTessellationDomainOriginStateCreateInfo structure is
defined as:
include::../api/structs/VkPipelineTessellationDomainOriginStateCreateInfo.txt[]
ifdef::VK_KHR_maintenance2[]
or the equivalent
include::../api/structs/VkPipelineTessellationDomainOriginStateCreateInfoKHR.txt[]
endif::VK_KHR_maintenance2[]
* pname:sType is the type of this structure.
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
* pname:domainOrigin controls the origin of the tessellation domain space,
and is of type elink:VkTessellationDomainOriginKHR.
and is of type elink:VkTessellationDomainOrigin.
If the sname:VkPipelineTessellationDomainOriginStateCreateInfoKHR structure
is included in the pname:pNext chain of
If the sname:VkPipelineTessellationDomainOriginStateCreateInfo structure is
included in the pname:pNext chain of
slink:VkPipelineTessellationStateCreateInfo, it controls the origin of the
tessellation domain.
If this structure is not present, it is as if pname:domainOrigin were
ename:VK_TESSELLATION_DOMAIN_ORIGIN_UPPER_LEFT_KHR.
ename:VK_TESSELLATION_DOMAIN_ORIGIN_UPPER_LEFT.
include::../validity/structs/VkPipelineTessellationDomainOriginStateCreateInfoKHR.txt[]
include::../validity/structs/VkPipelineTessellationDomainOriginStateCreateInfo.txt[]
--
[open,refpage='VkTessellationDomainOriginKHR',desc='Enum describing tessellation domain origin',type='enums']
[open,refpage='VkTessellationDomainOrigin',desc='Enum describing tessellation domain origin',type='enums']
--
The possible tessellation domain origins are specified by the
elink:VkTessellationDomainOriginKHR enumeration:
elink:VkTessellationDomainOrigin enumeration:
include::../api/enums/VkTessellationDomainOrigin.txt[]
ifdef::VK_KHR_maintenance2[]
or the equivalent
include::../api/enums/VkTessellationDomainOriginKHR.txt[]
endif::VK_KHR_maintenance2[]
* ename:VK_TESSELLATION_DOMAIN_ORIGIN_UPPER_LEFT_KHR indicates that the
origin of the domain space is in the upper left corner, as shown in
figure <<img-tessellation-topology-ul>>.
* ename:VK_TESSELLATION_DOMAIN_ORIGIN_LOWER_LEFT_KHR indicates that the
origin of the domain space is in the lower left corner, as shown in
figure <<img-tessellation-topology-ll>>.
* ename:VK_TESSELLATION_DOMAIN_ORIGIN_UPPER_LEFT indicates that the origin
of the domain space is in the upper left corner, as shown in figure
<<img-tessellation-topology-ul>>.
* ename:VK_TESSELLATION_DOMAIN_ORIGIN_LOWER_LEFT indicates that the origin
of the domain space is in the lower left corner, as shown in figure
<<img-tessellation-topology-ll>>.
This enum affects how the code:VertexOrderCw and code:VertexOrderCcw
tessellation execution modes are interpreted, since the winding is defined
@ -569,4 +581,4 @@ relative to the orientation of the domain.
--
endif::VK_KHR_maintenance2[]
endif::VK_VERSION_1_1,VK_KHR_maintenance2[]

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

@ -125,7 +125,7 @@ n is the sample index and is taken from the code:Sample image operand.
For all coordinate types, unused coordinates are assigned a value of zero.
[[textures-texel-coordinate-systems-diagrams]]
image::images/vulkantexture0.png[align="center",title="Texel Coordinate Systems",{fullimagewidth}]
image::images/vulkantexture0.svg[align="center",title="Texel Coordinate Systems",{fullimagewidth}]
The Texel Coordinate Systems - For the example shown of an 8{times}4 texel
two dimensional image.
@ -155,7 +155,7 @@ two dimensional image.
four texels selected by the offset are [eq]#i~0~j'~0~#,
[eq]#i~1~j'~0~#, [eq]#i~0~j'~1~#, and [eq]#i~1~j'~1~#.
ifdef::VK_KHR_sampler_ycbcr_conversion[]
ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
[NOTE]
.Note
====
@ -164,9 +164,9 @@ For formats with reduced-resolution channels, [eq]#{DeltaUpper}~i~# and
highest-resolution channel, and therefore may be divided by two relative to
the unnormalized coordinate space of the lower-resolution channels.
====
endif::VK_KHR_sampler_ycbcr_conversion[]
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
image::images/vulkantexture1.png[align="center",title="Texel Coordinate Systems",{fullimagewidth}]
image::images/vulkantexture1.svg[align="center",title="Texel Coordinate Systems",{fullimagewidth}]
The Texel Coordinate Systems - For the example shown of an 8{times}4 texel
two dimensional image.
@ -326,10 +326,10 @@ They include the following steps, which are performed in the listed order:
* <<textures-depth-compare-operation,Depth comparison>>
* <<textures-conversion-to-rgba,Conversion to RGBA>>
* <<textures-component-swizzle,Component swizzle>>
ifdef::VK_KHR_sampler_ycbcr_conversion[]
ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
* <<textures-chroma-reconstruction,Chroma reconstruction>>
* <<textures-sampler-YCbCr-conversion,Y'C~B~C~R~ conversion>>
endif::VK_KHR_sampler_ycbcr_conversion[]
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
For texel input instructions involving multiple texels (for sampling or
gathering), these steps are applied for each texel that is used in the
@ -338,12 +338,12 @@ Depending on the type of image instruction, other steps are conditionally
performed between these steps or involving multiple coordinate or texel
values.
ifdef::VK_KHR_sampler_ycbcr_conversion[]
ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
If <<textures-chroma-reconstruction,Chroma Reconstruction>> is implicit,
<<textures-texel-filtering, Texel Filtering>> instead takes place during
chroma reconstruction, before <<textures-sampler-YCbCr-conversion,sampler
Y'C~B~C~R~ conversion>> occurs.
endif::VK_KHR_sampler_ycbcr_conversion[]
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
[[textures-input-validation]]
@ -422,7 +422,7 @@ These cases include:
not equal to ename:VK_SAMPLE_COUNT_1_BIT, the instruction must: have
code:MS = 1.
ifdef::VK_KHR_sampler_ycbcr_conversion[]
ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
Only code:OpImageSample* and code:OpImageSparseSample* can: be used with a
sampler that enables <<samplers-YCbCr-conversion,sampler Y'C~B~C~R~
conversion>>.
@ -434,7 +434,7 @@ code:OpImageSparse*code:Gather must: not be used with a sampler that enables
The code:ConstOffset and code:Offset operands must: not be used with a
sampler that enables <<samplers-YCbCr-conversion,sampler Y'C~B~C~R~
conversion>>.
endif::VK_KHR_sampler_ycbcr_conversion[]
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
[[textures-integer-coordinate-validation]]
@ -540,7 +540,7 @@ If the texel reads from an unbound region of a sparse image, the texel is a
_sparse unbound texel_, and processing continues with
<<textures-texel-replacement,texel replacement>>.
ifdef::VK_KHR_sampler_ycbcr_conversion[]
ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
[[textures-layout-validation]]
==== Layout Validation
@ -550,7 +550,7 @@ If all planes of a _disjoint_ _multi-planar_ image are not in the same
<<samplers-YCbCr-conversion,sampler Y'C~B~C~R~ conversion>>, the result of
texel reads is undefined.
endif::VK_KHR_sampler_ycbcr_conversion[]
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
[[textures-format-conversion]]
=== Format Conversion
@ -640,23 +640,11 @@ components in the image format
| Four component color format | [eq]#C~rgba~ = (B~r~,B~g~,B~b~,B~a~)#
|====
If the read operation is from a buffer resource, and the
pname:robustBufferAccess feature is enabled, an invalid texel is replaced as
described <<features-features-robustBufferAccess,here>>.
If the pname:robustBufferAccess feature is not enabled, the value of an
invalid texel is undefined.
ifdef::editing-notes[]
[NOTE]
.editing-note
====
(Bill) This is not currently catching this significant case.
For opImageFetch, which fetches from an *image* not a buffer, the result is
defined if pname:robustBufferAccess is enabled.
====
endif::editing-notes[]
The value returned by a read of an invalid texel is undefined, unless that
read operation is from a buffer resource and the pname:robustBufferAccess
feature is enabled.
In that case, an invalid texel is replaced as described by the
<<features-features-robustBufferAccess,pname:robustBufferAccess feature>>.
If the
slink:VkPhysicalDeviceSparseProperties::pname:residencyNonResidentStrict
@ -664,8 +652,8 @@ property is ename:VK_TRUE, a sparse unbound texel is replaced with 0 or 0.0
values for integer and floating-point components of the image format,
respectively.
If pname:residencyNonResidentStrict is ename:VK_FALSE, the read must: be
safe, but the value of the sparse unbound texel is undefined.
If pname:residencyNonResidentStrict is ename:VK_FALSE, the value of the
sparse unbound texel is undefined.
[[textures-depth-compare-operation]]
@ -729,12 +717,12 @@ where [eq]#one = 1.0f# for floating-point formats and depth aspects, and
[[textures-component-swizzle]]
=== Component Swizzle
ifndef::VK_KHR_sampler_ycbcr_conversion[]
ifndef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
All texel input instructions apply a _swizzle_ based on the
elink:VkComponentSwizzle enums in the pname:components member of the
slink:VkImageViewCreateInfo structure for the image being read.
endif::VK_KHR_sampler_ycbcr_conversion[]
ifdef::VK_KHR_sampler_ycbcr_conversion[]
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
All texel input instructions apply a _swizzle_ based on:
* the elink:VkComponentSwizzle enums in the pname:components member of the
@ -742,11 +730,11 @@ All texel input instructions apply a _swizzle_ based on:
<<samplers-YCbCr-conversion,sampler Y'C~B~C~R~ conversion>> is not
enabled, and
* the elink:VkComponentSwizzle enums in the pname:components member of the
slink:VkSamplerYcbcrConversionCreateInfoKHR structure for the
slink:VkSamplerYcbcrConversionCreateInfo structure for the
<<samplers-YCbCr-conversion,sampler Y'C~B~C~R~ conversion>> if sampler
Y'C~B~C~R~ conversion is enabled.
endif::VK_KHR_sampler_ycbcr_conversion[]
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
The swizzle can: rearrange the components of the texel, or substitute zero
and one for any components.
@ -805,7 +793,7 @@ This code can: be interpreted by the code:OpImageSparseTexelsResident
instruction which converts the residency code to a boolean value.
ifdef::VK_KHR_sampler_ycbcr_conversion[]
ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
[[textures-chroma-reconstruction]]
=== Chroma Reconstruction
@ -831,7 +819,7 @@ reconstruction`" irrespective of the actual color model.
The location of the chroma samples relative to the luma coordinates is
determined by the pname:xChromaOffset and pname:yChromaOffset members of the
slink:VkSamplerYcbcrConversionCreateInfoKHR structure used to create the
slink:VkSamplerYcbcrConversionCreateInfo structure used to create the
sampler Y'C~B~C~R~ conversion.
The following diagrams show the relationship between unnormalized (_u_,_v_)
@ -851,30 +839,30 @@ positions where required for interpolation.
The limits of a sample for etext:NEAREST sampling is shown as a grid.
====
image::images/chromasamples_422_cosited.svg[align="center",title="422 downsampling, xChromaOffset=COSITED_EVEN",width="400"]
image::images/chromasamples_422_cosited.svg[align="center",title="422 downsampling, xChromaOffset=COSITED_EVEN",{fullimagewidth}]
image::images/chromasamples_422_midpoint.svg[align="center",title="422 downsampling, xChromaOffset=MIDPOINT",width="400"]
image::images/chromasamples_422_midpoint.svg[align="center",title="422 downsampling, xChromaOffset=MIDPOINT",{fullimagewidth}]
image::images/chromasamples_420_xcosited_ycosited.svg[align="center",title="420 downsampling, xChromaOffset=COSITED_EVEN, yChromaOffset=COSITED_EVEN",width="400"]
image::images/chromasamples_420_xcosited_ycosited.svg[align="center",title="420 downsampling, xChromaOffset=COSITED_EVEN, yChromaOffset=COSITED_EVEN",{fullimagewidth}]
image::images/chromasamples_420_xmidpoint_ycosited.svg[align="center",title="420 downsampling, xChromaOffset=MIDPOINT, yChromaOffset=COSITED_EVEN",width="400"]
image::images/chromasamples_420_xmidpoint_ycosited.svg[align="center",title="420 downsampling, xChromaOffset=MIDPOINT, yChromaOffset=COSITED_EVEN",{fullimagewidth}]
image::images/chromasamples_420_xcosited_ymidpoint.svg[align="center",title="420 downsampling, xChromaOffset=COSITED_EVEN, yChromaOffset=MIDPOINT",width="400"]
image::images/chromasamples_420_xcosited_ymidpoint.svg[align="center",title="420 downsampling, xChromaOffset=COSITED_EVEN, yChromaOffset=MIDPOINT",{fullimagewidth}]
image::images/chromasamples_420_xmidpoint_ymidpoint.svg[align="center",title="420 downsampling, xChromaOffset=MIDPOINT, yChromaOffset=MIDPOINT",width="400"]
image::images/chromasamples_420_xmidpoint_ymidpoint.svg[align="center",title="420 downsampling, xChromaOffset=MIDPOINT, yChromaOffset=MIDPOINT",{fullimagewidth}]
Reconstruction is implemented in one of two ways:
If the format of the image that is to be sampled sets
ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_CHROMA_RECONSTRUCTION_EXPLICIT_BIT_KHR,
or the sname:VkSamplerYcbcrConversionCreateInfoKHR's
ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_CHROMA_RECONSTRUCTION_EXPLICIT_BIT,
or the sname:VkSamplerYcbcrConversionCreateInfo's
pname:forceExplicitReconstruction is set to ename:VK_TRUE, reconstruction is
performed as an explicit step independent of filtering, described in the
<<textures-explicit-reconstruction>> section.
If the format of the image that is to be sampled does not set
ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_CHROMA_RECONSTRUCTION_EXPLICIT_BIT_KHR
and if the sname:VkSamplerYcbcrConversionCreateInfoKHR's
ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_CHROMA_RECONSTRUCTION_EXPLICIT_BIT
and if the sname:VkSamplerYcbcrConversionCreateInfo's
pname:forceExplicitReconstruction is set to ename:VK_FALSE, reconstruction
is performed as an implicit part of filtering prior to color model
conversion, with no separate post-conversion texel filtering step, as
@ -885,7 +873,7 @@ section.
==== Explicit Reconstruction
* If the pname:chromaFilter member of the
slink:VkSamplerYcbcrConversionCreateInfoKHR structure is
slink:VkSamplerYcbcrConversionCreateInfo structure is
ename:VK_FILTER_NEAREST:
** If the format's R and B channels are reduced in resolution in just
width by a factor of two relative to the G channel (i.e. this is a
@ -923,12 +911,12 @@ pname:chromaFilter is ename:VK_FILTER_NEAREST for explicit reconstruction.
====
* If the pname:chromaFilter member of the
slink:VkSamplerYcbcrConversionCreateInfoKHR structure is
slink:VkSamplerYcbcrConversionCreateInfo structure is
ename:VK_FILTER_LINEAR:
** If the format's R and B channels are reduced in resolution in just
width by a factor of two relative to the G channel (i.e. this is a
"`422`" format):
*** If pname:xChromaOffset is ename:VK_CHROMA_LOCATION_COSITED_EVEN_KHR:
*** If pname:xChromaOffset is ename:VK_CHROMA_LOCATION_COSITED_EVEN:
+
[latexmath]
+++++
@ -939,7 +927,7 @@ pname:chromaFilter is ename:VK_FILTER_NEAREST for explicit reconstruction.
\end{cases}
+++++
+
*** If pname:xChromaOffset is ename:VK_CHROMA_LOCATION_MIDPOINT_KHR:
*** If pname:xChromaOffset is ename:VK_CHROMA_LOCATION_MIDPOINT:
+
[latexmath]
+++++
@ -991,6 +979,7 @@ pname:chromaFilter is ename:VK_FILTER_NEAREST for explicit reconstruction.
+++++
[NOTE]
.Note
====
In the case where the texture itself is bilinearly interpolated as described
in <<textures-texel-filtering,Texel Filtering>>, thus requiring four
@ -1007,6 +996,18 @@ required, depending on the sample location.
Implicit reconstruction takes place by the samples being interpolated, as
required by the filter settings of the sampler, except that
pname:chromaFilter takes precedence for the chroma samples.
If pname:chromaFilter is ename:VK_FILTER_NEAREST, an implementation may:
behave as if pname:xChromaOffset and pname:yChromaOffset were both
ename:VK_CHROMA_LOCATION_MIDPOINT, irrespective of the values set.
[NOTE]
.Note
====
This will not have any visible effect if the locations of the luma samples
coincide with the location of the samples used for rasterization.
====
The sample coordinates are adjusted by the downsample factor of the channel
(such that, for example, the sample coordinates are divided by two if the
channel has a downsample factor of two relative to the luma channel):
@ -1049,14 +1050,14 @@ For example, the input values to this stage have been converted using the
normal <<textures-format-conversion,format conversion>> rules.
Sampler Y'C~B~C~R~ range expansion is not applied if pname:ycbcrModel is
ename:VK_SAMPLER_YCBCR_MODEL_CONVERSION_RGB_IDENTITY_KHR.
ename:VK_SAMPLER_YCBCR_MODEL_CONVERSION_RGB_IDENTITY.
That is, the shader receives the vector C'~rgba~ as output by the Component
Swizzle stage without further modification.
For other values of pname:ycbcrModel, range expansion is applied to the
texel channel values output by the <<textures-component-swizzle,Component
Swizzle>> defined by the pname:components member of
slink:VkSamplerYcbcrConversionCreateInfoKHR.
slink:VkSamplerYcbcrConversionCreateInfo.
Range expansion applies independently to each channel of the image.
For the purposes of range expansion and Y'C~B~C~R~ model conversion, the R
and B channels contain color difference (chroma) values and the G channel
@ -1064,9 +1065,9 @@ contains luma.
The A channel is not modified by sampler Y'C~B~C~R~ range expansion.
The range expansion to be applied is defined by the pname:ycbcrRange member
of the sname:VkSamplerYcbcrConversionCreateInfoKHR structure:
of the sname:VkSamplerYcbcrConversionCreateInfo structure:
* If pname:ycbcrRange is ename:VK_SAMPLER_YCBCR_RANGE_ITU_FULL_KHR, the
* If pname:ycbcrRange is ename:VK_SAMPLER_YCBCR_RANGE_ITU_FULL, the
following transformations are applied:
+
[latexmath]
@ -1088,7 +1089,7 @@ Should any future amendments be made to the ITU specifications from which
these equations are derived, the formulae used by Vulkan may: also be
updated to maintain parity.
====
* If pname:ycbcrRange is ename:VK_SAMPLER_YCBCR_RANGE_ITU_NARROW_KHR, the
* If pname:ycbcrRange is ename:VK_SAMPLER_YCBCR_RANGE_ITU_NARROW, the
following transformations are applied:
+
[latexmath]
@ -1121,25 +1122,25 @@ in the range [-0.5,0.5].
The range-expanded values are converted between color models, according to
the color model conversion specified in the pname:ycbcrModel member:
ename:VK_SAMPLER_YCBCR_MODEL_CONVERSION_RGB_IDENTITY_KHR::
ename:VK_SAMPLER_YCBCR_MODEL_CONVERSION_RGB_IDENTITY::
The color channels are not modified by the color model conversion since
they are assumed already to represent the desired color model in which the
shader is operating; Y'C~B~C~R~ range expansion is also ignored.
ename:VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_IDENTITY_KHR::
ename:VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_IDENTITY::
The color channels are not modified by the color model conversion and are
assumed to be treated as though in Y'C~B~C~R~ form both in memory and in
the shader; Y'C~B~C~R~ range expansion is applied to the channels as for
other Y'C~B~C~R~ models, with the vector (C~R~,Y',C~B~,A) provided to the
shader.
ename:VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_709_KHR::
ename:VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_709::
The color channels are transformed from a Y'C~B~C~R~ representation to an
R'G'B' representation as described in the "`BT.709 Y'C~B~C~R~ conversion`"
section of the <<data-format,Khronos Data Format Specification>>.
ename:VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_601_KHR::
ename:VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_601::
The color channels are transformed from a Y'C~B~C~R~ representation to an
R'G'B' representation as described in the "`BT.601 Y'C~B~C~R~ conversion`"
section of the <<data-format,Khronos Data Format Specification>>.
ename:VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_2020_KHR::
ename:VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_2020::
The color channels are transformed from a Y'C~B~C~R~ representation to an
R'G'B' representation as described in the "`BT.2020 Y'C~B~C~R~
conversion`" section of the <<data-format,Khronos Data Format
@ -1202,7 +1203,7 @@ ename:VK_FILTER_NEAREST, these operations are redundant and sampling using
sample coordinates will produce the "`correct`" results without further
processing.
====
endif::VK_KHR_sampler_ycbcr_conversion[]
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
== Texel Output Operations
@ -1257,11 +1258,10 @@ texel is a sparse unbound texel.
In such a case, if the
slink:VkPhysicalDeviceSparseProperties::pname:residencyNonResidentStrict
property is ename:VK_TRUE, the sparse unbound texel write has no effect.
If pname:residencyNonResidentStrict is ename:VK_FALSE, the effect of the
write is undefined but must: be safe.
In addition, the write may: have a side effect that is visible to other
image instructions, but must: not be written to any device memory
allocation.
If pname:residencyNonResidentStrict is ename:VK_FALSE, the write may: have a
side effect that becomes visible to other accesses to unbound texels in any
resource, but will not be visible to any device memory allocated by the
application.
[[textures-output-format-conversion]]
@ -1285,7 +1285,7 @@ SPIR-V derivative instructions include code:OpDPdx, code:OpDPdy,
code:OpDPdxFine, code:OpDPdyFine, code:OpDPdxCoarse, and code:OpDPdyCoarse.
Derivative instructions are only available in a fragment shader.
image::images/vulkantexture2.png[align="center",title="Implicit Derivatives",{fullimagewidth}]
image::images/vulkantexture2.svg[align="center",title="Implicit Derivatives",width="400"]
Derivatives are computed as if there is a 2{times}2 neighborhood of
fragments for each fragment shader invocation.
@ -1333,10 +1333,10 @@ Implementations must: make the same choice of either coarse or fine for both
code:OpDPdx and code:OpDPdy, and implementations should: make the choice
that is more efficient to compute.
ifdef::VK_KHR_sampler_ycbcr_conversion[]
ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
For multi-planar formats, the derivatives are computed based on the plane
with the largest dimensions.
endif::VK_KHR_sampler_ycbcr_conversion[]
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
[[textures-normalized-operations]]
@ -1663,14 +1663,9 @@ determined by:
:: [eq]#{rho}~max~ = max({rho}~x~, {rho}~y~)#
:: [eq]#{rho}~min~ = min({rho}~x~, {rho}~y~)#
The sampling rate is determined by:
The ratio of anisotropy is determined by:
[latexmath]
++++++++++++++++++++++++
\begin{aligned}
N & = \min \left (\left \lceil \rho_{max}/\rho_{min} \right \rceil ,max_{Aniso} \right )
\end{aligned}
++++++++++++++++++++++++
:: [eq]#{eta} = min({rho}~max~/{rho}~min~, max~Aniso~)#
where:
@ -1685,16 +1680,25 @@ zero, the fragment's footprint in texel space is a point, and [eq]#N#
should: be treated as 1.
If [eq]#{rho}~max~ {neq} 0# and [eq]#{rho}~min~ = 0# then all partial
derivatives along one axis are zero, the fragment's footprint in texel space
is a line segment, and [eq]#N# should: be treated as [eq]#max~Aniso~#.
is a line segment, and [eq]#{eta}# should: be treated as [eq]#max~Aniso~#.
However, anytime the footprint is small in texel space the implementation
may: use a smaller value of [eq]#N#, even when [eq]#{rho}~min~# is zero or
close to zero.
may: use a smaller value of [eq]#{eta}#, even when [eq]#{rho}~min~# is zero
or close to zero.
If either slink:VkPhysicalDeviceFeatures::pname:samplerAnisotropy or
slink:VkSamplerCreateInfo::pname:anisotropyEnable are ename:VK_FALSE,
[eq]#max~Aniso~# is set to 1.
If [eq]#{eta} = 1#, sampling is isotropic.
If [eq]#{eta} > 1#, sampling is anisotropic.
The sampling rate ([eq]#N#) is derived as:
:: [eq]#N = {lceil}{eta}{rceil}#
An implementation may: round [eq]#N# up to the nearest supported sampling
rate.
If [eq]#N = 1#, sampling is isotropic.
If [eq]#N > 1#, sampling is anisotropic.
An implementation may: use the value of [eq]#N# as an approximation of
[eq]#{eta}#.
[[textures-level-of-detail-operation]]
@ -1707,8 +1711,8 @@ The LOD parameter [eq]#{lambda}# is computed as follows:
\begin{aligned}
\lambda_{base}(x,y) & =
\begin{cases}
shaderOp.Lod & \text{(from optional SPIR-V operand)} \\
\log_2 \left ( \frac{\rho_{max}}{N} \right ) & \text{otherwise}
shaderOp.Lod & \text{(from optional SPIR-V operand)} \\
\log_2 \left ( \frac{\rho_{max}}{\eta} \right ) & \text{otherwise}
\end{cases} \\
\lambda'(x,y) & = \lambda_{base} + \mathbin{clamp}(sampler.bias + shaderOp.bias,-maxSamplerLodBias,maxSamplerLodBias) \\
\lambda & =
@ -2063,10 +2067,10 @@ comp & \,\text{from SPIR-V operand Component}
\end{aligned}
++++++++++++++++++++++++
ifdef::VK_KHR_sampler_ycbcr_conversion[]
ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
code:OpImage*Gather must: not be used on a sampled image with
<<samplers-YCbCr-conversion,sampler Y'C~B~C~R~ conversion>> enabled.
endif::VK_KHR_sampler_ycbcr_conversion[]
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
[[textures-texel-filtering]]

38
doc/specs/vulkan/chapters/vertexpostproc.txt
View File

@ -275,33 +275,39 @@ If the primitive under consideration is a point or line segment, then
clipping passes it unchanged if its vertices lie entirely within the clip
volume.
ifndef::VK_KHR_maintenance2[]
ifndef::VK_VERSION_1_1,VK_KHR_maintenance2[]
If a point's vertex lies outside of the clip volume, the entire primitive
may: be discarded.
endif::VK_KHR_maintenance2[]
endif::VK_VERSION_1_1,VK_KHR_maintenance2[]
ifdef::VK_KHR_maintenance2[]
ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[]
[open,refpage='VkPointClippingBehaviorKHR',desc='Enum specifying the point clipping behaviour',type='enums']
[open,refpage='VkPointClippingBehavior',desc='Enum specifying the point clipping behaviour',type='enums']
--
Possible values of
slink:VkPhysicalDevicePointClippingPropertiesKHR::pname:pointClippingBehavior,
slink:VkPhysicalDevicePointClippingProperties::pname:pointClippingBehavior,
specifying clipping behavior of a point primitive whose vertex lies outside
the clip volume, are:
include::../api/enums/VkPointClippingBehaviorKHR.txt[]
include::../api/enums/VkPointClippingBehavior.txt[]
* ename:VK_POINT_CLIPPING_BEHAVIOR_ALL_CLIP_PLANES_KHR specifies that the
ifdef::VK_KHR_maintenance2[]
or the equivalent
include::../api/enums/VkPointClippingBehaviorKHR.txt[]
endif::VK_KHR_maintenance2[]
* ename:VK_POINT_CLIPPING_BEHAVIOR_ALL_CLIP_PLANES specifies that the
primitive is discarded if the vertex lies outside any clip plane,
including the planes bounding the view volume.
* ename:VK_POINT_CLIPPING_BEHAVIOR_USER_CLIP_PLANES_ONLY_KHR specifies that
the primitive is discarded only if the vertex lies outside any user clip
* ename:VK_POINT_CLIPPING_BEHAVIOR_USER_CLIP_PLANES_ONLY specifies that the
primitive is discarded only if the vertex lies outside any user clip
plane.
--
endif::VK_KHR_maintenance2[]
endif::VK_VERSION_1_1,VK_KHR_maintenance2[]
If either of a line segment's vertices lie outside of the clip volume, the
line segment may: be clipped, with new vertex coordinates computed for each
@ -671,7 +677,7 @@ values as
:: [eq]#p~y~ = pname:height#
:: [eq]#p~z~ = pname:maxDepth - pname:minDepth#.
ifdef::VK_KHR_maintenance1[]
ifdef::VK_VERSION_1_1,VK_KHR_maintenance1[]
The application can: specify a negative term for pname:height, which has the
effect of negating the y coordinate in clip space before performing the
transform.
@ -681,7 +687,7 @@ the upper left corner.
Using the negative pname:height allows the application to avoid having to
negate the y component of the code:Position output from the last vertex
processing stage in shaders that also target other graphics APIs.
endif::VK_KHR_maintenance1[]
endif::VK_VERSION_1_1,VK_KHR_maintenance1[]
The width and height of the <<features-limits-maxViewportDimensions,
implementation-dependent maximum viewport dimensions>> must: be greater than
@ -698,10 +704,10 @@ The floating-point viewport bounds are represented with an
* [[VUID-VkViewport-width-01771]]
pname:width must: be less than or equal to
sname:VkPhysicalDeviceLimits::pname:maxViewportDimensions[0]
ifndef::VK_KHR_maintenance1,VK_AMD_negative_viewport_height[]
ifndef::VK_VERSION_1_1,VK_KHR_maintenance1,VK_AMD_negative_viewport_height[]
* [[VUID-VkViewport-height-01772]]
pname:height must: be greater than `0.0`
endif::VK_KHR_maintenance1,VK_AMD_negative_viewport_height[]
endif::VK_VERSION_1_1,VK_KHR_maintenance1,VK_AMD_negative_viewport_height[]
* [[VUID-VkViewport-height-01773]]
The absolute value of pname:height must: be less than or equal to
sname:VkPhysicalDeviceLimits::pname:maxViewportDimensions[1]
@ -712,13 +718,13 @@ endif::VK_KHR_maintenance1,VK_AMD_negative_viewport_height[]
pname:viewportBoundsRange[1]
* [[VUID-VkViewport-y-01775]]
pname:y must: be greater than or equal to pname:viewportBoundsRange[0]
ifdef::VK_KHR_maintenance1,VK_AMD_negative_viewport_height[]
ifdef::VK_VERSION_1_1,VK_KHR_maintenance1,VK_AMD_negative_viewport_height[]
* [[VUID-VkViewport-y-01776]]
pname:y must: be less than or equal to pname:viewportBoundsRange[1]
* [[VUID-VkViewport-y-01777]]
[eq]#(pname:y {plus} pname:height)# must: be greater than or equal to
pname:viewportBoundsRange[0]
endif::VK_KHR_maintenance1,VK_AMD_negative_viewport_height[]
endif::VK_VERSION_1_1,VK_KHR_maintenance1,VK_AMD_negative_viewport_height[]
* [[VUID-VkViewport-y-01233]]
[eq]#(pname:y {plus} pname:height)# must: be less than or equal to
pname:viewportBoundsRange[1]

6
doc/specs/vulkan/config/README.md
View File

@ -12,10 +12,14 @@ Asciidoctor is customized to insert KaTeX `<script>` tags from
`math.js` for HTML5, and properly pass through math which has
`\begin{}\/end{}` delimiters instead of $$\[\]\(\).
For PDF builds, asciidoctor-mathematical is used to generate
For PDF builds, asciidoctor-mathematical is used to generate
`math-docbook.conf` is heavily conditionalized depending on whether the
final output format (which should be described in the a2x-format variable)
is `pdf` or not, since Docbook passes through math differently to dblatex
vs. the XHTML stylesheets. This could be simplified now that we're only
using Docbook for PDFs.
## Stylesheets
`khronos.css` is the stylesheet used for HTML output.

1
doc/specs/vulkan/config/attribs.txt
View File

@ -26,6 +26,7 @@
:lambda: λ
:rho: ρ
:tau: τ
:eta: η
:lceil: ⌈
:rceil: ⌉
:lfloor: ⌊

714
doc/specs/vulkan/config/khronos.css Normal file
View File

@ -0,0 +1,714 @@
/*! normalize.css v2.1.2 | MIT License | git.io/normalize */
/* ========================================================================== HTML5 display definitions ========================================================================== */
/** Correct `block` display not defined in IE 8/9. */
article, aside, details, figcaption, figure, footer, header, hgroup, main, nav, section, summary { display: block; }
/** Correct `inline-block` display not defined in IE 8/9. */
audio, canvas, video { display: inline-block; }
/** Prevent modern browsers from displaying `audio` without controls. Remove excess height in iOS 5 devices. */
audio:not([controls]) { display: none; height: 0; }
/** Address `[hidden]` styling not present in IE 8/9. Hide the `template` element in IE, Safari, and Firefox < 22. */
[hidden], template { display: none; }
script { display: none !important; }
/* ========================================================================== Base ========================================================================== */
/** 1. Set default font family to sans-serif. 2. Prevent iOS text size adjust after orientation change, without disabling user zoom. */
html { font-family: sans-serif; /* 1 */ -ms-text-size-adjust: 100%; /* 2 */ -webkit-text-size-adjust: 100%; /* 2 */ }
/** Remove default margin. */
body { margin: 0; }
/* ========================================================================== Links ========================================================================== */
/** Remove the gray background color from active links in IE 10. */
a { background: transparent; }
/** Address `outline` inconsistency between Chrome and other browsers. */
a:focus { outline: thin dotted; }
/** Improve readability when focused and also mouse hovered in all browsers. */
a:active, a:hover { outline: 0; }
/* ========================================================================== Typography ========================================================================== */
/** Address variable `h1` font-size and margin within `section` and `article` contexts in Firefox 4+, Safari 5, and Chrome. */
h1 { font-size: 2em; margin: 0.67em 0; }
/** Address styling not present in IE 8/9, Safari 5, and Chrome. */
abbr[title] { border-bottom: 1px dotted; }
/** Address style set to `bolder` in Firefox 4+, Safari 5, and Chrome. */
b, strong { font-weight: bold; }
/** Address styling not present in Safari 5 and Chrome. */
dfn { font-style: italic; }
/** Address differences between Firefox and other browsers. */
hr { -moz-box-sizing: content-box; box-sizing: content-box; height: 0; }
/** Address styling not present in IE 8/9. */
mark { background: #ff0; color: #000; }
/** Correct font family set oddly in Safari 5 and Chrome. */
code, kbd, pre, samp { font-family: monospace, serif; font-size: 1em; }
/** Improve readability of pre-formatted text in all browsers. */
pre { white-space: pre-wrap; }
/** Set consistent quote types. */
q { quotes: "\201C" "\201D" "\2018" "\2019"; }
/** Address inconsistent and variable font size in all browsers. */
small { font-size: 80%; }
/** Prevent `sub` and `sup` affecting `line-height` in all browsers. */
sub, sup { font-size: 75%; line-height: 0; position: relative; vertical-align: baseline; }
sup { top: -0.5em; }
sub { bottom: -0.25em; }
/* ========================================================================== Embedded content ========================================================================== */
/** Remove border when inside `a` element in IE 8/9. */
img { border: 0; }
/** Correct overflow displayed oddly in IE 9. */
svg:not(:root) { overflow: hidden; }
/* ========================================================================== Figures ========================================================================== */
/** Address margin not present in IE 8/9 and Safari 5. */
figure { margin: 0; }
/* ========================================================================== Forms ========================================================================== */
/** Define consistent border, margin, and padding. */
fieldset { border: 1px solid #c0c0c0; margin: 0 2px; padding: 0.35em 0.625em 0.75em; }
/** 1. Correct `color` not being inherited in IE 8/9. 2. Remove padding so people aren't caught out if they zero out fieldsets. */
legend { border: 0; /* 1 */ padding: 0; /* 2 */ }
/** 1. Correct font family not being inherited in all browsers. 2. Correct font size not being inherited in all browsers. 3. Address margins set differently in Firefox 4+, Safari 5, and Chrome. */
button, input, select, textarea { font-family: inherit; /* 1 */ font-size: 100%; /* 2 */ margin: 0; /* 3 */ }
/** Address Firefox 4+ setting `line-height` on `input` using `!important` in the UA stylesheet. */
button, input { line-height: normal; }
/** Address inconsistent `text-transform` inheritance for `button` and `select`. All other form control elements do not inherit `text-transform` values. Correct `button` style inheritance in Chrome, Safari 5+, and IE 8+. Correct `select` style inheritance in Firefox 4+ and Opera. */
button, select { text-transform: none; }
/** 1. Avoid the WebKit bug in Android 4.0.* where (2) destroys native `audio` and `video` controls. 2. Correct inability to style clickable `input` types in iOS. 3. Improve usability and consistency of cursor style between image-type `input` and others. */
button, html input[type="button"], input[type="reset"], input[type="submit"] { -webkit-appearance: button; /* 2 */ cursor: pointer; /* 3 */ }
/** Re-set default cursor for disabled elements. */
button[disabled], html input[disabled] { cursor: default; }
/** 1. Address box sizing set to `content-box` in IE 8/9. 2. Remove excess padding in IE 8/9. */
input[type="checkbox"], input[type="radio"] { box-sizing: border-box; /* 1 */ padding: 0; /* 2 */ }
/** 1. Address `appearance` set to `searchfield` in Safari 5 and Chrome. 2. Address `box-sizing` set to `border-box` in Safari 5 and Chrome (include `-moz` to future-proof). */
input[type="search"] { -webkit-appearance: textfield; /* 1 */ -moz-box-sizing: content-box; -webkit-box-sizing: content-box; /* 2 */ box-sizing: content-box; }
/** Remove inner padding and search cancel button in Safari 5 and Chrome on OS X. */
input[type="search"]::-webkit-search-cancel-button, input[type="search"]::-webkit-search-decoration { -webkit-appearance: none; }
/** Remove inner padding and border in Firefox 4+. */
button::-moz-focus-inner, input::-moz-focus-inner { border: 0; padding: 0; }
/** 1. Remove default vertical scrollbar in IE 8/9. 2. Improve readability and alignment in all browsers. */
textarea { overflow: auto; /* 1 */ vertical-align: top; /* 2 */ }
/* ========================================================================== Tables ========================================================================== */
/** Remove most spacing between table cells. */
table { border-collapse: collapse; border-spacing: 0; }
meta.foundation-mq-small { font-family: "only screen and (min-width: 768px)"; width: 768px; }
meta.foundation-mq-medium { font-family: "only screen and (min-width:1280px)"; width: 1280px; }
meta.foundation-mq-large { font-family: "only screen and (min-width:1440px)"; width: 1440px; }
*, *:before, *:after { -moz-box-sizing: border-box; -webkit-box-sizing: border-box; box-sizing: border-box; }
html, body { font-size: 100%; }
body { background: #fff; color: #222; padding: 0; margin: 0; font-family: "Helvetica Neue", "Helvetica", Helvetica, Arial, sans-serif; font-weight: normal; font-style: normal; line-height: 1; position: relative; cursor: auto; }
a:hover { cursor: pointer; }
img, object, embed { max-width: 100%; height: auto; }
object, embed { height: 100%; }
img { -ms-interpolation-mode: bicubic; }
#map_canvas img, #map_canvas embed, #map_canvas object, .map_canvas img, .map_canvas embed, .map_canvas object { max-width: none !important; }
.left { float: left !important; }
.right { float: right !important; }
.text-left { text-align: left !important; }
.text-right { text-align: right !important; }
.text-center { text-align: center !important; }
.text-justify { text-align: justify !important; }
.hide { display: none; }
.antialiased { -webkit-font-smoothing: antialiased; }
img { display: inline-block; vertical-align: middle; }
textarea { height: auto; min-height: 50px; }
select { width: 100%; }
object, svg { display: inline-block; vertical-align: middle; }
.center { margin-left: auto; margin-right: auto; }
.spread { width: 100%; }
p.lead, .paragraph.lead > p, #preamble > .sectionbody > .paragraph:first-of-type p { font-size: 1.21875em; line-height: 1.6; }
.subheader, .admonitionblock td.content > .title, .audioblock > .title, .exampleblock > .title, .imageblock > .title, .listingblock > .title, .literalblock > .title, .stemblock > .title, .openblock > .title, .paragraph > .title, .quoteblock > .title, table.tableblock > .title, .verseblock > .title, .videoblock > .title, .dlist > .title, .olist > .title, .ulist > .title, .qlist > .title, .hdlist > .title { line-height: 1.4; color: black; font-weight: 300; margin-top: 0.2em; margin-bottom: 0.5em; }
/* Typography resets */
div, dl, dt, dd, ul, ol, li, h1, h2, h3, #toctitle, .sidebarblock > .content > .title, h4, h5, h6, pre, form, p, blockquote, th, td { margin: 0; padding: 0; direction: ltr; }
/* Default Link Styles */
a { color: #0068b0; text-decoration: none; line-height: inherit; }
a:hover, a:focus { color: #333; }
a img { border: none; }
/* Default paragraph styles */
p { font-family: Noto, sans-serif; font-weight: normal; font-size: 1em; line-height: 1.6; margin-bottom: 0.75em; text-rendering: optimizeLegibility; }
p aside { font-size: 0.875em; line-height: 1.35; font-style: italic; }
/* Default header styles */
h1, h2, h3, #toctitle, .sidebarblock > .content > .title, h4, h5, h6 { font-family: Noto, sans-serif; font-weight: normal; font-style: normal; color: black; text-rendering: optimizeLegibility; margin-top: 0.5em; margin-bottom: 0.5em; line-height: 1.2125em; }
h1 small, h2 small, h3 small, #toctitle small, .sidebarblock > .content > .title small, h4 small, h5 small, h6 small { font-size: 60%; color: #4d4d4d; line-height: 0; }
h1 { font-size: 2.125em; }
h2 { font-size: 1.6875em; }
h3, #toctitle, .sidebarblock > .content > .title { font-size: 1.375em; }
h4 { font-size: 1.125em; }
h5 { font-size: 1.125em; }
h6 { font-size: 1em; }
hr { border: solid #ddd; border-width: 1px 0 0; clear: both; margin: 1.25em 0 1.1875em; height: 0; }
/* Helpful Typography Defaults */
em, i { font-style: italic; line-height: inherit; }
strong, b { font-weight: bold; line-height: inherit; }
small { font-size: 60%; line-height: inherit; }
code { font-family: Consolas, "Liberation Mono", Courier, monospace; font-weight: normal; color: #264357; }
/* Lists */
ul, ol, dl { font-size: 1em; line-height: 1.6; margin-bottom: 0.75em; list-style-position: outside; font-family: Noto, sans-serif; }
ul, ol { margin-left: 1.5em; }
ul.no-bullet, ol.no-bullet { margin-left: 1.5em; }
/* Unordered Lists */
ul li ul, ul li ol { margin-left: 1.25em; margin-bottom: 0; font-size: 1em; /* Override nested font-size change */ }
ul.square li ul, ul.circle li ul, ul.disc li ul { list-style: inherit; }
ul.square { list-style-type: square; }
ul.circle { list-style-type: circle; }
ul.disc { list-style-type: disc; }
ul.no-bullet { list-style: none; }
/* Ordered Lists */
ol li ul, ol li ol { margin-left: 1.25em; margin-bottom: 0; }
/* Definition Lists */
dl dt { margin-bottom: 0.3em; font-weight: bold; }
dl dd { margin-bottom: 0.75em; }
/* Abbreviations */
abbr, acronym { text-transform: uppercase; font-size: 90%; color: black; border-bottom: 1px dotted #ddd; cursor: help; }
abbr { text-transform: none; }
/* Blockquotes */
blockquote { margin: 0 0 0.75em; padding: 0.5625em 1.25em 0 1.1875em; border-left: 1px solid #ddd; }
blockquote cite { display: block; font-size: 0.8125em; color: #5e93b8; }
blockquote cite:before { content: "\2014 \0020"; }
blockquote cite a, blockquote cite a:visited { color: #5e93b8; }
blockquote, blockquote p { line-height: 1.6; color: #333; }
/* Microformats */
.vcard { display: inline-block; margin: 0 0 1.25em 0; border: 1px solid #ddd; padding: 0.625em 0.75em; }
.vcard li { margin: 0; display: block; }
.vcard .fn { font-weight: bold; font-size: 0.9375em; }
.vevent .summary { font-weight: bold; }
.vevent abbr { cursor: auto; text-decoration: none; font-weight: bold; border: none; padding: 0 0.0625em; }
@media only screen and (min-width: 768px) { h1, h2, h3, #toctitle, .sidebarblock > .content > .title, h4, h5, h6 { line-height: 1.4; }
h1 { font-size: 2.75em; }
h2 { font-size: 2.3125em; }
h3, #toctitle, .sidebarblock > .content > .title { font-size: 1.6875em; }
h4 { font-size: 1.4375em; } }
/* Tables */
table { background: #fff; margin-bottom: 1.25em; border: solid 1px #d8d8ce; }
table thead, table tfoot { background: #eee; font-weight: bold; }
table thead tr th, table thead tr td, table tfoot tr th, table tfoot tr td { padding: 0.5em 0.625em 0.625em; font-size: inherit; color: #222; text-align: left; }
table tr th, table tr td { padding: 0.5625em 0.625em; font-size: inherit; color: #6d6e71; }
table tr.even, table tr.alt, table tr:nth-of-type(even) { background: #f8f8f8; }
table thead tr th, table tfoot tr th, table tbody tr td, table tr td, table tfoot tr td { display: table-cell; line-height: 1.4; }
body { -moz-osx-font-smoothing: grayscale; -webkit-font-smoothing: antialiased; tab-size: 4; }
h1, h2, h3, #toctitle, .sidebarblock > .content > .title, h4, h5, h6 { line-height: 1.4; }
a:hover, a:focus { text-decoration: underline; }
.clearfix:before, .clearfix:after, .float-group:before, .float-group:after { content: " "; display: table; }
.clearfix:after, .float-group:after { clear: both; }
*:not(pre) > code { font-size: inherit; font-style: normal !important; letter-spacing: 0; padding: 0; background-color: transparent; -webkit-border-radius: 0; border-radius: 0; line-height: inherit; word-wrap: break-word; }
*:not(pre) > code.nobreak { word-wrap: normal; }
*:not(pre) > code.nowrap { white-space: nowrap; }
pre, pre > code { line-height: 1.6; color: #264357; font-family: Consolas, "Liberation Mono", Courier, monospace; font-weight: normal; }
em em { font-style: normal; }
strong strong { font-weight: normal; }
.keyseq { color: #333333; }
kbd { font-family: Consolas, "Liberation Mono", Courier, monospace; display: inline-block; color: black; font-size: 0.65em; line-height: 1.45; background-color: #f7f7f7; border: 1px solid #ccc; -webkit-border-radius: 3px; border-radius: 3px; -moz-box-shadow: 0 1px 0 rgba(0, 0, 0, 0.2), 0 0 0 0.1em white inset; -webkit-box-shadow: 0 1px 0 rgba(0, 0, 0, 0.2), 0 0 0 0.1em white inset; box-shadow: 0 1px 0 rgba(0, 0, 0, 0.2), 0 0 0 0.1em white inset; margin: 0 0.15em; padding: 0.2em 0.5em; vertical-align: middle; position: relative; top: -0.1em; white-space: nowrap; }
.keyseq kbd:first-child { margin-left: 0; }
.keyseq kbd:last-child { margin-right: 0; }
.menuseq, .menuref { color: #000; }
.menuseq b:not(.caret), .menuref { font-weight: inherit; }
.menuseq { word-spacing: -0.02em; }
.menuseq b.caret { font-size: 1.25em; line-height: 0.8; }
.menuseq i.caret { font-weight: bold; text-align: center; width: 0.45em; }
b.button:before, b.button:after { position: relative; top: -1px; font-weight: normal; }
b.button:before { content: "["; padding: 0 3px 0 2px; }
b.button:after { content: "]"; padding: 0 2px 0 3px; }
#header, #content, #footnotes, #footer { width: 100%; margin-left: auto; margin-right: auto; margin-top: 0; margin-bottom: 0; max-width: 62.5em; *zoom: 1; position: relative; padding-left: 1.5em; padding-right: 1.5em; }
#header:before, #header:after, #content:before, #content:after, #footnotes:before, #footnotes:after, #footer:before, #footer:after { content: " "; display: table; }
#header:after, #content:after, #footnotes:after, #footer:after { clear: both; }
#content { margin-top: 1.25em; }
#content:before { content: none; }
#header > h1:first-child { color: black; margin-top: 2.25rem; margin-bottom: 0; }
#header > h1:first-child + #toc { margin-top: 8px; border-top: 1px solid #ddd; }
#header > h1:only-child, body.toc2 #header > h1:nth-last-child(2) { border-bottom: 1px solid #ddd; padding-bottom: 8px; }
#header .details { border-bottom: 1px solid #ddd; line-height: 1.45; padding-top: 0.25em; padding-bottom: 0.25em; padding-left: 0.25em; color: #5e93b8; display: -ms-flexbox; display: -webkit-flex; display: flex; -ms-flex-flow: row wrap; -webkit-flex-flow: row wrap; flex-flow: row wrap; }
#header .details span:first-child { margin-left: -0.125em; }
#header .details span.email a { color: #333; }
#header .details br { display: none; }
#header .details br + span:before { content: "\00a0\2013\00a0"; }
#header .details br + span.author:before { content: "\00a0\22c5\00a0"; color: #333; }
#header .details br + span#revremark:before { content: "\00a0|\00a0"; }
#header #revnumber { text-transform: capitalize; }
#header #revnumber:after { content: "\00a0"; }
#content > h1:first-child:not([class]) { color: black; border-bottom: 1px solid #ddd; padding-bottom: 8px; margin-top: 0; padding-top: 1rem; margin-bottom: 1.25rem; }
#toc { border-bottom: 0 solid #ddd; padding-bottom: 0.5em; }
#toc > ul { margin-left: 0.125em; }
#toc ul.sectlevel0 > li > a { font-style: italic; }
#toc ul.sectlevel0 ul.sectlevel1 { margin: 0.5em 0; }
#toc ul { font-family: Noto, sans-serif; list-style-type: none; }
#toc li { line-height: 1.3334; margin-top: 0.3334em; }
#toc a { text-decoration: none; }
#toc a:active { text-decoration: underline; }
#toctitle { color: black; font-size: 1.2em; }
@media only screen and (min-width: 768px) { #toctitle { font-size: 1.375em; }
body.toc2 { padding-left: 15em; padding-right: 0; }
#toc.toc2 { margin-top: 0 !important; background-color: #fff; position: fixed; width: 15em; left: 0; top: 0; border-right: 1px solid #ddd; border-top-width: 0 !important; border-bottom-width: 0 !important; z-index: 1000; padding: 1.25em 1em; height: 100%; overflow: auto; }
#toc.toc2 #toctitle { margin-top: 0; margin-bottom: 0.8rem; font-size: 1.2em; }
#toc.toc2 > ul { font-size: 0.9em; margin-bottom: 0; }
#toc.toc2 ul ul { margin-left: 0; padding-left: 1em; }
#toc.toc2 ul.sectlevel0 ul.sectlevel1 { padding-left: 0; margin-top: 0.5em; margin-bottom: 0.5em; }
body.toc2.toc-right { padding-left: 0; padding-right: 15em; }
body.toc2.toc-right #toc.toc2 { border-right-width: 0; border-left: 1px solid #ddd; left: auto; right: 0; } }
@media only screen and (min-width: 1280px) { body.toc2 { padding-left: 20em; padding-right: 0; }
#toc.toc2 { width: 20em; }
#toc.toc2 #toctitle { font-size: 1.375em; }
#toc.toc2 > ul { font-size: 0.95em; }
#toc.toc2 ul ul { padding-left: 1.25em; }
body.toc2.toc-right { padding-left: 0; padding-right: 20em; } }
#content #toc { border-style: solid; border-width: 1px; border-color: #e6e6e6; margin-bottom: 1.25em; padding: 1.25em; background: #fff; -webkit-border-radius: 0; border-radius: 0; }
#content #toc > :first-child { margin-top: 0; }
#content #toc > :last-child { margin-bottom: 0; }
#footer { max-width: 100%; background-color: none; padding: 1.25em; }
#footer-text { color: black; line-height: 1.44; }
#content { margin-bottom: 0.625em; }
.sect1 { padding-bottom: 0.625em; }
@media only screen and (min-width: 768px) { #content { margin-bottom: 1.25em; }
.sect1 { padding-bottom: 1.25em; } }
.sect1:last-child { padding-bottom: 0; }
.sect1 + .sect1 { border-top: 0 solid #ddd; }
#content h1 > a.anchor, h2 > a.anchor, h3 > a.anchor, #toctitle > a.anchor, .sidebarblock > .content > .title > a.anchor, h4 > a.anchor, h5 > a.anchor, h6 > a.anchor { position: absolute; z-index: 1001; width: 1.5ex; margin-left: -1.5ex; display: block; text-decoration: none !important; visibility: hidden; text-align: center; font-weight: normal; }
#content h1 > a.anchor:before, h2 > a.anchor:before, h3 > a.anchor:before, #toctitle > a.anchor:before, .sidebarblock > .content > .title > a.anchor:before, h4 > a.anchor:before, h5 > a.anchor:before, h6 > a.anchor:before { content: "\00A7"; font-size: 0.85em; display: block; padding-top: 0.1em; }
#content h1:hover > a.anchor, #content h1 > a.anchor:hover, h2:hover > a.anchor, h2 > a.anchor:hover, h3:hover > a.anchor, #toctitle:hover > a.anchor, .sidebarblock > .content > .title:hover > a.anchor, h3 > a.anchor:hover, #toctitle > a.anchor:hover, .sidebarblock > .content > .title > a.anchor:hover, h4:hover > a.anchor, h4 > a.anchor:hover, h5:hover > a.anchor, h5 > a.anchor:hover, h6:hover > a.anchor, h6 > a.anchor:hover { visibility: visible; }
#content h1 > a.link, h2 > a.link, h3 > a.link, #toctitle > a.link, .sidebarblock > .content > .title > a.link, h4 > a.link, h5 > a.link, h6 > a.link { color: black; text-decoration: none; }
#content h1 > a.link:hover, h2 > a.link:hover, h3 > a.link:hover, #toctitle > a.link:hover, .sidebarblock > .content > .title > a.link:hover, h4 > a.link:hover, h5 > a.link:hover, h6 > a.link:hover { color: black; }
.audioblock, .imageblock, .literalblock, .listingblock, .stemblock, .videoblock { margin-bottom: 1.25em; }
.admonitionblock td.content > .title, .audioblock > .title, .exampleblock > .title, .imageblock > .title, .listingblock > .title, .literalblock > .title, .stemblock > .title, .openblock > .title, .paragraph > .title, .quoteblock > .title, table.tableblock > .title, .verseblock > .title, .videoblock > .title, .dlist > .title, .olist > .title, .ulist > .title, .qlist > .title, .hdlist > .title { text-rendering: optimizeLegibility; text-align: left; }
table.tableblock > caption.title { white-space: nowrap; overflow: visible; max-width: 0; }
.paragraph.lead > p, #preamble > .sectionbody > .paragraph:first-of-type p { color: black; }
table.tableblock #preamble > .sectionbody > .paragraph:first-of-type p { font-size: inherit; }
.admonitionblock > table { border-collapse: separate; border: 0; background: none; width: 100%; }
.admonitionblock > table td.icon { text-align: center; width: 80px; }
.admonitionblock > table td.icon img { max-width: initial; }
.admonitionblock > table td.icon .title { font-weight: bold; font-family: Noto, sans-serif; text-transform: uppercase; }
.admonitionblock > table td.content { padding-left: 1.125em; padding-right: 1.25em; border-left: 1px solid #ddd; color: #5e93b8; }
.admonitionblock > table td.content > :last-child > :last-child { margin-bottom: 0; }
.exampleblock > .content { border-style: solid; border-width: 1px; border-color: #e6e6e6; margin-bottom: 1.25em; padding: 1.25em; background: #fff; -webkit-border-radius: 0; border-radius: 0; }
.exampleblock > .content > :first-child { margin-top: 0; }
.exampleblock > .content > :last-child { margin-bottom: 0; }
.sidebarblock { border-style: solid; border-width: 1px; border-color: #e6e6e6; margin-bottom: 1.25em; padding: 1.25em; background: #fff; -webkit-border-radius: 0; border-radius: 0; }
.sidebarblock > :first-child { margin-top: 0; }
.sidebarblock > :last-child { margin-bottom: 0; }
.sidebarblock > .content > .title { color: black; margin-top: 0; }
.exampleblock > .content > :last-child > :last-child, .exampleblock > .content .olist > ol > li:last-child > :last-child, .exampleblock > .content .ulist > ul > li:last-child > :last-child, .exampleblock > .content .qlist > ol > li:last-child > :last-child, .sidebarblock > .content > :last-child > :last-child, .sidebarblock > .content .olist > ol > li:last-child > :last-child, .sidebarblock > .content .ulist > ul > li:last-child > :last-child, .sidebarblock > .content .qlist > ol > li:last-child > :last-child { margin-bottom: 0; }
.literalblock pre, .listingblock pre:not(.highlight), .listingblock pre[class="highlight"], .listingblock pre[class^="highlight "], .listingblock pre.CodeRay, .listingblock pre.prettyprint { background: #eee; }
.sidebarblock .literalblock pre, .sidebarblock .listingblock pre:not(.highlight), .sidebarblock .listingblock pre[class="highlight"], .sidebarblock .listingblock pre[class^="highlight "], .sidebarblock .listingblock pre.CodeRay, .sidebarblock .listingblock pre.prettyprint { background: #f2f1f1; }
.literalblock pre, .literalblock pre[class], .listingblock pre, .listingblock pre[class] { border: 1px hidden #666; -webkit-border-radius: 0; border-radius: 0; word-wrap: break-word; padding: 1.25em 1.5625em 1.125em 1.5625em; font-size: 0.8125em; }
.literalblock pre.nowrap, .literalblock pre[class].nowrap, .listingblock pre.nowrap, .listingblock pre[class].nowrap { overflow-x: auto; white-space: pre; word-wrap: normal; }
@media only screen and (min-width: 768px) { .literalblock pre, .literalblock pre[class], .listingblock pre, .listingblock pre[class] { font-size: 0.90625em; } }
@media only screen and (min-width: 1280px) { .literalblock pre, .literalblock pre[class], .listingblock pre, .listingblock pre[class] { font-size: 1em; } }
.literalblock.output pre { color: #eee; background-color: #264357; }
.listingblock pre.highlightjs { padding: 0; }
.listingblock pre.highlightjs > code { padding: 1.25em 1.5625em 1.125em 1.5625em; -webkit-border-radius: 0; border-radius: 0; }
.listingblock > .content { position: relative; }
.listingblock code[data-lang]:before { display: none; content: attr(data-lang); position: absolute; font-size: 0.75em; top: 0.425rem; right: 0.5rem; line-height: 1; text-transform: uppercase; color: #999; }
.listingblock:hover code[data-lang]:before { display: block; }
.listingblock.terminal pre .command:before { content: attr(data-prompt); padding-right: 0.5em; color: #999; }
.listingblock.terminal pre .command:not([data-prompt]):before { content: "$"; }
table.pyhltable { border-collapse: separate; border: 0; margin-bottom: 0; background: none; }
table.pyhltable td { vertical-align: top; padding-top: 0; padding-bottom: 0; line-height: 1.6; }
table.pyhltable td.code { padding-left: .75em; padding-right: 0; }
pre.pygments .lineno, table.pyhltable td:not(.code) { color: #999; padding-left: 0; padding-right: .5em; border-right: 1px solid #ddd; }
pre.pygments .lineno { display: inline-block; margin-right: .25em; }
table.pyhltable .linenodiv { background: none !important; padding-right: 0 !important; }
.quoteblock { margin: 0 1em 0.75em 1.5em; display: table; }
.quoteblock > .title { margin-left: -1.5em; margin-bottom: 0.75em; }
.quoteblock blockquote, .quoteblock blockquote p { color: #333; font-size: 1.15rem; line-height: 1.75; word-spacing: 0.1em; letter-spacing: 0; font-style: italic; text-align: justify; }
.quoteblock blockquote { margin: 0; padding: 0; border: 0; }
.quoteblock blockquote:before { content: "\201c"; float: left; font-size: 2.75em; font-weight: bold; line-height: 0.6em; margin-left: -0.6em; color: black; text-shadow: 0 1px 2px rgba(0, 0, 0, 0.1); }
.quoteblock blockquote > .paragraph:last-child p { margin-bottom: 0; }
.quoteblock .attribution { margin-top: 0.5em; margin-right: 0.5ex; text-align: right; }
.quoteblock .quoteblock { margin-left: 0; margin-right: 0; padding: 0.5em 0; border-left: 3px solid #5e93b8; }
.quoteblock .quoteblock blockquote { padding: 0 0 0 0.75em; }
.quoteblock .quoteblock blockquote:before { display: none; }
.verseblock { margin: 0 1em 0.75em 1em; }
.verseblock pre { font-family: "Open Sans", "DejaVu Sans", sans; font-size: 1.15rem; color: #333; font-weight: 300; text-rendering: optimizeLegibility; }
.verseblock pre strong { font-weight: 400; }
.verseblock .attribution { margin-top: 1.25rem; margin-left: 0.5ex; }
.quoteblock .attribution, .verseblock .attribution { font-size: 0.8125em; line-height: 1.45; font-style: italic; }
.quoteblock .attribution br, .verseblock .attribution br { display: none; }
.quoteblock .attribution cite, .verseblock .attribution cite { display: block; letter-spacing: -0.025em; color: #5e93b8; }
.quoteblock.abstract { margin: 0 0 0.75em 0; display: block; }
.quoteblock.abstract blockquote, .quoteblock.abstract blockquote p { text-align: left; word-spacing: 0; }
.quoteblock.abstract blockquote:before, .quoteblock.abstract blockquote p:first-of-type:before { display: none; }
table.tableblock { max-width: 100%; border-collapse: separate; }
table.tableblock td > .paragraph:last-child p > p:last-child, table.tableblock th > p:last-child, table.tableblock td > p:last-child { margin-bottom: 0; }
table.tableblock, th.tableblock, td.tableblock { border: 0 solid #d8d8ce; }
table.grid-all > thead > tr > .tableblock, table.grid-all > tbody > tr > .tableblock { border-width: 0 1px 1px 0; }
table.grid-all > tfoot > tr > .tableblock { border-width: 1px 1px 0 0; }
table.grid-cols > * > tr > .tableblock { border-width: 0 1px 0 0; }
table.grid-rows > thead > tr > .tableblock, table.grid-rows > tbody > tr > .tableblock { border-width: 0 0 1px 0; }
table.grid-rows > tfoot > tr > .tableblock { border-width: 1px 0 0 0; }
table.grid-all > * > tr > .tableblock:last-child, table.grid-cols > * > tr > .tableblock:last-child { border-right-width: 0; }
table.grid-all > tbody > tr:last-child > .tableblock, table.grid-all > thead:last-child > tr > .tableblock, table.grid-rows > tbody > tr:last-child > .tableblock, table.grid-rows > thead:last-child > tr > .tableblock { border-bottom-width: 0; }
table.frame-all { border-width: 1px; }
table.frame-sides { border-width: 0 1px; }
table.frame-topbot { border-width: 1px 0; }
th.halign-left, td.halign-left { text-align: left; }
th.halign-right, td.halign-right { text-align: right; }
th.halign-center, td.halign-center { text-align: center; }
th.valign-top, td.valign-top { vertical-align: top; }
th.valign-bottom, td.valign-bottom { vertical-align: bottom; }
th.valign-middle, td.valign-middle { vertical-align: middle; }
table thead th, table tfoot th { font-weight: bold; }
tbody tr th { display: table-cell; line-height: 1.4; background: #eee; }
tbody tr th, tbody tr th p, tfoot tr th, tfoot tr th p { color: #222; font-weight: bold; }
p.tableblock > code:only-child { background: none; padding: 0; }
p.tableblock { font-size: 1em; }
td > div.verse { white-space: pre; }
ol { margin-left: 1.75em; }
ul li ol { margin-left: 1.5em; }
dl dd { margin-left: 1.125em; }
dl dd:last-child, dl dd:last-child > :last-child { margin-bottom: 0; }
ol > li p, ul > li p, ul dd, ol dd, .olist .olist, .ulist .ulist, .ulist .olist, .olist .ulist { margin-bottom: 0.375em; }
ul.checklist, ul.none, ol.none, ul.no-bullet, ol.no-bullet, ol.unnumbered, ul.unstyled, ol.unstyled { list-style-type: none; }
ul.no-bullet, ol.no-bullet, ol.unnumbered { margin-left: 0.625em; }
ul.unstyled, ol.unstyled { margin-left: 0; }
ul.checklist { margin-left: 0.625em; }
ul.checklist li > p:first-child > .fa-square-o:first-child, ul.checklist li > p:first-child > .fa-check-square-o:first-child { width: 1.25em; font-size: 0.8em; position: relative; bottom: 0.125em; }
ul.checklist li > p:first-child > input[type="checkbox"]:first-child { margin-right: 0.25em; }
ul.inline { display: -ms-flexbox; display: -webkit-box; display: flex; -ms-flex-flow: row wrap; -webkit-flex-flow: row wrap; flex-flow: row wrap; list-style: none; margin: 0 0 0.375em -0.75em; }
ul.inline > li { margin-left: 0.75em; }
.unstyled dl dt { font-weight: normal; font-style: normal; }
ol.arabic { list-style-type: decimal; }
ol.decimal { list-style-type: decimal-leading-zero; }
ol.loweralpha { list-style-type: lower-alpha; }
ol.upperalpha { list-style-type: upper-alpha; }
ol.lowerroman { list-style-type: lower-roman; }
ol.upperroman { list-style-type: upper-roman; }
ol.lowergreek { list-style-type: lower-greek; }
.hdlist > table, .colist > table { border: 0; background: none; }
.hdlist > table > tbody > tr, .colist > table > tbody > tr { background: none; }
td.hdlist1, td.hdlist2 { vertical-align: top; padding: 0 0.625em; }
td.hdlist1 { font-weight: bold; padding-bottom: 0.75em; }
.literalblock + .colist, .listingblock + .colist { margin-top: -0.5em; }
.colist > table tr > td:first-of-type { padding: 0.4em 0.75em 0 0.75em; line-height: 1; vertical-align: top; }
.colist > table tr > td:first-of-type img { max-width: initial; }
.colist > table tr > td:last-of-type { padding: 0.25em 0; }
.thumb, .th { line-height: 0; display: inline-block; border: solid 4px #fff; -webkit-box-shadow: 0 0 0 1px #ddd; box-shadow: 0 0 0 1px #ddd; }
.imageblock.left, .imageblock[style*="float: left"] { margin: 0.25em 0.625em 1.25em 0; }
.imageblock.right, .imageblock[style*="float: right"] { margin: 0.25em 0 1.25em 0.625em; }
.imageblock > .title { margin-bottom: 0; }
.imageblock.thumb, .imageblock.th { border-width: 6px; }
.imageblock.thumb > .title, .imageblock.th > .title { padding: 0 0.125em; }
.image.left, .image.right { margin-top: 0.25em; margin-bottom: 0.25em; display: inline-block; line-height: 0; }
.image.left { margin-right: 0.625em; }
.image.right { margin-left: 0.625em; }
a.image { text-decoration: none; display: inline-block; }
a.image object { pointer-events: none; }
sup.footnote, sup.footnoteref { font-size: 0.875em; position: static; vertical-align: super; }
sup.footnote a, sup.footnoteref a { text-decoration: none; }
sup.footnote a:active, sup.footnoteref a:active { text-decoration: underline; }
#footnotes { padding-top: 0.75em; padding-bottom: 0.75em; margin-bottom: 0.625em; }
#footnotes hr { width: 20%; min-width: 6.25em; margin: -0.25em 0 0.75em 0; border-width: 1px 0 0 0; }
#footnotes .footnote { padding: 0 0.375em 0 0.225em; line-height: 1.3334; font-size: 0.875em; margin-left: 1.2em; margin-bottom: 0.2em; }
#footnotes .footnote a:first-of-type { font-weight: bold; text-decoration: none; margin-left: -1.05em; }
#footnotes .footnote:last-of-type { margin-bottom: 0; }
#content #footnotes { margin-top: -0.625em; margin-bottom: 0; padding: 0.75em 0; }
.gist .file-data > table { border: 0; background: #fff; width: 100%; margin-bottom: 0; }
.gist .file-data > table td.line-data { width: 99%; }
div.unbreakable { page-break-inside: avoid; }
.big { font-size: larger; }
.small { font-size: smaller; }
.underline { text-decoration: underline; }
.overline { text-decoration: overline; }
.line-through { text-decoration: line-through; }
.aqua { color: #00bfbf; }
.aqua-background { background-color: #00fafa; }
.black { color: black; }
.black-background { background-color: black; }
.blue { color: #0000bf; }
.blue-background { background-color: #0000fa; }
.fuchsia { color: #bf00bf; }
.fuchsia-background { background-color: #fa00fa; }
.gray { color: #606060; }
.gray-background { background-color: #7d7d7d; }
.green { color: #006000; }
.green-background { background-color: #007d00; }
.lime { color: #00bf00; }
.lime-background { background-color: #00fa00; }
.maroon { color: #600000; }
.maroon-background { background-color: #7d0000; }
.navy { color: #000060; }
.navy-background { background-color: #00007d; }
.olive { color: #606000; }
.olive-background { background-color: #7d7d00; }
.purple { color: #600060; }
.purple-background { background-color: #7d007d; }
.red { color: #bf0000; }
.red-background { background-color: #fa0000; }
.silver { color: #909090; }
.silver-background { background-color: #bcbcbc; }
.teal { color: #006060; }
.teal-background { background-color: #007d7d; }
.white { color: #bfbfbf; }
.white-background { background-color: #fafafa; }
.yellow { color: #bfbf00; }
.yellow-background { background-color: #fafa00; }
span.icon > .fa { cursor: default; }
a span.icon > .fa { cursor: inherit; }
.admonitionblock td.icon [class^="fa icon-"] { font-size: 2.5em; text-shadow: 1px 1px 2px rgba(0, 0, 0, 0.5); cursor: default; }
.admonitionblock td.icon .icon-note:before { content: "\f05a"; color: #29475c; }
.admonitionblock td.icon .icon-tip:before { content: "\f0eb"; text-shadow: 1px 1px 2px rgba(155, 155, 0, 0.8); color: #111; }
.admonitionblock td.icon .icon-warning:before { content: "\f071"; color: #bf6900; }
.admonitionblock td.icon .icon-caution:before { content: "\f06d"; color: #bf3400; }
.admonitionblock td.icon .icon-important:before { content: "\f06a"; color: #bf0000; }
.conum[data-value] { display: inline-block; color: #fff !important; background-color: black; -webkit-border-radius: 100px; border-radius: 100px; text-align: center; font-size: 0.75em; width: 1.67em; height: 1.67em; line-height: 1.67em; font-family: "Open Sans", "DejaVu Sans", sans-serif; font-style: normal; font-weight: bold; }
.conum[data-value] * { color: #fff !important; }
.conum[data-value] + b { display: none; }
.conum[data-value]:after { content: attr(data-value); }
pre .conum[data-value] { position: relative; top: -0.125em; }
b.conum * { color: inherit !important; }
.conum:not([data-value]):empty { display: none; }
h1, h2, h3, #toctitle, .sidebarblock > .content > .title, h4, h5, h6 { border-bottom: 1px solid #ddd; }
.sect1 { padding-bottom: 0; }
#toctitle { color: #00406F; font-weight: normal; margin-top: 1.5em; }
.sidebarblock { border-color: #aaa; }
code { -webkit-border-radius: 4px; border-radius: 4px; }
p.tableblock.header { color: #6d6e71; }
.literalblock pre, .listingblock pre { background: #eee; }

108
doc/specs/vulkan/copyright-spec.txt
View File

@ -1,61 +1,71 @@
Copyright 2014-2018 The Khronos Group Inc.
This specification is protected by copyright laws and contains material proprietary
to Khronos. Except as described by these terms, it or any components
may not be reproduced, republished, distributed, transmitted, displayed, broadcast
or otherwise exploited in any manner without the express prior written permission
of Khronos.
This Specification is protected by copyright laws and contains material
proprietary to Khronos. Except as described by these terms, it or any
components may not be reproduced, republished, distributed, transmitted,
displayed, broadcast or otherwise exploited in any manner without the
express prior written permission of Khronos.
Khronos grants a conditional copyright license to use and reproduce the
unmodified Specification for any purpose, without fee or royalty, EXCEPT no
licenses to any patent, trademark or other intellectual property rights are
granted under these terms.
This specification has been created under the Khronos Intellectual Property Rights
Policy, which is Attachment A of the Khronos Group Membership Agreement available at
www.khronos.org/files/member_agreement.pdf. Khronos Group grants a conditional
copyright license to use and reproduce the unmodified specification for any purpose,
without fee or royalty, EXCEPT no licenses to any patent, trademark or other
intellectual property rights are granted under these terms. Parties desiring to
implement the specification and make use of Khronos trademarks in relation to that
implementation, and receive reciprocal patent license protection under the Khronos
IP Policy must become Adopters and confirm the implementation as conformant under
the process defined by Khronos for this specification;
see https://www.khronos.org/adopters.
Khronos makes no, and expressly disclaims any, representations or
warranties, express or implied, regarding this Specification, including,
without limitation: merchantability, fitness for a particular purpose,
non-infringement of any intellectual property, correctness, accuracy,
completeness, timeliness, and reliability.
Under no circumstances will Khronos, or any of its Promoters, Contributors
or Members, or their respective partners, officers, directors, employees,
agents or representatives be liable for any damages, whether direct,
indirect, special or consequential damages for lost revenues, lost profits,
or otherwise, arising from or in connection with these materials.
Khronos makes no, and expressly disclaims any, representations or warranties,
express or implied, regarding this specification, including, without limitation:
merchantability, fitness for a particular purpose, non-infringement of any
intellectual property, correctness, accuracy, completeness, timeliness, and
reliability. Under no circumstances will Khronos, or any of its Promoters,
Contributors or Members, or their respective partners, officers, directors,
employees, agents or representatives be liable for any damages, whether direct,
indirect, special or consequential damages for lost revenues, lost profits, or
otherwise, arising from or in connection with these materials.
This Specification has been created under the Khronos Intellectual Property
Rights Policy, which is Attachment A of the Khronos Group Membership
Agreement available at www.khronos.org/files/member_agreement.pdf, and which
defines the terms 'Scope', 'Compliant Portion', and 'Necessary Patent Claims'.
Parties desiring to implement the Specification and make use of Khronos trademarks
in relation to that implementation, and receive reciprocal patent license protection
under the Khronos Intellectual Property Rights Policy must become Adopters and
confirm the implementation as conformant under the process defined by Khronos for
this Specification; see https://www.khronos.org/adopters.
This specification contains substantially unmodified functionality from, and is a
This Specification contains substantially unmodified functionality from, and is a
successor to, Khronos specifications including OpenGL, OpenGL ES and OpenCL.
Some parts of this Specification are purely informative and do not define requirements
necessary for compliance and so are outside the Scope of this Specification. These
parts of the Specification are marked by the "`Note`" icon or designated "`Informative`".
Some parts of this Specification are purely informative and so are EXCLUDED from
the Scope of this Specification. The <<introduction-conventions>> section of the
<<introduction>> defines how these parts of the Specification are identified.
Where this Specification uses terms, defined in the Glossary or otherwise, that refer to
enabling technologies that are not expressly set forth as being required for compliance,
those enabling technologies are outside the Scope of this Specification.
Where this Specification uses <<introduction-technical-terminology,technical
terminology>>, defined in the <<glossary>> or otherwise, that refer to
enabling technologies that are not expressly set forth in this
Specification, those enabling technologies are EXCLUDED from the Scope of
this Specification.
For clarity, enabling technologies not disclosed with particularity in this
Specification (e.g. semiconductor manufacturing technology, hardware
architecture, processor architecture or microarchitecture, memory
architecture, compiler technology, object oriented technology, basic
operating system technology, compression technology, algorithms, and so on)
are NOT to be considered expressly set forth; only those application program
interfaces and data structures disclosed with particularity are included in
the Scope of this Specification.
Where this Specification uses the terms "`may`", or "`optional`", such features or
behaviors do not define requirements necessary for compliance and so are outside the
Scope of this Specification.
For purposes of the Khronos Intellectual Property Rights Policy as it relates
to the definition of Necessary Patent Claims, all recommended or optional
features, behaviors and functionality set forth in this Specification, if
implemented, are considered to be included as Compliant Portions.
Where this Specification uses the terms "`not required`", such features or
behaviors may be omitted from certain implementations, but when they are included, they
define requirements necessary for compliance and so are INCLUDED in the Scope of this
Specification.
Where this Specification includes normative references to external documents, the
specifically identified sections and functionality of those external documents are in
Scope. Requirements defined by external documents not created by Khronos may contain
contributions from non-members of Khronos not covered by the Khronos Intellectual
Property Rights Policy.
Where this Specification includes <<introduction-normative-references,
normative references to external documents>>, only the specifically
identified sections of those external documents are INCLUDED in the Scope of
this Specification. If not created by Khronos, those external documents may
contain contributions from non-members of Khronos not covered by the Khronos
Intellectual Property Rights Policy.
Vulkan is a registered trademark, and Khronos is a trademark of The Khronos
Group Inc. ASTC is a trademark of ARM Holdings PLC; OpenCL is a trademark of Apple Inc.;
and OpenGL is a registered trademark of Silicon Graphics International, all used under license by
Khronos. All other product names, trademarks, and/or company names are used solely for
identification and belong to their respective owners.
Group Inc. ASTC is a trademark of ARM Holdings PLC; OpenCL is a trademark of
Apple Inc.; and OpenGL is a registered trademark of Silicon Graphics International,
all used under license by Khronos. All other product names, trademarks, and/or
company names are used solely for identification and belong to their respective owners.

7
doc/specs/vulkan/genRef.py
View File

@ -220,7 +220,6 @@ def refPageTail(pageName, seeAlso, fp, auto = False):
# file - list of strings making up the file, indexed by pi
def emitPage(baseDir, specDir, pi, file):
pageName = baseDir + '/' + pi.name + '.txt'
fp = open(pageName, 'w', encoding='utf-8')
# Add a dictionary entry for this page
global genDict
@ -231,6 +230,11 @@ def emitPage(baseDir, specDir, pi, file):
if pi.desc == None:
pi.desc = '(no short description available)'
# Not sure how this happens yet
if pi.include == None:
logWarn('emitPage:', pageName, 'INCLUDE == None, no page generated')
return
# Specification text
lines = remapIncludes(file[pi.begin:pi.include+1], baseDir, specDir)
specText = ''.join(lines)
@ -261,6 +265,7 @@ def emitPage(baseDir, specDir, pi, file):
fieldText, n = specLinksPattern.subn(specLinksSubstitute, fieldText)
descText, n = specLinksPattern.subn(specLinksSubstitute, descText)
fp = open(pageName, 'w', encoding='utf-8')
refPageHead(pi.name,
pi.desc,
specText,

126
doc/specs/vulkan/genRelease
View File

@ -15,47 +15,111 @@
# limitations under the License.
# Ensure config/extDependency.py is up-to-date before we import it.
import subprocess
subprocess.check_call(['make', 'config/extDependency.py'])
# If it is up to date, 'make' will print a useless warning without '-s'.
import subprocess,sys
subprocess.check_call(['make', '-s', 'config/extDependency.py'])
# Must alter sys.path to import config/extDependency.py.
import sys
# Alter sys.path to import config/extDependency.py.
sys.path = sys.path + [ 'config' ]
from genspec import *
from extDependency import allExts, khrExts, khxExts
from extDependency import allExts, khrExts
repoDir = '/home/tree/git/Vulkan-Docs'
outDir = '/home/tree/git/registry/vulkan/specs'
# Eventually, these may be defined by extDependency.py
allVersions = [ 'VK_VERSION_1_0', 'VK_VERSION_1_1' ]
Version1_0 = [ 'VK_VERSION_1_0' ]
print('echo Building in', repoDir, 'for public release')
publicRelease = True
if publicRelease:
# For public release
repoDir = '/home/tree/git/Vulkan-Docs'
outDir = '/home/tree/git/registry/vulkan/specs'
else:
# For internal build & pseudo-release
repoDir = '/home/tree/git/vulkan'
#outDir = '/home/tree/git/vulkan/doc/specs/vulkan/reg'
outDir = '/home/tree/git/registry/vulkan/specs'
print('echo Building release from', repoDir, 'to', outDir)
print('')
buildBranch('1.0-extensions',
extensions = allExts,
apititle = '(with all registered Vulkan extensions)',
xmlTargets = 'clobber install',
specTargets = 'html pdf validusage',
repoDir = repoDir,
outDir = outDir)
# Spec targets to build - html, pdf, or both.
# pdf is very slow, but needed for public releases.
specTargets = 'html pdf'
buildBranch('1.0-wsi_extensions',
extensions = khrExts,
apititle = '(with KHR extensions)',
xmlTargets = 'clobber install',
specTargets = 'html pdf',
repoDir = repoDir,
outDir = outDir)
print('echo Info: not build spec PDF targets')
# Vulkan 1.1 specs
# Build validusage target only for 1.1 + all extensions
buildBranch('1.1-extensions',
versions = allVersions,
extensions = allExts,
apititle = '(with all registered Vulkan extensions)',
xmlTargets = 'clobber install',
specTargets = specTargets + ' validusage',
repoDir = repoDir,
outDir = outDir)
buildBranch('1.1-khr-extensions',
versions = allVersions,
extensions = khrExts,
apititle = '(with KHR extensions)',
xmlTargets = 'clobber install',
specTargets = specTargets,
repoDir = repoDir,
outDir = outDir)
# Build ref pages, style guide, and registry documentation targets only for
# 1.1 + no extensions.
# Ref page build isn't quite working yet. Once it is, replace argument
# specTargets with:
# specTargets = specTargets + ' styleguide registry manhtml manhtmlpages manpdf',
buildBranch('1.1',
versions = allVersions,
extensions = None,
apititle = None,
xmlTargets = 'clobber install',
specTargets = specTargets + ' styleguide registry',
repoDir = repoDir,
outDir = outDir,
needRefSources = True)
print('echo Info: Not building 1.1 reference pages yet')
# Vulkan 1.0 specs (TBD, doesn't quite work right yet)
if False:
buildBranch('1.0-extensions',
versions = Version1_0,
extensions = allExts,
apititle = '(with all registered Vulkan extensions)',
xmlTargets = 'clobber install',
specTargets = specTargets,
repoDir = repoDir,
outDir = outDir)
buildBranch('1.0-wsi_extensions',
versions = Version1_0,
extensions = khrExts,
apititle = '(with KHR extensions)',
xmlTargets = 'clobber install',
specTargets = specTargets,
repoDir = repoDir,
outDir = outDir)
buildBranch('1.0',
versions = Version1_0,
extensions = None,
apititle = None,
xmlTargets = 'clobber install',
specTargets = specTargets,
repoDir = repoDir,
outDir = outDir)
else:
print('echo Info: Not building 1.0 specs yet')
# Only build ref pages for 1.0 target
buildBranch('1.0',
extensions = None,
apititle = None,
xmlTargets = 'clobber install',
specTargets = 'html styleguide registry manhtml manhtmlpages pdf manpdf',
repoDir = repoDir,
outDir = outDir,
needRefSources = True)
print('echo Info: post-generation cleanup')

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

@ -38,6 +38,7 @@ def buildOnFriday():
return friday
# label = textual label to use for target being generated
# versions = list of core API versions to include
# extensions = list of extension names to include
# outdir = directory to generate specs in
# apititle = extra title to apply to the specification
@ -48,7 +49,10 @@ def buildOnFriday():
# miscSrc = path to copy misc files from, if non-None
# miscDst = path to copy misc files to, if non-None
# needRefSources = True if ref pages must be extracted from the spec sources
def buildRelease(label, extensions, outdir,
def buildRelease(label,
versions,
extensions,
outdir,
apititle,
xmlDir, xmlTargets,
specDir, specTargets,
@ -59,6 +63,11 @@ def buildRelease(label, extensions, outdir,
outarg = 'OUTDIR=' + outdir
if (versions != None and len(versions) > 0):
versarg = 'VERSIONS="' + ' '.join(versions) + '"'
else:
versarg = ''
if (extensions != None and len(extensions) > 0):
extarg = 'EXTENSIONS="' + ' '.join(extensions) + '"'
else:
@ -69,7 +78,8 @@ def buildRelease(label, extensions, outdir,
else:
titlearg = ''
# print('echo Info: Cleaning spec in', outdir)
# print('echo Info: Creating directory and cleaning spec in', outdir)
print('mkdir -p', outdir)
print('(cd ', outdir, '&& rm -rf',
'html chunked pdf',
'man config checks',
@ -87,12 +97,10 @@ def buildRelease(label, extensions, outdir,
# specTargets require ref page sources, and they aren't already present
# at the time the make is invoked, that target will not be built.
if needRefSources:
print('make', outarg, extarg, 'man/apispec.txt')
print('make', outarg, versarg, extarg, 'man/apispec.txt')
# Now make the actual targets.
print('make -O -k -j 8',
outarg,
extarg,
titlearg,
outarg, versarg, extarg, titlearg,
'NOTEOPTS="-a implementation-guide"',
specTargets)
@ -105,27 +113,36 @@ def buildRelease(label, extensions, outdir,
# Build all target documents
# repoDir = path to the Vulkan git repo containing the specs
# outDir = path to the output base directory in which targets are generated
def buildBranch(targetDir, extensions, apititle,
xmlTargets, specTargets,
repoDir, outDir,
def buildBranch(targetDir,
versions,
extensions,
apititle,
xmlTargets,
specTargets,
repoDir,
outDir,
needRefSources = False):
# Directory with vk.xml and generation tools
xmlDir = repoDir + '/src/spec'
# Directory with spec sources
specDir = repoDir + '/doc/specs/vulkan'
# Src/dst directories with misc. GLSL extension specs
# This will no longer be done after !2559 is accepted, since the
# extensions will have moved to the GLSL repository.
# miscSrc = repoDir + '/doc/specs/misc'
# miscDst = outDir + '/misc'
# Directory containing misc. files to copy to registry.
# At present there are none, since GLSL extensions have moved to the
# GLSL repository and are redirected from the Vulkan registy website.
# These should be relative to repoDir and outDir, respectively
miscSrc = None
miscDst = None
buildRelease(targetDir, extensions, outDir + '/' + targetDir,
buildRelease(targetDir,
versions,
extensions,
outDir + '/' + targetDir,
apititle,
xmlDir, xmlTargets, specDir, specTargets,
miscSrc, miscDst, needRefSources)
xmlDir, xmlTargets,
specDir, specTargets,
miscSrc, miscDst,
needRefSources)
# Commands to tag the git branches
# releaseNum = release number of this spec update, to tag the tree with
@ -135,8 +152,8 @@ def createTags(releaseNum, tagdate):
now = tagdate.strftime('%Y%m%d')
print('echo To tag the spec branch for this release, execute the command:')
print('echo git tag -a -m \\"Tag Vulkan API specification for 1.0.' +
releaseNum, 'release\\"', 'v1.0.' + releaseNum + '-core')
print('echo git tag -a -m \\"Tag Vulkan API specification for 1.1.' +
releaseNum, 'release\\"', 'v1.1.' + releaseNum + '-core')
#print('echo git tag -a -m \\"Tag Vulkan API specification for', now,
# 'release\\"', 'v1.0-core-' + now)
# 'release\\"', 'v1.1-core-' + now)

48
doc/specs/vulkan/images/Makefile
View File

@ -1,48 +0,0 @@
# This Makefile should be used to regenerate alternate forms of
# documents when the source changes. Note that pipeline.* is
# treated specially since its original source format is .pptx
#
# Targets:
# all - regenerate all images from source formats
# clean - remove all generated images
# individual files in $(TARGETS) below
# Default rules go from Inkscape SVG -> PDF.
# Some bashing is required for vulkanpipeline.*, which originally
# comes from PowerPoint -> export to PDF -> convert to SVG. Converting
# the other way using inkscape just does not work - horrible drop
# shadows everywhere.
# If a recipe fails, delete its target file. Without this cleanup, the leftover
# file from the failed recipe can falsely satisfy dependencies on subsequent
# runs of `make`.
.DELETE_ON_ERROR:
#.SUFFIXES: .pdf .svg
#.svg.pdf: ; $(INKSCAPE) -f $< -A $@
# Tool to convert image formats
INKSCAPE ?= inkscape
# PDFs to regenerate from SVGs - everything except pipeline.pdf
SVGEXCLUDES = pipeline.svg tstripadj.svg vulkantexture0.svg
SVGSRC = $(filter-out $(SVGEXCLUDES),$(wildcard [A-Za-z]*.svg))
PDFDST = $(SVGSRC:%.svg=%.pdf) tstripadj.pdf
SVGDST = pipeline.svg tstripadj.svg
all: $(PDFDST) $(SVGDST)
$(PDFDST): %.pdf: %.svg
$(INKSCAPE) -f $< -A $@
# This came from PowerPoint originally (I think)
pipeline.svg: pipeline.pdf
$(INKSCAPE) -f $< -l $@
# This doesn't render properly in Firefox/IE 11 due to Inkscape markup.
tstripadj.svg: Source/tstripadj.svg
$(INKSCAPE) -f $< -l $@
clean:
-rm -f $(PDFDST) $(SVGDST)

22
doc/specs/vulkan/images/README
View File

@ -1,22 +0,0 @@
Figures for the Vulkan spec. With the exception of pipeline.pptx, the
current source format for all figures is Inkscape SVG, which is
converted to PDF by the Makefile.
For the pipeline figure, the source is .pptx, which must be manually
exported to PDF (using Powerpoint) and then to SVG (using Inkscape).
Many figures were originally generated in the open source "Dia" drawing
program format. The .dia files are now in oldSource/*.dia, since we're
trying to centralize on Inkscape SVG -> PDF wherever possible. The main
drawback of this is that all the connectivity information in the .dia
file is lost, so modifying these figures in Inkscape will be very
painful. It might be best to edit the original .dia file if anything
nontrivial needs to be done.
To convert .dia -> Inkscape SVG, you can use
inkscape -f oldSource/file.dia -A file.svg
followed by running Inkscape on file.svg, setting the bounding box of
the figure to the contents using the File / Preferences dialog, and
overwriting file.svg.

32
doc/specs/vulkan/images/README.adoc Normal file
View File

@ -0,0 +1,32 @@
= Diagrams
Diagrams in this folder have been created with Inkscape, using a restricted
color palette (white, black, 50% gray and pure red), one choice of dotted
vs. solid lines, and only two text sizes (8 and 12) using the generic
"sans serif" font family.
If adding any new diagrams, please try to maintain consistency with the rest
of these diagrams in order to aid consistency and readability of the Vulkan
specification.
Inkscape does not need to be used, but is recommended as a powerful free
tool for generating vector diagrams, and is known to generate diagrams
compatible with the rest of the Vulkan toolchain.
If using other tools, please ensure that the diagram renders correctly in
popular browsers and in the PDF generation path for the specification.
== UTF-8 Characters
At the moment, the PDF conversion path only supports the Windows-1252
character set, as we are currently using the standard fonts built into every
PDF viewer - such that we don't have to embed a different font.
Unfortunately these only support Windows-1252, which is a highly limited
character set.
As such, characters not in that set will not display properly when present
in an SVG, and will fire a warning when building the PDF.
Luckily, Inkscape has an "Object to path" function built in, which will
convert text to a raw path, allowing these characters to be supported.
Please ensure that you build the PDF before submitting any new images,
particularly with non-standard characters, in order to catch such errors.

BIN
doc/specs/vulkan/images/Source/innerquad.dia
View File

Binary file not shown.

2752
doc/specs/vulkan/images/Source/innertri.dia
View File

File diff suppressed because it is too large Load Diff

BIN
doc/specs/vulkan/images/Source/lineadj.dia
View File

Binary file not shown.

1078
doc/specs/vulkan/images/Source/tstripadj.svg
View File

File diff suppressed because it is too large Load Diff
Side by Side

Before

Width:  |  Height:  |  Size: 34 KiB

Some files were not shown because too many files have changed in this diff Show More