status-im/Vulkan-Docs
2
0
Fork 0
mirror of https://github.com/status-im/Vulkan-Docs.git synced 2025-02-22 11:08:19 +00:00
Code Issues Projects Releases Wiki Activity

Change log for January 23, 2017 Vulkan 1.0.39 spec update:

Browse Source 
* Bump API patch number and header version number to 39 for this update.

Github Issues:

  * Clarified that only accesses via the specified buffer/image subresource
    ranges are included in the access scopes (public issue 306).
  * Add missing valid usage statements for flink:vkCreateComputePipelines
    and flink:vkCreateGraphicsPipelines (public issue 427).

Internal Issues:

  * Add a Note to the <<invariance,Invariance>> appendix about a difference
    between OpenGL and Vulkan with regards to how primitives derived from
    offsets are handled (internal issue 355).
  * Add the +<<VK_KHR_get_physical_device_properties2>>+,
    +<<VK_KHR_maintenance1>>+, and +<<VK_KHR_shader_draw_parameters>>+
    extensions (internal issue 448).
  * Add the +<<VK_EXT_shader_subgroup_vote>>+ and
    +<<VK_EXT_shader_subgroup_ballot>>+ extensions (internal issue 449).
  * Update the texture level-of-detail equation in the
    <<textures-scale-factor,Scale Factor Operation>> section to better
    approximate the ellipse major and minor axes (internal issue 547).
  * Forbid non-explicitly allowed uses of interface decorations in the
    introduction to the <<interfaces,Shader Interfaces>> chapter (internal
    issue 607).
  * Replace use of MathJax with KaTeX, for improved load-time performance as
    well as avoiding the scrolling-and-scrolling behavior due to MathJax
    asynchronous rendering when loading at an anchor inside the spec. This
    change also requires moving to HTML5 output for the spec instead of
    XHTML, and there is a visible difference in that the chapter navigation
    index is now in a scrollable sidebar instead of at the top of the
    document. We may or may not retain the nav sidebar based on feedback
    (internal issue 613).
  * Improve consistency of markup and formatting in extension appendices
    (internal issue 631).

Other Issues:

  * Add explicit valid usage statements to slink:VkImageCopy requiring that
    the source and destination layer ranges be contained in their respective
    source and destination images.
  * Add valid usage language for swapchain of flink:vkAcquireNextImage. If
    the swapchain has been replaced, then it should not be passed to
    flink:vkAcquireNextImage.
  * Add a valid usage statement to flink:vkCreateImageView, that the image
    must have been created with an appropriate usage bit set.
  * Noted that slink:VkDisplayPresentInfoKHR is a valid extension of
    slink:VkPresentInfoKHR in the <<wsi_swapchain,WSI Swapchain>> section.
  * Update valid usage for flink:vkCmdSetViewport and flink:vkCmdSetScissor
    to account for the multiple viewport feature. If the feature is not
    enabled, the parameters for these functions have required values that
    are defined in the <<features-features-multiViewport,multiple
    viewports>> section of the spec but were not reflected in the valid
    usage text for these functions.
  * Add the +<<VK_EXT_swapchain_colorspace>>+ extension defining common
    color spaces.
This commit is contained in:
Jon Leech 2017-01-17 20:11:25 -08:00
parent 70b659d28d
commit ca4abe0d34
252 changed files with 16636 additions and 1656 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

61
ChangeLog.txt
View File

@ -1765,3 +1765,64 @@ Other Issues:
* Vulkan(R) is now a registered trademark symbol, and this is reflected in
documents and copyright statements.
-----------------------------------------------------
Change log for January 23, 2017 Vulkan 1.0.39 spec update:
* Bump API patch number and header version number to 39 for this update.
Github Issues:
* Clarified that only accesses via the specified buffer/image subresource
ranges are included in the access scopes (public issue 306).
* Add missing valid usage statements for flink:vkCreateComputePipelines
and flink:vkCreateGraphicsPipelines (public issue 427).
Internal Issues:
* Add a Note to the <<invariance,Invariance>> appendix about a difference
between OpenGL and Vulkan with regards to how primitives derived from
offsets are handled (internal issue 355).
* Add the +<<VK_KHR_get_physical_device_properties2>>+,
+<<VK_KHR_maintenance1>>+, and +<<VK_KHR_shader_draw_parameters>>+
extensions (internal issue 448).
* Add the +<<VK_EXT_shader_subgroup_vote>>+ and
+<<VK_EXT_shader_subgroup_ballot>>+ extensions (internal issue 449).
* Update the texture level-of-detail equation in the
<<textures-scale-factor,Scale Factor Operation>> section to better
approximate the ellipse major and minor axes (internal issue 547).
* Forbid non-explicitly allowed uses of interface decorations in the
introduction to the <<interfaces,Shader Interfaces>> chapter (internal
issue 607).
* Replace use of MathJax with KaTeX, for improved load-time performance as
well as avoiding the scrolling-and-scrolling behavior due to MathJax
asynchronous rendering when loading at an anchor inside the spec. This
change also requires moving to HTML5 output for the spec instead of
XHTML, and there is a visible difference in that the chapter navigation
index is now in a scrollable sidebar instead of at the top of the
document. We may or may not retain the nav sidebar based on feedback
(internal issue 613).
* Improve consistency of markup and formatting in extension appendices
(internal issue 631).
Other Issues:
* Add explicit valid usage statements to slink:VkImageCopy requiring that
the source and destination layer ranges be contained in their respective
source and destination images.
* Add valid usage language for swapchain of flink:vkAcquireNextImage. If
the swapchain has been replaced, then it should not be passed to
flink:vkAcquireNextImage.
* Add a valid usage statement to flink:vkCreateImageView, that the image
must have been created with an appropriate usage bit set.
* Noted that slink:VkDisplayPresentInfoKHR is a valid extension of
slink:VkPresentInfoKHR in the <<wsi_swapchain,WSI Swapchain>> section.
* Update valid usage for flink:vkCmdSetViewport and flink:vkCmdSetScissor
to account for the multiple viewport feature. If the feature is not
enabled, the parameters for these functions have required values that
are defined in the <<features-features-multiViewport,multiple
viewports>> section of the spec but were not reflected in the valid
usage text for these functions.
* Add the +<<VK_EXT_swapchain_colorspace>>+ extension defining common
color spaces.

6
README.md
View File

@ -1,5 +1,5 @@
Vulkan^(R)^ API Documentation Project
=====================================
Vulkan<sup>:registered:</sup> API Documentation Project
=======================================================
This repository contains formal documentation of the Vulkan API. This
includes the main API Specification, the reference (man) pages, the XML API
@ -56,7 +56,7 @@ Cygwin running under Microsoft Windows.
There are several make targets in doc/specs/vulkan :
* make xhtml - Build one large HTML specification document.
* make html - Build one large HTML specification document.
* make pdf - Build one large PDF specification document.
* make chunked - Build an HTML document broken into one file per chapter.
* make manhtml - Make HTML API reference (all man pages as one big file).

119
doc/specs/vulkan/Makefile
View File

@ -1,4 +1,4 @@
# Copyright (c) 2014-2016 The Khronos Group Inc.
# Copyright (c) 2014-2017 The Khronos Group Inc.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
@ -31,25 +31,22 @@ EXTOPTIONS := $(foreach ext,$(EXTS),-extension $(ext))
APITITLE =
# The default 'all' target builds the following sub-targets:
# xhtml - XHTML single-page API specification
# pdf - PDF single-page API specification
# styleguide - HTML single-page "Documentation and Extensions" guide
# manhtml - XHTML single-page reference guide
# styleguide - HTML5 single-page "Documentation and Extensions" guide
# manhtml - HTML5 single-page reference guide
# manpdf - PDF reference guide
# manhtmlpages - XHTML separate per-feature reference pages
# manhtmlpages - HTML5 separate per-feature reference pages
# checkinc - validator script for asciidoc include files
# checklinks - validator script for asciidoc xrefs
#
# The following targets are supported, but not invoked by default:
# html - HTML5 single-page API specification
# chunked - XHTML chunked (page per section) API specification
# manpages - nroff Unix 'man' format separate per-feature reference pages
all: alldocs allchecks
alldocs: allspecs allman
allspecs: xhtml pdf styleguide
allspecs: html pdf styleguide
allman: manhtml manpdf manhtmlpages
@ -74,15 +71,10 @@ ECHO = echo
# Target directories for output files
# HTMLDIR - 'html' target
# XHTMLDIR - 'xhtml' target
# CHUNKDIR - 'chunked' target
# PDFDIR - 'pdf' target
# CHECKDIR - 'allchecks' target
# STYLEXHTMLDIR - 'styleguide' target
OUTDIR := ../../../out/1.0
HTMLDIR := $(OUTDIR)/html
XHTMLDIR := $(OUTDIR)/xhtml
CHUNKDIR := $(OUTDIR)/chunked
PDFDIR := $(OUTDIR)/pdf
CHECKDIR := $(OUTDIR)/checks
# Images used in the API spec
@ -103,17 +95,17 @@ KEEP =
# EXTATTRIBS sets attributes for enabled extensions (set above based on
# $(EXTENSIONS))
# CONFIG Vulkan-specific Asciidoc macros. File used depends on target.
# ADOCOPTS options for asciidoc->HTML output
# ADOCDBOPTS options for asciidoc->XHTML or PDF output via docbook
# ADOCOPTS options for asciidoc->HTML5 output
# ADOCDBOPTS options for asciidoc->PDF output via docbook
XMLLINT = --no-xmllint
NOTEOPTS = -a editing-notes -a implementation-guide
ATTRIBOPTS = -a apirevision="$(SPECREVISION)" \
-a apititle="$(APITITLE)" \
-a mathjax $(EXTATTRIBS)
-a katex $(EXTATTRIBS)
CONFIG = config/vkspec.conf
ADOCOPTS = $(ATTRIBOPTS) $(NOTEOPTS) -f config/mathjax-asciidoc.conf \
ADOCOPTS = $(ATTRIBOPTS) $(NOTEOPTS) -f config/math-asciidoc.conf \
-f $(CONFIG) $(VERBOSE)
ADOCDBOPTS = $(ATTRIBOPTS) $(NOTEOPTS) -f config/mathjax-docbook.conf \
ADOCDBOPTS = $(ATTRIBOPTS) $(NOTEOPTS) -f config/math-docbook.conf \
-f $(CONFIG) $(VERBOSE)
# All the options except the first are taken from a2x defaults
@ -124,13 +116,7 @@ XSLTOPTS = \
--stringparam admon.textlabel 0 \
--stringparam admon.graphics 1
# XSL customizing Asciibook XSL to pass through equations and add
# MathJax. This varies depending on target type.
XHTMLXSL = config/docbook-xsl/xhtml.xsl
CHUNKXSL = config/docbook-xsl/chunked.xsl
MANPAGEXSL = config/docbook-xsl/manpage.xsl
# dblatex options, passed directly to dblatex
# dblatex options
DBLATEXOPTS := $(KEEP) -V -T db2latex -I. -I images -I images/icons -s $(DBLATEXPREFIX)/asciidoc-dblatex.sty
# Misc. files to clean up (see 'checkinc' target below)
@ -138,15 +124,16 @@ DIRT = $(SPECVERSION)
.PHONY: directories
# Images and icons that are used in or referenced by targets.
# Images, icons, and scripts that are used in or referenced by targets.
# For some targets they must be copied to output directories.
ICONFILES := $(wildcard $(ICONPATH)/*.png)
PNGFILES := $(ICONFILES) $(wildcard $(IMAGEPATH)/*.png)
# Don't use vulkantexture0.svg as a source SVG file, PNG is available
SVGFILES := $(filter-out $(IMAGEPATH)/vulkantexture0.svg,$(wildcard $(IMAGEPATH)/*.svg))
PDFFILES := $(SVGFILES:.svg=.pdf)
KATEX := katex
# File suffix for image targets for HTML and PDF Builds - Asciidoc {svgtype} attribute
# File suffix for image targets for HTML5 and PDF Builds - Asciidoc {svgtype} attribute
SVGTYPEHTML := svg
SVGTYPEPDF := pdf
# Top-level spec source file
@ -160,55 +147,32 @@ GENDEPENDS = api/timeMarker validity/timeMarker hostsynctable/timeMarker
COMMONDOCS = $(CHAPTERS) $(GENINCLUDE) $(GENDEPENDS)
# A generated included file containing the spec version, date, and git commit
SPECVERSION = specversion.txt
SPECREVISION = 1.0.38
SPECREVISION = 1.0.39
SPECREMARK =
# README.md is a proxy for all the katex files that need to be installed
katexinst: $(OUTDIR)/katex/README.md
$(OUTDIR)/katex/README.md: katex/README.md
$(QUIET)$(MKDIR) $(OUTDIR)
$(QUIET)$(CP) -rf katex $(OUTDIR)
# Spec targets
# There is some complexity to try and avoid short virtual targets like 'html'
# causing specs to *always* be regenerated.
html: $(HTMLDIR)/vkspec.html $(TOPDOC) $(COMMONDOCS)
$(HTMLDIR)/vkspec.html: $(CONFIG) $(SPECVERSION) $(TOPDOC) $(COMMONDOCS)
$(HTMLDIR)/vkspec.html: $(CONFIG) $(SPECVERSION) $(TOPDOC) $(COMMONDOCS) katexinst
$(QUIET)$(MKDIR) $(HTMLDIR)/images/icons
$(QUIET)$(ASCIIDOC) -b html5 $(ADOCOPTS) \
-a themedir=$(CURDIR)/config -a theme=vkspec-html \
-a katexpath=../katex \
-o $(HTMLDIR)/vkspec.html -a svgpdf=$(SVGTYPEHTML) $(TOPDOC)
# Copy resource files in explicitly
$(QUIET)$(CP) $(SVGFILES) $(PNGFILES) $(HTMLDIR)/images
$(QUIET)$(CP) $(ICONFILES) $(HTMLDIR)/images/icons
xhtml: $(XHTMLDIR)/vkspec.html $(TOPDOC) $(COMMONDOCS)
$(XHTMLDIR)/vkspec.html: $(CONFIG) $(SPECVERSION) $(TOPDOC) $(COMMONDOCS)
$(QUIET)$(MKDIR) $(XHTMLDIR)/images/icons $(XHTMLDIR)/config
$(QUIET)$(ASCIIDOC) --backend docbook $(ADOCDBOPTS) \
-a a2x-format=xhtml -a svgpdf=$(SVGTYPEHTML) \
-o $(XHTMLDIR)/vkspec.xml $(TOPDOC)
$(QUIET)$(XSLTPROC) $(XSLTOPTS) -o $@ $(XHTMLXSL) \
$(XHTMLDIR)/vkspec.xml
# Copy resource files in explicitly
$(QUIET)$(CP) config/vkspec-xhtml.css $(XHTMLDIR)/config/
$(QUIET)$(CP) $(SVGFILES) $(PNGFILES) $(XHTMLDIR)/images
$(QUIET)$(CP) $(ICONFILES) $(XHTMLDIR)/images/icons
$(QUIET)$(RM) $(XHTMLDIR)/vkspec.xml
chunked: $(CHUNKDIR)/index.html $(TOPDOC) $(COMMONDOCS)
$(CHUNKDIR)/index.html: $(CONFIG) $(SPECVERSION) $(TOPDOC) $(COMMONDOCS)
$(QUIET)$(MKDIR) $(CHUNKDIR)/images/icons $(CHUNKDIR)/config
$(QUIET)$(ASCIIDOC) --backend docbook $(ADOCDBOPTS) \
-a a2x-format=chunked -a svgpdf=$(SVGTYPEHTML) \
-o $(CHUNKDIR)/vkspec.xml $(TOPDOC)
$(QUIET)$(XSLTPROC) $(XSLTOPTS) \
--stringparam base.dir $(CHUNKDIR)/ \
-o $@ $(CHUNKXSL) $(CHUNKDIR)/vkspec.xml
# Copy resource files in explicitly
$(QUIET)$(CP) config/vkspec-xhtml.css $(CHUNKDIR)/config/
$(QUIET)$(CP) $(SVGFILES) $(PNGFILES) $(CHUNKDIR)/images
$(QUIET)$(CP) $(ICONFILES) $(CHUNKDIR)/images/icons
$(QUIET)$(RM) $(CHUNKDIR)/vkspec.xml
pdf: $(PDFDIR)/vkspec.pdf
$(PDFDIR)/vkspec.pdf: $(CONFIG) $(SPECVERSION) $(TOPDOC) $(COMMONDOCS) $(PDFFILES)
@ -234,7 +198,7 @@ $(SPECVERSION):
$(QUIET)echo ":revremark: $(SPECREMARK) Git branch information not available" >> $@
else
# Could use `git log -1 --format="%cd"` to get branch commit date
# This used to be a dependency in the spec html/chunked/pdf targets,
# This used to be a dependency in the spec html/pdf targets,
# but that's likely to lead to merge conflicts. Just regenerate
# when pushing a new spec for review to the sandbox.
# The dependency on HEAD is per the suggestion in
@ -254,10 +218,11 @@ STYLEFILES = $(wildcard style/[A-Za-z]*.txt)
styleguide: $(OUTDIR)/styleguide.html
$(OUTDIR)/styleguide.html: $(CONFIG) $(SPECVERSION) $(STYLESRC) $(STYLEFILES) $(GENINCLUDE) $(GENDEPENDS)
$(OUTDIR)/styleguide.html: $(CONFIG) $(SPECVERSION) $(STYLESRC) $(STYLEFILES) $(GENINCLUDE) $(GENDEPENDS) katexinst
$(QUIET)$(MKDIR) $(OUTDIR)
$(QUIET)$(ASCIIDOC) -b html5 $(ADOCOPTS) \
-a themedir=$(CURDIR)/config -a theme=vkspec-html \
-a katexpath=katex \
-o $@ -a svgpdf=$(SVGTYPEHTML) \
$(STYLESRC)
@ -274,7 +239,7 @@ reflow:
clean: clean_html clean_pdf clean_man clean_checks clean_generated clean_dirt
clean_html:
$(QUIET)$(RMRF) $(HTMLDIR) $(XHTMLDIR) $(CHUNKDIR)
$(QUIET)$(RMRF) $(HTMLDIR) $(OUTDIR)/katex
$(QUIET)$(RM) $(OUTDIR)/apispec.html $(OUTDIR)/styleguide.html
clean_pdf:
@ -326,25 +291,7 @@ man/apispec.txt: $(CHAPTERS) genRef.py reflib.py vkapi.py
# These dependencies don't take into account include directives
# These targets are Unix 'man' nroff source, and are essentially useless
# since the ref pages contain both LaTeX math equations and images.
MANPAGEDIR := $(OUTDIR)/man/$(MANSECTION)
MANPAGES = $(MANSOURCES:$(MANDIR)/%.txt=$(MANPAGEDIR)/%.$(MANSECTION))
manpages: man/apispec.txt $(MANPAGES)
$(MANPAGEDIR)/%.$(MANSECTION): CONFIG=config/manpages.conf
$(MANPAGEDIR)/%.$(MANSECTION): $(MANDIR)/%.txt $(MANCOPYRIGHT) config/manpages.conf $(GENINCLUDE) $(GENDEPENDS)
$(QUIET)$(MKDIR) $(MANPAGEDIR)
$(QUIET)$(ASCIIDOC) --backend docbook $(ADOCDBOPTS) --doctype manpage \
-a a2x-format=manpage -a svgpdf=$(SVGTYPEHTML) \
-o $@.xml $<
$(QUIET)$(XSLTPROC) $(XSLTOPTS) -o $@ $(MANPAGEXSL) $@.xml
$(QUIET)$(RM) $@.xml
# These targets are HTML ref pages
# These targets are HTML5 ref pages
MANHTMLDIR := $(OUTDIR)/man/html
MANHTML = $(MANSOURCES:$(MANDIR)/%.txt=$(MANHTMLDIR)/%.html)
@ -353,13 +300,14 @@ manhtmlpages: man/apispec.txt $(MANHTML)
$(MANHTMLDIR)/%.html: CONFIG=config/manpages.conf
$(MANHTMLDIR)/%.html: $(MANDIR)/%.txt $(MANCOPYRIGHT) config/manpages.conf $(GENINCLUDE) $(GENDEPENDS)
$(MANHTMLDIR)/%.html: $(MANDIR)/%.txt $(MANCOPYRIGHT) config/manpages.conf $(GENINCLUDE) $(GENDEPENDS) katexinst
$(QUIET)$(MKDIR) $(MANHTMLDIR)
$(QUIET)$(ASCIIDOC) -b html5 -d manpage $(ADOCOPTS) \
-a themedir=$(CURDIR)/config -a theme=vkman \
-a katexpath=../../katex \
-o $@ -a svgpdf=$(SVGTYPEHTML) $<
# These targets are HTML and PDF single-file versions of the ref pages
# These targets are HTML5 and PDF single-file versions of the ref pages
manpdf: $(OUTDIR)/apispec.pdf
@ -376,9 +324,10 @@ $(OUTDIR)/apispec.pdf: $(CONFIG) $(SPECVERSION) man/apispec.txt $(MANSOURCES) $(
-o $(OUTDIR) $(OUTDIR)/apispec.xml
$(QUIET)$(RM) $(OUTDIR)/apispec.xml
$(OUTDIR)/apispec.html: $(CONFIG) $(SPECVERSION) man/apispec.txt $(MANSOURCES) $(MANCOPYRIGHT) $(SVGFILES) $(GENINCLUDE) $(GENDEPENDS)
$(OUTDIR)/apispec.html: $(CONFIG) $(SPECVERSION) man/apispec.txt $(MANSOURCES) $(MANCOPYRIGHT) $(SVGFILES) $(GENINCLUDE) $(GENDEPENDS) katexinst
$(QUIET)$(MKDIR) $(OUTDIR)
$(QUIET)$(ASCIIDOC) -b html5 -d book $(ADOCOPTS) \
-a katexpath=katex \
-a themedir=$(CURDIR)/config -a theme=vkspec-xhtml \
-o $@ -a svgpdf=$(SVGTYPEHTML) man/apispec.txt

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

@ -36,7 +36,7 @@ non-Windows environments.
or equivalently:
$ make xhtml pdf styleguide manhtml manpdf manhtmlpages checkinc checklinks
$ make html pdf styleguide manhtml manpdf manhtmlpages checkinc checklinks
will generate a variety of targets in the directory specified by the
Makefile variable +$(OUTDIR)+ (by default, +../../../out/1.0+). The
@ -44,7 +44,7 @@ checked-in file +../../../out/1.0/index.html+ links to all these
targets, or they can individually be found as follows:
* API spec:
** +xhtml+ - Single-file XHTML in +$(OUTDIR)/xhtml/vkspec.html+
** +html+ - Single-file 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+
@ -199,7 +199,7 @@ contents will not change.
NOTE: Section mostly TBD.
There is a Vulkan-specific XHTML CSS stylesheet in
There is a Vulkan-specific CSS stylesheet in
+config/vkspec-xhtml.css+ . It started as a clone of the default
Asciidoc stylesheet, but added some new features. Similar CSS in
+config/vkman.css+ is used for the reference pages.
@ -207,6 +207,9 @@ Asciidoc stylesheet, but added some new features. Similar CSS in
=== Marking Changes ===
NOTE: The XHTML targets are no longer supported, so this section is out of
date and unusable.
There is the start of support for marking added, removed, and changed text
in the spec body. Currently this is supported *only* in the XHTML targets
(+xhtml+ and +chunked+), and *only* for paragraphs and spans of words.
@ -236,6 +239,10 @@ git diffs.
=== Marking Normative Language ===
NOTE: The XHTML targets are no longer supported, so while normative language
macros should still be used, they aren't rendered visibly in the HTML5
output.
There is support for marking normative language in the document. Currently
this is supported *only* in the XHTML targets (+xhtml+ and +chunked+).
@ -253,16 +260,22 @@ build time.
[[equations]]
== Imbedding Equations
Equations should be written using the latexmath: inline and block macros.
The contents of the latexmath: blocks should be LaTeX math notation,
surrounded by appropriate delimiters - pass:[$$], +++\[\\]+++, pass:[\(\)],
or pass:[\begin{env}/\end{env}] math environments such as pass:[{equation*}]
or pass:[{align*}].
Where possible, equations should be written using straight asciidoc markup
using the _eq_ role. This covers many common equations and is faster than
the alternatives.
For more complex equations, such as multi-case statements, matrices, and
complex fractions, equations should be written using the latexmath: inline
and block macros. The contents of the latexmath: blocks should be LaTeX math
notation, surrounded by appropriate delimiters - pass:[$$], +++\[\\]+++, and
pass:[\(\)].
The asciidoc macros and configuration files, as well as the dblatex
customization layers, have been modified significantly so that LaTeX math is
passed through unmodified to all HTML output forms (using the MathJax engine
for real-time rendering of equations) and to dblatex for PDF output.
passed through unmodified to the HTML output, which uses the KaTeX engine
for in-browser rendering of equations, and to dblatex for PDF output. A
local copy of the KaTeX release is kept in doc/specs/vulkan/katex and copied
to the HTML output directory during spec generation.
The following caveats apply:
@ -271,16 +284,20 @@ The following caveats apply:
Instead use +\lt+ for +<+ and +\gt+ for +>+. +&+ is an alignment construct
for multiline equations, and should only appear in block macros anyway.
* AMSmath environments (e.g. pass:[\begin{equation*}], pass:[{align*}],
etc.) can be used, to the extent MathJax supports them.
etc.) cannot be used in KaTeX at present, and have been replaced with
constructs supported by KaTeX such as pass:[{aligned}].
* When using AMSmath environments, do *not* also surround the equation block
with +++\[\\]+++ brackets. That is not legal LaTeX math and will break the
PDF build. It is good practice to make sure all spec targets build
properly before proposing a merge to master.
* Arbitrary LaTeX constructs cannot be used with MathJax. It is an equation
* Arbitrary LaTeX constructs cannot be used with KaTeX. It is an equation
renderer, not an full LaTeX engine. So imbedding LaTeX like \Large or
pass:[\hbox{\tt\small VK\_FOO}] may not work in any of the HTML backends,
and should be avoided.
See the ``Vulkan Documentation and Extensions'' document for more details of
supported LaTeX math constructs.
[[anchors]]
== Asciidoc Anchors And Xrefs
@ -344,7 +361,8 @@ know that. Later versions should work.
- Docbook LaTeX toolchain (dblatex, version: 0.3.5-2)
- Source code highlighter (source-highlight, version: 3.1.7-1+b1)
- LaTeX distribution (texlive, version: 2014.20141024-2)
- KaTeX distribution (version 0.7.0 from https://github.com/Khan/KaTeX ,
cached under doc/specs/vulkan/katex/)
[[depends-cygwin]]
=== Cygwin Dependencies ===
@ -373,6 +391,7 @@ Optional Cygwin packages (current version):
[[history]]
== Revision History
* 2017-01-06 - Replace MathJax with KaTeX.
* 2016-08-25 - Update for the single-branch model.
* 2016-07-10 - Update for current state of spec and ref page generation.
* 2015-11-11 - Add new can: etc. macros and DBLATEXPREFIX variable.

78
doc/specs/vulkan/README.html
View File

@ -3,7 +3,7 @@
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<meta name="generator" content="AsciiDoc 8.6.9">
<title>Vulkan Specification Build Instructions and Notes</title>
<title>Vulkan<sup>&#174;</sup> Specification Build Instructions and Notes</title>
<style type="text/css">
/* Shared CSS for AsciiDoc xhtml11 and html5 backends */
@ -729,18 +729,14 @@ install: function(toclevels) {
asciidoc.install();
/*]]>*/
</script>
<script type="text/x-mathjax-config">
MathJax.Hub.Config({
MathML: { extensions: ["content-mathml.js"] },
tex2jax: { inlineMath: [['$','$'], ['\\(','\\)']] }
});
</script>
<script type="text/javascript" src="https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML">
</script>
<!-- Load KaTeX from CDN -->
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.6.0/katex.min.css">
<script src="https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.6.0/katex.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.6.0/contrib/auto-render.min.js"></script>
</head>
<body class="article">
<div id="header">
<h1>Vulkan Specification Build Instructions and Notes</h1>
<h1>Vulkan<sup>&#174;</sup> Specification Build Instructions and Notes</h1>
</div>
<div id="content">
<div id="preamble">
@ -819,7 +815,7 @@ non-Windows environments.</p></div>
<div class="paragraph"><p>or equivalently:</p></div>
<div class="literalblock">
<div class="content monospaced">
<pre>$ make xhtml pdf styleguide manhtml manpdf manhtmlpages checkinc checklinks</pre>
<pre>$ make html pdf styleguide manhtml manpdf manhtmlpages checkinc checklinks</pre>
</div></div>
<div class="paragraph"><p>will generate a variety of targets in the directory specified by the
Makefile variable <span class="monospaced">$(OUTDIR)</span> (by default, <span class="monospaced">../../../out/1.0</span>). The
@ -833,7 +829,7 @@ API spec:
<div class="ulist"><ul>
<li>
<p>
<span class="monospaced">xhtml</span> - Single-file XHTML in <span class="monospaced">$(OUTDIR)/xhtml/vkspec.html</span>
<span class="monospaced">html</span> - Single-file HTML5 in <span class="monospaced">$(OUTDIR)/html/vkspec.html</span>
</p>
</li>
<li>
@ -1050,6 +1046,15 @@ Asciidoc stylesheet, but added some new features. Similar CSS in
<span class="monospaced">config/vkman.css</span> is used for the reference pages.</p></div>
<div class="sect2">
<h3 id="_marking_changes">Marking Changes</h3>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">The XHTML targets are no longer supported, so this section is out of
date and unusable.</td>
</tr></table>
</div>
<div class="paragraph"><p>There is the start of support for marking added, removed, and changed text
in the spec body. Currently this is supported <strong>only</strong> in the XHTML targets
(<span class="monospaced">xhtml</span> and <span class="monospaced">chunked</span>), and <strong>only</strong> for paragraphs and spans of words.</p></div>
@ -1077,6 +1082,16 @@ git diffs.</p></div>
</div>
<div class="sect2">
<h3 id="_marking_normative_language">Marking Normative Language</h3>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">The XHTML targets are no longer supported, so while normative language
macros should still be used, they aren&#8217;t rendered visibly in the HTML5
output.</td>
</tr></table>
</div>
<div class="paragraph"><p>There is support for marking normative language in the document. Currently
this is supported <strong>only</strong> in the XHTML targets (<span class="monospaced">xhtml</span> and <span class="monospaced">chunked</span>).</p></div>
<div class="paragraph"><p>Normative language is marked with the asciidoc <strong>role</strong> named <em>normative</em>.
@ -1093,15 +1108,20 @@ build time.</p></div>
<div class="sect1">
<h2 id="equations">Imbedding Equations</h2>
<div class="sectionbody">
<div class="paragraph"><p>Equations should be written using the latexmath: inline and block macros.
The contents of the latexmath: blocks should be LaTeX math notation,
surrounded by appropriate delimiters - $$, \[\], \(\),
or \begin{env}/\end{env} math environments such as {equation*}
or {align*}.</p></div>
<div class="paragraph"><p>Where possible, equations should be written using straight asciidoc markup
using the <em>eq</em> role. This covers many common equations and is faster than
the alternatives.</p></div>
<div class="paragraph"><p>For more complex equations, such as multi-case statements, matrices, and
complex fractions, equations should be written using the latexmath: inline
and block macros. The contents of the latexmath: blocks should be LaTeX math
notation, surrounded by appropriate delimiters - $$, \[\], and
\(\).</p></div>
<div class="paragraph"><p>The asciidoc macros and configuration files, as well as the dblatex
customization layers, have been modified significantly so that LaTeX math is
passed through unmodified to all HTML output forms (using the MathJax engine
for real-time rendering of equations) and to dblatex for PDF output.</p></div>
passed through unmodified to the HTML output, which uses the KaTeX engine
for in-browser rendering of equations, and to dblatex for PDF output. A
local copy of the KaTeX release is kept in doc/specs/vulkan/katex and copied
to the HTML output directory during spec generation.</p></div>
<div class="paragraph"><p>The following caveats apply:</p></div>
<div class="ulist"><ul>
<li>
@ -1115,7 +1135,8 @@ The special characters <span class="monospaced">&lt;</span> , <span class="monos
<li>
<p>
AMSmath environments (e.g. \begin{equation*}, {align*},
etc.) can be used, to the extent MathJax supports them.
etc.) cannot be used in KaTeX at present, and have been replaced with
constructs supported by KaTeX such as {aligned}.
</p>
</li>
<li>
@ -1128,13 +1149,15 @@ When using AMSmath environments, do <strong>not</strong> also surround the equat
</li>
<li>
<p>
Arbitrary LaTeX constructs cannot be used with MathJax. It is an equation
Arbitrary LaTeX constructs cannot be used with KaTeX. It is an equation
renderer, not an full LaTeX engine. So imbedding LaTeX like \Large or
\hbox{\tt\small VK\_FOO} may not work in any of the HTML backends,
and should be avoided.
</p>
</li>
</ul></div>
<div class="paragraph"><p>See the &#8220;Vulkan Documentation and Extensions&#8221; document for more details of
supported LaTeX math constructs.</p></div>
</div>
</div>
<div class="sect1">
@ -1216,6 +1239,12 @@ Source code highlighter (source-highlight, version: 3.1.7-1+b1)
LaTeX distribution (texlive, version: 2014.20141024-2)
</p>
</li>
<li>
<p>
KaTeX distribution (version 0.7.0 from <a href="https://github.com/Khan/KaTeX">https://github.com/Khan/KaTeX</a> ,
cached under doc/specs/vulkan/katex/)
</p>
</li>
</ul></div>
</div>
<div class="sect2">
@ -1288,6 +1317,11 @@ Devel/git (2.5.1-1) - Needed for updating specversion.txt
<div class="ulist"><ul>
<li>
<p>
2017-01-06 - Replace MathJax with KaTeX.
</p>
</li>
<li>
<p>
2016-08-25 - Update for the single-branch model.
</p>
</li>
@ -1332,7 +1366,7 @@ Devel/git (2.5.1-1) - Needed for updating specversion.txt
<div id="footer">
<div id="footer-text">
Last updated
2016-10-25 14:15:38 KST
2017-01-08 18:30:08 PST
</div>
</div>
</body>

18
doc/specs/vulkan/appendices/VK_AMD_draw_indirect_count.txt
View File

@ -14,17 +14,17 @@
*IP Status*::
No known IP claims.
*Dependencies*::
- This extension is written against version 1.0 of the Vulkan API.
- This extension is written against version 1.0 of the Vulkan API.
*Contributors*::
- Matthaeus G.
Chajdas, AMD
- Derrick Owens, AMD
- Graham Sellers, AMD
- Daniel Rakos, AMD
- Dominik Witczak, AMD
- Matthaeus G.
Chajdas, AMD
- Derrick Owens, AMD
- Graham Sellers, AMD
- Daniel Rakos, AMD
- Dominik Witczak, AMD
*Contacts*::
- Matthaeus G.
Chajdas, AMD (matthaeus.chajdas@amd.com)
- Matthaeus G.
Chajdas, AMD (matthaeus.chajdas@amd.com)
This extension allows an application to source the number of draw calls for
indirect draw calls from a buffer.

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

@ -14,14 +14,14 @@
*IP Status*::
No known IP claims.
*Dependencies*::
- This extension is written against version 1.0.15 of the Vulkan API.
- This extension is written against version 1.0.15 of the Vulkan API.
*Contributors*::
- Dominik Witczak, AMD
- Daniel Rakos, AMD
- Rex Xu, AMD
- Graham Sellers, AMD
- Dominik Witczak, AMD
- Daniel Rakos, AMD
- Rex Xu, AMD
- Graham Sellers, AMD
*Contacts*::
- Dominik Witczak, AMD (dominik.witczak@amd.com)
- Dominik Witczak, AMD (dominik.witczak@amd.com)
This extension adds support for the following SPIR-V extension in {apiname}:

17
doc/specs/vulkan/appendices/VK_AMD_gpu_shader_half_float.txt
View File

@ -14,17 +14,16 @@
*IP Status*::
No known IP claims.
*Dependencies*::
- This extension is written against version 1.0.27 of the Vulkan API.
- This extension is written against version 1.0.27 of the Vulkan API.
*Contributors*::
- Daniel Rakos, AMD
- Dominik Witczak, AMD
- Donglin Wei, AMD
- Graham Sellers, AMD
- Qun Lin, AMD
- Rex Xu, AMD
- Daniel Rakos, AMD
- Dominik Witczak, AMD
- Donglin Wei, AMD
- Graham Sellers, AMD
- Qun Lin, AMD
- Rex Xu, AMD
*Contacts*::
- Dominik Witczak, AMD (Dominik.Witczak@amd.com)
- Dominik Witczak, AMD (Dominik.Witczak@amd.com)
This extension adds support for the following SPIR-V extension in {apiname}:

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

@ -14,15 +14,15 @@
*IP Status*::
No known IP claims.
*Dependencies*::
- This extension is written against version 1.0 of the Vulkan API.
- This extension is written against version 1.0 of the Vulkan API.
*Contributors*::
- Matthaeus G.
Chajdas, AMD
- Graham Sellers, AMD
- Baldur Karlsson
- Matthaeus G.
Chajdas, AMD
- Graham Sellers, AMD
- Baldur Karlsson
*Contacts*::
- Matthaeus G.
Chajdas, AMD (matthaeus.chajdas@amd.com)
- Matthaeus G.
Chajdas, AMD (matthaeus.chajdas@amd.com)
This extension allows an application to specify a negative viewport height.
The result is that the viewport transformation will flip along the y-axis.

36
doc/specs/vulkan/appendices/VK_AMD_rasterization_order.txt
View File

@ -81,33 +81,33 @@ None
1) How is this extension useful to application developers?
RESOLVED: Allows them to increase primitive throughput for cases when
strict API order rasterization is not important due to the nature of the
content, the configuration used, or the requirements towards the output
of the rendering.
*RESOLVED*: Allows them to increase primitive throughput for cases when
strict API order rasterization is not important due to the nature of the
content, the configuration used, or the requirements towards the output of
the rendering.
2) How does this extension interact with content optimizations aiming to
reduce overdraw by appropriately ordering the input primitives?
reduce overdraw by appropriately ordering the input primitives?
RESOLVED: While the relaxed rasterization order might somewhat limit the
effectiveness of such content optimizations, most of the benefits of it
are expected to be retained even when the relaxed rasterization order is
used so applications are still recommended to apply these optimizations
even if they intend to use the extension.
*RESOLVED*: While the relaxed rasterization order might somewhat limit the
effectiveness of such content optimizations, most of the benefits of it are
expected to be retained even when the relaxed rasterization order is used so
applications are still recommended to apply these optimizations even if they
intend to use the extension.
3) Are there any guarantees about the primitive rasterization order when
using the new relaxed mode?
using the new relaxed mode?
RESOLVED: No.
The rasterization order is completely implementation dependent in this
case but in practice it is expected to partially still follow the order
of incoming primitives.
*RESOLVED*: No.
The rasterization order is completely implementation dependent in this case
but in practice it is expected to partially still follow the order of
incoming primitives.
4) Does the new relaxed rasterization order have any adverse effect on
repeatability and other invariance rules of the API?
repeatability and other invariance rules of the API?
RESOLVED: Yes, in the sense that it extends the list of exceptions when
the repeatability requirement does not apply.
*RESOLVED*: Yes, in the sense that it extends the list of exceptions when
the repeatability requirement does not apply.
=== Examples

18
doc/specs/vulkan/appendices/VK_AMD_shader_ballot.txt
View File

@ -14,17 +14,17 @@
*IP Status*::
No known IP claims.
*Dependencies*::
- This extension is written against version 1.0.27 of the Vulkan API.
- This extension is written against version 1.0.27 of the Vulkan API.
*Contributors*::
- Qun Lin, AMD
- Graham Sellers, AMD
- Daniel Rakos, AMD
- Rex Xu, AMD
- Dominik Witczak, AMD
- Matthäus G.
Chajdas, AMD
- Qun Lin, AMD
- Graham Sellers, AMD
- Daniel Rakos, AMD
- Rex Xu, AMD
- Dominik Witczak, AMD
- Matthäus G.
Chajdas, AMD
*Contacts*::
- Dominik Witczak, AMD (Dominik.Witczak@amd.com)
- Dominik Witczak, AMD (Dominik.Witczak@amd.com)
This extension adds support for the following SPIR-V extension in {apiname}:

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

@ -14,16 +14,16 @@
*IP Status*::
No known IP claims.
*Dependencies*::
- This extension is written against version 1.0.11 of the Vulkan API.
- This extension is written against version 1.0.11 of the Vulkan API.
*Contributors*::
- Matthaeus G.
Chajdas, AMD
- Qun Lin, AMD
- Daniel Rakos, AMD
- Graham Sellers, AMD
- Rex Xu, AMD
- Matthaeus G.
Chajdas, AMD
- Qun Lin, AMD
- Daniel Rakos, AMD
- Graham Sellers, AMD
- Rex Xu, AMD
*Contacts*::
- Qun Lin, AMD (quentin.lin@amd.com)
- Qun Lin, AMD (quentin.lin@amd.com)
This extension adds support for the following SPIR-V extension in {apiname}:

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

@ -14,16 +14,16 @@
*IP Status*::
No known IP claims.
*Dependencies*::
- This extension is written against version 1.0.11 of the Vulkan API.
- This extension is written against version 1.0.11 of the Vulkan API.
*Contributors*::
- Matthaeus G.
Chajdas, AMD
- Qun Lin, AMD
- Daniel Rakos, AMD
- Graham Sellers, AMD
- Rex Xu, AMD
- Matthaeus G.
Chajdas, AMD
- Qun Lin, AMD
- Daniel Rakos, AMD
- Graham Sellers, AMD
- Rex Xu, AMD
*Contacts*::
- Qun Lin, AMD (quentin.lin@amd.com)
- Qun Lin, AMD (quentin.lin@amd.com)
This extension adds support for the following SPIR-V extension in {apiname}:

80
doc/specs/vulkan/appendices/VK_EXT_acquire_xlib_display.txt Normal file
View File

@ -0,0 +1,80 @@
[[VK_EXT_acquire_xlib_display]]
== VK_EXT_acquire_xlib_display
*Name String*::
+VK_EXT_acquire_xlib_display+
*Extension Type*::
Instance extension
*Registered Extension Number*::
90
*Last Modified Date*::
2016-12-13
*Revision*::
1
*IP Status*::
No known IP claims.
*Dependencies*::
- This extension is written against version 1.0.37 of the Vulkan API.
- Requires +VK_KHR_display+.
- Requires +VK_EXT_direct_mode_display+.
*Contributors*::
- Dave Airlie, Red Hat
- Pierre Boudier, NVIDIA
- James Jones, NVIDIA
- Damien Leone, NVIDIA
- Pierre-Loup Griffais, Valve
- Liam Middlebrook, NVIDIA
- Daniel Vetter, Intel
*Contacts*::
- James Jones, NVIDIA (jajones 'at' nvidia.com)
This extension allows an application to take exclusive control on a display
currently associated with an X11 screen.
When control is acquired, the display will be deassociated from the X11
screen until control is released or the specified display connection is
closed.
Essentially, the X11 screen will behave as if the monitor has been unplugged
until control is released.
=== New Enum Constants
None.
=== New Enums
None.
=== New Structures
None.
=== New Functions
* flink:vkAcquireXlibDisplayEXT
* flink:vkGetRandROutputDisplayEXT
=== Issues
1) Should flink:vkAcquireXlibDisplayEXT take an RandR display ID, or a
Vulkan display handle as input?
*RESOLVED*: A Vulkan display handle.
Otherwise there would be no way to specify handles to displays that had been
``blacklisted'' or prevented from being included in the X11 display list by
some native platform or vendor-specific mechanism.
2) How does an application figure out which RandR display corresponds to a
Vulkan display?
*RESOLVED*: A new function, flink:vkGetRandROutputDisplayEXT, is introduced
for this purpose.
3) Should flink:vkGetRandROutputDisplayEXT be part of this extension, or a
general Vulkan + RandR or Vulkan + Xlib extension?
*RESOLVED*: To avoid yet another extension, include it in this extension.
=== Version History
* Revision 1, 2016-12-13 (James Jones)
- Initial draft

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

@ -160,34 +160,32 @@ submitted.
=== Issues
1) Should the tag or name for an object be specified using the pNext
parameter in the object's CreateInfo structure?
1) Should the tag or name for an object be specified using the pname:pNext
parameter in the object's stext:Vk*CreateInfo structure?
RESOLVED: No.
While this fits with other Vulkan patterns and would allow more type
safety and future proofing against future objects, it has notable
downsides.
In particular passing the name at CreateInfo time does not allow
renaming, prevents late binding of naming information, and does not allow
naming of implicitly created objects such as queues and swap chain
images.
*RESOLVED*: No.
While this fits with other Vulkan patterns and would allow more type safety
and future proofing against future objects, it has notable downsides.
In particular passing the name at stext:Vk*CreateInfo time does not allow
renaming, prevents late binding of naming information, and does not allow
naming of implicitly created objects such as queues and swap chain images.
2) Should the command annotation functions vkCmdDebugMarkerBeginEXT() and
vkCmdDebugMarkerEndEXT() support the ability to specify a color?
2) Should the command annotation functions flink:vkCmdDebugMarkerBeginEXT
and flink:vkCmdDebugMarkerEndEXT support the ability to specify a color?
RESOLVED: Yes.
The functions have been expanded to take an optional color which can be
used at will by implementations consuming the command buffer annotations
in their visualisation.
*RESOLVED*: Yes.
The functions have been expanded to take an optional color which can be used
at will by implementations consuming the command buffer annotations in their
visualisation.
3) Should the functions added in this extension accept an extensible
structure as their parameter for a more flexible API, as opposed to
direct function parameters? If so, which functions?
structure as their parameter for a more flexible API, as opposed to direct
function parameters? If so, which functions?
RESOLVED: Yes.
All functions have been modified to take a structure type with extensible
pNext pointer, to allow future extensions to add additional annotation
information in the same commands.
*RESOLVED*: Yes.
All functions have been modified to take a structure type with extensible
pNext pointer, to allow future extensions to add additional annotation
information in the same commands.
=== Version History

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

@ -2,7 +2,7 @@
== VK_EXT_debug_report
*Name String*::
VK_EXT_debug_report
+VK_EXT_debug_report+
*Extension Type*::
Instance
*Registered Extension Number*::
@ -74,17 +74,17 @@ enabled, but they will only be called for loader and, if implemented, driver
events.
To capture issues found while creating or destroying an instance an
application can link a sname:VkDebugReportCallbackCreateInfoEXT structure to
the pname:pNext element of the sname:VkInstanceCreateInfo structure given to
fname:vkCreateInstance.
This callback is only valid for the duration of the fname:vkCreateInstance
and the fname:vkDestroyInstance call.
application can link a slink:VkDebugReportCallbackCreateInfoEXT 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:vkCreateDebugReportCallbackEXT to create persistent callback
objects.
Example uses: Create three callback objects.
One will log errors and warnings to the debug console using Windows
OutputDebugString.
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,{basebackend@docbook:c++:cpp}]

73
doc/specs/vulkan/appendices/VK_EXT_direct_mode_display.txt Normal file
View File

@ -0,0 +1,73 @@
[[VK_EXT_direct_mode_display]]
== VK_EXT_direct_mode_display
*Name String*::
+VK_EXT_direct_mode_display+
*Extension Type*::
Instance extension
*Registered Extension Number*::
89
*Last Modified Date*::
2016-12-13
*Revision*::
1
*IP Status*::
No known IP claims.
*Dependencies*::
- This extension is written against version 1.0.37 of the Vulkan API.
- Requires +VK_KHR_display+
*Contributors*::
- Pierre Boudier, NVIDIA
- James Jones, NVIDIA
- Damien Leone, NVIDIA
- Pierre-Loup Griffais, Valve
- Liam Middlebrook, NVIDIA
*Contacts*::
- James Jones, NVIDIA (jajones 'at' nvidia.com)
This is extension, along with related platform exentions, allows
applications to take exclusive control of displays associated with a native
windowing system.
This is especially useful for virtual reality applications that wish to hide
HMDs (head mounted displays) from the native platform's display management
system, desktop, and/or other applications.
=== New Enum Constants
None.
=== New Enums
None.
=== New Structures
None.
=== New Functions
* flink:vkReleaseDisplayEXT
=== Issues
1) Should this extension and its related platform-specific extensions
leverage +VK_KHR_display+, or provide separate equivalent interfaces.
*RESOLVED*: Use +VK_KHR_display+ concepts and objects.
+VK_KHR_display+ can be used to enumerate all displays on the system,
including those attached to/in use by a window system or native platform,
but +VK_KHR_display_swapchain+ will fail to create a swapchain on in-use
displays.
This extension and its platform-specific children will allow applications to
grab in-use displays away from window systems and/or native platforms,
allowing them to be used with +VK_KHR_display_swapchain+.
2) Are separate calls needed to acquire displays and enable direct mode?
*RESOLVED*: No, these operations happen in one combined command.
Acquiring a display puts it into direct mode.
=== Version History
* Revision 1, 2016-12-13 (James Jones)
- Initial draft

92
doc/specs/vulkan/appendices/VK_EXT_display_control.txt Normal file
View File

@ -0,0 +1,92 @@
[[VK_EXT_display_control]]
== VK_EXT_display_control
*Name String*::
+VK_EXT_display_control+
*Extension Type*::
Device extension
*Registered Extension Number*::
92
*Last Modified Date*::
2016-12-13
*Revision*::
1
*IP Status*::
No known IP claims.
*Dependencies*::
- This extension is written against version 1.0.37 of the Vulkan API.
- Requires +VK_KHR_display+
- Requires +VK_EXT_display_surface_counter+
- Requires +VK_KHR_swapchain+
*Contributors*::
- Pierre Boudier, NVIDIA
- James Jones, NVIDIA
- Damien Leone, NVIDIA
- Pierre-Loup Griffais, Valve
- Daniel Vetter, Intel
*Contacts*::
- James Jones, NVIDIA (jajones 'at' nvidia.com)
This extension defines a set of utility functions for use with the
+VK_KHR_display+ and +VK_KHR_display_swapchain+ extensions.
=== New Enum Constants
* Extending ename:VkStructureType:
** ename:VK_STRUCTURE_TYPE_DISPLAY_POWER_INFO_EXT
** ename:VK_STRUCTURE_TYPE_DEVICE_EVENT_INFO_EXT
** ename:VK_STRUCTURE_TYPE_DISPLAY_EVENT_INFO_EXT
** ename:VK_STRUCTURE_TYPE_SWAPCHAIN_COUNTER_CREATE_INFO_EXT
=== New Enums
* elink:VkDisplayPowerStateEXT
* elink:VkDeviceEventTypeEXT
* elink:VkDisplayEventTypeEXT
=== New Structures
* slink:VkDisplayPowerInfoEXT
* slink:VkDeviceEventInfoEXT
* slink:VkDisplayEventInfoEXT
* slink:VkSwapchainCounterCreateInfoEXT
=== New Functions
* flink:vkDisplayPowerControlEXT
* flink:vkRegisterDeviceEventEXT
* flink:vkRegisterDisplayEventEXT
* flink:vkGetSwapchainCounterEXT
=== Issues
1) Should this extension add an explicit "WaitForVsync" API or a fence
signaled at vsync that the application can wait on?
*RESOLVED*: A fence.
A separate API could later be provided that allows exporting the fence to a
native object that could be inserted into standard run loops on POSIX and
Windows systems.
2) Should callbacks be added for a vsync event, or in general to monitor
events in Vulkan?
*RESOLVED*: No, fences should be used.
Some events are generated by interrupts which are managed in the kernel.
In order to use a callback provided by the application, drivers would need
to have the userspace driver spawn threads that would wait on the kernel
event, and hence the callbacks could be difficult for the application to
synchronize with its other work given they would arrive on a foreign thread.
3) Should vblank or scanline events be exposed?
*RESOLVED*: Vblank events.
Scanline events could be added by a separate extension, but the latency of
processing an interrupt and waking up a userspace event is high enough that
the accuracy of a scanline event would be rather low.
Further, per-scanline interrupts are not supported by all hardware.
=== Version History
* Revision 1, 2016-12-13 (James Jones)
- Initial draft

58
doc/specs/vulkan/appendices/VK_EXT_display_surface_counter.txt Normal file
View File

@ -0,0 +1,58 @@
[[VK_EXT_display_surface_counter]]
== VK_EXT_display_surface_counter
*Name String*::
+VK_EXT_display_surface_counter+
*Extension Type*::
Instance extension
*Registered Extension Number*::
91
*Last Modified Date*::
2016-12-13
*Revision*::
1
*IP Status*::
No known IP claims.
*Dependencies*::
- This extension is written against version 1.0.37 of the Vulkan API.
- Requires +VK_KHR_display+
*Contributors*::
- Pierre Boudier, NVIDIA
- James Jones, NVIDIA
- Damien Leone, NVIDIA
- Pierre-Loup Griffais, Valve
- Daniel Vetter, Intel
*Contacts*::
- James Jones, NVIDIA (jajones 'at' nvidia.com)
This is extension defines a vertical blanking period counter associated with
display surfaces.
It provides a mechanism to query support for such a counter from a
slink:VkSurface object.
=== New Enum Constants
* Extending ename:VkStructureType:
** ename:VK_STRUCTURE_TYPE_SURFACE_CAPABILITIES2_EXT
=== New Enums
* elink:VkSurfaceCounterFlagsEXT
* elink:VkSurfaceCounterFlagBitsEXT
=== New Structures
* slink:VkSurfaceCapabilities2EXT
=== New Functions
* flink:vkGetPhysicalDeviceSurfaceCapabilities2EXT
=== Issues
None.
=== Version History
* Revision 1, 2016-12-13 (James Jones)
- Initial draft

127
doc/specs/vulkan/appendices/VK_EXT_shader_subgroup_ballot.txt Normal file
View File

@ -0,0 +1,127 @@
[[VK_EXT_shader_subgroup_ballot]]
== VK_EXT_shader_subgroup_ballot
*Name String*::
VK_EXT_shader_subgroup_ballot
*Extension Type*::
Device extension
*Registered Extension Number*::
65
*Status*::
Draft
*Last Modified Date*::
2016-11-28
*Revision*::
1
*IP Status*::
No known IP claims.
*Dependencies*::
- This extension is written against version 1.0 of the Vulkan API.
- This extension requires Vulkan 1.0.
- This extension requires the
https://www.khronos.org/registry/spir-v/extensions/KHR/SPV_KHR_shader_ballot.html[+SPV_KHR_shader_ballot+]
SPIR-V extension.
- This extension requires the
https://www.opengl.org/registry/specs/ARB/shader_ballot.txt[+GL_ARB_shader_ballot+]
extension for GLSL source languages.
*Contributors*::
- Jeff Bolz, NVIDIA
- Neil Henning, Codeplay
- Daniel Koch, NVIDIA Corporation
*Contact*::
- Daniel Koch (dkoch 'at' nvidia.com)
*Overview*::
+
--
This extension adds support for the following SPIR-V extension in Vulkan:
* SPV_KHR_shader_ballot
This extension provides the ability for a group of invocations, which
execute in parallel, to do limited forms of cross-invocation communication
via a group broadcast of a invocation value, or broadcast of a bitarray
representing a predicate value from each invocation in the group.
This extension provides access to a number of additional built-in shader
variables in Vulkan:
* code:SubgroupEqMaskKHR, which contains the subgroup mask of the current
subgroup invocation,
* code:SubgroupGeMaskKHR, which contains the subgroup mask of the
invocations greater than or equal to the current invocation,
* code:SubgroupGtMaskKHR, which contains the subgroup mask of the
invocations greater than the current invocation,
* code:SubgroupLeMaskKHR, which contains the subgroup mask of the
invocations less than or equal to the current invocation,
* code:SubgroupLtMaskKHR, which contains the subgroup mask of the
invocations less than the current invocation,
* code:SubgroupLocalInvocationId, which contains the index of an
invocation within a subgroup, and
* code:SubgroupSize, which contains the maximum number of invocations in a
subgroup.
Additionally, this extension provides access to the new SPIR-V instructions:
* code:OpSubgroupBallotKHR,
* code:OpSubgroupFirstInvocationKHR, and
* code:OpSubgroupReadInvocationKHR,
When using GLSL source-based shader languages, the following variables and
shader functions from GL_ARB_shader_ballot can map to these SPIR-V built-in
decorations and instructions:
* in uint64_t gl_SubGroupEqMaskARB; -> code:SubgroupEqMaskKHR,
* in uint64_t gl_SubGroupGeMaskARB; -> code:SubgroupGeMaskKHR,
* in uint64_t gl_SubGroupGtMaskARB; -> code:SubgroupGtMaskKHR,
* in uint64_t gl_SubGroupLeMaskARB; -> code:SubgroupLeMaskKHR,
* in uint64_t gl_SubGroupLtMaskARB; -> code:SubgroupLtMaskKHR,
* in uint gl_SubGroupInvocationARB; -> code:SubgroupLocalInvocationId,
* uniform uint gl_SubGroupSizeARB; -> code:SubgroupSize,
* ballotARB() -> code:OpSubgroupBallotKHR,
* readFirstInvocationARB() -> code:OpSubgroupFirstInvocationKHR, and
* readInvocationARB() -> code:OpSubgroupReadInvocationKHR.
--
=== New Object Types
None.
=== New Enum Constants
None.
=== New Enums
None.
=== New Structures
None.
=== New Functions
None.
=== New Built-In Variables
* <<interfaces-builtin-variables-sgeq,code:SubgroupEqMaskKHR>>
* <<interfaces-builtin-variables-sgge,code:SubgroupGeMaskKHR>>
* <<interfaces-builtin-variables-sggt,code:SubgroupGtMaskKHR>>
* <<interfaces-builtin-variables-sgle,code:SubgroupLeMaskKHR>>
* <<interfaces-builtin-variables-sglt,code:SubgroupLtMaskKHR>>
* <<interfaces-builtin-variables-sgli,code:SubgroupLocalInvocationId>>
* <<interfaces-builtin-variables-sgs,code:SubgroupSize>>
=== New SPIR-V Capabilities
* <<spirvenv-capabilities-table-subgroupballot,SubgroupBallotKHR>>
=== Issues
None.
=== Version History
* Revision 1, 2016-11-28 (Daniel Koch)
- Initial draft

151
doc/specs/vulkan/appendices/VK_EXT_shader_subgroup_vote.txt Normal file
View File

@ -0,0 +1,151 @@
[[VK_EXT_shader_subgroup_vote]]
== VK_EXT_shader_subgroup_vote
*Name String*::
VK_EXT_shader_subgroup_vote
*Extension Type*::
Device extension
*Registered Extension Number*::
66
*Status*::
Draft
*Last Modified Date*::
2016-11-28
*Revision*::
1
*IP Status*::
No known IP claims.
*Dependencies*::
- This extension is written against version 1.0 of the Vulkan API.
- This extension requires Vulkan 1.0.
- This extension requires the
https://www.khronos.org/registry/spir-v/extensions/KHR/SPV_KHR_subgroup_vote.html[+SPV_KHR_subgroup_vote+]
SPIR-V extension.
- This extension requires the
https://www.opengl.org/registry/specs/ARB/shader_group_vote.txt[+GL_ARB_shader_group_vote+]
extension for GLSL source languages.
*Contributors*::
- Neil Henning, Codeplay
- Daniel Koch, NVIDIA Corporation
*Contact*::
- Daniel Koch (dkoch 'at' nvidia.com)
*Overview*::
+
--
This extension adds support for the following SPIR-V extension in Vulkan:
* SPV_KHR_subgroup_vote
This extension provides new SPIR-V instructions:
* code:OpSubgroupAllKHR,
* code:OpSubgroupAnyKHR, and
* code:OpSubgroupAllEqualKHR.
to compute the composite of a set of boolean conditions across a group of
shader invocations that are running concurrently (a _subgroup_).
These composite results may be used to execute shaders more efficiently on a
slink:VkPhysicalDevice.
When using GLSL source-based shader languages, the following shader
functions from GL_ARB_shader_group_vote can map to these SPIR-V
instructions:
* code:anyInvocationARB() -> code:OpSubgroupAnyKHR,
* code:allInvocationsARB() -> code:OpSubgroupAllKHR, and
* code:allInvocationsEqualARB() -> code:OpSubgroupAllEqualKHR.
The subgroup across which the boolean conditions are evaluated is
implementation-dependent, and this extension provides no guarantee over how
individual shader invocations are assigned to subgroups.
In particular, a subgroup has no necessary relationship with the compute
shader _local workgroup_ -- any pair of shader invocations in a compute
local workgroup may execute in different subgroups as used by these
instructions.
Compute shaders operate on an explicitly specified group of threads (a local
workgroup), but many implementations will also group non-compute shader
invocations and execute them concurrently.
When executing code like
[source,{basebackend@docbook:c++:cpp}]
----------------------------------------
if (condition) {
result = do_fast_path();
} else {
result = do_general_path();
}
----------------------------------------
where code:condition diverges between invocations, an implementation might
first execute code:do_fast_path() for the invocations where code:condition
is true and leave the other invocations dormant.
Once code:do_fast_path() returns, it might call code:do_general_path() for
invocations where code:condition is false and leave the other invocations
dormant.
In this case, the shader executes *both* the fast and the general path and
might be better off just using the general path for all invocations.
This extension provides the ability to avoid divergent execution by
evaluating a condition across an entire subgroup using code like:
[source,{basebackend@docbook:c++:cpp}]
----------------------------------------
if (allInvocationsARB(condition)) {
result = do_fast_path();
} else {
result = do_general_path();
}
----------------------------------------
The built-in function code:allInvocationsARB() will return the same value
for all invocations in the group, so the group will either execute
code:do_fast_path() or code:do_general_path(), but never both.
For example, shader code might want to evaluate a complex function
iteratively by starting with an approximation of the result and then
refining the approximation.
Some input values may require a small number of iterations to generate an
accurate result (code:do_fast_path) while others require a larger number
(code:do_general_path).
In another example, shader code might want to evaluate a complex function
(code:do_general_path) that can be greatly simplified when assuming a
specific value for one of its inputs (code:do_fast_path).
--
=== New Object Types
None.
=== New Enum Constants
None.
=== New Enums
None.
=== New Structures
None.
=== New Functions
None.
=== New Built-In Variables
None.
=== New SPIR-V Capabilities
* <<spirvenv-capabilities-table-subgroupvote,SubgroupVoteKHR>>
=== Issues
None.
=== Version History
* Revision 1, 2016-11-28 (Daniel Koch)
- Initial draft

164
doc/specs/vulkan/appendices/VK_EXT_swapchain_colorspace.txt Normal file
View File

@ -0,0 +1,164 @@
[[VK_EXT_swapchain_colorspace]]
== VK_EXT_swapchain_colorspace
*Name String*::
+VK_EXT_swapchain_colorspace+
*Extension Type*::
Instance
*Registered Extension Number*::
105
*Last Modified Date*::
2017-01-13
*Revision*::
1
*IP Status*::
No known IP claims.
*Dependencies*::
- This extension is written against version 1.0 of the Vulkan API.
- This extension requires +VK_KHR_surface+
*Contributors*::
- Courtney Goeltzenleuchter, Google
*Contacts*::
- Courtney Goeltzenleuchter, Google
This extension defines enums for elink:VkColorSpaceKHR that correspond to
the following color spaces::
[[VK_EXT_swapchain_colorspace-table]]
.Color Spaces and Attributes
[options="header"]
|====
| Name | Red Primary | Green Primary | Blue Primary | White-point | OETF
| DCI-P3 | 0.680, 0.320 | 0.265, 0.690 | 0.150, 0.060 | 0.3127, 0.3290 (D65) | Gamma 2.6
| Display-P3 | 0.680, 0.320 | 0.265, 0.690 | 0.150, 0.060 | 0.3127, 0.3290 (D65) | sRGB
| BT709 | 0.640, 0.330 | 0.300, 0.600 | 0.150, 0.060 | 0.3127, 0.3290 (D65) | SMPTE 170M
| sRGB | 0.640, 0.330 | 0.300, 0.600 | 0.150, 0.060 | 0.3127, 0.3290 (D65) | sRGB
| scRGB | 0.640, 0.330 | 0.300, 0.600 | 0.150, 0.060 | 0.3127, 0.3290 (D65) | scRGB
| BT2020 | 0.708, 0.292 | 0.170, 0.797 | 0.131, 0.046 | 0.3127, 0.3290 (D65) | SMPTE 170M
| AdobeRGB | 0.640, 0.330 | 0.210, 0.710 | 0.150, 0.060 | 0.3127, 0.3290 (D65) | Gamma 2.2
|====
For Opto-Electrical Transfer Function (OETF), unless otherwise specified,
the values of [eq]#L# and [eq]#E# are defined as:
[eq]#L# - luminance of image [eq]#0 {leq} L {leq} 1# for conventional
colorimetry
[eq]#E# - corresponding electrical signal (value stored in memory)
=== sRGB OETF
[latexmath]
+++++++++++++++++++
\[ \begin{aligned}
E & =
\begin{cases}
1.055 \times L^{1 \over 2.4} - 0.055 & \text{for } 0.0031308 \leq L \leq 1 \\
12.92 \times L & \text{for } 0 \leq L < 0.0031308
\end{cases}
\end{aligned} \]
+++++++++++++++++++
=== scRGB OETF
[latexmath]
+++++++++++++++++++
\[ \begin{aligned}
E & =
\begin{cases}
1.055 \times L^{1 \over 2.4} - 0.055 & \text{for } 0.0031308 \leq L \leq 7.5913 \\
12.92 \times L & \text{for } 0 \leq L < 0.0031308 \\
-E \times -L & \text{for } L < 0
\end{cases}
\end{aligned} \]
+++++++++++++++++++
[eq]#L# - luminance of image is within [eq]#[-0.6038, 7.5913]#.
[eq]#E# can be negative and/or > 1.
That is how scRGB specifies colors outside the standard sRGB gamut.
=== SMPTE 170M OETF
[latexmath]
+++++++++++++++++++
\[ \begin{aligned}
E & =
\begin{cases}
1.099 \times L^0.45 - 0.099 & \text{for } 0.018 \leq L \leq 1 \\
4.5 \times L & \text{for } 0 \leq L < 0.018
\end{cases}
\end{aligned} \]
+++++++++++++++++++
=== Display Gamma 2.2 OETF
latexmath:[$E = L^{1 \over 2.2}$]
=== Display Gamma 2.6 OETF
latexmath:[$E = L^{1 \over 2.6}$]
An implementation supporting this extension indicates support for these
color spaces via slink:VkSurfaceFormatKHR structures returned from
flink:vkGetPhysicalDeviceSurfaceFormatsKHR.
Specifying the supported surface color space when calling
flink:vkCreateSwapchainKHR will create a swapchain using that color space.
Vulkan requires that all implementations support the sRGB OETF and EOTF when
using an SRGB pixel format.
Other transfer functions, such as SMPTE 170M, must not: be performed by the
implementation, but can: be performed by the application shader.
=== New Enum Constants
* Extending elink:VkColorSpaceKHR:
** ename:VK_COLOR_SPACE_DISPLAY_P3_LINEAR_EXT - supports the Display-P3
color space and applies a linear OETF.
** ename:VK_COLOR_SPACE_DISPLAY_P3_NONLINEAR_EXT - supports the Display-P3
color space and applies the sRGB OETF.
** ename:VK_COLOR_SPACE_SCRGB_LINEAR_EXT - supports the scRGB color space
and applies a linear OETF.
** ename:VK_COLOR_SPACE_SCRGB_NONLINEAR_EXT - supports the scRGB color
space and applies the scRGB OETF.
** ename:VK_COLOR_SPACE_DCI_P3_LINEAR_EXT - supports the DCI-P3 color
space and applies a linear OETF.
** ename:VK_COLOR_SPACE_DCI_P3_NONLINEAR_EXT - supports the DCI-P3 color
space and applies the Gamma 2.6 OETF.
** ename:VK_COLOR_SPACE_BT709_LINEAR_EXT - supports the BT709 color space
and applies a linear OETF.
** ename:VK_COLOR_SPACE_BT709_NONLINEAR_EXT - supports the BT709 color
space and applies the SMPTE 170M OETF.
** ename:VK_COLOR_SPACE_BT2020_LINEAR_EXT - supports the BT2020 color
space and applies a linear OETF.
** ename:VK_COLOR_SPACE_BT2020_NONLINEAR_EXT - supports the BT2020 color
space and applies the SMPTE 170M OETF.
** ename:VK_COLOR_SPACE_ADOBERGB_LINEAR_EXT - supports the AdobeRGB color
space and applies a linear OETF.
** ename:VK_COLOR_SPACE_ADOBERGB_NONLINEAR_EXT - supports the AdobeRGB
color space and applies the Gamma 2.2 OETF.
=== Issues
1) Does the spec need to specify which kinds of image formats support the
color spaces?
*RESOLVED*: Pixel format is independent of color space (though some color
spaces really want / need floating point color components to be useful).
Therefore, do not plan on documenting what formats support which
colorspaces.
An application can: call flink:vkGetPhysicalDeviceSurfaceFormatsKHR to query
what a particular implementation supports.
2) How does application determine if HW supports appropriate transfer
function for a colorspace?
*RESOLVED*: Extension indicates that implementation must: not do the OETF
encoding if it's not sRGB.
That responsibility falls to the application shaders.
=== Version History
* Revision 1, 2016-12-27 (Courtney Goeltzenleuchter)
- Initial version

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

@ -14,14 +14,14 @@
*IP Status*::
No known IP claims.
*Dependencies*::
- This extension is written against version 1.0.25 of the Vulkan API.
- This extension is written against version 1.0.25 of the Vulkan API.
*Contributors*::
- Tobin Ehlis, Google
- Courtney Goeltzenleuchter, Google
- Tobin Ehlis, Google
- Courtney Goeltzenleuchter, Google
*Contacts*::
- Tobin Ehlis, Google (tobine@google.com)
- Tobin Ehlis, Google (tobine@google.com)
This extension provides the sname:VkValidationFlagsEXT struct that can be
This extension provides the slink:VkValidationFlagsEXT struct that can be
included in the pname:pNext chain at flink:vkCreateInstance time.
The new struct contains an array of elink:VkValidationCheckEXT values that
will be disabled by the validation layers.
@ -37,7 +37,7 @@ will be disabled by the validation layers.
=== New Structures
* slink:VkValidationFlagsEXT
* slink:VkValidationFlagsEXT
=== New Functions

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

@ -14,11 +14,11 @@
*Revision*::
1
*Dependencies*::
- This extension is written against version 1.0 of the Vulkan API.
- This extension is written against version 1.0 of the Vulkan API.
*Contributors*::
- Tobias Hector, Imagination Technologies
- Tobias Hector, Imagination Technologies
*Contacts*::
- Tobias Hector (tobias.hector@imgtec.com)
- Tobias Hector (tobias.hector@imgtec.com)
+VK_IMG_filter_cubic+ adds an additional, high quality cubic filtering mode
to Vulkan, using a Catmull-Rom bicubic filter.

16
doc/specs/vulkan/appendices/VK_KHR_android_surface/vk_khr_android_surface.txt
View File

@ -1,4 +1,4 @@
// Copyright (c) 2014-2016 The Khronos Group Inc.
// Copyright (c) 2014-2017 The Khronos Group Inc.
// Copyright notice at https://www.khronos.org/registry/speccopyright.html
[[VK_KHR_android_surface]]
@ -18,7 +18,7 @@
No known IP claims.
*Dependencies*::
- This extension is written against version 1.0 of the Vulkan API.
- This extension requires +VK_KHR_surface+.
- Requires +VK_KHR_surface+.
*Contributors*::
- Patrick Doane, Blizzard
- Jason Ekstrand, Intel
@ -40,7 +40,7 @@
- Jesse Hall, Google
The +VK_KHR_android_surface+ extension is an instance extension.
It provides a mechanism to create a sname:VkSurfaceKHR object (defined by
It provides a mechanism to create a slink:VkSurfaceKHR object (defined by
the +VK_KHR_surface+ extension) that refers to an code:ANativeWindow,
Android's native surface type.
The code:ANativeWindow represents the producer endpoint of any buffer queue,
@ -73,12 +73,12 @@ None
=== Issues
1) Does Android need a way to query for compatibility between a particular
physical device (and queue family?) and a specific Android display?
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.
*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.
=== Version History

238
doc/specs/vulkan/appendices/VK_KHR_display/vk_khr_display.txt
View File

@ -1,4 +1,4 @@
// Copyright (c) 2014-2016 The Khronos Group Inc.
// Copyright (c) 2014-2017 The Khronos Group Inc.
// Copyright notice at https://www.khronos.org/registry/speccopyright.html
[[VK_KHR_display]]
@ -19,24 +19,24 @@
*IP Status*::
No known IP claims.
*Dependencies*::
- This extension is written against version 1.0 of the Vulkan API.
- This extension requires +VK_KHR_surface+.
- This extension is written against version 1.0 of the Vulkan API.
- Requires +VK_KHR_surface+.
*Contributors*::
- James Jones, NVIDIA
- Norbert Nopper, Freescale
- Jeff Vigil, Qualcomm
- Daniel Rakos, AMD
- James Jones, NVIDIA
- Norbert Nopper, Freescale
- Jeff Vigil, Qualcomm
- Daniel Rakos, AMD
*Contacts*::
- James Jones (jajones 'at' nvidia.com)
- Norbert Nopper (Norbert.Nopper 'at' freescale.com)
- James Jones (jajones 'at' nvidia.com)
- Norbert Nopper (Norbert.Nopper 'at' freescale.com)
This extension provides the API to enumerate displays and available modes on
a given device.
=== New Object Types
* sname:VkDisplayKHR
* sname:VkDisplayModeKHR
* slink:VkDisplayKHR
* slink:VkDisplayModeKHR
=== New Enum Constants
@ -70,170 +70,174 @@ a given device.
=== Issues
1) Which properties of a mode should be fixed in the mode info Vs.
settable in some other function when setting the mode? E.g., do we need
to double the size of the mode pool to include both stereo and
non-stereo modes? YUV and RGB scanout even if they both take RGB input
images? BGR Vs.
RGB input? etc.
1) Which properties of a mode should be fixed in the mode info vs.
settable in some other function when setting the mode? E.g., do we need to
double the size of the mode pool to include both stereo and non-stereo
modes? YUV and RGB scanout even if they both take RGB input images? BGR vs.
RGB input? etc.
PROPOSED RESOLUTION: Many modern displays support at most a handful of
resolutions and timings natively.
Other "modes" are expected to be supported using scaling hardware on the
display engine or GPU.
Other properties, such as rotation and mirroring should not require
duplicating hardware modes just to express all combinations.
Further, these properties may be implemented on a per-display or
per-overlay granularity.
*PROPOSED RESOLUTION*: Many modern displays support at most a handful of
resolutions and timings natively.
Other ``modes'' are expected to be supported using scaling hardware on the
display engine or GPU.
Other properties, such as rotation and mirroring should not require
duplicating hardware modes just to express all combinations.
Further, these properties may be implemented on a per-display or per-overlay
granularity.
To avoid the exponential growth of modes as mutable properties are
added, as was the case with EGLConfig/WGL pixel formats/GLXFBConfig,
this specification should separate out hardware properties and
configurable state into separate objects.
Modes and overlay planes will express capabilities of the hardware,
while a separate structure will allow applications to configure scaling,
rotation, mirroring, color keys, LUT values, alpha masks, etc.
for a given swapchain independent of the mode in use.
Constraints on these settings will be established by properties of the
immutable objects.
To avoid the exponential growth of modes as mutable properties are added, as
was the case with EGLConfig/WGL pixel formats/GLXFBConfig, this
specification should separate out hardware properties and configurable state
into separate objects.
Modes and overlay planes will express capabilities of the hardware, while a
separate structure will allow applications to configure scaling, rotation,
mirroring, color keys, LUT values, alpha masks, etc.
for a given swapchain independent of the mode in use.
Constraints on these settings will be established by properties of the
immutable objects.
Note the resolution of this issue may affect issue (5) as well.
Note the resolution of this issue may affect issue 5 as well.
2) What properties of a display itself are useful?
PROPOSED RESOLUTION: This issue is too broad.
It was meant to prompt general discussion, but resolving this issue
amounts to completing this specification.
All interesting properties should be included.
The issue will remain as a placeholder since removing it would make it
hard to parse existing discussion notes that refer to issues by number.
*PROPOSED RESOLUTION*: This issue is too broad.
It was meant to prompt general discussion, but resolving this issue amounts
to completing this specification.
All interesting properties should be included.
The issue will remain as a placeholder since removing it would make it hard
to parse existing discussion notes that refer to issues by number.
3) How are multiple overlay planes within a display or mode enumerated?
PROPOSED RESOLUTION: They are referred to by an index.
Each display will report the number of overlay planes it contains.
*PROPOSED RESOLUTION*: They are referred to by an index.
Each display will report the number of overlay planes it contains.
4) Should swapchains be created relative to a mode or a display?
PROPOSED RESOLUTION: When using this extension, swapchains are created
relative to a mode and a plane.
The mode implies the display object the swapchain will present to.
If the specified mode is not the display's current mode, the new mode
will be applied when the first image is presented to the swapchain, and
the default operating system mode, if any, will be restored when the
swapchain is destroyed.
*PROPOSED RESOLUTION*: When using this extension, swapchains are created
relative to a mode and a plane.
The mode implies the display object the swapchain will present to.
If the specified mode is not the display's current mode, the new mode will
be applied when the first image is presented to the swapchain, and the
default operating system mode, if any, will be restored when the swapchain
is destroyed.
5) Should users query generic ranges from displays and construct their own
modes explicitly using those constraints rather than querying a fixed
set of modes (Most monitors only have one real "mode" these days, even
though many support relatively arbitrary scaling, either on the monitor
side or in the GPU display engine, making "modes" something of a
relic/compatibility construct).
modes explicitly using those constraints rather than querying a fixed set of
modes (Most monitors only have one real ``mode'' these days, even though
many support relatively arbitrary scaling, either on the monitor side or in
the GPU display engine, making ``modes'' something of a relic/compatibility
construct).
PROPOSED RESOLUTION: Expose both.
Display info structures will expose a set of predefined modes, as well
as any attributes necessary to construct a customized mode.
*PROPOSED RESOLUTION*: Expose both.
Display info structures will expose a set of predefined modes, as well as
any attributes necessary to construct a customized mode.
6) Is it fine if we return the display and display mode handles in the
structure used to query their properties?
structure used to query their properties?
PROPOSED RESOLUTION: Yes.
*PROPOSED RESOLUTION*: Yes.
7) Is there a possibility that not all displays of a device work with all of
the present queues of a device? If yes, how do we determine which
displays work with which present queues?
the present queues of a device? If yes, how do we determine which displays
work with which present queues?
PROPOSED RESOLUTION: No known hardware has such limitations, but
determining such limitations is supported automatically using the
existing VK_EXT_KHR_surface and VK_EXT_KHR_swapchain query mechanisms.
*PROPOSED RESOLUTION*: No known hardware has such limitations, but
determining such limitations is supported automatically using the existing
+VK_KHR_surface+ and +VK_KHR_swapchain+ query mechanisms.
8) Should all presentation need to be done relative to an overlay plane, or
can a display mode + display be used alone to target an output?
can a display mode + display be used alone to target an output?
PROPOSED RESOLUTION: Require specifying a plane explicitly.
*PROPOSED RESOLUTION*: Require specifying a plane explicitly.
9) Should displays have an associated window system display, such as an HDC
or Display*?
or Display*?
PROPOSED RESOLUTION: No.
Displays are independent of any windowing system in use on the system.
Further, neither HDC nor Display* refer to a physical display object.
*PROPOSED RESOLUTION*: No.
Displays are independent of any windowing system in use on the system.
Further, neither HDC nor Display* refer to a physical display object.
10) Are displays queried from a physical GPU or from a device instance?
PROPOSED RESOLUTION: Developers prefer to query modes directly from the
physical GPU so they can use display information as an input to their
device selection algorithms prior to device creation.
This avoids the need to create dummy device instances to enumerate
displays.
*PROPOSED RESOLUTION*: Developers prefer to query modes directly from the
physical GPU so they can use display information as an input to their device
selection algorithms prior to device creation.
This avoids the need to create dummy device instances to enumerate displays.
This preference must be weighed against the extra initialization that
must be done by driver vendors prior to device instance creation to
support this usage.
This preference must be weighed against the extra initialization that must
be done by driver vendors prior to device instance creation to support this
usage.
11) Should displays and/or modes be dispatchable objects? If functions are
to take displays, overlays, or modes as their first parameter, they must
be dispatchable objects as defined in Khronos bug 13529.
If they are not added to the list of dispatchable objects, functions
operating on them must take some higher-level object as their first
parameter.
There is no performance case against making them dispatchable objects,
but they would be the first extension objects to be dispatchable.
to take displays, overlays, or modes as their first parameter, they must be
dispatchable objects as defined in Khronos bug 13529.
If they are not added to the list of dispatchable objects, functions
operating on them must take some higher-level object as their first
parameter.
There is no performance case against making them dispatchable objects, but
they would be the first extension objects to be dispatchable.
PROPOSED RESOLUTION: Do not make displays or modes dispatchable.
They will dispatch based on their associated physical device.
*PROPOSED RESOLUTION*: Do not make displays or modes dispatchable.
They will dispatch based on their associated physical device.
12) Should hardware cursor capabilities be exposed?
PROPOSED RESOLUTION: Defer.
This could be a separate extension on top of the base WSI specs.
*PROPOSED RESOLUTION*: Defer.
This could be a separate extension on top of the base WSI specs.
[NOTE]
.editing-note
==================
There appears to be a missing sentence for the first part of issue 13 here.
==================
endif::editing-notes[]
if they are one physical display device to an end user, but may
internally be implemented as two side-by-side displays using the same
display engine (and sometimes cabling) resources as two physically
separate display devices.
if they are one physical display device to an end user, but may internally
be implemented as two side-by-side displays using the same display engine
(and sometimes cabling) resources as two physically separate display
devices.
PROPOSED RESOLUTION: Tiled displays will appear as a single display
object in this API.
*PROPOSED RESOLUTION*: Tiled displays will appear as a single display object
in this API.
14) Should the raw EDID data be included in the display information?
PROPOSED RESOLUTION: None.
Unclear whether this is a good idea.
Provides a path for forward-compatibility as new EDID extensions are
introduced, but may be complicated by the outcome of issue 13.
*PROPOSED RESOLUTION*: None.
Unclear whether this is a good idea.
Provides a path for forward-compatibility as new EDID extensions are
introduced, but may be complicated by the outcome of issue 13.
15) Should min and max scaling factor capabilities of overlays be exposed?
PROPOSED RESOLUTION: Yes.
This is exposed indirectly by allowing applications to query the min/max
position and extent of the source and destination regions from which
image contents are fetched by the display engine when using a particular
mode and overlay pair.
*PROPOSED RESOLUTION*: Yes.
This is exposed indirectly by allowing applications to query the min/max
position and extent of the source and destination regions from which image
contents are fetched by the display engine when using a particular mode and
overlay pair.
16) Should devices be able to expose planes that can be moved between
displays? If so, how?
displays? If so, how?
PROPOSED RESOLUTION: None.
*PROPOSED RESOLUTION*: None.
17) Should there be a way to destroy display modes? If so, does it support
destroying "built in" modes?
destroying ``built in'' modes?
PROPOSED RESOLUTION: None.
*PROPOSED RESOLUTION*: None.
18) What should the lifetime of display and built-in display mode objects
be?
be?
PROPOSED RESOLUTION: The lifetime of the instance.
These objects can not be destroyed.
A future extension may be added to expose a way to destroy these objects
and/or support display hotplug.
*PROPOSED RESOLUTION*: The lifetime of the instance.
These objects can not be destroyed.
A future extension may be added to expose a way to destroy these objects
and/or support display hotplug.
19) Should persistent mode for smart panels be enabled/disabled at swap
chain creation time, or on a per-present basis.
chain creation time, or on a per-present basis.
PROPOSED RESOLUTION: On a per-present basis.
*PROPOSED RESOLUTION*: On a per-present basis.
=== Examples

77
doc/specs/vulkan/appendices/VK_KHR_display_swapchain/vk_khr_display_swapchain.txt
View File

@ -1,4 +1,4 @@
// Copyright (c) 2014-2016 The Khronos Group Inc.
// Copyright (c) 2014-2017 The Khronos Group Inc.
// Copyright notice at https://www.khronos.org/registry/speccopyright.html
[[VK_KHR_display_swapchain]]
@ -19,14 +19,15 @@
*IP Status*::
No known IP claims.
*Dependencies*::
- This extension is written against version 1.0 of the Vulkan API.
- This extension requires +VK_KHR_swapchain+ and +VK_KHR_display+
- This extension is written against version 1.0 of the Vulkan API.
- Requires +VK_KHR_swapchain+.
- Requires +VK_KHR_display+.
*Contributors*::
- James Jones, NVIDIA
- Jeff Vigil, Qualcomm
- Jesse Hall, Google
- James Jones, NVIDIA
- Jeff Vigil, Qualcomm
- Jesse Hall, Google
*Contacts*::
- James Jones (jajones 'at' nvidia.com)
- James Jones (jajones 'at' nvidia.com)
This extension provides an API to create a swapchain directly on a device's
display without any underlying window system.
@ -57,49 +58,49 @@ None
=== Issues
1) Should swapchains sharing images each hold a reference to the images, or
should it be up to the application to destroy the swapchains and images
in an order that avoids the need for reference counting?
should it be up to the application to destroy the swapchains and images in
an order that avoids the need for reference counting?
PROPOSED RESOLUTION: Take a reference.
The lifetime of presentable images is already complex enough.
*PROPOSED RESOLUTION*: Take a reference.
The lifetime of presentable images is already complex enough.
2) Should the srcRect/dstRect parameters be specified as part of the present
command, or at swapchain creation time?
command, or at swapchain creation time?
PROPOSED RESOLUTION: As part of the presentation command.
This allows moving and scaling the image on the screen without the need
to respecify the mode or create a new swapchain presentable images.
*PROPOSED RESOLUTION*: As part of the presentation command.
This allows moving and scaling the image on the screen without the need to
respecify the mode or create a new swapchain presentable images.
3) Should srcRect/dstRect be specified as rects, or separate offset/extent
values?
values?
PROPOSED RESOLUTION: As rects.
Specifying them separately might make it easier for hardware to expose
support for one but not the other, but in such cases applications must
just take care to obey the reported capabilities and not use non-zero
offsets or extents that require scaling, as appropriate.
*PROPOSED RESOLUTION*: As rects.
Specifying them separately might make it easier for hardware to expose
support for one but not the other, but in such cases applications must just
take care to obey the reported capabilities and not use non-zero offsets or
extents that require scaling, as appropriate.
4) How can applications create multiple swapchains that use the same images?
RESOLUTION: By calling vkCreateSharedSwapchainsKHR().
RESOLUTION: By calling flink:vkCreateSharedSwapchainsKHR.
An earlier resolution used vkCreateSwapchainKHR(), chaining multiple
VkSwapchainCreateInfoKHR structures through pNext.
In order to allow each swapchain to also allow other extension structs,
a level of indirection was used: VkSwapchainCreateInfoKHR::pNext pointed
to a different structure, which had both an sType/pNext for additional
extensions, and also had a pointer to the next VkSwapchainCreateInfoKHR
structure.
The number of swapchains to be created could only be found by walking
this linked list of alternating structures, and the pSwapchains out
parameter was reinterpreted to be an array of VkSwapchainKHR handles.
An earlier resolution used flink:vkCreateSwapchainKHR, chaining multiple
slink:VkSwapchainCreateInfoKHR structures through pname:pNext.
In order to allow each swapchain to also allow other extension structs, a
level of indirection was used: slink:VkSwapchainCreateInfoKHR::pname:pNext
pointed to a different structure, which had both an pname:sType/pname:pNext
for additional extensions, and also had a pointer to the next
slink:VkSwapchainCreateInfoKHR structure.
The number of swapchains to be created could only be found by walking this
linked list of alternating structures, and the pSwapchains out parameter was
reinterpreted to be an array of slink:VkSwapchainKHR handles.
Another option considered was a method to specify a "shared" swapchain
when creating a new swapchain, such that groups of swapchains using the
same images could be built up one at a time.
This was deemed unusable because drivers need to know all of the
displays an image will be used on when determining which internal
formats and layouts to use for that image.
Another option considered was a method to specify a ``shared'' swapchain
when creating a new swapchain, such that groups of swapchains using the same
images could be built up one at a time.
This was deemed unusable because drivers need to know all of the displays an
image will be used on when determining which internal formats and layouts to
use for that image.
=== Examples

150
doc/specs/vulkan/appendices/VK_KHR_get_physical_device_properties2.txt Normal file
View File

@ -0,0 +1,150 @@
// Copyright (c) 2016-2017 The Khronos Group Inc.
// Copyright notice at https://www.khronos.org/registry/speccopyright.html
[[VK_KHR_get_physical_device_properties2]]
== VK_KHR_get_physical_device_properties2
*Name String*::
+VK_KHR_get_physical_device_properties2+
*Extension Type*::
Instance extension
*Registered Extension Number*::
60
*Status*::
Complete.
*Last Modified Date*::
2016-11-02
*Revision*::
2
*IP Status*::
No known IP claims.
*Dependencies*::
- This extension is written against version 1.0 of the Vulkan API.
*Contributors*::
- Jeff Bolz, NVIDIA
- Ian Elliott, Google
*Contacts*::
- Jeff Bolz (jbolz 'at' nvidia.com)
This extension provides new entry points to query device features, device
properties, and format properties in a way that can be easily extended by
other extensions, without introducing any further entry points.
The Vulkan 1.0 feature/limit/formatproperty structures do not include an
sType/pNext, this extension wraps them in new structures with sType/pNext so
an application can query a chain of feature/limit/formatproperty structures
by constructing the chain and letting the implementation fill them in.
A new command is added for each ftext:vkGetPhysicalDevice* command in core
Vulkan 1.0.
The new feature structure (and a chain of extensions) can also be passed in
to device creation to enable features.
This extension also allows applications to use the physical-device
components of device extensions before flink:vkCreateDevice is called.
=== New Object Types
None.
=== New Enum Constants
* Extending ename:VkStructureType:
** ename:VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FEATURES_2_KHR
** ename:VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PROPERTIES_2_KHR
** ename:VK_STRUCTURE_TYPE_FORMAT_PROPERTIES_2_KHR
** ename:VK_STRUCTURE_TYPE_IMAGE_FORMAT_PROPERTIES_2_KHR
** ename:VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_IMAGE_FORMAT_INFO_2_KHR
** ename:VK_STRUCTURE_TYPE_QUEUE_FAMILY_PROPERTIES_2_KHR
** ename:VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MEMORY_PROPERTIES_2_KHR
** ename:VK_STRUCTURE_TYPE_SPARSE_IMAGE_FORMAT_PROPERTIES_2_KHR
** ename:VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SPARSE_IMAGE_FORMAT_INFO_2_KHR
=== New Enums
None.
=== New Structures
* slink:VkPhysicalDeviceFeatures2KHR
* slink:VkPhysicalDeviceProperties2KHR
* slink:VkFormatProperties2KHR
* slink:VkImageFormatProperties2KHR
* slink:VkPhysicalDeviceImageFormatInfo2KHR
* slink:VkQueueFamilyProperties2KHR
* slink:VkPhysicalDeviceMemoryProperties2KHR
* slink:VkSparseImageFormatProperties2KHR
* slink:VkPhysicalDeviceSparseImageFormatInfo2KHR
=== New Functions
* flink:vkGetPhysicalDeviceFeatures2KHR
* flink:vkGetPhysicalDeviceProperties2KHR
* flink:vkGetPhysicalDeviceFormatProperties2KHR
* flink:vkGetPhysicalDeviceImageFormatProperties2KHR
* flink:vkGetPhysicalDeviceQueueFamilyProperties2KHR
* flink:vkGetPhysicalDeviceMemoryProperties2KHR
* flink:vkGetPhysicalDeviceSparseImageFormatProperties2KHR
=== Issues
None.
=== Examples
[source,{basebackend@docbook:c++:cpp}]
----------------------------------------
// Get features with a hypothetical future extension.
VkHypotheticalExtensionFeaturesKHR hypotheticalFeatures =
{
VK_STRUCTURE_TYPE_HYPOTHETICAL_FEATURES_KHR, // sType
NULL, // pNext
};
VkPhysicalDeviceFeatures2KHR features =
{
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FEATURES_2_KHR, // sType
&hypotheticalFeatures, // pNext
};
// After this call, features and hypotheticalFeatures have been filled out.
vkGetPhysicalDeviceFeatures2KHR(physicalDevice, &features);
// Properties/limits can be chained and queried similarly.
// Enable some features:
VkHypotheticalExtensionFeaturesKHR enabledHypotheticalFeatures =
{
VK_STRUCTURE_TYPE_HYPOTHETICAL_FEATURES_KHR, // sType
NULL, // pNext
};
VkPhysicalDeviceFeatures2KHR enabledFeatures =
{
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FEATURES_2_KHR, // sType
&enabledHypotheticalFeatures, // pNext
};
enabledFeatures.features.xyz = VK_TRUE;
enabledHypotheticalFeatures.abc = VK_TRUE;
VkDeviceCreateInfo deviceCreateInfo =
{
VK_STRUCTURE_TYPE_DEVICE_CREATE_INFO, // sType
&enabledFeatures, // pNext
...
NULL, // pEnabledFeatures
}
VkDevice device;
vkCreateDevice(physicalDevice, &deviceCreateInfo, NULL, &device);
----------------------------------------
=== Version History
* Revision 1, 2016-09-12 (Jeff Bolz)
- Internal revisions
* Revision 2, 2016-11-02 (Ian Elliott)
- Added ability for applications to use the physical-device components of
device extensions before vkCreateDevice is called.

108
doc/specs/vulkan/appendices/VK_KHR_maintenance1.txt Normal file
View File

@ -0,0 +1,108 @@
// Copyright (c) 2016-2017 The Khronos Group Inc.
// Copyright notice at https://www.khronos.org/registry/speccopyright.html
[[VK_KHR_maintenance1]]
== VK_KHR_maintenance1
*Name String*::
+VK_KHR_maintenance1+
*Extension Type*::
Device extension
*Registered Extension Number*::
70
*Status*::
Draft
*Last Modified Date*::
2016-10-26
*Revision*::
1
*Dependencies*::
- This extension is written against version 1.0 of the Vulkan API.
*Contributors*::
- Dan Ginsburg, Valve
- Daniel Koch, NVIDIA
- Daniel Rakos, AMD
- Jan-Harald Fredriksen, ARM
- Jason Ekstrand, Intel
- Jeff Bolz, NVIDIA
- Jesse Hall, Google
- John Kessenich, Google
- Michael Worcester, Imagination Technologies
- Neil Henning, Codeplay Software Ltd.
- Piers Daniell, NVIDIA
- Slawomir Grajewski, Intel
- Tobias Hector, Imagination Technologies
- Tom Olson, ARM
*Contacts*::
- Piers Daniell (pdaniell 'at' nvidia.com)
*Overview*::
+VK_KHR_maintenance1+ 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:
* Allow 2D and 2D array image views to be created from 3D images, which
can then be used as color framebuffer attachments.
This allows applications to render to slices of a 3D image.
* Support flink:vkCmdCopyImage between 2D array layers and 3D slices.
This extension allows copying from layers of a 2D array image to slices
of a 3D image and vice versa.
* 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.
* Allow implementations to express support for doing just transfers and
clears of image formats that they otherwise support no other format
features for.
This is done by adding new format feature flags
ename:VK_FORMAT_FEATURE_TRANSFER_SRC_BIT_KHR and
ename:VK_FORMAT_FEATURE_TRANSFER_DST_BIT_KHR.
* Support flink:vkCmdFillBuffer on transfer-only queues.
Previously flink:vkCmdFillBuffer was defined to only work on command
buffers allocated from command pools which support graphics or compute
queues.
It is now allowed on queues that just support transfer operations.
* Fix the inconsistency of how error conditions are returned between the
flink:vkCreateGraphicsPipelines and flink:vkCreateComputePipelines
functions and the flink:vkAllocateDescriptorSets and
flink:vkAllocateCommandBuffers functions.
* Add new ename:VK_ERROR_OUT_OF_POOL_MEMORY_KHR error so implementations
can give a more precise reason for flink:vkAllocateDescriptorSets
failures.
* Add a new command flink:vkTrimCommandPoolKHR which gives the
implementation an opportunity to release any unused command pool memory
back to the system.
=== New Object Types
None.
=== New Enum Constants
* ename:VK_ERROR_OUT_OF_POOL_MEMORY_KHR
* ename:VK_FORMAT_FEATURE_TRANSFER_SRC_BIT_KHR
* ename:VK_FORMAT_FEATURE_TRANSFER_DST_BIT_KHR
* ename:VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT_KHR
=== New Enums
None.
=== New Structures
None.
=== New Functions
* flink:vkTrimCommandPoolKHR
=== Issues
None.
=== Version History
* Revision 1, 2016-10-26 (Piers Daniell)
- Internal revisions

19
doc/specs/vulkan/appendices/VK_KHR_mir_surface/vk_khr_mir_surface.txt
View File

@ -1,4 +1,4 @@
// Copyright (c) 2014-2016 The Khronos Group Inc.
// Copyright (c) 2014-2017 The Khronos Group Inc.
// Copyright notice at https://www.khronos.org/registry/speccopyright.html
[[VK_KHR_mir_surface]]
@ -18,7 +18,7 @@
No known IP claims.
*Dependencies*::
- This extension is written against version 1.0 of the Vulkan API.
- This extension requires +VK_KHR_surface+.
- Requires +VK_KHR_surface+.
*Contributors*::
- Patrick Doane, Blizzard
- Jason Ekstrand, Intel
@ -42,7 +42,7 @@
The +VK_KHR_mir_surface+ extension is an instance extension.
It provides a mechanism to create a sname:VkSurfaceKHR object (defined by
It provides a mechanism to create a slink:VkSurfaceKHR object (defined by
the +VK_KHR_surface extension+) that refers to a Mir surface, as well as a
query to determine support for rendering to the windows desktop.
@ -52,7 +52,7 @@ None
=== New Enum Constants
* Extending ename:VkStructureType:
* Extending elink:VkStructureType:
** ename:VK_STRUCTURE_TYPE_MIR_SURFACE_CREATE_INFO_KHR
=== New Enums
@ -71,11 +71,11 @@ None
=== Issues
1) Does Mir need a way to query for compatibility between a particular
physical device (and queue family?) and a specific Mir connection,
screen, window, etc.?
physical device (and queue family?) and a specific Mir connection, screen,
window, etc.?
RESOLVED: Yes, vkGetPhysicalDeviceMirPresentationSupportKHR() was added
to address this.
*RESOLVED*: Yes, flink:vkGetPhysicalDeviceMirPresentationSupportKHR was
added to address this.
=== Version History
@ -84,8 +84,7 @@ None
(later renamed VK_EXT_KHR_surface).
* Revision 2, 2015-10-02 (James Jones)
- Added vkGetPhysicalDeviceMirPresentationSupportKHR() to resolve issue
#1.
- Added vkGetPhysicalDeviceMirPresentationSupportKHR to resolve issue #1.
* Revision 3, 2015-10-26 (Ian Elliott)
- Renamed from VK_EXT_KHR_mir_surface to VK_KHR_mir_surface.

13
doc/specs/vulkan/appendices/VK_KHR_sampler_mirror_clamp_to_edge.txt
View File

@ -1,4 +1,4 @@
// Copyright (c) 2014-2016 The Khronos Group Inc.
// Copyright (c) 2014-2017 The Khronos Group Inc.
// Copyright notice at https://www.khronos.org/registry/speccopyright.html
[[VK_KHR_sampler_mirror_clamp_to_edge]]
@ -17,15 +17,14 @@
*Revision*::
1
*Dependencies*::
- This extension is written against version 1.0.
of the Vulkan API.
- This extension is written against version 1.0 of the Vulkan API.
*Contributors*::
- Tobias Hector, Imagination Technologies
- Tobias Hector, Imagination Technologies
*Contacts*::
- Tobias Hector (tobias.hector@imgtec.com)
- Tobias Hector (tobias.hector@imgtec.com)
VK_KHR_sampler_mirror_clamp_to_edge extends the set of sampler address modes
to include an additional mode
+VK_KHR_sampler_mirror_clamp_to_edge+ extends the set of sampler address
modes to include an additional mode
(ename:VK_SAMPLER_ADDRESS_MODE_MIRROR_CLAMP_TO_EDGE) that effectively uses a
texture map twice as large as the original image in which the additional
half of the new image is a mirror image of the original image.

116
doc/specs/vulkan/appendices/VK_KHR_shader_draw_parameters.txt Normal file
View File

@ -0,0 +1,116 @@
// Copyright (c) 2016-2017 The Khronos Group Inc.
// Copyright notice at https://www.khronos.org/registry/speccopyright.html
[[VK_KHR_shader_draw_parameters]]
== VK_KHR_shader_draw_parameters
*Name String*::
+VK_KHR_shader_draw_parameters+
*Extension Type*::
Device extension
*Registered Extension Number*::
64
*Status*::
Complete
*Last Modified Data*::
2016-10-05
*Revision*::
1
*IP Status*::
No known IP claims.
*Dependencies*::
- This extension is written against version 1.0 of the Vulkan API.
- Requires Vulkan 1.0.
- Requires the +SPV_KHR_shader_draw_parameters+ SPIR-V extension.
- Requires +GL_ARB_shader_draw_parameters+ for GLSL source languages.
*Contributors*::
- Daniel Koch, NVIDIA Corporation
- Jeff Bolz, NVIDIA
- Daniel Rakos, AMD
- Jan-Harald Fredriksen, ARM
- John Kessenich, Google
- Stuart Smith, IMG
*Contact*::
- Daniel Koch (dkoch 'at' nvidia.com)
*Overview*::
This extension adds support for the following SPIR-V extension in Vulkan:
* +SPV_KHR_shader_draw_parameters+
+
--
The extension provides access to three additional built-in shader variables
in Vulkan:
* code:BaseInstance, which contains the firstInstance parameter passed to
draw commands,
* code:BaseVertex, which contains the firstVertex/vertexOffset parameter
passed to draw commands, and
* code:DrawIndex, which contains the index of the draw call currently
being processed from an indirect draw call.
When using GLSL source-based shader languages, the following variables from
+GL_ARB_shader_draw_parameters+ can map to these SPIR-V built-in
decorations:
* in int gl_BaseInstanceARB; -> code:BaseInstance,
* in int gl_BaseVertexARB -> code:BaseVertex, and
* in int gl_DrawIDARB; -> code:DrawIndex.
--
=== New Object Types
None.
=== New Enum Constants
None.
=== New Enums
None.
=== New Structures
None.
=== New Functions
None.
=== New Built-In Variables
* <<interfaces-builtin-variables-baseinstance,code:BaseInstance>>
* <<interfaces-builtin-variables-basevertex,code:BaseVertex>>
* <<interfaces-builtin-variables-drawindex,code:DrawIndex>>
=== New SPIR-V Capabilities
* <<spirvenv-capabilities-table-drawparameters,DrawParameters>>
=== Issues
1) Is this the same functionality as +GL_ARB_shader_draw_parameters+?
*RESOLVED*: It's actually a superset as it also adds in support for arrayed
drawing commands.
In GL for +GL_ARB_shader_draw_parameters+, code:gl_BaseVertexARB holds the
integer value passed to the parameter to the command that resulted in the
current shader invocation.
In the case where the command has no baseVertex parameter, the value of
code:gl_BaseVertexARB is zero.
This means that code:gl_BaseVertexARB = baseVertex (for code:glDrawElements
commands with baseVertex) or 0.
In particular there are no code:glDrawArrays commands that take a baseVertex
parameter.
Now in Vulkan, we have *BaseVertex* = _vertexOffset_ (for indexed drawing
commands) or _firstVertex_ (for arrayed drawing commands), and so Vulkan's
version is really a superset of GL functionality.
=== Version History
* Revision 1, 2016-10-05 (Daniel Koch)
- Internal revisions

85
doc/specs/vulkan/appendices/VK_KHR_surface/vk_khr_surface.txt
View File

@ -1,4 +1,4 @@
// Copyright (c) 2014-2016 The Khronos Group Inc.
// Copyright (c) 2014-2017 The Khronos Group Inc.
// Copyright notice at https://www.khronos.org/registry/speccopyright.html
[[VK_KHR_surface]]
@ -36,19 +36,19 @@
- Ian Elliott, LunarG
The +VK_KHR_surface+ extension is an instance extension.
It introduces sname:VkSurfaceKHR objects, which abstract native platform
It introduces slink:VkSurfaceKHR objects, which abstract native platform
surface or window objects for use with Vulkan.
It also provides a way to determine whether a queue family in a physical
device supports presenting to particular surface.
Separate extensions for each each platform provide the mechanisms for
creating sname:VkSurfaceKHR objects, but once created they may be used in
creating slink:VkSurfaceKHR objects, but once created they may be used in
this and other platform-independent extensions, in particular the
+VK_KHR_swapchain+ extension.
=== New Object Types
* sname:VkSurfaceKHR
* slink:VkSurfaceKHR
=== New Enum Constants
@ -91,54 +91,53 @@ https://github.com/KhronosGroup/Vulkan-LoaderAndValidationLayers/blob/master/dem
=== Issues
1) Should this extension include a method to query whether a physical device
supports presenting to a specific window or native surface on a given
platform?
supports presenting to a specific window or native surface on a given
platform?
RESOLVED: Yes.
Without this, applications would need to create a device instance to
determine whether a particular window can be presented to.
Knowing that a device supports presentation to a platform in general is
not sufficient, as a single machine might support multiple seats, or
instances of the platform that each use different underlying physical
devices.
Additionally, some platforms, such as X windows, different drivers and
devices might be used for different windows depending on which section of
the desktop they exist on.
*RESOLVED*: Yes.
Without this, applications would need to create a device instance to
determine whether a particular window can be presented to.
Knowing that a device supports presentation to a platform in general is not
sufficient, as a single machine might support multiple seats, or instances
of the platform that each use different underlying physical devices.
Additionally, on some platforms, such as the X Window System, different
drivers and devices might be used for different windows depending on which
section of the desktop they exist on.
2) Should the vkGetSurfacePropertiesKHR(), vkGetSurfaceFormatsKHR(), and
vkGetSurfacePresentModesKHR() functions from VK_KHR_swapchain be modified
to operate on physical devices and moved to this extension to implement
the resolution of issue 1?
2) Should the flink:vkGetSurfacePropertiesKHR, flink:vkGetSurfaceFormatsKHR,
and flink:vkGetSurfacePresentModesKHR functions from +VK_KHR_swapchain+ be
modified to operate on physical devices and moved to this extension to
implement the resolution of issue 1?
RESOLVED: No, separate query functions are needed, as the purposes served
are similar but incompatible.
The vkGetSurface*KHR functions return information that could potentially
depend on an initialized device.
For example, the formats supported for presentation to the surface might
vary depending on which device extensions are enabled.
The query introduced to resolve issue 1 should be used only to query
generic driver or platform properties.
The physical device parameter is intended to serve only as an identifier
rather than a stateful object.
*RESOLVED*: No, separate query functions are needed, as the purposes served
are similar but incompatible.
The flink:vkGetSurface*KHR functions return information that could
potentially depend on an initialized device.
For example, the formats supported for presentation to the surface might
vary depending on which device extensions are enabled.
The query introduced to resolve issue 1 should be used only to query generic
driver or platform properties.
The physical device parameter is intended to serve only as an identifier
rather than a stateful object.
3) Should Vulkan include support Xlib or XCB as the API for accessing the X
Window System platform?
Window System platform?
RESOLVED: Both.
XCB is a more modern and efficient API, but Xlib usage is deeply
ingrained in many applications and likely will remain in use for the
foreseeable future.
Not all drivers necessarily need to support both, but including both as
options in the core specification will probably encourage support, which
should in turn eases adoption of the Vulkan API in older codebases.
Additionally, the performance improvements possible with XCB likely will
not have a measurable impact on the performance of Vulkan presentation
and other minimal window system interactions defined here.
*RESOLVED*: Both.
XCB is a more modern and efficient API, but Xlib usage is deeply ingrained
in many applications and likely will remain in use for the foreseeable
future.
Not all drivers necessarily need to support both, but including both as
options in the core specification will probably encourage support, which
should in turn eases adoption of the Vulkan API in older codebases.
Additionally, the performance improvements possible with XCB likely will not
have a measurable impact on the performance of Vulkan presentation and other
minimal window system interactions defined here.
4) Should the GBM platform be included in the list of platform enums?
RESOLVED: Deferred, and will be addressed with a platform-specific
extension to be written in the future.
*RESOLVED*: Deferred, and will be addressed with a platform-specific
extension to be written in the future.
=== Version History

10
doc/specs/vulkan/appendices/VK_KHR_surface/wsi.txt
View File

@ -1,4 +1,4 @@
// Copyright (c) 2014-2016 The Khronos Group Inc.
// Copyright (c) 2014-2017 The Khronos Group Inc.
// Copyright notice at https://www.khronos.org/registry/speccopyright.html
= Window System Integration (WSI) Extensions
@ -53,3 +53,11 @@ endif::VK_KHR_xcb_surface[]
ifdef::VK_KHR_xlib_surface[]
include::../VK_KHR_xlib_surface/vk_khr_xlib_surface.txt[]
endif::VK_KHR_xlib_surface[]
ifdef::VK_NN_vi_surface[]
include::../VK_NN_vi_surface/vk_nn_vi_surface.txt[]
endif::VK_NN_vi_surface[]
ifdef::VK_EXT_swapchain_colorspace[]
include::../VK_EXT_swapchain_colorspace.txt[]
endif::VK_EXT_swapchain_colorspace[]

582
doc/specs/vulkan/appendices/VK_KHR_swapchain/vk_khr_swapchain.txt
View File

@ -1,4 +1,4 @@
// Copyright (c) 2014-2016 The Khronos Group Inc.
// Copyright (c) 2014-2017 The Khronos Group Inc.
// Copyright notice at https://www.khronos.org/registry/speccopyright.html
[[VK_KHR_swapchain]]
@ -42,12 +42,12 @@
The +VK_KHR_swapchain+ extension is the device-level companion to the
+VK_KHR_surface+ extension.
It introduces sname:VkSwapchainKHR objects, which provide the ability to
It introduces slink:VkSwapchainKHR objects, which provide the ability to
present rendering results to a surface.
=== New Object Types
* sname:VkSwapchainKHR
* slink:VkSwapchainKHR
=== New Enum Constants
@ -80,376 +80,368 @@ None
=== Issues
1) Does this extension allow the application to specify the memory backing
of the presentable images?
of the presentable images?
RESOLVED: No.
Unlike standard images, the implementation will allocate the memory
backing of the presentable image.
*RESOLVED*: No.
Unlike standard images, the implementation will allocate the memory backing
of the presentable image.
2) What operations are allowed on presentable images?
RESOLVED: This is determined by the imageUsageFlags specified when
creating the presentable image's swapchain.
*RESOLVED*: This is determined by the image usage flags specified when
creating the presentable image's swapchain.
3) Does this extension support MSAA presentable images?
RESOLVED: No.
Presentable images are always single-sampled.
Multi-sampled rendering must use regular images.
To present the rendering results the application must manually resolve
the multi- sampled image to a single-sampled presentable image prior to
presentation.
*RESOLVED*: No.
Presentable images are always single-sampled.
Multi-sampled rendering must use regular images.
To present the rendering results the application must manually resolve the
multi- sampled image to a single-sampled presentable image prior to
presentation.
4) Does this extension support stereo/multi-view presentable images?
RESOLVED: Yes.
The number of views associated with a presentable image is determined by
the imageArraySize specified when creating a swapchain.
All presentable images in a given swapchain use the same array size.
*RESOLVED*: Yes.
The number of views associated with a presentable image is determined by the
imageArraySize specified when creating a swapchain.
All presentable images in a given swapchain use the same array size.
5) Are the layers of stereo presentable images half-sized?
RESOLVED: No.
The image extents always match those requested by the application.
*RESOLVED*: No.
The image extents always match those requested by the application.
6) Do the "present" and "acquire next image" commands operate on a queue? If
not, do they need to include explicit semaphore objects to interlock
them with queue operations?
6) Do the ``present'' and ``acquire next image'' commands operate on a
queue? If not, do they need to include explicit semaphore objects to
interlock them with queue operations?
RESOLVED: The present command operates on a queue.
The image ownership operation it represents happens in order with other
operations on the queue, so no explicit semaphore object is required to
synchronize its actions.
Applications may want to acquire the next image in separate threads from
those in which they manage their queue, or in multiple threads.
To make such usage easier, the acquire next image command takes a
semaphore to signal as a method of explicit synchronization.
The application must later queue a wait for this semaphore before
queuing execution of any commands using the image.
*RESOLVED*: The present command operates on a queue.
The image ownership operation it represents happens in order with other
operations on the queue, so no explicit semaphore object is required to
synchronize its actions.
7) Does vkAcquireNextImageKHR() block if no images are available?
Applications may want to acquire the next image in separate threads from
those in which they manage their queue, or in multiple threads.
To make such usage easier, the acquire next image command takes a semaphore
to signal as a method of explicit synchronization.
The application must later queue a wait for this semaphore before queuing
execution of any commands using the image.
RESOLVED: The command takes a timeout parameter.
Special values for the timeout are 0, which makes the call a
non-blocking operation, and UINT64_MAX, which blocks indefinitely.
Values in between will block for up to the specified time.
The call will return when an image becomes available or an error occurs.
It may, but is not required to, return before the specified timeout
expires if the swapchain becomes out of date.
7) Does flink:vkAcquireNextImageKHR block if no images are available?
*RESOLVED*: The command takes a timeout parameter.
Special values for the timeout are 0, which makes the call a non-blocking
operation, and UINT64_MAX, which blocks indefinitely.
Values in between will block for up to the specified time.
The call will return when an image becomes available or an error occurs.
It may, but is not required to, return before the specified timeout expires
if the swapchain becomes out of date.
8) Can multiple presents be queued using one QueuePresent call?
RESOLVED: Yes.
VkPresentInfoKHR contains a list of swapchains and corresponding image
indices that will be presented.
When supported, all presentations queued with a single vkQueuePresentKHR
call will be applied atomically as one operation.
The same swapchain must not appear in the list more than once.
Later extensions may provide applications stronger guarantees of
atomicity for such present operations, and/or allow them to query
whether atomic presentation of a particular group of swapchains is
possible.
*RESOLVED*: Yes.
slink:VkPresentInfoKHR contains a list of swapchains and corresponding image
indices that will be presented.
When supported, all presentations queued with a single
flink:vkQueuePresentKHR call will be applied atomically as one operation.
The same swapchain must not appear in the list more than once.
Later extensions may provide applications stronger guarantees of atomicity
for such present operations, and/or allow them to query whether atomic
presentation of a particular group of swapchains is possible.
9) How do the presentation and acquire next image functions notify the
application the targeted surface has changed?
application the targeted surface has changed?
RESOLVED: Two new result codes are introduced for this purpose:
*RESOLVED*: Two new result codes are introduced for this purpose:
VK_SUBOPTIMAL_KHR - Presentation will still succeed, subject to the
window resize behavior, but the swapchain is no longer configured
optimally for the surface it targets.
Applications should query updated surface information and recreate
their swapchain at the next convenient opportunity.
* ename:VK_SUBOPTIMAL_KHR - Presentation will still succeed, subject to
the window resize behavior, but the swapchain is no longer configured
optimally for the surface it targets.
Applications should query updated surface information and recreate their
swapchain at the next convenient opportunity.
* ename:VK_ERROR_OUT_OF_DATE_KHR - Failure.
The swapchain is no longer compatible with the surface it targets.
The application must query updated surface information and recreate the
swapchain before presentation will succeed.
VK_ERROR_OUT_OF_DATE_KHR - Failure.
The swapchain is no longer compatible with the surface it targets.
The application must query updated surface information and recreate
the swapchain before presentation will succeed.
These can be returned by both flink:vkAcquireNextImageKHR and
flink:vkQueuePresentKHR.
These can be returned by both vkAcquireNextImageKHR and
vkQueuePresentKHR.
10) Does the flink:vkAcquireNextImageKHR command return a semaphore to the
application via an output parameter, or accept a semaphore to signal from
the application as an object handle parameter?
10) Does the vkAcquireNextImageKHR command return a semaphore to the
application via an output parameter, or accept a semaphore to signal
from the application as an object handle parameter?
RESOLVED: Accept a semaphore to signal as an object handle.
This avoids the need to specify whether the application must destroy the
semaphore or whether it is owned by the swapchain, and if the latter,
what its lifetime is and whether it can be re-used for other operations
once it is received from vkAcquireNextImageKHR.
*RESOLVED*: Accept a semaphore to signal as an object handle.
This avoids the need to specify whether the application must destroy the
semaphore or whether it is owned by the swapchain, and if the latter, what
its lifetime is and whether it can be re-used for other operations once it
is received from flink:vkAcquireNextImageKHR.
11) What types of swapchain queuing behavior should be exposed? Options
include swap interval specification, mailbox/most recent Vs.
FIFO queue management, targeting specific vertical blank intervals or
absolute times for a given present operation, and probably others.
For some of these, whether they are specified at swapchain creation time
or as per-present parameters needs to be decided as well.
include swap interval specification, mailbox/most recent vs.
FIFO queue management, targeting specific vertical blank intervals or
absolute times for a given present operation, and probably others.
For some of these, whether they are specified at swapchain creation time or
as per-present parameters needs to be decided as well.
RESOLVED: The base swapchain extension will expose 3 possible behaviors
(of which, FIFO will always be supported):
*RESOLVED*: The base swapchain extension will expose 3 possible behaviors
(of which, FIFO will always be supported):
-Immediate present: Does not wait for vertical blanking period to
update the current image, likely resulting in visible tearing.
No internal queue is used.
Present requests are applied immediately.
- Immediate present: Does not wait for vertical blanking period to update
the current image, likely resulting in visible tearing.
No internal queue is used.
Present requests are applied immediately.
- Mailbox queue: Waits for the next vertical blanking period to update the
current image.
No tearing should be observed.
An internal single-entry queue is used to hold pending presentation
requests.
If the queue is full when a new presentation request is received, the
new request replaces the existing entry, and any images associated with
the prior entry become available for re-use by the application.
- FIFO queue: Waits for the next vertical blanking period to update the
current image.
No tearing should be observed.
An internal queue containing [eq]#pname:numSwapchainImages - 1# entries
is used to hold pending presentation requests.
New requests are appended to the end of the queue, and one request is
removed from the beginning of the queue and processed during each
vertical blanking period in which the queue is non-empty
-Mailbox queue: Waits for the next vertical blanking period to update
the current image.
No tearing should be observed.
An internal single-entry queue is used to hold pending presentation
requests.
If the queue is full when a new presentation request is received,
the new request replaces the existing entry, and any images
associated with the prior entry become available for re-use by the
application.
Not all surfaces will support all of these modes, so the modes supported
will be returned using a surface info query.
All surfaces must support the FIFO queue mode.
Applications must choose one of these modes up front when creating a
swapchain.
Switching modes can be accomplished by recreating the swapchain.
-FIFO queue: Waits for the next vertical blanking period to update
the current image.
No tearing should be observed.
An internal queue containing (numSwapchainImages - 1) entries is
used to hold pending presentation requests.
New requests are appended to the end of the queue, and one request
is removed from the beginning of the queue and processed during each
vertical blanking period in which the queue is non-empty
12) Can ename:VK_PRESENT_MODE_MAILBOX_KHR provide non-blocking guarantees
for flink:vkAcquireNextImageKHR? If so, what is the proper criteria?
Not all surfaces will support all of these modes, so the modes supported
will be returned using a surface info query.
All surfaces must support the FIFO queue mode.
Applications must choose one of these modes up front when creating a
swapchain.
Switching modes can be accomplished by recreating the swapchain.
12) Can VK_PRESENT_MODE_MAILBOX_KHR provide non-blocking guarantees for
vkAcquireNextImageKHR()? If so, what is the proper criteria?
RESOLVED: Yes.
The difficulty is not immediately obvious here.
Naively, if at least 3 images are requested, mailbox mode should always
have an image available for the application if the application does not
own any images when the call to vkAcquireNextImageKHR() was made.
However, some presentation engines may have more than one "current"
image, and would still need to block in some cases.
The right requirement appears to be that if the application allocates
the surface's minimum number of images + 1 then it is guaranteed
non-blocking behavior when it does not currently own any images.
*RESOLVED*: Yes.
The difficulty is not immediately obvious here.
Naively, if at least 3 images are requested, mailbox mode should always have
an image available for the application if the application does not own any
images when the call to flink:vkAcquireNextImageKHR was made.
However, some presentation engines may have more than one ``current'' image,
and would still need to block in some cases.
The right requirement appears to be that if the application allocates the
surface's minimum number of images + 1 then it is guaranteed non-blocking
behavior when it does not currently own any images.
13) Is there a way to create and initialize a new swapchain for a surface
that has generated a VK_SUBOPTIMAL_KHR return code while still using the
old swapchain?
that has generated a ename:VK_SUBOPTIMAL_KHR return code while still using
the old swapchain?
RESOLVED: Not as part of this specification.
This could be useful to allow the application to create an "optimal"
replacement swapchain and rebuild all its command buffers using it in a
background thread at a low priority while continuing to use the
"suboptimal" swapchain in the main thread.
It could probably use the same "atomic replace" semantics proposed for
recreating direct-to-device swapchains without incurring a mode switch.
However, after discussion, it was determined some platforms probably
could not support concurrent swapchains for the same surface though, so
this will be left out of the base KHR extensions.
A future extension could add this for platforms where it is supported.
*RESOLVED*: Not as part of this specification.
This could be useful to allow the application to create an ``optimal''
replacement swapchain and rebuild all its command buffers using it in a
background thread at a low priority while continuing to use the
``suboptimal'' swapchain in the main thread.
It could probably use the same ``atomic replace'' semantics proposed for
recreating direct-to-device swapchains without incurring a mode switch.
However, after discussion, it was determined some platforms probably could
not support concurrent swapchains for the same surface though, so this will
be left out of the base KHR extensions.
A future extension could add this for platforms where it is supported.
14) Should there be a special value for
VkSurfacePropertiesKHR::maxImageCount to indicate there are no practical
limits on the number of images in a swapchain?
slink:VkSurfacePropertiesKHR::pname:maxImageCount to indicate there are no
practical limits on the number of images in a swapchain?
RESOLVED: Yes.
There where often be cases where there is no practical limit to the
number of images in a swapchain other than the amount of available
resources (I.e., memory) in the system.
Trying to derive a hard limit from things like memory size is prone to
failure.
It is better in such cases to leave it to applications to figure such
soft limits out via trial/failure iterations.
*RESOLVED*: Yes.
There where often be cases where there is no practical limit to the number
of images in a swapchain other than the amount of available resources (I.e.,
memory) in the system.
Trying to derive a hard limit from things like memory size is prone to
failure.
It is better in such cases to leave it to applications to figure such soft
limits out via trial/failure iterations.
15) Should there be a special value for
VkSurfacePropertiesKHR::currentExtent to indicate the size of the
platform surface is undefined?
slink:VkSurfacePropertiesKHR::pname:currentExtent to indicate the size of
the platform surface is undefined?
RESOLVED: Yes.
On some platforms (Wayland, for example), the surface size is defined by
the images presented to it rather than the other way around.
*RESOLVED*: Yes.
On some platforms (Wayland, for example), the surface size is defined by the
images presented to it rather than the other way around.
16) Should there be a special value for
VkSurfacePropertiesKHR::maxImageExtent to indicate there is no practical
limit on the surface size?
slink:VkSurfacePropertiesKHR::pname:maxImageExtent to indicate there is no
practical limit on the surface size?
RESOLVED: No.
It seems unlikely such a system would exist.
0 could be used to indicate the platform places no limits on the extents
beyond those imposed by Vulkan for normal images, but this query could
just as easily return those same limits, so a special "unlimited" value
does not seem useful for this field.
*RESOLVED*: No.
It seems unlikely such a system would exist.
0 could be used to indicate the platform places no limits on the extents
beyond those imposed by Vulkan for normal images, but this query could just
as easily return those same limits, so a special ``unlimited'' value does
not seem useful for this field.
17) How should surface rotation and mirroring be exposed to applications?
How do they specify rotation and mirroring transforms applied prior to
presentation?
How do they specify rotation and mirroring transforms applied prior to
presentation?
RESOLVED: Applications can query both the supported and current
transforms of a surface.
Both are specified relative to the device's "natural" display rotation
and direction.
The supported transforms indicates which orientations the presentation
engine accepts images in.
For example, a presentation engine that does not support transforming
surfaces as part of presentation, and which is presenting to a surface
that is displayed with a 90-degree rotation, would return only one
supported transform bit: VK_SURFACE_TRANSFORM_ROT90_BIT_KHR.
Applications must transform their rendering by the transform they
specify when creating the swapchain in preTransform field.
*RESOLVED*: Applications can query both the supported and current transforms
of a surface.
Both are specified relative to the device's ``natural'' display rotation and
direction.
The supported transforms indicates which orientations the presentation
engine accepts images in.
For example, a presentation engine that does not support transforming
surfaces as part of presentation, and which is presenting to a surface that
is displayed with a 90-degree rotation, would return only one supported
transform bit: ename:VK_SURFACE_TRANSFORM_ROT90_BIT_KHR.
Applications must transform their rendering by the transform they specify
when creating the swapchain in preTransform field.
18) Can surfaces ever not support VK_MIRROR_NONE? Can they support vertical
and horizontal mirroring simultaneously? Relatedly, should
VK_MIRROR_NONE[_BIT] be zero, or bit one, and should applications be
allowed to specify multiple pre and current mirror transform bits, or
exactly one?
18) Can surfaces ever not support ename:VK_MIRROR_NONE? Can they support
vertical and horizontal mirroring simultaneously? Relatedly, should
etext:VK_MIRROR_NONE[_BIT] be zero, or bit one, and should applications be
allowed to specify multiple pre and current mirror transform bits, or
exactly one?
RESOLVED: Since some platforms may not support presenting with a
transform other than the native window's current transform, and
prerotation/mirroring are specified relative to the device's natural
rotation and direction, rather than relative to the surface's current
rotation and direction, it is necessary to express lack of support for
no mirroring.
To allow this, the MIRROR_NONE enum must occupy a bit in the flags.
Since MIRROR_NONE must be a bit in the bitmask rather than a bitmask
with no values set, allowing more than one bit to be set in the bitmask
would make it possible to describe undefined transforms such as
VK_MIRROR_NONE_BIT | VK_MIRROR_HORIZONTAL_BIT, or a transform that
includes both "no mirroring" and "horizontal mirroring simultaneously.
Therefore, it is desirable to allow specifying all supported mirroring
transforms using only one bit.
The question then becomes, should there be a
VK_MIRROR_HORIZONTAL_AND_VERTICAL_BIT to represent a simultaneous
horizontal and vertical mirror transform? However, such a transform is
equivalent to a 180 degree rotation, so presentation engines and
applications that wish to support or use such a transform can express it
through rotation instead.
Therefore, 3 exclusive bits are sufficient to express all needed
mirroring transforms.
*RESOLVED*: Since some platforms may not support presenting with a transform
other than the native window's current transform, and prerotation/mirroring
are specified relative to the device's natural rotation and direction,
rather than relative to the surface's current rotation and direction, it is
necessary to express lack of support for no mirroring.
To allow this, the etext:MIRROR_NONE enum must occupy a bit in the flags.
Since etext:MIRROR_NONE must be a bit in the bitmask rather than a bitmask
with no values set, allowing more than one bit to be set in the bitmask
would make it possible to describe undefined transforms such as
ename:VK_MIRROR_NONE_BIT | ename:VK_MIRROR_HORIZONTAL_BIT, or a transform
that includes both ``no mirroring'' and ``horizontal mirroring
simultaneously.
Therefore, it is desirable to allow specifying all supported mirroring
transforms using only one bit.
The question then becomes, should there be a
ename:VK_MIRROR_HORIZONTAL_AND_VERTICAL_BIT to represent a simultaneous
horizontal and vertical mirror transform? However, such a transform is
equivalent to a 180 degree rotation, so presentation engines and
applications that wish to support or use such a transform can express it
through rotation instead.
Therefore, 3 exclusive bits are sufficient to express all needed mirroring
transforms.
19) Should support for sRGB be required?
RESOLVED: In the advent of UHD and HDR display devices, proper color
space information is vital to the display pipeline represented by the
swapchain.
The app can discover the supported format/color-space pairs and select a
pair most suited to its rendering needs.
Currently only the sRGB color space is supported, future extensions may
provide support for more color spaces.
See issues 23) and 24).
*RESOLVED*: In the advent of UHD and HDR display devices, proper color space
information is vital to the display pipeline represented by the swapchain.
The app can discover the supported format/color-space pairs and select a
pair most suited to its rendering needs.
Currently only the sRGB color space is supported, future extensions may
provide support for more color spaces.
See issues 23 and 24.
20) Is there a mechanism to modify or replace an existing swapchain with one
targeting the same surface?
targeting the same surface?
RESOLVED: Yes.
This is described above in the text.
*RESOLVED*: Yes.
This is described above in the text.
21) Should there be a way to set prerotation and mirroring using native APIs
when presenting using a Vulkan swapchain?
when presenting using a Vulkan swapchain?
RESOLVED: Yes.
The transforms that can be expressed in this extension are a subset of
those possible on native platforms.
If a platform exposes a method to specify the transform of presented
images for a given surface using native methods and exposes more
transforms or other properties for surfaces than Vulkan supports, it
might be impossible, difficult, or inconvenient to set some of those
properties using Vulkan KHR extensions and some using the native
interfaces.
To avoid overwriting properties set using native commands when
presenting using a Vulkan swapchain, the application can set the
pretransform to "inherit", in which case the current native properties
will be used, or if none are available, a platform-specific default will
be used.
Platforms that do not specify a reasonable default or do not provide
native mechanisms to specify such transforms should not include the
inherit bits in the supportedTransform bitmask they return in
VkSurfacePropertiesKHR.
*RESOLVED*: Yes.
The transforms that can be expressed in this extension are a subset of those
possible on native platforms.
If a platform exposes a method to specify the transform of presented images
for a given surface using native methods and exposes more transforms or
other properties for surfaces than Vulkan supports, it might be impossible,
difficult, or inconvenient to set some of those properties using Vulkan KHR
extensions and some using the native interfaces.
To avoid overwriting properties set using native commands when presenting
using a Vulkan swapchain, the application can set the pretransform to
``inherit'', in which case the current native properties will be used, or if
none are available, a platform-specific default will be used.
Platforms that do not specify a reasonable default or do not provide native
mechanisms to specify such transforms should not include the inherit bits in
the supportedTransform bitmask they return in slink:VkSurfacePropertiesKHR.
22) Should the content of presentable images be clipped by objects obscuring
their target surface?
their target surface?
RESOLVED: Applications can choose which behavior they prefer.
Allowing the content to be clipped could enable more optimal
presentation methods on some platforms, but some applications might rely
on the content of presentable images to perform techniques such as
partial updates or motion blurs.
*RESOLVED*: Applications can choose which behavior they prefer.
Allowing the content to be clipped could enable more optimal presentation
methods on some platforms, but some applications might rely on the content
of presentable images to perform techniques such as partial updates or
motion blurs.
23) What is the purpose of specifying a VkColorSpaceKHR along with VkFormat
when creating a swapchain?
23) What is the purpose of specifying a slink:VkColorSpaceKHR along with
slink:VkFormat when creating a swapchain?
RESOLVED: While Vulkan itself is color space agnostic (e.g. even the
meaning of R, G, B and A can be freely defined by the rendering
application), the swapchain eventually will have to present the images
on a display device with specific color reproduction characteristics.
If any color space transformations are necessary before an image can be
displayed, the color space of the presented image must be known to the
swapchain.
A swapchain will only support a restricted set of color format and
-space pairs.
This set can be discovered via vkGetSurfaceInfoKHR.
As it can be expected that most display devices support the sRGB color
space, at least one format/color-space pair has to be exposed, where the
color space is VK_COLOR_SPACE_SRGB_NONLINEAR.
*RESOLVED*: While Vulkan itself is color space agnostic (e.g. even the
meaning of R, G, B and A can be freely defined by the rendering
application), the swapchain eventually will have to present the images on a
display device with specific color reproduction characteristics.
If any color space transformations are necessary before an image can be
displayed, the color space of the presented image must be known to the
swapchain.
A swapchain will only support a restricted set of color format and -space
pairs.
This set can be discovered via flink:vkGetSurfaceInfoKHR.
As it can be expected that most display devices support the sRGB color
space, at least one format/color-space pair has to be exposed, where the
color space is ename:VK_COLOR_SPACE_SRGB_NONLINEAR.
24) How are sRGB formats and the sRGB color space related?
RESOLVED: While Vulkan exposes a number of SRGB texture formats, using
such formats does not guarantee working in a specific color space.
It merely means that the hardware can directly support applying the
non-linear transfer functions defined by the sRGB standard color space
when reading from or writing to images of that these formats.
Still, it is unlikely that a swapchain will expose a _SRGB format along
with any color space other than VK_COLOR_SPACE_SRGB_NONLINEAR.
*RESOLVED*: While Vulkan exposes a number of SRGB texture formats, using
such formats does not guarantee working in a specific color space.
It merely means that the hardware can directly support applying the
non-linear transfer functions defined by the sRGB standard color space when
reading from or writing to images of that these formats.
Still, it is unlikely that a swapchain will expose a _SRGB format along with
any color space other than ename:VK_COLOR_SPACE_SRGB_NONLINEAR.
On the other hand, non-_SRGB formats will be very likely exposed in pair
with a SRGB color space.
This means, the hardware will not apply any transfer function when
reading from or writing to such images, yet they will still be presented
on a device with sRGB display characteristics.
In this case the application is responsible for applying the transfer
function, for instance by using shader math.
On the other hand, non-_SRGB formats will be very likely exposed in pair
with a SRGB color space.
This means, the hardware will not apply any transfer function when reading
from or writing to such images, yet they will still be presented on a device
with sRGB display characteristics.
In this case the application is responsible for applying the transfer
function, for instance by using shader math.
25) How are the lifetime of surfaces and swapchains targeting them related?
RESOLVED: A surface must outlive any swapchains targeting it.
A VkSurfaceKHR owns the binding of the native window to the Vulkan
driver.
*RESOLVED*: A surface must outlive any swapchains targeting it.
A slink:VkSurfaceKHR owns the binding of the native window to the Vulkan
driver.
26) How can the client control the way the alpha channel of swap chain
images is treated by the presentation engine during compositing?
images is treated by the presentation engine during compositing?
RESOLVED: We should add new enum values to allow the client to negotiate
with the presentation engine on how to treat image alpha values during
the compositing process.
Since not all platforms can practically control this through the Vulkan
driver, a value of INHERIT is provided like for surface transforms.
*RESOLVED*: We should add new enum values to allow the client to negotiate
with the presentation engine on how to treat image alpha values during the
compositing process.
Since not all platforms can practically control this through the Vulkan
driver, a value of INHERIT is provided like for surface transforms.
27) Is vkCreateSwapchainKHR() the right function to return
VK_ERROR_NATIVE_WINDOW_IN_USE_KHR, or should the various platform-
specific VkSurface factory functions catch this error earlier?
27) Is flink:vkCreateSwapchainKHR the right function to return
ename:VK_ERROR_NATIVE_WINDOW_IN_USE_KHR, or should the various
platform-specific slink:VkSurface factory functions catch this error
earlier?
RESOLVED: For most platforms, the VkSurface structure is a simple
container holding the data that identifies a native window or other
object representing a surface on a particular platform.
For the surface factory functions to return this error, they would
likely need to register a reference on the native objects with the
native display server some how, and ensure no other such references
exist.
Surfaces were not intended to be that heavy- weight.
*RESOLVED*: For most platforms, the slink:VkSurface structure is a simple
container holding the data that identifies a native window or other object
representing a surface on a particular platform.
For the surface factory functions to return this error, they would likely
need to register a reference on the native objects with the native display
server some how, and ensure no other such references exist.
Surfaces were not intended to be that heavy-weight.
Swapchains are intended to be the objects that directly manipulate
native windows and communicate with the native presentation mechanisms.
Swapchains will already need to communicate with the native display
server to negotiate allocation and/or presentation of presentable images
for a native surface.
Therefore, it makes more sense for swapchain creation to be the point at
which native object exclusivity is enforced.
Platforms may choose to enforce further restrictions on the number of
VkSurface objects that may be created for the same native window if such
a requirement makes sense on a particular platform, but a global
requirement is only sensible at the swapchain level.
Swapchains are intended to be the objects that directly manipulate native
windows and communicate with the native presentation mechanisms.
Swapchains will already need to communicate with the native display server
to negotiate allocation and/or presentation of presentable images for a
native surface.
Therefore, it makes more sense for swapchain creation to be the point at
which native object exclusivity is enforced.
Platforms may choose to enforce further restrictions on the number of
slink:VkSurface objects that may be created for the same native window if
such a requirement makes sense on a particular platform, but a global
requirement is only sensible at the swapchain level.
=== Examples

20
doc/specs/vulkan/appendices/VK_KHR_wayland_surface/vk_khr_wayland_surface.txt
View File

@ -1,4 +1,4 @@
// Copyright (c) 2014-2016 The Khronos Group Inc.
// Copyright (c) 2014-2017 The Khronos Group Inc.
// Copyright notice at https://www.khronos.org/registry/speccopyright.html
[[VK_KHR_wayland_surface]]
@ -42,7 +42,7 @@
The +VK_KHR_wayland_surface+ extension is an instance extension.
It provides a mechanism to create a sname:VkSurfaceKHR object (defined by
It provides a mechanism to create a slink:VkSurfaceKHR object (defined by
the +VK_KHR_surface+ extension) that refers to a Wayland code:wl_surface, as
well as a query to determine support for rendering to the windows desktop.
@ -71,15 +71,15 @@ None
=== Issues
1) Does Wayland need a way to query for compatibility between a particular
physical device and a specific Wayland display? This would be a more
general query than vkGetPhysicalDeviceSurfaceSupportKHR: if the Wayland-
specific query returned true for a (VkPhysicalDevice, struct wl_display*)
pair, then the physical device could be assumed to support presentation
to any VkSurface for surfaces on the display.
physical device and a specific Wayland display? This would be a more general
query than flink:vkGetPhysicalDeviceSurfaceSupportKHR: if the
Wayland-specific query returned true for a (slink:VkPhysicalDevice, struct
wl_display*) pair, then the physical device could be assumed to support
presentation to any slink:VkSurface for surfaces on the display.
RESOLVED: Yes.
vkGetPhysicalDeviceWaylandPresentationSupportKHR() was added to address
this issue.
*RESOLVED*: Yes.
flink:vkGetPhysicalDeviceWaylandPresentationSupportKHR was added to address
this issue.
=== Version History

21
doc/specs/vulkan/appendices/VK_KHR_win32_surface/vk_khr_win32_surface.txt
View File

@ -1,4 +1,4 @@
// Copyright (c) 2014-2016 The Khronos Group Inc.
// Copyright (c) 2014-2017 The Khronos Group Inc.
// Copyright notice at https://www.khronos.org/registry/speccopyright.html
[[VK_KHR_win32_surface]]
@ -42,7 +42,7 @@
The +VK_KHR_win32_surface+ extension is an instance extension.
It provides a mechanism to create a sname:VkSurfaceKHR object (defined by
It provides a mechanism to create a slink:VkSurfaceKHR object (defined by
the +VK_KHR_surface+ extension) that refers to a Win32 code:HWND, as well as
a query to determine support for rendering to the windows desktop.
@ -71,16 +71,15 @@ None
=== Issues
1) Does Win32 need a way to query for compatibility between a particular
physical device and a specific screen? Compatibility between a physical
device and a window generally only depends on what screen the window is
on.
However, there is not an obvious way to identify a screen without already
having a window on the screen.
physical device and a specific screen? Compatibility between a physical
device and a window generally only depends on what screen the window is on.
However, there is not an obvious way to identify a screen without already
having a window on the screen.
RESOLVED: No.
While it may be useful, there is not a clear way to do this on Win32.
However, a method was added to query support for presenting to the
windows desktop as a whole.
*RESOLVED*: No.
While it may be useful, there is not a clear way to do this on Win32.
However, a method was added to query support for presenting to the windows
desktop as a whole.
=== Version History

22
doc/specs/vulkan/appendices/VK_KHR_xcb_surface/vk_khr_xcb_surface.txt
View File

@ -1,4 +1,4 @@
// Copyright (c) 2014-2016 The Khronos Group Inc.
// Copyright (c) 2014-2017 The Khronos Group Inc.
// Copyright notice at https://www.khronos.org/registry/speccopyright.html
[[VK_KHR_xcb_surface]]
@ -18,7 +18,7 @@
No known IP claims.
*Dependencies*::
- This extension is written against version 1.0 of the Vulkan API.
- This extension requires +VK_KHR_surface+.
- Requires +VK_KHR_surface+.
*Contributors*::
- Patrick Doane, Blizzard
- Jason Ekstrand, Intel
@ -42,7 +42,7 @@
The +VK_KHR_xcb_surface+ extension is an instance extension.
It provides a mechanism to create a sname:VkSurfaceKHR object (defined by
It provides a mechanism to create a slink:VkSurfaceKHR object (defined by
the +VK_KHR_surface extension+) that refers to an X11 code:Window, using the
XCB client-side library, as well as a query to determine support for
rendering via XCB.
@ -72,15 +72,15 @@ None
=== Issues
1) Does XCB need a way to query for compatibility between a particular
physical device and a specific screen? This would be a more general query
than vkGetPhysicalDeviceSurfaceSupportKHR: If it returned true, then the
physical device could be assumed to support presentation to any window on
that screen.
physical device and a specific screen? This would be a more general query
than flink:vkGetPhysicalDeviceSurfaceSupportKHR: If it returned true, then
the physical device could be assumed to support presentation to any window
on that screen.
RESOLVED: Yes, this is needed for toolkits that want to create a VkDevice
before creating a window.
To ensure the query is reliable, it must be made against a particular X
visual rather than the screen in general.
*RESOLVED*: Yes, this is needed for toolkits that want to create a
slink:VkDevice before creating a window.
To ensure the query is reliable, it must be made against a particular X
visual rather than the screen in general.
=== Version History

22
doc/specs/vulkan/appendices/VK_KHR_xlib_surface/vk_khr_xlib_surface.txt
View File

@ -1,4 +1,4 @@
// Copyright (c) 2014-2016 The Khronos Group Inc.
// Copyright (c) 2014-2017 The Khronos Group Inc.
// Copyright notice at https://www.khronos.org/registry/speccopyright.html
[[VK_KHR_xlib_surface]]
@ -18,7 +18,7 @@
No known IP claims.
*Dependencies*::
- This extension is written against version 1.0 of the Vulkan API.
- This extension requires +VK_KHR_surface+.
- Requires +VK_KHR_surface+.
*Contributors*::
- Patrick Doane, Blizzard
- Jason Ekstrand, Intel
@ -42,7 +42,7 @@
The +VK_KHR_xlib_surface+ extension is an instance extension.
It provides a mechanism to create a sname:VkSurfaceKHR object (defined by
It provides a mechanism to create a slink:VkSurfaceKHR object (defined by
the +VK_KHR_surface+ extension) that refers to an X11 code:Window, using the
Xlib client-side library, as well as a query to determine support for
rendering via Xlib.
@ -72,15 +72,15 @@ None
=== Issues
1) Does X11 need a way to query for compatibility between a particular
physical device and a specific screen? This would be a more general query
than vkGetPhysicalDeviceSurfaceSupportKHR: If it returned true, then the
physical device could be assumed to support presentation to any window on
that screen.
physical device and a specific screen? This would be a more general query
than flink:vkGetPhysicalDeviceSurfaceSupportKHR : if it returned true, then
the physical device could be assumed to support presentation to any window
on that screen.
RESOLVED: Yes, this is needed for toolkits that want to create a VkDevice
before creating a window.
To ensure the query is reliable, it must be made against a particular X
visual rather than the screen in general.
*RESOLVED*: Yes, this is needed for toolkits that want to create a
slink:VkDevice before creating a window.
To ensure the query is reliable, it must be made against a particular X
visual rather than the screen in general.
=== Version History

77
doc/specs/vulkan/appendices/VK_NN_vi_surface/vk_nn_vi_surface.txt Normal file
View File

@ -0,0 +1,77 @@
[[VK_NN_vi_surface]]
== VK_NN_vi_surface
*Name String*::
+VK_NN_vi_surface+
*Extension Type*::
Instance extension
*Registered Extension Number*::
63
*Last Modified Date*::
2016-12-2
*Revision*::
1
*IP Status*::
No known IP claims.
*Dependencies*::
- This extension is written against version 1.0 of the Vulkan API.
- Requires +VK_KHR_surface+.
*Contributors*::
- Mathias Heyer, NVIDIA
- Michael Chock, NVIDIA
- Yasuhiro Yoshioka, Nintendo
- Daniel Koch, NVIDIA
*Contacts*::
- Mathias Heyer, NVIDIA
The +VK_NN_vi_surface+ extension is an instance extension.
It provides a mechanism to create a slink:VkSurfaceKHR object (defined by
the +VK_KHR_surface+ extension) associated with an
code:nn::code:vi::code:Layer.
=== New Object Types
None
=== New Enum Constants
* Extending ename:VkStructureType:
** ename:VK_STRUCTURE_TYPE_VI_SURFACE_CREATE_INFO_NN
=== New Enums
None
=== New Structures
* slink:VkViSurfaceCreateInfoNN
=== New Functions
* flink:vkCreateViSurfaceNN
=== Issues
1) Does VI need a way to query for compatibility between a particular
physical device (and queue family?) and a specific VI display?
*RESOLVED*: No.
It is currently always assumed that the device and display will always be
compatible.
2) slink:VkViSurfaceCreateInfoNN::pname:pWindow is intended to store an
code:nn::code:vi::code:NativeWindowHandle, but its declared type is a bare
code:void* to store the window handle.
Why the discrepancy?
*RESOLVED*: It is for C compatibility.
The definition for the VI native window handle type is defined inside the
nn::vi C++ namespace.
This prevents its use in C source files.
nn::vi::NativeWindowHandle is always defined to be void*, so this
extension uses void* to match.
=== Version History
* Revision 1, 2016-12-2 (Michael Chock)
- Initial draft.

285
doc/specs/vulkan/appendices/VK_NVX_device_generated_commands.txt
View File

@ -12,19 +12,18 @@
*Revision*::
1
*Dependencies*::
- This extension is written against version 1.0 of the Vulkan API.
- This extension is written against version 1.0 of the Vulkan API.
*Contributors*::
- Pierre Boudier, NVIDIA
- Christoph Kubisch, NVIDIA
- Mathias Schott, NVIDIA
- Jeff Bolz, NVIDIA
- Eric Werness, NVIDIA
- Detlef Roettger, NVIDIA
- Daniel Koch, NVIDIA
- Pierre Boudier, NVIDIA
- Christoph Kubisch, NVIDIA
- Mathias Schott, NVIDIA
- Jeff Bolz, NVIDIA
- Eric Werness, NVIDIA
- Detlef Roettger, NVIDIA
- Daniel Koch, NVIDIA
*Contacts*::
- Pierre Boudier, NVIDIA (pboudier@nvidia.com)
- Christoph Kubisch, NVIDIA (ckubisch@nvidia.com)
- Pierre Boudier, NVIDIA (pboudier@nvidia.com)
- Christoph Kubisch, NVIDIA (ckubisch@nvidia.com)
This extension allows the device to generate a number of critical commands
for command buffers.
@ -54,11 +53,11 @@ scenario, or updates synchronized on the host.
The intended usage for this extension is for the application to:
* create its objects as in unextended Vulkan
* create a VkObjectTableNVX, and register the various Vulkan objects that
are needed to evaluate the input parameters.
* create a VkIndirectCommandsLayoutNVX, which lists the
VkIndirectCommandsTokenTypes it wants to dynamically change as atomic
command sequence.
* create a slink:VkObjectTableNVX, and register the various Vulkan objects
that are needed to evaluate the input parameters.
* create a slink:VkIndirectCommandsLayoutNVX, which lists the
slink:VkIndirectCommandsTokenTypes it wants to dynamically change as
atomic command sequence.
This step likely involves some internal device code compilation, since
the intent is for the GPU to generate the command buffer in the
pipeline.
@ -66,12 +65,12 @@ The intended usage for this extension is for the application to:
Each input is an array that will be filled with an index in the object
table, instead of using CPU pointers.
* set up a target secondary command buffer
* reserve command buffer space via vkCmdReserveSpaceForCommandsNVX in a
target command buffer at the position you want the generated commands to
be executed.
* call vkCmdProcessCommandsNVX to create the actual device commands for
all sequences based on the array contents into a provided target command
buffer.
* reserve command buffer space via flink:vkCmdReserveSpaceForCommandsNVX
in a target command buffer at the position you want the generated
commands to be executed.
* call flink:vkCmdProcessCommandsNVX to create the actual device commands
for all sequences based on the array contents into a provided target
command buffer.
* execute the target command buffer like a regular secondary command
buffer
@ -86,19 +85,19 @@ It is recommended to register a small number of objects and to use dynamic
offsets whenever possible.
While the GPU can be faster than a CPU to generate the commands, it may not
happen asynchronously, therefore the primary use-case is generating "less"
happen asynchronously, therefore the primary use-case is generating ``less''
total work (occlusion culling, classification to use specialized
shaders...).
=== New Object Types
* sname:VkObjectTableNVX
* sname:VkIndirectCommandsLayoutNVX
* slink:VkObjectTableNVX
* slink:VkIndirectCommandsLayoutNVX
=== New Flag Types
* sname:VkIndirectCommandsLayoutUsageFlagsNVX
* sname:VkObjectEntryUsageFlagsNVX
* elink:VkIndirectCommandsLayoutUsageFlagsNVX
* elink:VkObjectEntryUsageFlagsNVX
=== New Enum Constants
@ -115,6 +114,11 @@ Extending elink:VkPipelineStageFlagBits:
** ename:VK_PIPELINE_STAGE_COMMAND_PROCESS_BIT_NVX
Extending elink:VkAccessFlagBits:
** ename:VK_ACCESS_COMMAND_PROCESS_READ_BIT_NVX
** ename:VK_ACCESS_COMMAND_PROCESS_WRITE_BIT_NVX
=== New Enums
* elink:VkIndirectCommandsLayoutUsageFlagBitsNVX
@ -155,199 +159,206 @@ Extending elink:VkPipelineStageFlagBits:
1) How to name this extension ?
As usual one of the hardest issues ;)
*RESOLVED*: +VK_NVX_device_generated_commands+
VK_gpu_commands VK_execute_commands VK_device_commands
VK_device_execute_commands VK_device_execute VK_device_created_commands
VK_device_recorded_commands VK_device_generated_commands
As usual one of the hardest issues ;)
VK_gpu_commands VK_execute_commands VK_device_commands
VK_device_execute_commands VK_device_execute VK_device_created_commands
VK_device_recorded_commands VK_device_generated_commands
2) Should we use serial tokens or redundant sequence description?
Similar to VkPipeline, signatures have the most likeliness to be
cross-vendor adoptable.
They also benefit from being processable in parallel.
Similar to slink:VkPipeline, signatures have the most likeliness to be
cross-vendor adoptable.
They also benefit from being processable in parallel.
3) How to name sequence description
ExecuteCommandSignature a bit long, just ExecuteSignature or actually more
Vulkan nomenclature IndirectCommandsLayout
ExecuteCommandSignature a bit long, just ExecuteSignature or actually more
Vulkan nomenclature IndirectCommandsLayout
4) Do we want to provide indirectCommands inputs with layout or at
indirectCommands time?
Separate layout from data as Vulkan does.
Provide full flexibilty for indirectCommands.
Separate layout from data as Vulkan does.
Provide full flexibilty for indirectCommands.
5) Should the input be provided as SoA or AoS?
It is desired by application to reuse the list of objects and render them
with some kind override.
This can be done by just selecting a different input for a push constant
or a descriptor set, if they are defined as independent arrays.
If the data was interleaved, this would not be as easily possible.
It is desired by application to reuse the list of objects and render them
with some kind override.
This can be done by just selecting a different input for a push constant or
a descriptor set, if they are defined as independent arrays.
If the data was interleaved, this would not be as easily possible.
Allowing input divisors can also reduce the conservative command buffer
allocation.
Allowing input divisors can also reduce the conservative command buffer
allocation.
6) how do we know the size of the GPU command buffer generated by
vkCmdProcessCommandsNVX ?
6) How do we know the size of the GPU command buffer generated by
flink:vkCmdProcessCommandsNVX ?
maxSequenceCount can give an upper estimate, even if the actual count is
sourced from the gpu buffer at (buffer, countOffset).
As such maxSequenceCount must always be set correctly.
pname:maxSequenceCount can give an upper estimate, even if the actual count
is sourced from the gpu buffer at (buffer, countOffset).
As such pname:maxSequenceCount must always be set correctly.
Developers are encouraged to make well use the IndirectCommandsLayout's
pTokens->divisor, as they allow less conservative storage costs.
Especially pipeline changes on a per-draw basis can be costly memory wise.
Developers are encouraged to make well use the IndirectCommandsLayout's
pname:pTokens->divisor, as they allow less conservative storage costs.
Especially pipeline changes on a per-draw basis can be costly memory wise.
7) How to deal with dynamic offsets in DescriptorSets?
Maybe additional token VK_EXECUTE_DESCRIPTOR_SET_OFFSET_COMMAND_NVX that
works for a "single dynamic buffer" descriptor set and then use (32 bit
tableEntry + 32bit offset)
Maybe additional token etext:VK_EXECUTE_DESCRIPTOR_SET_OFFSET_COMMAND_NVX
that works for a ``single dynamic buffer'' descriptor set and then use (32
bit tableEntry + 32bit offset)
added dynamicCount field, variable sized input
8) Should we allow updates to the object table, similar to DescriptorSet?
Desired yes, people may change "material" shaders and not want to recreate
the entire register table.
However the developer must ensure to not overwrite a registered
objectindex while it is still being used.
Desired yes, people may change ``material'' shaders and not want to recreate
the entire register table.
However the developer must ensure to not overwrite a registered objectindex
while it is still being used.
9) Should we allow dynamic state changes?
Seems a bit excessive for "per-draw" type of scenario, but GPU could
partition work itself with viewport/scissor...
Seems a bit excessive for ``per-draw'' type of scenario, but GPU could
partition work itself with viewport/scissor...
10) How do we allow re-using already "filled" indirectCommands buffers?
10) How do we allow re-using already ``filled'' indirectCommands buffers?
just use a VkCommandBuffer for the output, and it can be reused easily.
just use a slink:VkCommandBuffer for the output, and it can be reused
easily.
11) How portable should such re-use be?
Same as secondary command buffer
Same as secondary command buffer
12) Should sequenceOrdered be part of IndirectCommandsLayout or
vkCmdProcessCommandsNVX?
slink:vkCmdProcessCommandsNVX?
Seems better for IndirectCommandsLayout, as that is when most heavy
lifting in terms of internal device code generation is done.
Seems better for IndirectCommandsLayout, as that is when most heavy lifting
in terms of internal device code generation is done.
13) Under which conditions is vkCmdProcessCommandsNVX legal?
13) Under which conditions is flink:vkCmdProcessCommandsNVX legal?
Options: a) on the host command buffer like a regular draw call b)
vkCmdProcessCommandsNVX makes use VkCommandBufferBeginInfo and serves
as vkBeginCommandBuffer/vkEndCommandBuffer implicitly.
c) The targetCommandbuffer must be inside the "begin" state already at the
moment of being passed.
This very likely suggests a new VkCommandBufferUsageFlags
VK_COMMAND_BUFFER_USAGE_DEVICE_GENERATED_BIT.
Options:
a) on the host command buffer like a regular draw call b)
flink:vkCmdProcessCommandsNVX makes use slink:VkCommandBufferBeginInfo
and serves as flink:vkBeginCommandBuffer / flink:vkEndCommandBuffer
implicitly.
c) The targetCommandbuffer must be inside the ``begin'' state already at
the moment of being passed.
This very likely suggests a new slink:VkCommandBufferUsageFlags
etext:VK_COMMAND_BUFFER_USAGE_DEVICE_GENERATED_BIT.
d) The targetCommandbuffer must reserve space via a new function.
used a & d.
used a & d.
14) What if different pipelines have different DescriptorSetLayouts at a
certain set unit that mismatches in "token.dynamicCount"?
certain set unit that mismatches in ``token.dynamicCount''?
Considered legal, as long as the maximum dynamic count of all used
DescriptorSetLayouts is provided.
Considered legal, as long as the maximum dynamic count of all used
DescriptorSetLayouts is provided.
15) Should we add "strides" to input arrays, so that "Array of Structures"
type setups can be support more easily?
15) Should we add ``strides'' to input arrays, so that ``Array of
Structures'' type setups can be support more easily?
Maybe provide a usage flag for packed tokens stream (all inputs from same
buffer, implicit stride).
Maybe provide a usage flag for packed tokens stream (all inputs from same
buffer, implicit stride).
No, given performance test was worse.
No, given performance test was worse.
16) Should we allow re-using the target command buffer directly, without
need to reset command buffer?
YES: new api vkCmdReserveSpaceForCommandsNVX.
YES: new api flink:vkCmdReserveSpaceForCommandsNVX.
17) Is vkCmdProcessCommandsNVX copying the input data or referencing it ?
17) Is flink:vkCmdProcessCommandsNVX copying the input data or referencing
it ?
There are multiple implementations possible:
There are multiple implementations possible:
* one could have some emulation code that parse the inputs, and generates
an output command buffer, therefore copying the inputs.
* one could just reference the inputs, and have the processing done in
pipe at execution time.
If the data is mandated to be copied, then it puts a penalty on
implementation that could process the inputs directly in pipe.
If the data is "referenced", then it allows both types of implementation
If the data is mandated to be copied, then it puts a penalty on
implementation that could process the inputs directly in pipe.
If the data is ``referenced'', then it allows both types of implementation
The inputs are "referenced", and should not be modified after the call to
vkCmdProcessCommands and until after the rendering of the target command
buffer is finished.
The inputs are ``referenced'', and should not be modified after the call to
flink:vkCmdProcessCommands and until after the rendering of the target
command buffer is finished.
18) Why is this NVX and not NV?
18) Why is this +NVX+ and not +NV+?
To allow early experimentation and feedback.
We expect that a version with a refined design as multi-vendor variant
will follow up.
To allow early experimentation and feedback.
We expect that a version with a refined design as multi-vendor variant will
follow up.
19) Should we make the availability for each token type a device limit?
Only distinguish between graphics/compute for now, further splitting up
may lead to too much fractioning.
Only distinguish between graphics/compute for now, further splitting up may
lead to too much fractioning.
20) When can the objectTable be modified?
Similar to the other inputs for vkCmdProcessCommandsNVX, only when all
device access via vkCmdProcessCommandsNVX or execution of target command
buffer has completed can an object at a given objectIndex be unregistered
or re-registered again.
Similar to the other inputs for flink:vkCmdProcessCommandsNVX, only when all
device access via flink:vkCmdProcessCommandsNVX or execution of target
command buffer has completed can an object at a given objectIndex be
unregistered or re-registered again.
21) Which buffer usage flags are required for the buffers referenced by
vkCmdProcessCommandsNVX
flink:vkCmdProcessCommandsNVX
reuse existing VK_BUFFER_USAGE_INDIRECT_BUFFER_BIT
reuse existing ename:VK_BUFFER_USAGE_INDIRECT_BUFFER_BIT
* VkCmdProcessCommandsInfoNVX::sequencesCountBuffer
* VkCmdProcessCommandsInfoNVX::sequencesIndexBuffer
* VkIndirectCommandsTokenNVX::buffer
* slink:VkCmdProcessCommandsInfoNVX::pname:sequencesCountBuffer
* slink:VkCmdProcessCommandsInfoNVX::pname:sequencesIndexBuffer
* slink:VkIndirectCommandsTokenNVX::pname:buffer
22) In which pipeline stage do the device generated command expansion
happen?
vkCmdProcessCommandsNVX is treated as if it occurs in a separate logical
pipeline from either graphics or compute, and that pipeline only includes
TOP_OF_PIPE, a new stage ename:VK_PIPELINE_STAGE_COMMAND_PROCESS_BIT, and
BOTTOM_OF_PIPE.
This new stage has two corresponding new access types,
ename:VK_ACCESS_COMMAND_PROCESS_READ_BIT_NVX and
ename:VK_ACCESS_COMMAND_PROCESS_WRITE_BIT_NVX, used to synchronize reading
the buffer inputs and writing the command buffer memory output.
The output written in the target command buffer is considered to be
consumed by the DRAW_INDIRECT pipeline stage.
flink:vkCmdProcessCommandsNVX is treated as if it occurs in a separate
logical pipeline from either graphics or compute, and that pipeline only
includes ename:VK_PIPELINE_STAGE_TOP_OF_PIPE_BIT, a new stage
ename:VK_PIPELINE_STAGE_COMMAND_PROCESS_BIT_NVX, and
ename:VK_PIPELINE_STAGE_BOTTOM_OF_PIPE_BIT.
This new stage has two corresponding new access types,
ename:VK_ACCESS_COMMAND_PROCESS_READ_BIT_NVX and
ename:VK_ACCESS_COMMAND_PROCESS_WRITE_BIT_NVX, used to synchronize reading
the buffer inputs and writing the command buffer memory output.
The output written in the target command buffer is considered to be consumed
by the DRAW_INDIRECT pipeline stage.
Thus, to synchronize from writing the input buffers to executing
flink:vkCmdProcessCommandsNVX, use:
Thus, to synchronize from writing the input buffers to executing
flink:vkCmdProcessCommandsNVX, use:
* dstStageMask = VK_PIPELINE_STAGE_COMMAND_PROCESS_BIT_NVX
* dstAccessMask = VK_ACCESS_COMMAND_PROCESS_READ_BIT_NVX
* pname:dstStageMask = ename:VK_PIPELINE_STAGE_COMMAND_PROCESS_BIT_NVX
* pname:dstAccessMask = ename:VK_ACCESS_COMMAND_PROCESS_READ_BIT_NVX
To synchronize from executing flink:vkCmdProcessCommandsNVX to executing
the generated commands, use
To synchronize from executing flink:vkCmdProcessCommandsNVX to executing the
generated commands, use
* srcStageMask = VK_PIPELINE_STAGE_COMMAND_PROCESS_BIT_NVX
* srcAccessMask = VK_ACCESS_COMMAND_PROCESS_WRITE_BIT_NVX
* dstStageMask = VK_PIPELINE_STAGE_DRAW_INDIRECT_BIT
* dstAccessMask = VK_ACCESS_INDIRECT_COMMAND_READ_BIT
* pname:srcStageMask = ename:VK_PIPELINE_STAGE_COMMAND_PROCESS_BIT_NVX
* pname:srcAccessMask = ename:VK_ACCESS_COMMAND_PROCESS_WRITE_BIT_NVX
* pname:dstStageMask = ename:VK_PIPELINE_STAGE_DRAW_INDIRECT_BIT
* pname:dstAccessMask = ename:VK_ACCESS_INDIRECT_COMMAND_READ_BIT
When flink:vkCmdProcessCommandsNVX is used with a
pname:targetCommandBuffer of `NULL`, the generated commands are
immediately executed and there is implicit synchronization between
generation and execution.
When flink:vkCmdProcessCommandsNVX is used with a pname:targetCommandBuffer
of `NULL`, the generated commands are immediately executed and there is
implicit synchronization between generation and execution.
23) What if most token data is "static", but we frequently want to render a
subsection?
23) What if most token data is ``static'', but we frequently want to render
a subsection?
added "sequencesIndexBuffer".
This allows to easier sort and filter what should actually be processed.
added ``sequencesIndexBuffer''.
This allows to easier sort and filter what should actually be processed.
=== Example Code

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

@ -16,12 +16,11 @@
*IP Status*::
No known IP claims.
*Dependencies*::
- This extension is written against version 1.0.
of the Vulkan API.
- This extension is written against version 1.0 of the Vulkan API.
*Contributors*::
- Jeff Bolz, NVIDIA
- Jeff Bolz, NVIDIA
*Contacts*::
- Jeff Bolz (jbolz 'at' nvidia.com)
- Jeff Bolz (jbolz 'at' nvidia.com)
This extension allows device memory to be allocated for a particular buffer
or image resource, which on some devices can significantly improve the

57
doc/specs/vulkan/appendices/VK_NV_external_memory.txt
View File

@ -16,13 +16,13 @@
*IP Status*::
No known IP claims.
*Dependencies*::
- This extension is written against version 1.0 of the Vulkan API.
- Requires +VK_NV_external_memory_capabilities+
- This extension is written against version 1.0 of the Vulkan API.
- Requires +VK_NV_external_memory_capabilities+.
*Contributors*::
- James Jones, NVIDIA
- Carsten Rohde, NVIDIA
- James Jones, NVIDIA
- Carsten Rohde, NVIDIA
*Contact*::
- James Jones (jajones 'at' nvidia.com)
- James Jones (jajones 'at' nvidia.com)
Applications may wish to export memory to other Vulkan instances or other
APIs, or import memory from other Vulkan instances or other APIs to enable
@ -61,35 +61,34 @@ None.
=== Issues
1) If memory objects are shared between processes and APIs, is this
considered aliasing according to the rules outlined in section 11.8,
Memory Aliasing?
considered aliasing according to the rules outlined in the
<<resources-memory-aliasing,Memory Aliasing>> section?
RESOLUTION: Yes, but strict exceptions to the rules are added to allow
some forms of aliasing in these cases.
Further, other extensions may build upon these new aliasing rules to
define specific support usage within Vulkan for imported native memory
objects, or memory objects from other APIs.
*RESOLVED*: Yes, but strict exceptions to the rules are added to allow some
forms of aliasing in these cases.
Further, other extensions may build upon these new aliasing rules to define
specific support usage within Vulkan for imported native memory objects, or
memory objects from other APIs.
2) Are new image layouts or metadata required to specify image layouts and
layout transitions compatible with non-Vulkan APIs, or with other
instances of the same Vulkan driver?
layout transitions compatible with non-Vulkan APIs, or with other instances
of the same Vulkan driver?
RESOLUTION: No.
Separate instances of the same Vulkan driver running on the same GPU
should have identical internal layout semantics, so applictions have the
tools they need to ensure views of images are consistent between the two
instances.
Other APIs will fall into two categories: Those that are Vulkan-
compatible (A term to be defined by subsequent interopability
extensions), or Vulkan incompatible.
When sharing images with Vulkan incompatible APIs, the Vulkan image must
be transitioned to the GENERAL layout before handing it off to the
external API.
*RESOLVED*: No.
Separate instances of the same Vulkan driver running on the same GPU should
have identical internal layout semantics, so applictions have the tools they
need to ensure views of images are consistent between the two instances.
Other APIs will fall into two categories: Those that are Vulkan compatible
(A term to be defined by subsequent interopability extensions), or Vulkan
incompatible.
When sharing images with Vulkan incompatible APIs, the Vulkan image must be
transitioned to the GENERAL layout before handing it off to the external
API.
Note this does not attempt to address cross-device transitions, nor
transitions to engines on the same device which are not visible within
the Vulkan API.
Both of these are beyond the scope of this extension.
Note this does not attempt to address cross-device transitions, nor
transitions to engines on the same device which are not visible within the
Vulkan API.
Both of these are beyond the scope of this extension.
=== Examples

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

@ -16,10 +16,10 @@
*IP Status*::
No known IP claims.
*Dependencies*::
- This extension is written against version 1.0 of the Vulkan API.
- Interacts with +VK_NV_dedicated_allocation+.
- This extension is written against version 1.0 of the Vulkan API.
- Interacts with +VK_NV_dedicated_allocation+.
*Contributors*::
- James Jones, NVIDIA
- James Jones, NVIDIA
*Contact*::
James Jones (jajones 'at' nvidia.com)
@ -39,45 +39,45 @@ None.
=== New Enums
* elink:VkExternalMemoryHandleTypeFlagBitsNV
* elink:VkExternalMemoryFeatureFlagBitsNV
* elink:VkExternalMemoryHandleTypeFlagBitsNV
* elink:VkExternalMemoryFeatureFlagBitsNV
=== New Structs
* slink:VkExternalImageFormatPropertiesNV
* slink:VkExternalImageFormatPropertiesNV
=== New Functions
* flink:vkGetPhysicalDeviceExternalImageFormatPropertiesNV
* flink:vkGetPhysicalDeviceExternalImageFormatPropertiesNV
=== Issues
1) Why do so many external memory capabilities need to be queried on a
per-memory-handle-type basis?
per-memory-handle-type basis?
RESOLUTION: This is because some handle types are based on OS-native
objects that have far more limited capabilities than the very generic
Vulkan memory objects.
Not all memory handle types can name memory objects that support 3D
images, for example.
Some handle types can not even support the deferred image and memory
binding behavior of Vulkan and require specifying the image when
allocating or importing the memory object.
*RESOLUTION*: This is because some handle types are based on OS-native
objects that have far more limited capabilities than the very generic Vulkan
memory objects.
Not all memory handle types can name memory objects that support 3D images,
for example.
Some handle types can not even support the deferred image and memory binding
behavior of Vulkan and require specifying the image when allocating or
importing the memory object.
2) Does the VkExternalImageFormatPropertiesNV struct need to include a list
of memory type bits that support the given handle type?
2) Does the slink:VkExternalImageFormatPropertiesNV struct need to include a
list of memory type bits that support the given handle type?
RESOLUTION: No.
The memory types that do not support the handle types will simply be
filtered out of the results returned by vkGetImageMemoryRequirements()
when a set of handle types was specified at image creation time.
*RESOLUTION*: No.
The memory types that do not support the handle types will simply be
filtered out of the results returned by flink:vkGetImageMemoryRequirements
when a set of handle types was specified at image creation time.
3) Should the non-opaque handle types be moved to their own extension?
RESOLUTION: Perhaps.
However, defining the handle type bits does very little and does not
require any platform-specific types on its own, and it is easier to
maintain the bitmask values in a single extension for now.
Presumably more handle types could be added by separate extensions
though, and it would be midly weird to have some platform- specific ones
defined in the core spec and some in extensions
*RESOLUTION*: Perhaps.
However, defining the handle type bits does very little and does not require
any platform-specific types on its own, and it is easier to maintain the
bitmask values in a single extension for now.
Presumably more handle types could be added by separate extensions though,
and it would be midly weird to have some platform-specific ones defined in
the core spec and some in extensions

78
doc/specs/vulkan/appendices/VK_NV_external_memory_win32.txt
View File

@ -16,14 +16,14 @@
*IP Status*::
No known IP claims.
*Dependencies*::
- This extension is written against version 1.0 of the Vulkan API.
- Requires +VK_NV_external_memory_capabilities+
- Requires +VK_NV_external_memory+
- This extension is written against version 1.0 of the Vulkan API.
- Requires +VK_NV_external_memory_capabilities+.
- Requires +VK_NV_external_memory+.
*Contributors*::
- James Jones, NVIDIA
- Carsten Rohde, NVIDIA
- James Jones, NVIDIA
- Carsten Rohde, NVIDIA
*Contact*::
- James Jones (jajones 'at' nvidia.com)
- James Jones (jajones 'at' nvidia.com)
Applications may wish to export memory to other Vulkan instances or other
APIs, or import memory from other Vulkan instances or other APIs to enable
@ -62,47 +62,45 @@ None.
=== Issues
1) If memory objects are shared between processes and APIs, is this
considered aliasing according to the rules outlined in section 11.8,
Memory Aliasing?
considered aliasing according to the rules outlined in the
<<resources-memory-aliasing,Memory Aliasing>> section?
RESOLUTION: Yes, but strict exceptions to the rules are added to allow
some forms of aliasing in these cases.
Further, other extensions may build upon these new aliasing rules to
define specific support usage within Vulkan for imported native memory
objects, or memory objects from other APIs.
*RESOLVED*: Yes, but strict exceptions to the rules are added to allow some
forms of aliasing in these cases.
Further, other extensions may build upon these new aliasing rules to define
specific support usage within Vulkan for imported native memory objects, or
memory objects from other APIs.
2) Are new image layouts or metadata required to specify image layouts and
layout transitions compatible with non-Vulkan APIs, or with other
instances of the same Vulkan driver?
layout transitions compatible with non-Vulkan APIs, or with other instances
of the same Vulkan driver?
RESOLUTION: No.
Separate instances of the same Vulkan driver running on the same GPU
should have identical internal layout semantics, so applictions have the
tools they need to ensure views of images are consistent between the two
instances.
Other APIs will fall into two categories: Those that are Vulkan-
compatible (A term to be defined by subsequent interopability
extensions), or Vulkan incompatible.
When sharing images with Vulkan incompatible APIs, the Vulkan image must
be transitioned to the GENERAL layout before handing it off to the
external API.
*RESOLVED*: No.
Separate instances of the same Vulkan driver running on the same GPU should
have identical internal layout semantics, so applictions have the tools they
need to ensure views of images are consistent between the two instances.
Other APIs will fall into two categories: Those that are Vulkan compatible
(A term to be defined by subsequent interopability extensions), or Vulkan
incompatible.
When sharing images with Vulkan incompatible APIs, the Vulkan image must be
transitioned to the GENERAL layout before handing it off to the external
API.
Note this does not attempt to address cross-device transitions, nor
transitions to engines on the same device which are not visible within
the Vulkan API.
Both of these are beyond the scope of this extension.
Note this does not attempt to address cross-device transitions, nor
transitions to engines on the same device which are not visible within the
Vulkan API.
Both of these are beyond the scope of this extension.
3) Do applications need to call CloseHandle() on the values returned from
VkGetMemoryWin32HandleKHR() when handleType is
VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_WIN32_BIT_KHR?
3) Do applications need to call code:CloseHandle() on the values returned
from flink:VkGetMemoryWin32HandleKHR when pname:handleType is
ename:VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_WIN32_BIT_KHR?
RESOLUTION: Yes, unless it is passed back in to another driver instance
to import the object.
A successful get call transfers ownership of the handle to the
application, while an import transfers ownership to the associated
driver.
Destroying the memory object will not destroy the handle or the handle's
reference to the underlying memory resource.
*RESOLVED*: Yes, unless it is passed back in to another driver instance to
import the object.
A successful get call transfers ownership of the handle to the application,
while an import transfers ownership to the associated driver.
Destroying the memory object will not destroy the handle or the handle's
reference to the underlying memory resource.
=== Examples

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

@ -16,12 +16,11 @@
*IP Status*::
No known IP claims.
*Dependencies*::
- This extension is written against version 1.0.
of the Vulkan API.
- This extension is written against version 1.0 of the Vulkan API.
*Contributors*::
- Piers Daniell, NVIDIA
- Piers Daniell, NVIDIA
*Contacts*::
- Piers Daniell (pdaniell 'at' nvidia.com)
- Piers Daniell (pdaniell 'at' nvidia.com)
This extension allows GLSL shaders written to the +GL_KHR_vulkan_glsl+
extension specification to be used instead of SPIR-V.

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

@ -16,14 +16,14 @@
*IP Status*::
No known IP claims.
*Dependencies*::
- This extension is written against version 1.0 of the Vulkan API.
- Requires +VK_NV_external_memory_capabilities+
- Requires +VK_NV_external_memory_win32+
- This extension is written against version 1.0 of the Vulkan API.
- Requires +VK_NV_external_memory_capabilities+
- Requires +VK_NV_external_memory_win32+
*Contributors*::
- James Jones, NVIDIA
- Carsten Rohde, NVIDIA
- James Jones, NVIDIA
- Carsten Rohde, NVIDIA
*Contact*::
- Carsten Rohde (crohde 'at' nvidia.com)
- Carsten Rohde (crohde 'at' nvidia.com)
Applications that wish to import Direct3D 11 memory objects into the Vulkan
API may wish to use the native keyed mutex mechanism to synchronize access

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

@ -1,4 +1,4 @@
// Copyright (c) 2016 The Khronos Group Inc.
// Copyright (c) 2016-2017 The Khronos Group Inc.
// Copyright notice at https://www.khronos.org/registry/speccopyright.html
[appendix]
@ -340,6 +340,9 @@ the macro is #defined are shown in the
| +VK_KHR_win32_surface+ | +VK_USE_PLATFORM_WIN32_KHR+ | Microsoft Windows | +<windows.h>+
| +VK_KHR_xcb_surface+ | +VK_USE_PLATFORM_XCB_KHR+ | X Window System Xcb library | +<xcb/xcb.h>+
| +VK_KHR_xlib_surface+ | +VK_USE_PLATFORM_XLIB_KHR+ | X Window System Xlib library | +<X11/Xlib.h>+
ifdef::VK_NN_vi_surface[]
| +VK_NN_vi_surface+ | +VK_USE_PLATFORM_VI_NN+ | VI | None
endif::VK_NN_vi_surface[]
|====
// @refEnd WSIheaders

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

@ -1,4 +1,4 @@
// Copyright (c) 2015-2016 The Khronos Group Inc.
// Copyright (c) 2015-2017 The Khronos Group Inc.
// Copyright notice at https://www.khronos.org/registry/speccopyright.html
[appendix]

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

@ -1,4 +1,4 @@
// Copyright (c) 2015-2016 The Khronos Group Inc.
// Copyright (c) 2015-2017 The Khronos Group Inc.
// Copyright notice at https://www.khronos.org/registry/speccopyright.html
[appendix]

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

@ -1,4 +1,4 @@
// Copyright (c) 2015-2016 The Khronos Group Inc.
// Copyright (c) 2015-2017 The Khronos Group Inc.
// Copyright notice at https://www.khronos.org/registry/speccopyright.html
[appendix]
@ -45,8 +45,20 @@ alphabetically.
// == Khronos +KHR+ Extensions
//
ifdef::VK_KHR_get_physical_device_properties2[]
include::VK_KHR_get_physical_device_properties2.txt[]
endif::VK_KHR_get_physical_device_properties2[]
ifdef::VK_KHR_maintenance1[]
include::VK_KHR_maintenance1.txt[]
endif::VK_KHR_maintenance1[]
include::VK_KHR_sampler_mirror_clamp_to_edge.txt[]
ifdef::VK_KHR_shader_draw_parameters[]
include::VK_KHR_shader_draw_parameters.txt[]
endif::VK_KHR_shader_draw_parameters[]
// WSI extensions are all grouped below
:leveloffset: 2
@ -74,6 +86,30 @@ ifdef::VK_EXT_validation_flags[]
include::VK_EXT_validation_flags.txt[]
endif::VK_EXT_validation_flags[]
ifdef::VK_EXT_direct_mode_display[]
include::VK_EXT_direct_mode_display.txt[]
endif::VK_EXT_direct_mode_display[]
ifdef::VK_EXT_acquire_xlib_display[]
include::VK_EXT_acquire_xlib_display.txt[]
endif::VK_EXT_acquire_xlib_display[]
ifdef::VK_EXT_display_surface_counter[]
include::VK_EXT_display_surface_counter.txt[]
endif::VK_EXT_display_surface_counter[]
ifdef::VK_EXT_display_control[]
include::VK_EXT_display_control.txt[]
endif::VK_EXT_display_control[]
ifdef::VK_EXT_shader_subgroup_ballot[]
include::VK_EXT_shader_subgroup_ballot.txt[]
endif::VK_EXT_shader_subgroup_ballot[]
ifdef::VK_EXT_shader_subgroup_vote[]
include::VK_EXT_shader_subgroup_vote.txt[]
endif::VK_EXT_shader_subgroup_vote[]
// :leveloffset: 1
@ -166,4 +202,3 @@ ifdef::VK_NVX_device_generated_commands[]
include::VK_NVX_device_generated_commands.txt[]
endif::VK_NVX_device_generated_commands[]
// :leveloffset: 1

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

@ -1,4 +1,4 @@
// Copyright (c) 2015-2016 The Khronos Group Inc.
// Copyright (c) 2015-2017 The Khronos Group Inc.
// Copyright notice at https://www.khronos.org/registry/speccopyright.html
// The asciidoc [glossary] template cannot contain subsections.
@ -108,12 +108,12 @@ Blending::
Buffer::
A resource that represents a linear array of data in device memory.
Represented by a sname:VkBuffer object.
Represented by a slink:VkBuffer object.
Buffer View::
An object that represents a range of a specific buffer, and state that
controls how the contents are interpreted.
Represented by a sname:VkBufferView object.
Represented by a slink:VkBufferView object.
Built-In Variable::
A variable decorated in a shader, where the decoration makes the
@ -150,7 +150,7 @@ Combined Image Sampler::
Command Buffer::
An object that records commands to be submitted to a queue.
Represented by a sname:VkCommandBuffer object.
Represented by a slink:VkCommandBuffer object.
Command Pool::
An object that command buffer memory is allocated from, and that owns
@ -158,7 +158,7 @@ Command Pool::
Command pools aid multithreaded performance by enabling different
threads to use different allocators, without internal synchronization on
each use.
Represented by a sname:VkCommandPool object.
Represented by a slink:VkCommandPool object.
Compatible Allocator::
When allocators are compatible, allocations from each allocator can: be
@ -207,7 +207,7 @@ Depth/Stencil Format::
A elink:VkFormat that includes depth and/or stencil components.
Depth/Stencil Image (or ImageView)::
A sname:VkImage (or sname:VkImageView) with a depth/stencil format.
A slink:VkImage (or slink:VkImageView) with a depth/stencil format.
Derivative Group::
A set of fragment shader invocations that cooperate to compute
@ -229,19 +229,19 @@ Descriptor Pool::
Descriptor pools aid multithreaded performance by enabling different
threads to use different allocators, without internal synchronization on
each use.
Represented by a sname:VkDescriptorPool object.
Represented by a slink:VkDescriptorPool object.
Descriptor Set::
An object that resource descriptors are written into via the API, and
that can: be bound to a command buffer such that the descriptors
contained within it can: be accessed from shaders.
Represented by a sname:VkDescriptorSet object.
Represented by a slink:VkDescriptorSet object.
Descriptor Set Layout::
An object that defines the set of resources (types and counts) and their
relative arrangement (in the binding namespace) within a descriptor set.
Used when allocating descriptor sets and when creating pipeline layouts.
Represented by a sname:VkDescriptorSetLayout object.
Represented by a slink:VkDescriptorSetLayout object.
Device::
The processor(s) and execution environment that perform tasks requested
@ -249,11 +249,11 @@ Device::
Device Memory::
Memory accessible to the device.
Represented by a sname:VkDeviceMemory object.
Represented by a slink:VkDeviceMemory object.
Device-Level Object::
Logical device objects and their child objects For example,
sname:VkDevice, sname:VkQueue, and sname:VkCommandBuffer objects are
slink:VkDevice, slink:VkQueue, and slink:VkCommandBuffer objects are
device-level objects.
Device-Local Memory::
@ -313,7 +313,7 @@ Event::
A synchronization primitive that is signaled when execution of previous
commands complete through a specified set of pipeline stages.
Events can be waited on by the device and polled by the host.
Represented by a sname:VkEvent object.
Represented by a slink:VkEvent object.
Executable State (Command Buffer)::
A command buffer that has ended recording commands and can: be executed.
@ -347,7 +347,7 @@ Fence::
A synchronization primitive that is signaled when a set of batches or
sparse binding operations complete execution on a queue.
Fences can: be waited on by the host.
Represented by a sname:VkFence object.
Represented by a slink:VkFence object.
Flat Shading::
A property of a vertex attribute that causes the value from a single
@ -368,7 +368,7 @@ Framebuffer::
A collection of image views and a set of dimensions that, in conjunction
with a render pass, define the inputs and outputs used by drawing
commands.
Represented by a sname:VkFramebuffer object.
Represented by a slink:VkFramebuffer object.
Framebuffer Attachment::
One of the image views used in a framebuffer.
@ -451,7 +451,7 @@ Host-Visible Memory::
Image::
A resource that represents a multi-dimensional formatted interpretation
of device memory.
Represented by a sname:VkImage object.
Represented by a slink:VkImage object.
Image Subresource::
A specific mipmap level and layer of an image.
@ -463,7 +463,7 @@ Image Subresource Range::
Image View::
An object that represents an image subresource range of a specific
image, and state that controls how the contents are interpreted.
Represented by a sname:VkImageView object.
Represented by a slink:VkImageView object.
Immutable Sampler::
A sampler descriptor provided at descriptor set layout creation time,
@ -503,9 +503,9 @@ Indirect Commands Layout::
A definition of a sequence of commands, that are generated on the device
via flink:vkCmdProcessCommandsNVX.
Each sequence is comprised of multiple
sname:VkIndirectCommandsTokenTypeNVX, which represent asubset of
elink:VkIndirectCommandsTokenTypeNVX, which represent a subset of
traditional command buffer commands.
Represented as sname:VkIndirectCommandsLayoutNVX.
Represented as slink:VkIndirectCommandsLayoutNVX.
endif::VK_NVX_device_generated_commands[]
Indirect Drawing Commands::
@ -529,12 +529,12 @@ Input Attachment::
Instance::
The top-level Vulkan object, which represents the application's
connection to the implementation.
Represented by a sname:VkInstance object.
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, sname:VkInstance and sname:VkPhysicalDevice objects are
For example, slink:VkInstance and slink:VkPhysicalDevice objects are
instance-level objects.
Internal Synchronization::
@ -560,7 +560,7 @@ Logical Device::
An object that represents the application's interface to the physical
device.
The logical device is the parent of most Vulkan objects.
Represented by a sname:VkDevice object.
Represented by a slink:VkDevice object.
Logical Operation::
Bitwise operations between a fragment color value and a value in a color
@ -619,10 +619,10 @@ Normalized Device Coordinates::
ifdef::VK_NVX_device_generated_commands[]
Object Table::
A binding table for various resources (sname:VkPipeline, sname:VkBuffer,
sname:VkDescriptorSet), so that they can be referenced in
A binding table for various resources (slink:VkPipeline, slink:VkBuffer,
slink:VkDescriptorSet), so that they can be referenced in
device-generated command processing.
Represented as sname:VkObjectTableNVX.
Represented as slink:VkObjectTableNVX.
Entries are registered or unregistered via ftext:uint32_t indices.
endif::VK_NVX_device_generated_commands[]
@ -640,14 +640,14 @@ Packed Format::
Physical Device::
An object that represents a single device in the system.
Represented by a sname:VkPhysicalDevice object.
Represented by a slink:VkPhysicalDevice object.
Pipeline::
An object that controls how graphics or compute work is executed on the
device.
A pipeline includes one or more shaders, as well as state controlling
any non-programmable stages of the pipeline.
Represented by a sname:VkPipeline object.
Represented by a slink:VkPipeline object.
Pipeline Barrier::
An execution and/or memory dependency recorded as an explicit command in
@ -658,7 +658,7 @@ Pipeline Cache::
An object that can: be used to collect and retrieve information from
pipelines as they are created, and can: be populated with previously
retrieved information in order to accelerate pipeline creation.
Represented by a sname:VkPipelineCache object.
Represented by a slink:VkPipelineCache object.
Pipeline Layout::
An object that defines the set of resources (via a collection of
@ -666,7 +666,7 @@ Pipeline Layout::
created using the layout.
Used when creating a pipeline and when binding descriptor sets and
setting push constant values.
Represented by a sname:VkPipelineLayout object.
Represented by a slink:VkPipelineLayout object.
Pipeline Stage::
A logically independent execution unit that performs some of the
@ -712,12 +712,12 @@ Push Constant Interface::
Query Pool::
An object that contains a number of query entries and their associated
state and results.
Represented by a sname:VkQueryPool object.
Represented by a slink:VkQueryPool object.
Queue::
An object that executes command buffers and sparse binding operations on
a device.
Represented by a sname:VkQueue object.
Represented by a slink:VkQueue object.
Queue Family::
A set of queues that have common properties and support the same
@ -748,7 +748,7 @@ Release Operation (Resource)::
Render Pass::
An object that represents a set of framebuffer attachments and phases of
rendering using those attachments.
Represented by a sname:VkRenderPass object.
Represented by a slink:VkRenderPass object.
Render Pass Instance::
A use of a render pass in a command buffer.
@ -774,7 +774,7 @@ Sampler::
An object that contains state that controls how sampled image data is
sampled (or filtered) when accessed in a shader.
Also a descriptor type describing the object.
Represented by a sname:VkSampler object.
Represented by a slink:VkSampler object.
Secondary Command Buffer::
A command buffer that can: be executed by a primary command buffer, and
@ -791,7 +791,7 @@ Semaphore::
A synchronization primitive that supports signal and wait operations,
and can: be used to synchronize operations within a queue or across
queues.
Represented by a sname:VkSemaphore object.
Represented by a slink:VkSemaphore object.
Shader::
Instructions selected (via an entry point) from a shader module, which
@ -803,7 +803,7 @@ Shader Code::
Shader Module::
A collection of shader code, potentially including several functions and
entry points, that is used to create shaders in pipelines.
Represented by a sname:VkShaderModule object.
Represented by a slink:VkShaderModule object.
Shader Stage::
A stage of the graphics or compute pipeline that executes shader code.
@ -848,6 +848,21 @@ 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[]
Subgroup::
The set of shader invocations exposed as running concurrently with the
current shader invocation.
In compute shaders, the _local workgroup_ is a superset of the subgroup.
endif::VK_EXT_shader_subgroup_vote[]
ifdef::VK_EXT_shader_subgroup_ballot[]
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[]
Subpass::
A phase of rendering within a render pass, that reads and writes a
subset of the attachments.

19
doc/specs/vulkan/appendices/invariance.txt
View File

@ -1,4 +1,4 @@
// Copyright (c) 2015-2016 The Khronos Group Inc.
// Copyright (c) 2015-2017 The Khronos Group Inc.
// Copyright notice at https://www.khronos.org/registry/speccopyright.html
[appendix]
@ -96,7 +96,7 @@ sequence, are pixel identical._
*Rule 4* _Identical pipelines will produce the same result when run multiple
times with the same input.
The wording ``Identical pipelines'' means sname:VkPipeline objects that have
The wording ``Identical pipelines'' means slink:VkPipeline objects that have
been created with identical SPIR-V binaries and identical state, which are
then used by commands executed using the same Vulkan state vector.
Invariance is relaxed for shaders with side effects, such as performing
@ -131,6 +131,21 @@ times with the same input as long as:_
* _no shader invocation, or other operation performed to process the
sequence of commands, reads memory written to by an image store._
[NOTE]
.Note
==================
The OpenGL spec has the following invariance rule: Consider a primitive p'
obtained by translating a primitive p through an offset (x, y) in window
coordinates, where x and y are integers.
As long as neither p' nor p is clipped, it must be the case that each
fragment f' produced from p' is identical to a corresponding fragment f from
p except that the center of f' is offset by (x, y) from the center of f.
This rule does not apply to Vulkan and is an intentional difference from
OpenGL.
==================
When any sequence of Vulkan commands triggers shader invocations that
perform image stores or atomic operations, and subsequent Vulkan commands
read the memory written by those shader invocations, these operations must:

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

@ -1,4 +1,4 @@
// Copyright (c) 2015-2016 The Khronos Group Inc.
// Copyright (c) 2015-2017 The Khronos Group Inc.
// Copyright notice at https://www.khronos.org/registry/speccopyright.html
[appendix]
@ -76,6 +76,18 @@ 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,VK_KHR_shader_draw_parameters>>
endif::VK_KHR_shader_draw_parameters[]
ifdef::VK_EXT_shader_subgroup_ballot[]
[[spirvenv-capabilities-table-subgroupballot]]
| code:SubgroupBallotKHR | <<VK_EXT_shader_subgroup_ballot,VK_EXT_shader_subgroup_ballot>>
endif::VK_EXT_shader_subgroup_ballot[]
ifdef::VK_EXT_shader_subgroup_vote[]
[[spirvenv-capabilities-table-subgroupvote]]
| code:SubgroupVoteKHR | <<VK_EXT_shader_subgroup_vote,VK_EXT_shader_subgroup_vote>>
endif::VK_EXT_shader_subgroup_vote[]
|====
ifdef::VK_AMD_shader_explicit_vertex_parameter[]
@ -103,6 +115,21 @@ The application can: pass a SPIR-V module to flink:vkCreateShaderModule that
uses the +SPV_AMD_shader_trinary_minmax+ SPIR-V extension.
endif::VK_AMD_shader_trinary_minmax[]
ifdef::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[]
ifdef::VK_EXT_shader_subgroup_ballot[]
The application can: pass a SPIR-V module to flink:vkCreateShaderModule that
uses the +SPV_KHR_shader_ballot+ SPIR-V extension.
endif::VK_EXT_shader_subgroup_ballot[]
ifdef::VK_EXT_shader_subgroup_vote[]
The application can: pass a SPIR-V module to flink:vkCreateShaderModule that
uses the +SPV_KHR_subgroup_vote+ SPIR-V extension.
endif::VK_EXT_shader_subgroup_vote[]
The application must: not pass a SPIR-V module containing any of the
following to flink:vkCreateShaderModule:

55
doc/specs/vulkan/chapters/VK_EXT_acquire_xlib_display/acquire_xlib_display.txt Normal file
View File

@ -0,0 +1,55 @@
// refBegin vkAcquireXlibDisplayEXT Acquire access to a VkDisplayKHR using Xlib
To acquire permission to directly access a display in Vulkan from an X11
server, call:
include::../../api/protos/vkAcquireXlibDisplayEXT.txt[]
* pname:physicalDevice The physical device the display is on.
* pname:dpy A connection to the X11 server that currently owns
pname:display.
* pname:display The display the caller wishes to control in Vulkan.
All permissions necessary to control the display are granted to the Vulkan
instance associated with pname:physicalDevice until the display is released
or the X11 connection specified by pname:dpy is terminated.
Permission to access the display may: be temporarily revoked during periods
when the X11 server from which control was acquired itself looses access to
pname:display.
During such periods, operations which require access to the display must:
fail with an approriate error code.
If the X11 server associated with pname:dpy does not own pname:display, or
if permission to access it has already been acquired by another entity, the
call must: return the error code VK_ERROR_INITIALIZATION_FAILED.
[NOTE]
.Note
====
One example of when an X11 server loses access to a display is when it loses
ownership of its virtual terminal.
====
include::../../validity/protos/vkAcquireXlibDisplayEXT.txt[]
// refBegin vkGetRandROutputDisplayEXT Query the VkDisplayKHR corresponding to an X11 RandR Output
When acquiring displays from an X11 server, an application may also wish to
enumerate and identify them using a native handle rather than a
sname:VkDisplayKHR handle.
To determine the sname:VkDisplayKHR handle corresponding to an X11 RandR
Output, call:
include::../../api/protos/vkGetRandROutputDisplayEXT.txt[]
* pname:physicalDevice The physical device to query the display handle on.
* pname:dpy A connection to the X11 server from which pname:rrOutput was
queried.
* pname:rrOutput An X11 RandR output ID.
* pname:pDisplay The corresponding VkDisplayKHR handle will be returned
here.
If there is no VkDisplayKHR corresponding to pname:rrOutput on
pname:physicalDevice, ename:VK_NULL_HANDLE must: be returned in
pname:pDisplay.
include::../../validity/protos/vkGetRandROutputDisplayEXT.txt[]

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

@ -99,10 +99,11 @@ include::../api/funcpointers/PFN_vkDebugReportCallbackEXT.txt[]
* pname:flags indicates the ename:VkDebugReportFlagBitsEXT that triggered
this callback.
* pname:objType is a elink:VkDebugReportObjectTypeEXT specifying the type
of object being used or created at the time the event was triggered.
* pname:objectType is a elink:VkDebugReportObjectTypeEXT specifying the
type of object being used or created at the time the event was
triggered.
* pname:object gives the object where the issue was detected.
pname:object may be ename:VK_NULL_OBJECT if there is no object
pname:object may be ename:VK_NULL_HANDLE if there is no object
associated with the event.
* pname:location is a component (layer, driver, loader) defined value that
indicates the _location_ of the trigger.
@ -145,8 +146,9 @@ include::../api/protos/vkDebugReportMessageEXT.txt[]
* pname:instance the instance the callback will be logged on.
* pname:flags indicates the ename:VkDebugReportFlagBitsEXT that triggered
this callback.
* pname:objType is a elink:VkDebugReportObjectTypeEXT specifying the type
of object being used or created at the time the event was triggered.
* pname:objectType is a elink:VkDebugReportObjectTypeEXT specifying the
type of object being used or created at the time the event was
triggered.
* pname:object is object where the issue was detected.
pname:object may be ename:VK_NULL_OBJECT if there is no object
associated with the event.
@ -168,7 +170,7 @@ registered.
.Valid Usage
****
* pname:object may: be a Vulkan object
* pname:object must: be a Vulkan object or ename:VK_NULL_HANDLE
****
include::../validity/protos/vkDebugReportMessageEXT.txt[]

22
doc/specs/vulkan/chapters/VK_EXT_direct_mode_display/acquire_release_displays.txt Normal file
View File

@ -0,0 +1,22 @@
==== Acquiring and Releasing Displays
On some platforms, access to displays is limited to a single process or
native driver instance.
On such platforms, some or all of the displays may not be available to
Vulkan if they are already in use by a native windowing system or other
application.
ifdef::VK_EXT_acquire_xlib_display[]
include::../VK_EXT_acquire_xlib_display/acquire_xlib_display.txt[]
endif::VK_EXT_acquire_xlib_display[]
// refBegin vkReleaseDisplayEXT Release access to an acquired VkDisplayKHR
To release a previously acquired display, call:
include::../../api/protos/vkReleaseDisplayEXT.txt[]
* pname:physicalDevice The physical device the display is on.
* pname:display The display to release control of.
include::../../validity/protos/vkReleaseDisplayEXT.txt[]

40
doc/specs/vulkan/chapters/VK_EXT_display_control/display_control.txt Normal file
View File

@ -0,0 +1,40 @@
=== Display Control
// refBegin vkDisplayPowerControlEXT Set the power state of a display
To set the power state of a display, call:
include::../../api/protos/vkDisplayPowerControlEXT.txt[]
* pname:device is a logical device associated with pname:display.
* pname:display is the display whose power state is modified.
* pname:pDisplayPowerInfo is an instance of slink:VkDisplayPowerInfoEXT
specifying the new power state of pname:display.
include::../../validity/protos/vkDisplayPowerControlEXT.txt[]
// refBegin VkDisplayPowerInfoEXT Describe the power state of a display
The sname:VkDisplayPowerInfoEXT structure is defined as:
include::../../api/structs/VkDisplayPowerInfoEXT.txt[]
* pname:sType is the type of this structure.
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
* pname:powerState is the new power state of the display.
Possible values are:
+
--
// refBegin VkDisplayPowerStateEXT Possible power states for a VkDisplay
include::../../api/enums/VkDisplayPowerStateEXT.txt[]
--
+
** ename:VK_DISPLAY_POWER_STATE_OFF_EXT means the display is powered down.
** ename:VK_DISPLAY_POWER_STATE_SUSPEND_EXT means the display is in a low
power mode, but may: be able to transition back to
ename:VK_DISPLAY_POWER_STATE_ON_EXT more quickly than if it were in
ename:VK_DISPLAY_POWER_STATE_OFF_EXT.
This state may: be the same as ename:VK_DISPLAY_POWER_STATE_OFF_EXT.
** ename:VK_DISPLAY_POWER_STATE_ON_EXT is powered on.
include::../../validity/structs/VkDisplayPowerInfoEXT.txt[]

87
doc/specs/vulkan/chapters/VK_EXT_display_control/fence_events.txt Normal file
View File

@ -0,0 +1,87 @@
=== Alternate Methods to Signal Fences
Besides submitting a fence to a queue as part of a
<<devsandqueues-submission, queue submission>> command, a fence may: also be
signaled when a particular event occurs on a device or display.
// refBegin vkRegisterDeviceEventEXT Signal a fence when a device event occurs
To create a fence that will be signaled when an event occurs on a device,
call:
include::../../api/protos/vkRegisterDeviceEventEXT.txt[]
* pname:device is a logical device on which the event may: occur.
* pname:pDeviceEventInfo is a pointer to an instance of the
slink:VkDeviceEventInfoEXT structure describing the event of interest to
the application.
* pname:pAllocator controls host memory allocation as described in the
<<memory-allocation, Memory Allocation>> chapter.
* pname:pFence points to a handle in which the resulting fence object is
returned.
include::../../validity/protos/vkRegisterDeviceEventEXT.txt[]
// refBegin VkDeviceEventInfoEXT Describe a device event to create
The sname:VkDeviceEventInfoEXT structure is defined as:
include::../../api/structs/VkDeviceEventInfoEXT.txt[]
* pname:sType is the type of this structure.
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
* pname:device specifies when the fence will be signaled.
Possible values are:
+
--
// refBegin VkDeviceEventTypeEXT Events that can occur on a device object
include::../../api/enums/VkDeviceEventTypeEXT.txt[]
--
+
** ename:VK_DEVICE_EVENT_TYPE_DISPLAY_HOTPLUG_EXT occurs when a display is
plugged into or unplugged from the specified device.
Applications can: use this notification to determine when they need to
re-enumerate the available displays on a device.
include::../../validity/structs/VkDeviceEventInfoEXT.txt[]
// refBegin vkRegisterDisplayEventEXT Signal a fence when a display event occurs
To create a fence that will be signaled when an event occurs on a
VkDisplayKHR object, call:
include::../../api/protos/vkRegisterDisplayEventEXT.txt[]
* pname:device is a logical device associated with pname:display
* pname:display is the display on which the event may: occur.
* pname:pDisplayEventInfo is a pointer to an instance of the
slink:VkDisplayEventInfoEXT structure describing the event of interest
to the application.
* pname:pAllocator controls host memory allocation as described in the
<<memory-allocation, Memory Allocation>> chapter.
* pname:pFence points to a handle in which the resulting fence object is
returned.
include::../../validity/protos/vkRegisterDisplayEventEXT.txt[]
// refBegin VkDisplayEventInfoEXT Describe a display event to create
The sname:VkDisplayEventInfoEXT structure is defined as:
include::../../api/structs/VkDisplayEventInfoEXT.txt[]
* pname:sType is the type of this structure.
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
* pname:displayEvent specifies when the fence will be signaled.
Possible values are:
+
--
// refBegin VkDisplayEventTypeEXT Events that can occur on a display object
include::../../api/enums/VkDisplayEventTypeEXT.txt[]
--
+
** ename:VK_DISPLAY_EVENT_TYPE_FIRST_PIXEL_OUT_EXT occurs when the first
pixel of the next display refresh cycle leaves the display engine for
the display.
include::../../validity/structs/VkDisplayEventInfoEXT.txt[]

46
doc/specs/vulkan/chapters/VK_EXT_display_control/swapchain_counters.txt Normal file
View File

@ -0,0 +1,46 @@
// refBegin VkSwapchainCounterCreateInfoEXT Specify the surface counters desired
To enable surface counters when creating a swapchain, add
sname:VkSwapchainCounterCreateInfoEXT to the pname:pNext chain of
slink:VkSwapchainCreateInfoKHR.
sname:VkSwapchainCounterCreateInfoEXT is defined as:
include::../../api/structs/VkSwapchainCounterCreateInfoEXT.txt[]
* pname:sType is the type of this structure.
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
* pname:surfaceCounters is a bitmask containing a bit set for each surface
counter to enable for the swapchain.
.Valid Usage
****
* The bits in pname:surfaceCounters must: be supported by
slink:VkSwapchainCreateInfoKHR::pname:surface, as reported by
flink:vkGetPhysicalDeviceSurfaceCapabilities2EXT.
****
include::../../validity/structs/VkSwapchainCounterCreateInfoEXT.txt[]
// refBegin vkGetSwapchainCounterEXT Query the current value of a surface counter
The requested counters become active when the first presentation command for
the associated swapchain is processed by the presentation engine.
To query the value of an active counter, use:
include::../../api/protos/vkGetSwapchainCounterEXT.txt[]
* pname:device is the sname:VkDevice associated with pname:swapchain.
* pname:swapchain is the swapchain from which to query the counter value.
* pname:counter is the counter to query.
* pname:pCounterValue will return the current value of the counter.
If a counter is not available because the swapchain is out of date, the
implementation may: return VK_ERROR_OUT_OF_DATE_KHR.
.Valid Usage
****
* One or more present commands on pname:swapchain must: have been
processed by the presentation engine.
****
include::../../validity/protos/vkGetSwapchainCounterEXT.txt[]

57
doc/specs/vulkan/chapters/VK_EXT_display_surface_counter/surface_capabilities.txt Normal file
View File

@ -0,0 +1,57 @@
// refBegin vkGetPhysicalDeviceSurfaceCapabilities2EXT Query surface capabilities
To query the basic capabilities of a surface, needed in order to create a
swapchain, call:
include::../../api/protos/vkGetPhysicalDeviceSurfaceCapabilities2EXT.txt[]
* pname:physicalDevice is the physical device that will be associated with
the swapchain to be created, as described for
flink:vkCreateSwapchainKHR.
* pname:surface is the surface that will be associated with the swapchain.
* pname:pSurfaceCapabilities is a pointer to an instance of the
slink:VkSurfaceCapabilities2EXT structure in which the capabilities are
returned.
fname:vkGetPhysicalDeviceSurfaceCapabilities2EXT behaves similarly to
flink:vkGetPhysicalDeviceSurfaceCapabilitiesKHR, with the ability to return
extended information via chained output structures.
include::../../validity/protos/vkGetPhysicalDeviceSurfaceCapabilities2EXT.txt[]
// refBegin VkSurfaceCapabilities2EXT Structure describing capabilities of a surface
The sname:VkSurfaceCapabilities2EXT structure is defined as:
include::../../api/structs/VkSurfaceCapabilities2EXT.txt[]
All members of sname:VkSurfaceCapabilities2EXT are identical to the
corresponding members of slink:VkSurfaceCapabilitiesKHR where one exists.
The remaining members are:
* pname:sType is the type of this structure.
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
* pname:supportedSurfaceCounters is a bitfield containing one bit set for
each surface counter type supported.
.Valid Usage
****
* pname:supportedSurfaceCounters must: not include
ename:VK_SURFACE_COUNTER_VBLANK_EXT unless the surface queried is a
<<wsi-display-surfaces,display surface>>.
****
include::../../validity/structs/VkSurfaceCapabilities2EXT.txt[]
// refBegin VkSurfaceCounterFlagBitsEXT Surface-relative counter types
Valid values for
slink:VkSurfaceCapabilities2EXT::pname:supportedSurfaceCounters are defined
by sname:VkSurfaceCounterFlagBitsEXT as follows:
include::../../api/enums/VkSurfaceCounterFlagBitsEXT.txt[]
* ename:VK_SURFACE_COUNTER_VBLANK_EXT A counter incrementing once every
time a vblank period occurs on the display associated with the surface.
// refEnd VkSurfaceCounterFlagBitsEXT

12
doc/specs/vulkan/chapters/VK_IMG_filter_cubic/filter_cubic_texel_filtering.txt
View File

@ -8,7 +8,7 @@ Catmull-Rom Spine interpolation of four points is defined by the equation:
[latexmath]
++++++++++++++++++++++++
\begin{align*}
\[ \begin{aligned}
cinterp(\tau_0, \tau_1, \tau_2, \tau_3, \omega) =
\frac{1}{2}
\begin{bmatrix}1 & \omega & \omega^2 & \omega^3 \end{bmatrix}
@ -26,7 +26,7 @@ cinterp(\tau_0, \tau_1, \tau_2, \tau_3, \omega) =
\tau_2 \\
\tau_3
\end{bmatrix}
\end{align*}
\end{aligned} \]
++++++++++++++++++++++++
Using the values calculated in texel selection, this equation is applied to
@ -50,11 +50,11 @@ result is then fed back into the equation and interpolated again:
[latexmath]
++++++++++++++++++++++++
\begin{align*}
\[ \begin{aligned}
\tau[level] &=
\begin{cases}
\tau_{2D}[level], &\textrm{for 2D image} \\
\tau_{1D}[level], &\textrm{for 1D image}
\tau_{2D}[level], & \text{for 2D image} \\
\tau_{1D}[level], & \text{for 1D image}
\end{cases}
\end{align*}
\end{aligned} \]
++++++++++++++++++++++++

10
doc/specs/vulkan/chapters/VK_IMG_filter_cubic/filter_cubic_texel_selection.txt
View File

@ -6,11 +6,11 @@ as well as weights [eq]#{alpha}# and [eq]#{beta}#.
[latexmath]
++++++++++++++++++++++++
\begin{align*}
i_{0} & = \left \lfloor u - \frac{3}{2} \right \rfloor & i_{1} & = i_{0} + 1 & i_{2} & = i_{1} + 1 & i_{3} & = i_{2} + 1 \\
\[ \begin{aligned}
i_{0} & = \left \lfloor u - \frac{3}{2} \right \rfloor & i_{1} & = i_{0} + 1 & i_{2} & = i_{1} + 1 & i_{3} & = i_{2} + 1 \\[1em]
j_{0} & = \left \lfloor u - \frac{3}{2} \right \rfloor & j_{1} & = j_{0} + 1 & j_{2} & = j_{1} + 1 & j_{3} & = j_{2} + 1 \\
\\
\alpha & = \operatorname{frac} \left ( u - \frac{1}{2} \right ) \\
\beta & = \operatorname{frac} \left ( v - \frac{1}{2} \right )
\end{align*}
\alpha & = \mathop{frac} \left ( u - \frac{1}{2} \right ) \\[1em]
\beta & = \mathop{frac} \left ( v - \frac{1}{2} \right )
\end{aligned} \]
++++++++++++++++++++++++

2
doc/specs/vulkan/chapters/VK_KHR_android_surface/platformCreateSurface_android.txt
View File

@ -1,4 +1,4 @@
// Copyright (c) 2014-2016 The Khronos Group Inc.
// Copyright (c) 2014-2017 The Khronos Group Inc.
// Copyright notice at https://www.khronos.org/registry/speccopyright.html
[[platformCreateSurface_android,platformCreateSurface_android]]

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

@ -1,4 +1,4 @@
// Copyright (c) 2014-2016 The Khronos Group Inc.
// Copyright (c) 2014-2017 The Khronos Group Inc.
// Copyright notice at https://www.khronos.org/registry/speccopyright.html
[[display,display]]
@ -94,6 +94,9 @@ screen needs to be updated in most frames.
include::../../validity/structs/VkDisplayPropertiesKHR.txt[]
ifdef::VK_EXT_direct_mode_display[]
include::../VK_EXT_direct_mode_display/acquire_release_displays.txt[]
endif::VK_EXT_direct_mode_display[]
==== Display Planes
@ -379,7 +382,11 @@ combinations.
include::../../validity/structs/VkDisplayPlaneCapabilitiesKHR.txt[]
ifdef::VK_EXT_display_control[]
include::../VK_EXT_display_control/display_control.txt[]
endif::VK_EXT_display_control[]
[[wsi-display-surfaces]]
=== Display Surfaces
// refBegin vkCreateDisplayPlaneSurfaceKHR - Create a slink:VkSurfaceKHR structure representing a display plane and mode

2
doc/specs/vulkan/chapters/VK_KHR_display_swapchain/create_shared_swapchains.txt
View File

@ -1,4 +1,4 @@
// Copyright (c) 2014-2016 The Khronos Group Inc.
// Copyright (c) 2014-2017 The Khronos Group Inc.
// Copyright notice at https://www.khronos.org/registry/speccopyright.html
[[create_shared_swapchains,create_shared_swapchains]]

2
doc/specs/vulkan/chapters/VK_KHR_display_swapchain/display_swapchain_present.txt
View File

@ -1,4 +1,4 @@
// Copyright (c) 2014-2016 The Khronos Group Inc.
// Copyright (c) 2014-2017 The Khronos Group Inc.
// Copyright notice at https://www.khronos.org/registry/speccopyright.html
[[display_swapchain_present,display_swapchain_present]]

2
doc/specs/vulkan/chapters/VK_KHR_mir_surface/platformCreateSurface_mir.txt
View File

@ -1,4 +1,4 @@
// Copyright (c) 2014-2016 The Khronos Group Inc.
// Copyright (c) 2014-2017 The Khronos Group Inc.
// Copyright notice at https://www.khronos.org/registry/speccopyright.html
[[platformCreateSurface_mir,platformCreateSurface_mir]]

2
doc/specs/vulkan/chapters/VK_KHR_mir_surface/platformQuerySupport_mir.txt
View File

@ -1,4 +1,4 @@
// Copyright (c) 2014-2016 The Khronos Group Inc.
// Copyright (c) 2014-2017 The Khronos Group Inc.
// Copyright notice at https://www.khronos.org/registry/speccopyright.html
[[platformQuerySupport_mir,platformQuerySupport_mir]]

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

@ -1,4 +1,4 @@
// Copyright (c) 2014-2016 The Khronos Group Inc.
// Copyright (c) 2014-2017 The Khronos Group Inc.
// Copyright notice at https://www.khronos.org/registry/speccopyright.html
[[wsi]]
@ -96,6 +96,10 @@ ifdef::VK_KHR_xlib_surface[]
include::../VK_KHR_xlib_surface/platformCreateSurface_xlib.txt[]
endif::VK_KHR_xlib_surface[]
ifdef::VK_NN_vi_surface[]
include::../VK_NN_vi_surface/platformCreateSurface_vi.txt[]
endif::VK_NN_vi_surface[]
=== Platform-Independent Information
@ -205,6 +209,10 @@ ifdef::VK_KHR_xlib_surface[]
include::../VK_KHR_xlib_surface/platformQuerySupport_xlib.txt[]
endif::VK_KHR_xlib_surface[]
ifdef::VK_NN_vi_surface[]
include::../VK_NN_vi_surface/platformQuerySupport_vi.txt[]
endif::VK_NN_vi_surface[]
== Surface Queries
@ -292,6 +300,10 @@ pname:maxImageCount may: be zero.
include::../../validity/structs/VkSurfaceCapabilitiesKHR.txt[]
#ifdef::VK_EXT_display_surface_counter[]
include::../VK_EXT_display_surface_counter/surface_capabilities.txt[]
#endif::VK_EXT_display_surface_counter[]
// refBegin VkSurfaceTransformFlagBitsKHR - presentation transforms supported on a device
slink:VkSurfaceCapabilitiesKHR::pname:supportedTransforms is a bitmask of,
@ -410,9 +422,8 @@ include::../../validity/structs/VkSurfaceFormatKHR.txt[]
While the pname:format of a presentable image refers to the encoding of each
pixel, the pname:colorSpace determines how the presentation engine
interprets the pixel values.
A color space in this document refers to a specific combination of color
model (i.e. RGB, YUV, HSL etc.), the actual color space (defined by the
chromaticities of its primaries and a white point in CIE Lab), and a
A color space in this document refers to a specific color space (defined by
the chromaticities of its primaries and a white point in CIE Lab), and a
transfer function that is applied before storing or transmitting color data
in the given color space.
@ -424,6 +435,35 @@ include::../../api/enums/VkColorSpaceKHR.txt[]
* ename:VK_COLOR_SPACE_SRGB_NONLINEAR_KHR: The presentation engine
supports the sRGB color space.
ifdef::VK_EXT_swapchain_colorspace[]
** ename:VK_COLOR_SPACE_SCRGB_LINEAR_EXT - supports the scRGB color space
and applies a linear OETF.
** ename:VK_COLOR_SPACE_SCRGB_NONLINEAR_EXT - supports the scRGB color
space and applies the scRGB OETF.
** ename:VK_COLOR_SPACE_DCI_P3_LINEAR_EXT - supports the DCI-P3 color
space and applies a linear OETF.
** ename:VK_COLOR_SPACE_DCI_P3_NONLINEAR_EXT - supports the DCI-P3 color
space and applies the Gamma 2.6 OETF.
** ename:VK_COLOR_SPACE_BT709_LINEAR_EXT - supports the BT709 color space
and applies a linear OETF.
** ename:VK_COLOR_SPACE_BT709_NONLINEAR_EXT - supports the BT709 color
space and applies the SMPTE 170M OETF.
** ename:VK_COLOR_SPACE_BT2020_LINEAR_EXT - supports the BT2020 color
space and applies a linear OETF.
** ename:VK_COLOR_SPACE_BT2020_NONLINEAR_EXT - supports the BT2020 color
space and applies the SMPTE 170M OETF.
** ename:VK_COLOR_SPACE_ADOBERGB_LINEAR_EXT - supports the AdobeRGB color
space and applies a linear OETF.
** ename:VK_COLOR_SPACE_ADOBERGB_NONLINEAR_EXT - supports the AdobeRGB
color space and applies the Gamma 2.2 OETF.
The color components of Non-linear color space swap chain images have had
the appropriate transfer function applied.
Vulkan requires that all implementations support the sRGB OETF and EOTF
transfer functions when using an SRGB pixel format.
Other transfer functions, such as SMPTE 170M, must not: be performed by the
implementation, but can: be performed by the application shader.
endif::VK_EXT_swapchain_colorspace[]
If pname:pSurfaceFormats includes an entry whose value for pname:colorSpace
is ename:VK_COLOR_SPACE_SRGB_NONLINEAR_KHR and whose value for pname:format

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

@ -1,4 +1,4 @@
// Copyright (c) 2014-2016 The Khronos Group Inc.
// Copyright (c) 2014-2017 The Khronos Group Inc.
// Copyright notice at https://www.khronos.org/registry/speccopyright.html
== WSI Swapchain
@ -227,6 +227,10 @@ effects that require them to run for all pixels in the presentable image.
include::../../validity/structs/VkSwapchainCreateInfoKHR.txt[]
ifdef::VK_EXT_display_control[]
include::../VK_EXT_display_control/swapchain_counters.txt[]
endif::VK_EXT_display_control[]
As mentioned above, if fname:vkCreateSwapchainKHR succeeds, it will return a
handle to a swapchain that contains an array of at least pname:minImageCount
presentable images.
@ -399,6 +403,9 @@ include::../../api/protos/vkAcquireNextImageKHR.txt[]
.Valid Usage
****
* pname:swapchain must: not have been replaced by being passed as the
sname:VkSwapchainCreateInfoKHR::pname:oldSwapchain value to
fname:vkCreateSwapchainKHR
* If pname:semaphore is not dlink:VK_NULL_HANDLE it must: be unsignaled
* 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

2
doc/specs/vulkan/chapters/VK_KHR_wayland_surface/platformCreateSurface_wayland.txt
View File

@ -1,4 +1,4 @@
// Copyright (c) 2014-2016 The Khronos Group Inc.
// Copyright (c) 2014-2017 The Khronos Group Inc.
// Copyright notice at https://www.khronos.org/registry/speccopyright.html
[[platformCreateSurface_wayland,platformCreateSurface_wayland]]

2
doc/specs/vulkan/chapters/VK_KHR_wayland_surface/platformQuerySupport_wayland.txt
View File

@ -1,4 +1,4 @@
// Copyright (c) 2014-2016 The Khronos Group Inc.
// Copyright (c) 2014-2017 The Khronos Group Inc.
// Copyright notice at https://www.khronos.org/registry/speccopyright.html
[[platformQuerySupport_walyand,platformQuerySupport_walyand]]

2
doc/specs/vulkan/chapters/VK_KHR_win32_surface/platformCreateSurface_win32.txt
View File

@ -1,4 +1,4 @@
// Copyright (c) 2014-2016 The Khronos Group Inc.
// Copyright (c) 2014-2017 The Khronos Group Inc.
// Copyright notice at https://www.khronos.org/registry/speccopyright.html
[[platformCreateSurface_win32,platformCreateSurface_win32]]

2
doc/specs/vulkan/chapters/VK_KHR_win32_surface/platformQuerySupport_win32.txt
View File

@ -1,4 +1,4 @@
// Copyright (c) 2014-2016 The Khronos Group Inc.
// Copyright (c) 2014-2017 The Khronos Group Inc.
// Copyright notice at https://www.khronos.org/registry/speccopyright.html
[[platformQuerySupport_win32,platformQuerySupport_win32]]

2
doc/specs/vulkan/chapters/VK_KHR_xcb_surface/platformCreateSurface_xcb.txt
View File

@ -1,4 +1,4 @@
// Copyright (c) 2014-2016 The Khronos Group Inc.
// Copyright (c) 2014-2017 The Khronos Group Inc.
// Copyright notice at https://www.khronos.org/registry/speccopyright.html
[[platformCreateSurface_xcb,platformCreateSurface_xcb]]

2
doc/specs/vulkan/chapters/VK_KHR_xcb_surface/platformQuerySupport_xcb.txt
View File

@ -1,4 +1,4 @@
// Copyright (c) 2014-2016 The Khronos Group Inc.
// Copyright (c) 2014-2017 The Khronos Group Inc.
// Copyright notice at https://www.khronos.org/registry/speccopyright.html
[[platformQuerySupport_xcb,platformQuerySupport_xcb]]

2
doc/specs/vulkan/chapters/VK_KHR_xlib_surface/platformCreateSurface_xlib.txt
View File

@ -1,4 +1,4 @@
// Copyright (c) 2014-2016 The Khronos Group Inc.
// Copyright (c) 2014-2017 The Khronos Group Inc.
// Copyright notice at https://www.khronos.org/registry/speccopyright.html
[[platformCreateSurface_xlib,platformCreateSurface_xlib]]

2
doc/specs/vulkan/chapters/VK_KHR_xlib_surface/platformQuerySupport_xlib.txt
View File

@ -1,4 +1,4 @@
// Copyright (c) 2014-2016 The Khronos Group Inc.
// Copyright (c) 2014-2017 The Khronos Group Inc.
// Copyright notice at https://www.khronos.org/registry/speccopyright.html
[[platformQuerySupport_xlib,platformQuerySupport_xlib]]

55
doc/specs/vulkan/chapters/VK_NN_vi_surface/platformCreateSurface_vi.txt Normal file
View File

@ -0,0 +1,55 @@
[[platformCreateSurface_vi,platformCreateSurface_vi]]
=== VI Platform
// refBegin vkCreateViSurfaceNN - Create a slink:VkSurfaceKHR object for a VI layer
To create a sname:VkSurfaceKHR object for an code:nn::code:vi::code:Layer,
query the layer's native handle using
code:nn::code:vi::code:GetNativeWindow, and then call:
include::../../api/protos/vkCreateViSurfaceNN.txt[]
* pname:instance is the instance with which to associate the surface.
* pname:pCreateInfo is a pointer to an instance of the
sname:VkViSurfaceCreateInfoNN structure containing parameters affecting
the creation of the surface object.
* pname:pAllocator is the allocator used for host memory allocated for the
surface object when there is no more specific allocator available (see
<<memory-allocation,Memory Allocation>>).
* pname:pSurface points to a sname:VkSurfaceKHR handle in which the
created surface object is returned.
During the lifetime of a surface created using a particular
code:nn::code:vi::code:NativeWindowHandle any attempts to create another
surface for the same code:nn::code:vi::code:Layer and any attempts to
connect to the same code:nn::code:vi::code:Layer through other platform
mechanisms will have undefined results.
The pname:currentExtent of a VI surface is always undefined.
Applications are expected to choose an appropriate size for the swapchain's
pname:imageExtent (e.g., by matching the the result of a call to
code:nn::code:vi::code:GetDisplayResolution).
include::../../validity/protos/vkCreateViSurfaceNN.txt[]
// refBegin VkViSurfaceCreateInfoNN - Structure specifying parameters of a newly created VI surface object
The sname:VkViSurfaceCreateInfoNN structure is defined as:
include::../../api/structs/VkViSurfaceCreateInfoNN.txt[]
* pname:sType is the type of this structure.
* pname:pNext is code:NULL or a pointer to an extension-specific
structure.
* pname:flags is reserved for future use.
* pname:window is the code:nn::code:vi::code:NativeWindowHandle for the
code:nn::code:vi::code:Layer with which to associate the surface.
.Valid Usage
****
* pname:window must: be a valid code:nn::code:vi::code:NativeWindowHandle
****
include::../../validity/structs/VkViSurfaceCreateInfoNN.txt[]

8
doc/specs/vulkan/chapters/VK_NN_vi_surface/platformQuerySupport_vi.txt Normal file
View File

@ -0,0 +1,8 @@
[[platformQuerySupport_vi,platformQuerySupport_vi]]
=== VI Platform
On VI, all physical devices and queue families must: be capable of
presentation with any layer.
As a result there is no VI-specific query for these capabilities.

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

@ -1,4 +1,4 @@
// Copyright (c) 2015-2016 The Khronos Group Inc.
// Copyright (c) 2015-2017 The Khronos Group Inc.
// Copyright notice at https://www.khronos.org/registry/speccopyright.html
[[clears]]
@ -42,6 +42,14 @@ pname:pColor.
.Valid Usage
****
ifdef::VK_KHR_maintenance1[]
* pname:image must: use a format that supports
ename:VK_FORMAT_FEATURE_TRANSFER_DST_BIT_KHR, 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[]
* pname:image must: have been created with
ename:VK_IMAGE_USAGE_TRANSFER_DST_BIT usage flag
* If pname:image is non-sparse then it must: be bound completely and
@ -90,6 +98,14 @@ include::../api/protos/vkCmdClearDepthStencilImage.txt[]
.Valid Usage
****
ifdef::VK_KHR_maintenance1[]
* pname:image must: use a format that supports
ename:VK_FORMAT_FEATURE_TRANSFER_DST_BIT_KHR, 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[]
* pname:image must: have been created with
ename:VK_IMAGE_USAGE_TRANSFER_DST_BIT usage flag
* If pname:image is non-sparse then it must: be bound completely and
@ -343,6 +359,10 @@ fname:vkCmdFillBuffer.
multiple of `4`
* pname:dstBuffer must: have been created with
ename:VK_BUFFER_USAGE_TRANSFER_DST_BIT usage flag
ifndef::VK_KHR_maintenance1[]
* The sname:VkCommandPool that pname:commandBuffer was allocated from
must: support graphics or compute operations
endif::VK_KHR_maintenance1[]
* If pname:dstBuffer is non-sparse then it must: be bound completely and
contiguously to a single sname:VkDeviceMemory object
****

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

@ -1,4 +1,4 @@
// Copyright (c) 2015-2016 The Khronos Group Inc.
// Copyright (c) 2015-2017 The Khronos Group Inc.
// Copyright notice at https://www.khronos.org/registry/speccopyright.html
[[commandbuffers]]
@ -154,6 +154,65 @@ include::../api/enums/VkCommandPoolCreateFlagBits.txt[]
include::../validity/structs/VkCommandPoolCreateInfo.txt[]
ifdef::VK_KHR_maintenance1[]
// refBegin vkTrimCommandPoolKHR Trim a command pool
To trim a command pool, call:
include::../api/protos/vkTrimCommandPoolKHR.txt[]
* pname:device is the logical device that owns the command pool.
* pname:commandPool is the command pool to trim.
* pname:flags is reserved for future use.
Trimming a command pool recycles unused memory from the command pool back to
the system.
Command buffers allocated from the pool are not affected by the command.
[NOTE]
.Note
====
This command provides applications with some control over the internal
memory allocations used by command pools.
Unused memory normally arises from command buffers that have been recorded
and later reset, such that they are no longer using the memory.
On reset, a command buffer can return memory to its command pool, but the
only way to release memory from a command pool to the system requires
calling flink:vkResetCommandPool, which cannot be executed while any command
buffers from that pool are still in use.
Subsequent recording operations into command buffers will re-use this memory
but since total memory requirements fluctuate over time, unused memory can
accumulate.
In this situation, trimming a command pool may: be useful to return unused
memory back to the system, returning the total outstanding memory allocated
by the pool back to a more "average" value.
Implementations utilize many internal allocation strategies that make it
impossible to guarantee that all unused memory is released back to the
system.
For instance, an implementation of a command pool may: involve allocating
memory in bulk from the system and sub-allocating from that memory.
In such an implementation any live command buffer that holds a reference to
a bulk allocation would prevent that allocation from being freed, even if
only a small proportion of the bulk allocation is in use.
In most cases trimming will result in a reduction in allocated but unused
memory, but it does not guarantee the "ideal" behaviour.
Trimming may: be an expensive operation, and should: not be called
frequently.
Trimming should: be treated as a way to relieve memory pressure after
application-known points when there exists enough unused memory that the
cost of trimming is "worth" it.
====
include::../validity/protos/vkTrimCommandPoolKHR.txt[]
endif::VK_KHR_maintenance1[]
// refBegin vkResetCommandPool Reset a command pool
To reset a command pool, call:
@ -236,6 +295,15 @@ include::../api/protos/vkAllocateCommandBuffers.txt[]
pname:commandBufferCount member of pname:pAllocateInfo.
Each allocated command buffer begins in the initial state.
ifdef::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
dlink:VK_NULL_HANDLE and return the error.
endif::VK_KHR_maintenance1[]
include::../validity/protos/vkAllocateCommandBuffers.txt[]
// refBegin VkCommandBufferAllocateInfo Structure specifying the allocation parameters for command buffer object

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

@ -1,4 +1,4 @@
// Copyright (c) 2015-2016 The Khronos Group Inc.
// Copyright (c) 2015-2017 The Khronos Group Inc.
// Copyright notice at https://www.khronos.org/registry/speccopyright.html
[[copies]]
@ -42,6 +42,20 @@ Some rules for valid operation are common to all copy commands:
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[]
* Source images must: use a format that supports
ename:VK_FORMAT_FEATURE_TRANSFER_SRC_BIT_KHR, 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
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[]
* 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
@ -243,6 +257,14 @@ images, but both images must: have the same number of samples.
* 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[]
* pname:srcImage must: use a format that supports
ename:VK_FORMAT_FEATURE_TRANSFER_SRC_BIT_KHR, 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[]
* pname:srcImage must: have been created with
ename:VK_IMAGE_USAGE_TRANSFER_SRC_BIT usage flag
* If pname:srcImage is non-sparse then it must: be bound completely and
@ -253,6 +275,14 @@ images, but both images must: have the same number of samples.
* pname:srcImageLayout must: be either of
ename:VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL or
ename:VK_IMAGE_LAYOUT_GENERAL
ifdef::VK_KHR_maintenance1[]
* pname:dstImage must: use a format that supports
ename:VK_FORMAT_FEATURE_TRANSFER_DST_BIT_KHR, 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[]
* pname:dstImage must: have been created with
ename:VK_IMAGE_USAGE_TRANSFER_DST_BIT usage flag
* If pname:dstImage is non-sparse then it must: be bound completely and
@ -286,10 +316,30 @@ include::../api/structs/VkImageCopy.txt[]
* pname:extent is the size in texels of the source image to copy in
pname:width, pname:height and pname:depth.
ifdef::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.
For images with multiple layers, copies are performed layer by layer
starting with the pname:baseArrayLayer member of the pname:srcSubresource or
pname:dstSubresource and copying pname:layerCount layers.
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[]
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[]
.Valid Usage
****
* The pname:aspectMask member of pname:srcSubresource and
pname:dstSubresource must: match
ifndef::VK_KHR_maintenance1[]
* The pname:layerCount member of pname:srcSubresource and
pname:dstSubresource must: match
* If either of the calling command's pname:srcImage or pname:dstImage
@ -297,6 +347,17 @@ include::../api/structs/VkImageCopy.txt[]
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[]
* 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
the pname:extent (for 3D) or layers of the pname:dstSubresource (for
non-3D)
* If either of the calling command's pname:srcImage or pname:dstImage
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[]
* The pname:aspectMask member of pname:srcSubresource must: specify
aspects present in the calling command's pname:srcImage
* The pname:aspectMask member of pname:dstSubresource must: specify
@ -316,6 +377,9 @@ include::../api/structs/VkImageCopy.txt[]
* If the calling command's pname:srcImage is of type
ename:VK_IMAGE_TYPE_1D or ename:VK_IMAGE_TYPE_2D, then pname:srcOffset.z
must: be `0` and pname:extent.depth must: be `1`.
* pname:srcSubresource.baseArrayLayer must: be less than and
(pname:srcSubresource.layerCount + pname:srcSubresource.baseArrayLayer)
must: be less than or equal to the number of layers in the source image
* pname:dstOffset.x and (pname:extent.width + pname:dstOffset.x) must:
both be greater than or equal to `0` and less than or equal to the
destination image subresource width
@ -331,6 +395,10 @@ include::../api/structs/VkImageCopy.txt[]
* If the calling command's pname:dstImage is of type
ename:VK_IMAGE_TYPE_1D or ename:VK_IMAGE_TYPE_2D, then pname:dstOffset.z
must: be `0` and pname:extent.depth must: be `1`.
* pname:dstSubresource.baseArrayLayer must: be less than and
(pname:dstSubresource.layerCount + pname:dstSubresource.baseArrayLayer)
must: be less than or equal to the number of layers in the destination
image
* If the calling command's pname:srcImage is a compressed format image:
** all members of pname:srcOffset must: be a multiple of the corresponding
dimensions of the compressed texel block
@ -425,6 +493,14 @@ source buffer to the specified region of the destination image.
in memory
* pname:srcBuffer must: have been created with
ename:VK_BUFFER_USAGE_TRANSFER_SRC_BIT usage flag
ifdef::VK_KHR_maintenance1[]
* pname:dstImage must: use a format that supports
ename:VK_FORMAT_FEATURE_TRANSFER_DST_BIT_KHR, 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[]
* If pname:srcBuffer is non-sparse then it must: be bound completely and
contiguously to a single sname:VkDeviceMemory object
* pname:dstImage must: have been created with
@ -471,6 +547,14 @@ source image to the specified region of the destination buffer.
* 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[]
* pname:srcImage must: use a format that supports
ename:VK_FORMAT_FEATURE_TRANSFER_SRC_BIT_KHR, 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[]
* pname:srcImage must: have been created with
ename:VK_IMAGE_USAGE_TRANSFER_SRC_BIT usage flag
* If pname:srcImage is non-sparse then it must: be bound completely and

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

@ -1,4 +1,4 @@
// Copyright (c) 2015-2016 The Khronos Group Inc.
// Copyright (c) 2015-2017 The Khronos Group Inc.
// Copyright notice at https://www.khronos.org/registry/speccopyright.html
[[descriptorsets]]
@ -1375,6 +1375,19 @@ Any returned error other than ename:VK_ERROR_FRAGMENTED_POOL does not imply
its usual meaning: applications should: assume that the allocation failed
due to fragmentation, and create a new descriptor pool.
ifdef::VK_KHR_maintenance1[]
If the allocation fails due to no more space in the descriptor pool, and not
because of system or device memory exhaustion, then
ename:VK_ERROR_OUT_OF_POOL_MEMORY_KHR must: be returned.
fname:vkAllocateDescriptorSets can: be used to create multiple descriptor
sets.
If the creation of any of those descriptor sets fails, then the
implementation must: destroy all successfully created descriptor set objects
from this command, set all entries of the pname:pDescriptorSets array to
dlink:VK_NULL_HANDLE and return the error.
endif::VK_KHR_maintenance1[]
[NOTE]
.Note
====

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

@ -1,4 +1,4 @@
// Copyright (c) 2015-2016 The Khronos Group Inc.
// Copyright (c) 2015-2017 The Khronos Group Inc.
// Copyright notice at https://www.khronos.org/registry/speccopyright.html
[[devsandqueues]]
@ -164,6 +164,47 @@ capabilities of the system, such as how many memory heaps there are.
// refEnd VkPhysicalDeviceType
ifdef::VK_KHR_get_physical_device_properties2[]
// refBegin vkGetPhysicalDeviceProperties2KHR Returns properties of a physical device
To query general properties of physical devices once enumerated, call:
include::../api/protos/vkGetPhysicalDeviceProperties2KHR.txt[]
* 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
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
indicating the value of that property or limit.
include::../validity/protos/vkGetPhysicalDeviceProperties2KHR.txt[]
// refBegin VkPhysicalDeviceProperties2KHR Structure specifying physical device properties
The sname:VkPhysicalDeviceProperties2KHR structure is defined as:
include::../api/structs/VkPhysicalDeviceProperties2KHR.txt[]
* pname:sType is the type of this structure.
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
* pname:properties is a structure of type slink:VkPhysicalDeviceProperties
describing the properties of the physical device.
This structure is written with the same values as if it were written by
flink:vkGetPhysicalDeviceProperties.
The pname:pNext chain of this structure is used to extend the structure with
properties defined by extensions.
include::../validity/structs/VkPhysicalDeviceProperties2KHR.txt[]
endif::VK_KHR_get_physical_device_properties2[]
// refBegin vkGetPhysicalDeviceQueueFamilyProperties Reports properties of the queues of the specified physical device
To query properties of queues available on a physical device, call:
@ -299,6 +340,44 @@ queried from the physical device.
For physical device feature queries see the <<features, Features>> chapter.
ifdef::VK_KHR_get_physical_device_properties2[]
// refBegin vkGetPhysicalDeviceQueueFamilyProperties2KHR Reports properties of the queues of the specified physical device
To query properties of queues available on a physical device, call:
include::../api/protos/vkGetPhysicalDeviceQueueFamilyProperties2KHR.txt[]
* pname:physicalDevice is the handle to the physical device whose
properties will be queried.
* pname:pQueueFamilyPropertyCount is a pointer to an integer related to
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.
fname:vkGetPhysicalDeviceQueueFamilyProperties2KHR behaves similarly to
flink:vkGetPhysicalDeviceQueueFamilyProperties, with the ability to return
extended information via chained output structures.
include::../validity/protos/vkGetPhysicalDeviceQueueFamilyProperties2KHR.txt[]
// refBegin VkQueueFamilyProperties2KHR Structure providing information about a queue family
The sname:VkQueueFamilyProperties2KHR structure is defined as:
include::../api/structs/VkQueueFamilyProperties2KHR.txt[]
* pname:sType is the type of this structure.
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
* pname:queueFamilyProperties is a structure of type
slink:VkQueueFamilyProperties which is populated with the same values as
in flink:vkGetPhysicalDeviceQueueFamilyProperties.
include::../validity/structs/VkQueueFamilyProperties2KHR.txt[]
endif::VK_KHR_get_physical_device_properties2[]
[[devsandqueues-devices]]
== Devices
@ -401,6 +480,16 @@ include::../api/structs/VkDeviceCreateInfo.txt[]
****
* The pname:queueFamilyIndex member of any given element of
pname:pQueueCreateInfos must: be unique within pname:pQueueCreateInfos
ifdef::VK_KHR_get_physical_device_properties2[]
* If the pname:pNext chain includes a slink:VkPhysicalDeviceFeatures2KHR
structure, then pname:pEnabledFeatures must: be `NULL`
endif::VK_KHR_get_physical_device_properties2[]
ifdef::VK_KHR_maintenance1[]
ifdef::VK_AMD_negative_viewport_height[]
* pname:ppEnabledExtensionNames must: not contain both
code:VK_KHR_maintenance1 and code:VK_AMD_negative_viewport_height
endif::VK_AMD_negative_viewport_height[]
endif::VK_KHR_maintenance1[]
****
include::../validity/structs/VkDeviceCreateInfo.txt[]

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

@ -1,4 +1,4 @@
// Copyright (c) 2015-2016 The Khronos Group Inc.
// Copyright (c) 2015-2017 The Khronos Group Inc.
// Copyright notice at https://www.khronos.org/registry/speccopyright.html
[[dispatch]]

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

@ -1,4 +1,4 @@
// Copyright (c) 2015-2016 The Khronos Group Inc.
// Copyright (c) 2015-2017 The Khronos Group Inc.
// Copyright notice at https://www.khronos.org/registry/speccopyright.html
[[drawing]]

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

@ -1,4 +1,4 @@
// Copyright (c) 2015-2016 The Khronos Group Inc.
// Copyright (c) 2015-2017 The Khronos Group Inc.
// Copyright notice at https://www.khronos.org/registry/speccopyright.html
[[extended-functionality]]
@ -340,6 +340,10 @@ In other cases, the decision is not so clear:
If some part of an instance extension's functionality might not be
available on all physical devices, the extension should: provide a query
to determine which physical devices provide the functionality.
ifdef::VK_KHR_get_physical_device_properties2[]
The +VK_KHR_get_physical_device_properties2+ extension allows such
functionality to be implemented as a device extension.
endif::VK_KHR_get_physical_device_properties2[]
* For a set of global functionality that provides new instance-level and
device-level commands, and can: be enabled for a subset of devices, it
is recommended that the functionality be partitioned across two

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

@ -1,4 +1,4 @@
// Copyright (c) 2015-2016 The Khronos Group Inc.
// Copyright (c) 2015-2017 The Khronos Group Inc.
// Copyright notice at https://www.khronos.org/registry/speccopyright.html
[[features]]
@ -20,12 +20,15 @@ implementation.
.Note on extensibility
====
The features and limits are reported via basic structures (that is
slink:VkPhysicalDeviceFeatures and slink:VkPhysicalDeviceLimits).
slink:VkPhysicalDeviceFeatures and slink:VkPhysicalDeviceLimits), as well as
extensible structures (sname:VkPhysicalDeviceFeatures2KHR and
sname:VkPhysicalDeviceProperties2KHR) which were added in
code:VK_KHR_get_physical_device_properties2.
It is expected that when new features or limits are added in a future Vulkan
version, new structure(s) and entry point(s) will be added as necessary to
query these.
New functionality added by <<extended-functionality-extensions,extensions>>
is not expected to modify the core feature and limit structures.
version or extensions, each extension should introduce one new feature
structure and/or limit structure (as needed) which can: be chained from the
sname:VkPhysicalDeviceFeatures2KHR and sname:VkPhysicalDeviceProperties2KHR
structures, respectively.
====
[[features-features]]
@ -67,14 +70,22 @@ fname:vkCreateDevice call.
If a member of pname:pEnabledFeatures is set to ename:VK_TRUE or
ename:VK_FALSE, then the device will be created with the indicated feature
enabled or disabled, respectively.
ifdef::VK_KHR_get_physical_device_properties2[]
Features can: also be enabled by using the
slink:VkPhysicalDeviceFeatures2KHR structure.
endif::VK_KHR_get_physical_device_properties2[]
If an application wishes to enable all features supported by a device, it
can: simply pass in the sname:VkPhysicalDeviceFeatures structure that was
previously returned by fname:vkGetPhysicalDeviceFeatures.
To disable an individual feature, the application can: set the desired
member to ename:VK_FALSE in the same structure.
Setting pname:pEnabledFeatures to `NULL` is equivalent to setting all
members of the structure to ename:VK_FALSE.
Setting pname:pEnabledFeatures to `NULL`
ifdef::VK_KHR_get_physical_device_properties2[]
and not including a slink:VkPhysicalDeviceFeatures2KHR in the pname:pNext
member of slink:VkDeviceCreateInfo
endif::VK_KHR_get_physical_device_properties2[]
is equivalent to setting all members of the structure to ename:VK_FALSE.
[NOTE]
.Note
@ -85,6 +96,50 @@ Application writers should: carefully consider the implications of enabling
all supported features.
====
ifdef::VK_KHR_get_physical_device_properties2[]
// refBegin vkGetPhysicalDeviceFeatures2KHR Reports capabilities of a physical device
To query supported features defined by the core or extensions, call:
include::../api/protos/vkGetPhysicalDeviceFeatures2KHR.txt[]
* pname:physicalDevice is the physical device from which to query the
supported features.
* pname:pFeatures is a pointer to a slink:VkPhysicalDeviceFeatures2KHR
structure in which the physical device features are returned.
Each structure in pname:pFeatures and its pname:pNext chain contain members
corresponding to fine-grained features.
fname:vkGetPhysicalDeviceFeatures2KHR writes each member to a boolean value
indicating whether that feature is supported.
include::../validity/protos/vkGetPhysicalDeviceFeatures2KHR.txt[]
// refBegin VkPhysicalDeviceFeatures2KHR Structure describing the fine-grained features that can be supported by an implementation
The sname:VkPhysicalDeviceFeatures2KHR structure is defined as:
include::../api/structs/VkPhysicalDeviceFeatures2KHR.txt[]
The sname:VkPhysicalDeviceFeatures2KHR structure is defined as:
* pname:sType is the type of this structure.
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
* pname:features is a structure of type slink:VkPhysicalDeviceFeatures
describing the fine-grained features of the Vulkan 1.0 API.
The pname:pNext chain of this structure is used to extend the structure with
features defined by extensions.
This structure can: be used in flink:vkGetPhysicalDeviceFeatures2KHR or can:
be in the pname:pNext chain of a slink:VkDeviceCreateInfo structure, in
which case it controls which features are enabled in the device in lieu of
pname:pEnabledFeatures.
include::../validity/structs/VkPhysicalDeviceFeatures2KHR.txt[]
endif::VK_KHR_get_physical_device_properties2[]
// refBegin VkPhysicalDeviceFeatures Structure describing the fine-grained features that can be supported by an implementation
The sname:VkPhysicalDeviceFeatures structure is defined as:
@ -3195,6 +3250,16 @@ If the format being queried is a depth/stencil format, this bit only
proportional to, or a weighted average of, the number of comparison
passes or failures.
ifdef::VK_KHR_maintenance1[]
ename:VK_FORMAT_FEATURE_TRANSFER_SRC_BIT_KHR::
sname:VkImage can: be used as a source image for <<copies, copy
commands>>.
ename:VK_FORMAT_FEATURE_TRANSFER_DST_BIT_KHR::
sname:VkImage can: be used as a destination image for <<copies, copy
commands>> and <<clears, clear commands>>.
endif::VK_KHR_maintenance1[]
ifdef::VK_IMG_filter_cubic[]
include::VK_IMG_filter_cubic/filter_cubic_sampled_bit_description.txt[]
endif::VK_IMG_filter_cubic[]
@ -3222,10 +3287,16 @@ flink:vkGetPhysicalDeviceFormatProperties::pname:format:
[NOTE]
.Note
====
ifndef::VK_KHR_maintenance1[]
If no format feature flags are supported, then the only possible use would
be image transfers - which alone are not useful.
As such, if no format feature flags are supported, the format itself is not
supported, and images of that format cannot be created.
endif::VK_KHR_maintenance1[]
ifdef::VK_KHR_maintenance1[]
If no format feature flags are supported, the format itself is not
supported, and images of that format cannot be created.
endif::VK_KHR_maintenance1[]
====
If pname:format is a block-compression format, then buffers must: not
@ -3233,6 +3304,43 @@ support any features for the format.
include::../validity/structs/VkFormatProperties.txt[]
ifdef::VK_KHR_get_physical_device_properties2[]
// refBegin vkGetPhysicalDeviceFormatProperties2KHR Lists physical device's format capabilities
To query supported format features which are properties of the physical
device, call:
include::../api/protos/vkGetPhysicalDeviceFormatProperties2KHR.txt[]
* pname:physicalDevice is the physical device from which to query the
format properties.
* pname:format is the format whose properties are queried.
* pname:pFormatProperties is a pointer to a slink:VkFormatProperties2KHR
structure in which physical device properties for pname:format are
returned.
fname:vkGetPhysicalDeviceFormatProperties2KHR behaves similarly to
flink:vkGetPhysicalDeviceFormatProperties, with the ability to return
extended information via chained output structures.
include::../validity/protos/vkGetPhysicalDeviceFormatProperties2KHR.txt[]
// refBegin VkFormatProperties2KHR Structure specifying image format properties
The sname:VkFormatProperties2KHR structure is defined as:
include::../api/structs/VkFormatProperties2KHR.txt[]
* pname:sType is the type of this structure.
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
* pname:formatProperties is a structure of type slink:VkFormatProperties
describing features supported by the requested format.
include::../validity/structs/VkFormatProperties2KHR.txt[]
endif::VK_KHR_get_physical_device_properties2[]
[[features-required-format-support]]
=== Required Format Support
@ -3248,6 +3356,12 @@ queried using the flink:vkGetPhysicalDeviceFormatProperties command.
The following tables show which feature bits must: be supported for each
format.
ifdef::VK_KHR_maintenance1[]
Formats that are required to support
ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_BIT must: also support
ename:VK_FORMAT_FEATURE_TRANSFER_SRC_BIT_KHR and
ename:VK_FORMAT_FEATURE_TRANSFER_DST_BIT_KHR.
endif::VK_KHR_maintenance1[]
.Key for format feature tables
[width="70%",cols="1,10"]
@ -3261,6 +3375,10 @@ where the symbol appears
.Feature bits in pname:optimalTilingFeatures
[width="70%"]
|====
ifdef::VK_KHR_maintenance1[]
|ename:VK_FORMAT_FEATURE_TRANSFER_SRC_BIT_KHR
|ename:VK_FORMAT_FEATURE_TRANSFER_DST_BIT_KHR
endif::VK_KHR_maintenance1[]
|ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_BIT
|ename:VK_FORMAT_FEATURE_BLIT_SRC_BIT
|ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BIT
@ -3818,6 +3936,239 @@ ifdef::VK_NV_external_memory_capabilities[]
include::./VK_NV_external_memory_capabilities/external_image_format.txt[]
endif::VK_NV_external_memory_capabilities[]
ifdef::VK_KHR_get_physical_device_properties2[]
// refBegin vkGetPhysicalDeviceImageFormatProperties2KHR Lists physical device's image format capabilities
To query additional capabilities specific to image types, call:
include::../api/protos/vkGetPhysicalDeviceImageFormatProperties2KHR.txt[]
* pname:physicalDevice is the physical device from which to query the
image capabilities.
* pname:pImageFormatInfo points to an instance of the
slink:VkPhysicalDeviceImageFormatInfo2KHR structure, describing the
parameters that would be consumed by flink:vkCreateImage.
* pname:pImageFormatProperties points to an instance of the
slink:VkImageFormatProperties2KHR structure in which capabilities are
returned.
fname:vkGetPhysicalDeviceImageFormatProperties2KHR behaves similarly to
flink:vkGetPhysicalDeviceImageFormatProperties, with the ability to return
extended information via chained output structures.
If the loader implementation emulates
fname:vkGetPhysicalDeviceImageFormatProperties2KHR on a device that doesn't
support the extension, and the query involves a structure the loader does
not support, fname:vkGetPhysicalDeviceImageFormatProperties2KHR returns
ename:VK_ERROR_FORMAT_NOT_SUPPORTED.
include::../validity/protos/vkGetPhysicalDeviceImageFormatProperties2KHR.txt[]
// refBegin VkPhysicalDeviceImageFormatInfo2KHR Structure specifying image creation parameters
The sname:VkPhysicalDeviceImageFormatInfo2KHR structure is defined as:
include::../api/structs/VkPhysicalDeviceImageFormatInfo2KHR.txt[]
* pname:sType is the type of this structure.
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
* pname:format is the image format, corresponding to
slink:VkImageCreateInfo::pname:format.
* pname:type is the image type, corresponding to
slink:VkImageCreateInfo::pname:imageType.
* pname:tiling is the image tiling, corresponding to
slink:VkImageCreateInfo::pname:tiling.
* pname:usage is the intended usage of the image, corresponding to
slink:VkImageCreateInfo::pname:usage.
* pname:flags is a bitmask describing additional parameters of the image,
corresponding to slink:VkImageCreateInfo::pname:flags.
The members of sname:VkPhysicalDeviceImageFormatInfo2KHR correspond to the
arguments to flink:vkGetPhysicalDeviceImageFormatProperties, with
pname:sType and pname:pNext added for extensibility.
include::../validity/structs/VkPhysicalDeviceImageFormatInfo2KHR.txt[]
// refBegin VkImageFormatProperties2KHR Structure specifying a image format properties
The sname:VkImageFormatProperties2KHR structure is defined as:
include::../api/structs/VkImageFormatProperties2KHR.txt[]
* pname:sType is the type of this structure.
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
* pname:imageFormatProperties is an instance of a
slink:VkImageFormatProperties structure in which capabilities are
returned.
If the combination of parameters to
fname:vkGetPhysicalDeviceImageFormatProperties2KHR is not supported by the
implementation for use in flink:vkCreateImage, then all members of
pname:imageFormatProperties will be filled with zero.
include::../validity/structs/VkImageFormatProperties2KHR.txt[]
ifdef::VK_KHX_external_memory_capabilities[]
// refBegin VkPhysicalDeviceExternalImageFormatInfoKHX Structure specifying external image creation parameters
To determine the image capabilities compatible with an external memory
handle type, add slink:VkPhysicalDeviceExternalImageFormatInfoKHX to the
pname:pNext chain of the slink:VkPhysicalDeviceImageFormatInfo2KHR structure
and sname:VkExternalImageFormatPropertiesKHX to the pname:pNext chain of the
slink:VkImageFormatProperties2KHR structure.
The sname:VkPhysicalDeviceExternalImageFormatInfoKHX structure is defined
as:
include::../api/structs/VkPhysicalDeviceExternalImageFormatInfoKHX.txt[]
* pname:sType is the type of this structure.
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
* pname:handleType is a bit indicating a memory handle type that will be
used with the memory associated with the image.
Bits which can be set include:
+
--
// refBegin VkExternalMemoryHandleTypeFlagBitsKHX - Bitmask of valid external memory handle types
include::../api/enums/VkExternalMemoryHandleTypeFlagBitsKHX.txt[]
--
+
** ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_FD_BIT_KHX is a POSIX file
descriptor handle that has only limited valid usage outside of Vulkan
and other compatible APIs.
It must: be compatible with the POSIX system calls fname:dup,
fname:dup2, fname:close, and the non-standard system call fname:dup3.
Additionally, it must: be transportable over a socket using an
ename:SCM_RIGHTS control message.
It owns a reference to the underlying memory resource represented by
its Vulkan memory object.
** ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_WIN32_BIT_KHX is an NT handle that
has only limited valid usage outside of Vulkan and other compatible
APIs.
It must: be compatible with the functions fname:DuplicateHandle,
fname:CloseHandle, fname:CompareObjectHandles,
fname:GetHandleInformation, and fname:SetHandleInformation.
It owns a reference to the underlying memory resource represented by
its Vulkan memory object.
** ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_KMT_BIT_KHX is a
global share handle that has only limited valid usage outside of Vulkan
and other compatible APIs.
It is not compatible with any native APIs.
It does not own own a reference to the underlying memory resource
represented its Vulkan memory object, and will therefore become invalid
when all Vulkan memory objects associated with it are destroyed.
** ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_BIT_KHX is an NT
handle returned by sname:IDXGIResource1::fname:CreateSharedHandle
referring to a Direct3D 10 or 11 texture resource.
It owns a reference to the memory used by the Direct3D resource.
** ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_KMT_BIT_KHX is a
global share handle returned by
sname:IDXGIResource::fname:GetSharedHandle referring to a Direct3D 10
or 11 texture resource.
It does not own own a reference to the underlying Direct3D resource,
and will therefore become invalid when all Vulkan memory objects and
Direct3D resources associated with it are destroyed.
** ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_HEAP_BIT_KHX is an NT handle
returned by sname:ID3D12Device::fname:CreateSharedHandle referring to a
Direct3D 12 heap resource.
It owns a reference to the resources used by the Direct3D heap.
** ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_RESOURCE_BIT_KHX is an NT
handle returned by sname:ID3D12Device::fname:CreateSharedHandle
referring to a Direct3D 12 committed resource.
It owns a reference to the memory used by the Direct3D resource.
If pname:handleType is 0, flink:vkGetPhysicalDeviceImageFormatProperties2KHR
will behave as if slink:VkPhysicalDeviceExternalImageFormatInfoKHX was not
present and slink:VkExternalImageFormatPropertiesKHX will be ignored.
If pname:handleType is not compatible with the pname:format, pname:type,
pname:tiling, pname:usage, and pname:flags specified in
slink:VkPhysicalDeviceImageFormatInfo2KHR, then
flink:vkGetPhysicalDeviceImageFormatProperties2KHR returns
ename:VK_ERROR_FORMAT_NOT_SUPPORTED.
include::../validity/structs/VkPhysicalDeviceExternalImageFormatInfoKHX.txt[]
// refBegin VkExternalImageFormatPropertiesKHX Structure specifying supported external handle properties
The sname:VkExternalImageFormatPropertiesKHX structure is defined as:
include::../api/structs/VkExternalImageFormatPropertiesKHX.txt[]
* pname:sType is the type of this structure.
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
* pname:externalMemoryProperties is an instance of the
slink:VkExternalMemoryPropertiesKHX structure specifying various
capabilities of the external handle type when used with the specified
image creation parameters.
include::../validity/structs/VkExternalImageFormatPropertiesKHX.txt[]
// refBegin VkExternalMemoryPropertiesKHX Structure specifying external memory handle type capabilities
The sname:VkExternalMemoryPropertiesKHX structure is defined as:
include::../api/structs/VkExternalMemoryPropertiesKHX.txt[]
* pname:externalMemoryFeatures is a bitmask describing the features of
pname:handleType.
See elink:VkExternalMemoryFeatureFlagBitsKHX below for a description of
the possible bits.
* pname:exportFromImportedHandleTypes is a bitmask specifying handle types
that can be used to import objects from which pname:handleType can be
exported.
* pname:compatibleHandleTypes is a bitmask specifying handle types which
can be specified at the same time as pname:handleType when creating an
image compatible with external memory.
pname:compatibleHandleTypes must: include at least pname:handleType.
Inclusion of a handle type in pname:compatibleHandleTypes does not imply the
values returned in slink:VkImageFormatProperties2KHR will be the same when
slink:VkPhysicalDeviceExternalImageFormatInfoKHX::pname:handleType is set to
that type.
The application is responsible for querying the capabilities of all handle
types intended for concurrent use in a single image and intersecting them to
obtain the compatible set of capabilities.
include::../validity/structs/VkExternalMemoryPropertiesKHX.txt[]
// refBegin VkExternalMemoryFeatureFlagBitsKHX Bitmask specifying features of an external memory handle type
The features of an external memory handle type are returned in
slink:VkExternalMemoryPropertiesKHX::pname:externalMemoryFeatures.
Bits which may: be set include:
include::../api/enums/VkExternalMemoryFeatureFlagBitsKHX.txt[]
These bits have the following meanings:
* ename:VK_EXTERNAL_MEMORY_FEATURE_DEDICATED_ONLY_BIT_KHX indicates that
images or buffers created with the specified parameters and handle type
must: use the mechanisms defined in the ename:VK_NV_dedicated_allocation
to create (or import) a dedicated allocation for the image or buffer.
* ename:VK_EXTERNAL_MEMORY_FEATURE_EXPORTABLE_BIT_KHX indicates handles of
this type can: be exported from Vulkan memory objects.
* ename:VK_INTERNAL_MEMORY_FEATURE_IMPORTABLE_BIT_KHX indicates handles of
this type can: be imported as Vulkan memory objects.
Because their semantics in external APIs roughly align with that of an image
or buffer with a dedicated allocation in Vulkan, implementations are
required: to report ename:VK_EXTERNAL_MEMORY_FEATURE_DEDICATED_ONLY_BIT_KHX
for the following external handle types:
* ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_BIT_KHX
* ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_KMT_BIT_KHX
* ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_RESOURCE_BIT_KHX
// refEnd VkExternalMemoryFeatureFlagBitsKHX
endif::VK_KHX_external_memory_capabilities[]
endif::VK_KHR_get_physical_device_properties2[]
[[features-supported-sample-counts]]
=== Supported Sample Counts

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

@ -1,4 +1,4 @@
// Copyright (c) 2015-2016 The Khronos Group Inc.
// Copyright (c) 2015-2017 The Khronos Group Inc.
// Copyright notice at https://www.khronos.org/registry/speccopyright.html
[[fragops]]
@ -71,6 +71,10 @@ values determining the size in pixels.
sname:VkPhysicalDeviceLimits::pname:maxViewports
* The sum of pname:firstScissor and pname:scissorCount must: be between
`1` and sname:VkPhysicalDeviceLimits::pname:maxViewports, inclusive
* If the <<features-features-multiViewport,multiple viewports>> feature is
not enabled, pname:firstScissor must: be `0`
* If the <<features-features-multiViewport,multiple viewports>> feature is
not enabled, pname:scissorCount must: be `1`
* The pname:x and pname:y members of pname:offset must: be greater than or
equal to `0`
* Evaluation of (pname:offset.x + pname:extent.width) must: not cause a

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

@ -1,4 +1,4 @@
// Copyright (c) 2015-2016 The Khronos Group Inc.
// Copyright (c) 2015-2017 The Khronos Group Inc.
// Copyright notice at https://www.khronos.org/registry/speccopyright.html
[[framebuffer]]

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

@ -1,4 +1,4 @@
// Copyright (c) 2015-2016 The Khronos Group Inc.
// Copyright (c) 2015-2017 The Khronos Group Inc.
// Copyright notice at https://www.khronos.org/registry/speccopyright.html
[[fundamentals]]
@ -885,6 +885,10 @@ 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 There is no more memory in the
descriptor set pool.
endif::VK_KHR_maintenance1[]
If a command returns a run time error, it will leave any result pointers
unmodified, unless other behavior is explicitly defined in the

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

@ -1,4 +1,4 @@
// Copyright (c) 2015-2016 The Khronos Group Inc.
// Copyright (c) 2015-2017 The Khronos Group Inc.
// Copyright notice at https://www.khronos.org/registry/speccopyright.html
[[fxvertex]]

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

@ -1,4 +1,4 @@
// Copyright (c) 2015-2016 The Khronos Group Inc.
// Copyright (c) 2015-2017 The Khronos Group Inc.
// Copyright notice at https://www.khronos.org/registry/speccopyright.html
[[geometry]]

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

@ -1,4 +1,4 @@
// Copyright (c) 2015-2016 The Khronos Group Inc.
// Copyright (c) 2015-2017 The Khronos Group Inc.
// Copyright notice at https://www.khronos.org/registry/speccopyright.html
[[initialization]]
@ -118,6 +118,30 @@ include::../api/funcpointers/PFN_vkVoidFunction.txt[]
// refEnd PFN_vkVoidFunction vkGetDeviceProcAddr vkGetInstanceProcAddr
ifdef::VK_KHR_get_physical_device_properties2[]
=== 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
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.
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 doesn't support the extension.
Device extensions may: define structures that can: be added to the
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 doesn't support the extension.
endif::VK_KHR_get_physical_device_properties2[]
[[initialization-instances]]
== Instances

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

@ -1,4 +1,4 @@
// Copyright (c) 2015-2016 The Khronos Group Inc.
// Copyright (c) 2015-2017 The Khronos Group Inc.
// Copyright notice at https://www.khronos.org/registry/speccopyright.html
[[interfaces]]
@ -14,6 +14,18 @@ a number of different interfaces.
* <<interfaces-inputattachment,Fragment Input Attachment Interface>>
* <<interfaces-resources,Shader Resource Interface>>
Interface definitions make use of the following SPIR-V decorations:
* code:DescriptorSet and code:Binding
* code:Location, code:Component, and code:Index
* code:Flat, code:NoPerspective, code:Centroid, and code:Sample
* code:Block and code:BufferBlock
* code:InputAttachmentIndex
* code:Offset, code:ArrayStride, and code:MatrixStride
* code:BuiltIn
This specification describes valid uses for Vulkan of these decorations.
Any other use of one of these decorations is invalid.
[[interfaces-iointerfaces]]
== Shader Input and Output Interfaces
@ -775,6 +787,50 @@ identity I + J + K = 1.0.
endif::VK_AMD_shader_explicit_vertex_parameter[]
ifdef::VK_KHR_shader_draw_parameters[]
[[interfaces-builtin-variables-baseinstance]]
code:BaseInstance::
Decorating a variable with the code:BaseInstance built-in will make that
variable contain the integer value corresponding to the first instance that
was passed to the command that invoked the current vertex shader invocation.
code:BaseInstance is the pname:firstInstance parameter to a _direct drawing
command_ or the pname:firstInstance member of a structure consumed by an
_indirect drawing command_.
+
The code:BaseInstance decoration must: be used only within vertex shaders.
+
The variable decorated with BaseInstance must: be declared using the input
storage class.
+
The variable decorated with BaseInstance must: be declared as a scalar
32-bit integer.
[[interfaces-builtin-variables-basevertex]]
code:BaseVertex::
Decorating a variable with the code:BaseVertex built-in will make that
variable contain the integer value corresponding to the first vertex or
vertex offset that was passed to the command that invoked the current vertex
shader invocation.
For _non-indexed drawing commands_, this variable is the pname:firstVertex
parameter to a _direct drawing command_ or the pname:firstVertex member of
the structure consumed by an _indirect drawing command_.
For _indexed drawing commands_, this variable is the pname:vertexOffset
parameter to a _direct drawing command_ or the pname:vertexOffset member of
the structure consumed by an _indirect drawing command_.
+
The code:BaseVertex decoration must: be used only within vertex shaders.
+
The variable decorated with code:BaseVertex must: be declared using the
input storage class.
+
The variable decorated with codeBaseVertex must: be declared as a scalar
32-bit integer.
endif::VK_KHR_shader_draw_parameters[]
code:ClipDistance::
Decorating a variable with the code:ClipDistance built-in decoration will
@ -858,6 +914,30 @@ the corresponding value from the code:CullDistance decorated output variable
from the previous shader stage.
====
ifdef::VK_KHR_shader_draw_parameters[]
[[interfaces-builtin-variables-drawindex]]
code:DrawIndex::
Decorating a variable with the code:DrawIndex built-in will make that
variable contain the integer value corresponding to the zero-based index of
the drawing command that invoked the current vertex shader invocation.
For _indirect drawing commands_, code:DrawIndex begins at zero and
increments by one for each draw command executed.
The number of draw commands is given by the pname:drawCount parameter.
For _direct drawing commands_, code:DrawIndex is always zero.
code:DrawIndex is dynamically uniform.
+
The code:DrawIndex decoration must: be used only within vertex shaders.
+
The variable decorated with code:DrawIndex must: be declared using the input
storage class.
+
The variable decorated with code:DrawIndex must: be declared as a scalar
32-bit integer.
endif::VK_KHR_shader_draw_parameters[]
code:FragCoord::
Decorating a variable with the code:FragCoord built-in decoration will make
@ -883,7 +963,8 @@ The code:FragCoord decoration must: be used only within fragment shaders.
The variable decorated with code:FragCoord must: be declared using the
code:Input storage class.
+
The code:Centroid interpolation decoration is ignored on code:FragCoord.
The code:Centroid interpolation decoration is ignored, but allowed, on
code:FragCoord.
+
The variable decorated with code:FragCoord must: be declared as a
four-component vector of 32-bit floating-point values.
@ -1325,6 +1406,123 @@ code:Input storage class.
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[]
[[interfaces-builtin-variables-sgeq]]
code:SubgroupEqMaskKHR::
+
Decorating a variable with the code:SubgroupEqMaskKHR 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.
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:SubgroupEqMaskKHR must: be declared as a
four-component vector of 32-bit integer values.
[[interfaces-builtin-variables-sgge]]
code:SubgroupGeMaskKHR::
+
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
code:SubgroupLocalInvocationId through code:SubgroupSize-1 are set in the
variable decorated with code:SubgroupGeMaskKHR.
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:SubgroupGeMaskKHR must: be declared as a
four-component vector of 32-bit integer values.
[[interfaces-builtin-variables-sggt]]
code:SubgroupGtMaskKHR::
+
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.
The bits corresponding to the invocations greater than
code:SubgroupLocalInvocationId through code:SubgroupSize-1 are set in the
variable decorated with code:SubgroupGtMaskKHR.
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:SubgroupGtMaskKHR must: be declared as a
four-component vector of 32-bit integer values.
[[interfaces-builtin-variables-sgle]]
code:SubgroupLeMaskKHR::
+
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.
The bits corresponding to the invocations less than or equal to
code:SubgroupLocalInvocationId are set in the variable decorated with
code:SubgroupLeMaskKHR.
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:SubgroupLeMaskKHR must: be declared as a
four-component vector of 32-bit integer values.
[[interfaces-builtin-variables-sglt]]
code:SubgroupLtMaskKHR::
+
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.
The bits corresponding to the invocations less than
code:SubgroupLocalInvocationId are set in the variable decorated with
code:SubgroupLtMaskKHR.
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:SubgroupLtMaskKHR must: be declared as a
four-component vector of 32-bit integer values.
[[interfaces-builtin-variables-sgli]]
code:SubgroupLocalInvocationId::
+
Decorating a variable with the code:SubgroupLocalInvocationId builtin
decoration will make that variable contain the index of the invocation
within the subgroup.
This variable is in range [0,code:SubgroupSize-1].
+
The variable decorated with code:SubgroupLocalInvocationId must: be declared
using the code:Input storage class.
+
The variable decorated with code:SubgroupLocalInvocationId must: be declared
as a scalar 32-bit integer.
[[interfaces-builtin-variables-sgs]]
code:SubgroupSize::
+
Decorating a variable with the code:SubgroupSize builtin decoration will
make that variable contain the implementation-dependent maximum number of
invocations in a subgroup.
The maximum number of invocations that an implementation can support per
subgroup is 128.
+
The variable decorated with code:SubgroupSize must: be declared using the
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[]
code:TessCoord::
Decorating a variable with the code:TessCoord built-in decoration will make

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

@ -1,4 +1,4 @@
// Copyright (c) 2015-2016 The Khronos Group Inc.
// Copyright (c) 2015-2017 The Khronos Group Inc.
// Copyright notice at https://www.khronos.org/registry/speccopyright.html
[[introduction]]

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

@ -1,4 +1,4 @@
// Copyright (c) 2015-2016 The Khronos Group Inc.
// Copyright (c) 2015-2017 The Khronos Group Inc.
// Copyright notice at https://www.khronos.org/registry/speccopyright.html
[[memory]]
@ -569,6 +569,41 @@ properties such as "0" or "host-visible and coherent".
include::../validity/structs/VkPhysicalDeviceMemoryProperties.txt[]
ifdef::VK_KHR_get_physical_device_properties2[]
// refBegin vkGetPhysicalDeviceMemoryProperties2KHR Reports memory information for the specified physical device
To query memory properties, call:
include::../api/protos/vkGetPhysicalDeviceMemoryProperties2KHR.txt[]
* pname:physicalDevice is the handle to the device to query.
* pname:pMemoryProperties points to an instance of
sname:VkPhysicalDeviceMemoryProperties2KHR structure in which the
properties are returned.
fname:vkGetPhysicalDeviceMemoryProperties2KHR behaves similarly to
flink:vkGetPhysicalDeviceMemoryProperties, with the ability to return
extended information via chained output structures.
include::../validity/protos/vkGetPhysicalDeviceMemoryProperties2KHR.txt[]
// refBegin VkPhysicalDeviceMemoryProperties2KHR Structure specifying physical device memory properties
The sname:VkPhysicalDeviceMemoryProperties2KHR structure is defined as:
include::../api/structs/VkPhysicalDeviceMemoryProperties2KHR.txt[]
* pname:sType is the type of this structure.
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
* pname:memoryProperties is a structure of type
slink:VkPhysicalDeviceMemoryProperties which is populated with the same
values as in flink:vkGetPhysicalDeviceMemoryProperties.
include::../validity/structs/VkPhysicalDeviceMemoryProperties2KHR.txt[]
endif::VK_KHR_get_physical_device_properties2[]
// refBegin VkMemoryHeap Structure specifying a memory heap
The sname:VkMemoryHeap structure is defined as:

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

@ -1,4 +1,4 @@
// Copyright (c) 2015-2016 The Khronos Group Inc.
// Copyright (c) 2015-2017 The Khronos Group Inc.
// Copyright notice at https://www.khronos.org/registry/speccopyright.html
[[pipelines]]
@ -142,6 +142,10 @@ endif::editing-notes[]
pname:basePipelineIndex member of that same element is not `-1`,
pname:basePipelineIndex must: be less than the index into
pname:pCreateInfos that corresponds to that element
* If the pname:flags member of any given element of pname:pCreateInfos
contains the ename:VK_PIPELINE_CREATE_DERIVATIVE_BIT flag, the base
pipeline must: have been created with the
ename:VK_PIPELINE_CREATE_ALLOW_DERIVATIVES_BIT flag set
****
include::../validity/protos/vkCreateComputePipelines.txt[]
@ -329,6 +333,10 @@ pipeline layout.
pname:basePipelineIndex member of that same element is not `-1`,
pname:basePipelineIndex must: be less than the index into
pname:pCreateInfos that corresponds to that element
* If the pname:flags member of any given element of pname:pCreateInfos
contains the ename:VK_PIPELINE_CREATE_DERIVATIVE_BIT flag, the base
pipeline must: have been created with the
ename:VK_PIPELINE_CREATE_ALLOW_DERIVATIVES_BIT flag set
****
include::../validity/protos/vkCreateGraphicsPipelines.txt[]

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