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

Merge misc. tweaks from private repository.

This commit is contained in:
Jon Leech 2016-07-10 18:35:55 -07:00
parent 89287838ea e2d981c029
commit 0dab353ee2
650 changed files with 32729 additions and 13980 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

11
.gitignore vendored
View File

@ -34,14 +34,9 @@
__pycache__
# Spec build temporary files and outputs
out/checks
out/html
out/xhtml
out/vkspec*
out/apispec*
out/man
out/pdf
out/core
out/1.0*
out/genRef
out/misc
doc/specs/vulkan/specversion.txt
# Header build temporary files

21
ChangeLog.txt
View File

@ -923,3 +923,24 @@ Other Commits:
wasn't listed in the error codes.
* Fix "correponds" typo in member definitions for
slink:VkSubpassDescription.
-----------------------------------------------------
Change log for July 8, 2016 Vulkan 1.0.20 spec update:
* Bump API patch number and header version number to 20 for this
update.
Github Issues:
* Replaced existing reference pages by text automatically extracted
from the specification source, or generated from vk.xml in some
cases. This isn't a complete solution for the reference pages, but
puts them in a much better state. The ref pages (only) are now
placed under a CC BY open source license, which is more current than
the obsolete license previously used.
Further improvements to the pages should not edit them directly, but
instead concentrate on the specification source from which the ref
pages are being extracted (public issues 44, 55, 160; internal issue
389).

79
doc/specs/vulkan/Makefile
View File

@ -93,7 +93,7 @@ A2XDBLATEXOPTS := --dblatex-opts='$(DBLATEXOPTS)'
# Misc. files to clean up (see 'checkinc' target below)
DIRT = $(SPECVERSION)
.PHONY: directories
.PHONY: directories $(MANHTMLDIR) $(MANPAGEDIR)
ICONFILES := \
$(ICONPATH)/caution.png \
@ -118,14 +118,15 @@ SVGTYPEHTML := svg
SVGTYPEPDF := pdf
# Main (root) asciidoc spec source file
TOPDOC := vkspec.txt
# Included chapters of the API spec
CHAPTERS := $(wildcard chapters/[A-Za-z]*.txt appendices/[A-Za-z]*.txt chapters/wsi/[A-Za-z]*.txt)
# Files making up sections of the API spec. The wildcard expression
# should work in extension branches to pull in those files as well.
CHAPTERS := $(wildcard chapters/[A-Za-z]*.txt appendices/[A-Za-z]*.txt chapters/*/[A-Za-z]*.txt appendices/*/[A-Za-z]*.txt)
INCLUDES := $(wildcard protos/*.txt structs/*.txt flags/*.txt enums/*.txt funcpointers/*.txt validity/structs/*.txt validity/protos/*.txt)
# All non-format-specific dependencies
COMMONDOCS := $(CHAPTERS) $(INCLUDES)
# A generated included file with the spec version, date, and git commit
SPECVERSION = specversion.txt
SPECREVISION = 1.0.19
SPECREVISION = 1.0.20
SPECREMARK =
# Spec targets
@ -203,7 +204,13 @@ $(OUTDIR)/styleguide.html: $(VKCONF) $(SPECVERSION) $(STYLESRC)
-o $(OUTDIR)/styleguide.html -a svgpdf=$(SVGTYPEHTML) \
$(STYLESRC)
clean: clean_html clean_pdf clean_chunked clean_checks clean_dirt
clean: clean_html clean_pdf clean_chunked clean_checks clean_dirt clean_man
clean_man:
$(RM) $(MANHTML)
$(RMRF) $(MANHTMLDIR)
$(RM) $(MANPAGES)
$(RMRF) $(MANPAGEDIR)
clean_html:
$(QUIET)$(RMRF) $(HTMLDIR) $(XHTMLDIR)
@ -221,9 +228,59 @@ clean_checks:
clean_dirt:
$(QUIET)$(RM) $(DIRT)
# Man page targets for individual pages
MANDIR:=man
-include man/manpages.mak
# Ref page targets for individual pages
MANDIR := man
MANSECTION := 3
# These lists should be autogenerated
# Ref page sources, split up by core vs. author IDs
# CORESOURCES expansion will accidentally pull in macros defined by
# extensions. Hopefully that won't happen.
WSISOURCES := $(wildcard $(MANDIR)/*KHR.txt)
EXTSOURCES := $(wildcard $(MANDIR)/*EXT.txt)
CORESOURCES := $(filter-out $(WSISOURCES) $(EXTSOURCES) $(MANDIR)/vkman.css,$(wildcard $(MANDIR)/[Vv][Kk]* $(MANDIR)/PFN*txt))
MANSOURCES := $(CORESOURCES) $(WSISOURCES) $(EXTSOURCES)
MANCOPYRIGHT:= $(MANDIR)/khronoscopyright.txt $(MANDIR)/footer.txt
MANPAGEDIR := $(OUTDIR)/man/$(MANSECTION)
MANPAGES := $(MANSOURCES:$(MANDIR)/%.txt=$(MANPAGEDIR)/%.$(MANSECTION))
MANHTMLDIR := $(OUTDIR)/man/html
MANHTML := $(MANSOURCES:$(MANDIR)/%.txt=$(MANHTMLDIR)/%.html)
manpagesall: manpages manhtmlpages
manpages: $(MANPAGEDIR) $(MANPAGES)
manhtmlpages: $(MANHTMLDIR) $(MANHTML)
manhtmlpages: VKCONF=config/manpages.conf
# Automatic generation of ref pages. Needs to have a proper dependency
# causing the man page sources to be generated by running genRef (once),
# but adding $(MANSOURCES) to the targets causes genRef to run
# once/target.
man/apispec.txt: $(CHAPTERS) genRef.py reflib.py vkapi.py
$(PYTHON) genRef.py $(CHAPTERS)
# These dependencies don't take into account include directives
$(MANPAGEDIR)/%.$(MANSECTION): $(MANDIR)/%.$(MANSECTION)
$(QUIET)mv $< $@
$(MANDIR)/%.$(MANSECTION): $(MANDIR)/%.txt $(MANCOPYRIGHT) config/manpages.conf
$(QUIET)$(ECHO) Building $@
$(QUIET)$(A2X) -d manpage -f manpage --asciidoc-opts "-f config/manpages.conf" $(A2XOPTS) $<
$(MANHTMLDIR)/%.html: $(MANDIR)/%.txt $(MANCOPYRIGHT) config/manpages.conf
$(QUIET)$(ECHO) Building $@
$(QUIET)$(A2X) -d manpage -f xhtml --asciidoc-opts "-f config/manpages.conf" --stylesheet=vkman.css $(A2XOPTS) --destination-dir=$(@D) $<
$(MANHTMLDIR):
$(QUIET)$(MKDIR) $@
$(MANPAGEDIR):
$(QUIET)$(MKDIR) $@
# Man page targets for HTML and PDF single-file documents
@ -231,13 +288,13 @@ manpdf: $(OUTDIR)/apispec.pdf
manhtml: $(OUTDIR)/apispec.html
$(OUTDIR)/apispec.pdf: $(CONFFILE) man/apispec.txt $(MANSOURCES) $(PDFXSL)
$(OUTDIR)/apispec.pdf: $(CONFFILE) man/apispec.txt $(MANSOURCES) $(MANCOPYRIGHT) $(PDFXSL)
$(QUIET)if test ! -d $(OUTDIR) ; then $(MKDIR) $(OUTDIR) ; fi
$(QUIET)$(A2X) -f pdf $(A2XDBLATEXOPTS) $(A2XOPTS) --icons man/apispec.txt --destination-dir=$(OUTDIR)
$(OUTDIR)/apispec.html: $(CONFFILE) man/apispec.txt $(MANSOURCES) $(SVGFILES)
$(OUTDIR)/apispec.html: $(CONFFILE) man/apispec.txt $(MANSOURCES) $(MANCOPYRIGHT) $(SVGFILES)
$(QUIET)if test ! -d $(OUTDIR) ; then $(MKDIR) $(OUTDIR) ; fi
$(QUIET)$(ASCIIDOC) $(ADOCOPTS) -d book -b html --out-file=$(OUTDIR)/apispec.html man/apispec.txt
$(QUIET)$(ASCIIDOC) -b html5 $(ADOCOPTS) -d book -b html --out-file=$(OUTDIR)/apispec.html man/apispec.txt
$(HTMLDIR)/images/%: images/%
$(QUIET)$(MKDIR) $(@D)

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

@ -755,6 +755,11 @@ asciidoc.install();
</li>
<li>
<p>
<a href="#refpages">Reference Pages</a>
</p>
</li>
<li>
<p>
<a href="#styles">Our stylesheets</a>
</p>
</li>
@ -792,7 +797,7 @@ specification and reference pages building properly.</p></div>
<h2 id="building">Building The Spec</h2>
<div class="sectionbody">
<div class="paragraph"><p>Assuming you have all the right tools installed (see <a href="#depends">Software Dependencies</a> below), you should be able to go to
&#8230;path-to-git-repo/vulkan/doc/specs/vulkan and:</p></div>
<span class="monospaced">&#8230;path-to-git-repo/vulkan/doc/specs/vulkan</span> and:</p></div>
<div class="literalblock">
<div class="content monospaced">
<pre>$ make all</pre>
@ -802,9 +807,9 @@ specification and reference pages building properly.</p></div>
<div class="content monospaced">
<pre>$ make xhtml chunked pdf manhtml manpdf manpages manhtmlpages checkinc checklinks</pre>
</div></div>
<div class="paragraph"><p>This should generate a variety of targets under $(OUTDIR) (by default,
../../../out/). The checked-in file $(OUTDIR)/index.html links to them
all, or they can individually be found as follows:</p></div>
<div class="paragraph"><p>This should generate a variety of targets under <span class="monospaced">$(OUTDIR)</span> (by default,
<span class="monospaced">../../../out/1.0</span>). The checked-in file <span class="monospaced">$(OUTDIR)/index.html</span> links to
them all, or they can individually be found as follows:</p></div>
<div class="ulist"><ul>
<li>
<p>
@ -813,17 +818,17 @@ API spec:
<div class="ulist"><ul>
<li>
<p>
Single-file XHTML (from a2x) - $(OUTDIR)/xhtml/vkspec.html
Single-file XHTML (from a2x) - <span class="monospaced">$(OUTDIR)/xhtml/vkspec.html</span>
</p>
</li>
<li>
<p>
Chunked HTML (from a2x) - $(OUTDIR)/vkspec.chunked/index.html
Chunked HTML (from a2x) - <span class="monospaced">$(OUTDIR)/vkspec.chunked/index.html</span>
</p>
</li>
<li>
<p>
PDF (from a2x) - $(OUTDIR)/pdf/vkspec.pdf
PDF (from a2x) - <span class="monospaced">$(OUTDIR)/pdf/vkspec.pdf</span>
</p>
</li>
</ul></div>
@ -835,17 +840,17 @@ Man pages:
<div class="ulist"><ul>
<li>
<p>
Single-file HTML - $(OUTDIR)/apispec.html
Single-file HTML - <span class="monospaced">$(OUTDIR)/apispec.html</span>
</p>
</li>
<li>
<p>
File-per-entry-point HTML - $(OUTDIR)/man/html/*
File-per-entry-point HTML - <span class="monospaced">$(OUTDIR)/man/html/*</span>
</p>
</li>
<li>
<p>
File-per-entry-point nroff source - $(OUTDIR)/man/3/*
File-per-entry-point nroff source - <span class="monospaced">$(OUTDIR)/man/3/*</span>
</p>
</li>
</ul></div>
@ -858,65 +863,62 @@ Validator output:
<li>
<p>
List of commands, structs, etc. missing from the API spec -
$(OUTDIR)/checks/notInSpec.txt
<span class="monospaced">$(OUTDIR)/checks/notInSpec.txt</span>
</p>
</li>
<li>
<p>
Validator script output for API spec - $(OUTDIR)/checks/specErrs.txt
Validator script output for API spec - +$(OUTDIR)/checks/specErrs.txt
</p>
</li>
<li>
<p>
Validator script output for reference pages -
$(OUTDIR)/checks/manErrs.txt
<span class="monospaced">$(OUTDIR)/checks/manErrs.txt</span>
</p>
</li>
</ul></div>
</li>
</ul></div>
<div class="paragraph"><p>We strongly sugges that once you have the basic build working, you use e.g.
<em>-j 8</em> (or other appropriate number depending on the number of cores in your
CPU) to parallelize the reference page builds, since there are so many of
them.</p></div>
<div class="paragraph"><p>We strongly sugges that once you have the basic build working, you use e.g.</p></div>
<div class="literalblock">
<div class="content monospaced">
<pre>$ make -j 8</pre>
</div></div>
<div class="paragraph"><p>(or other appropriate number depending on the number of CPU cores you have)
to parallelize the reference page builds, since there are so many of them.</p></div>
<div class="paragraph"><p>If your asciidoc installation does not put the stylesheets and xsl files in
the standard /etc/asciidoc/dblatex directory, set the environment variable
DBLATEXPREFIX to the path to that directory (the one containing the
asciidoc-dblatex.xsl and asciidoc-dblatex.sty installed with asciidoc).</p></div>
the standard <span class="monospaced">/etc/asciidoc/dblatex</span> directory, set the environment variable
<span class="monospaced">DBLATEXPREFIX</span> to the path to that directory (the one containing the
<span class="monospaced">asciidoc-dblatex.xsl</span> and <span class="monospaced">asciidoc-dblatex.sty</span> files installed with
asciidoc).</p></div>
<div class="sect2">
<h3 id="building-test">Alternate and Test Builds</h3>
<div class="paragraph"><p>If you are just testing asciidoc formatting, macros, stylesheets, etc., you
can edit test.txt, which is a stripped-down version of vkspec.txt,
and build an alternate version of the spec with either</p></div>
<div class="literalblock">
<div class="content monospaced">
<pre>$ make TOPDOCHTML=test.txt xhtml</pre>
</div></div>
<div class="paragraph"><p>or the simpler</p></div>
<div class="literalblock">
<div class="content monospaced">
<pre>tmake xhtml</pre>
</div></div>
<div class="paragraph"><p>This example will generate the file $(OUTDIR)/xhtml/test.html . Note that
TOPDOCHTML only applies to the xhtml and chunked targets at present.</p></div>
<div class="paragraph"><p>If you are just testing asciidoc formatting, macros, stylesheets, etc.,
we suggest editing <span class="monospaced">vkspec.txt</span> to comment out most of the chapter
includes.</p></div>
<div class="paragraph"><p>In addition to the XHTML and PDF targets, there is also a single-file HTML5
target, <em>html</em>, which generates output directly from asciidoc without going
target, <span class="monospaced">html</span>, which generates output directly from asciidoc without going
through Docbook. This is somewhat quicker to generate, but formatting and
section numbers aren&#8217;t consistent with the other builds and it is not for
publication - just testing. The <em>html</em> target will generate the file
$(OUTDIR)/html/vkspec.html .</p></div>
publication - just testing. The <span class="monospaced">html</span> target will generate the file
<span class="monospaced">$(OUTDIR)/html/vkspec.html</span> .</p></div>
</div>
<div class="sect2">
<h3 id="_rebuilding_the_generated_images">Rebuilding The Generated Images</h3>
<div class="paragraph"><p>There are some images in the images/ directory which are maintained in one
<div class="paragraph"><p>There are some images in the <span class="monospaced">images/</span> directory which are maintained in one
format but need to be converted to another format for corresponding types of
output. Most are SVG converted to PDF, some are PPT converted to PDF
converted to SVG. SVG and PDF forms are needed for the HTML and PDF output
formats, respectively.</p></div>
<div class="paragraph"><p>These files are not automatically converted by the Makefile. Instead, all
output forms required are checked into images/ . On the rare occasions that
someone changes a source document and needs to regenerate the other forms,
go into images and <em>make</em> in the directory.</p></div>
output forms required are checked into <span class="monospaced">images/</span> . On the rare occasions that
someone changes a source document and needs to regenerate the other forms:</p></div>
<div class="literalblock">
<div class="content monospaced">
<pre>cd images
make</pre>
</div></div>
</div>
</div>
</div>
@ -928,118 +930,49 @@ sources. The validator scripts rely on these macros as part of their sanity
checks, and you should use the macros whenever referring to an API command,
struct, token, or enum name, so the documents are semantically tagged and
more easily verifiable.</p></div>
<div class="paragraph"><p>The supported macros are defined in config/vkspec.conf (for the API spec)
and config/manpages.conf (for the reference pages).</p></div>
<div class="paragraph"><p>Tags used in both the specification and reference pages:</p></div>
<div class="ulist"><ul>
<li>
<p>
flink:vkBlah - the name of an API command.
</p>
</li>
<li>
<p>
fname:vkBlah - the name of an API command.
</p>
</li>
<li>
<p>
ftext:anything - the name of something that looks like an API command, but
isn&#8217;t (wildcards like ftext:vkCmd*).
</p>
</li>
<li>
<p>
slink:VkBlah - the name of an API C structure, handle, or scalar type. The
slink:VkBlah.membername syntax is <strong>not</strong> currently supported.
</p>
</li>
<li>
<p>
sname:VkBlah - the name of an API C structure, handle, or scalar type. The
notation sname:VkBlah.membername is also allowed where that makes sense
(NOTE: VkBlah.membername is <strong>not</strong> properly validated at present).
</p>
</li>
<li>
<p>
stext:anything - the name of something that looks like an API structure,
handle, or scalar type, but isn&#8217;t (wildcards like stext:Vk*CreateInfo).
</p>
</li>
<li>
<p>
elink:VkBlahFlags - the name of an API C "enum" type (bitmask or
enumeration).
</p>
</li>
<li>
<p>
ename:VK_BLAH - the name of an API enumeration or #define token.
</p>
</li>
<li>
<p>
etext:anything - the name of something that looks like an API "enum" type,
enumeration or #define token, but isn&#8217;t (wildcards or partial token names,
like etext:BC5).
</p>
</li>
<li>
<p>
pname:param - the name of a command parameter or struct member being
documented
</p>
</li>
<li>
<p>
basetype:type - the name of a base scalar type, such as basetype:VkBool32.
</p>
</li>
<li>
<p>
code:varname - the name of a shading language variable
</p>
</li>
</ul></div>
<div class="paragraph"><p>Tags used only in the specification, at present:</p></div>
<div class="ulist"><ul>
<li>
<p>
can:, cannot:, may:, maynot:, must:, mustnot:, optional:, recommend:,
required:, should:, and shouldnot: - used to tag places in the spec where
these terms are used in accordance with their definitions in section 1.3
"Terminology". They do not currently do anything but expand to their names
(adding a space for e.g. mustnot: &#8594; must not), but may be used to
generate an index or some visual indicator in the future.
</p>
</li>
</ul></div>
<div class="paragraph"><p>The [efs]link: macros are used for validation, and are also expanded into
xref links to the correspondingly named anchor.</p></div>
<div class="paragraph"><p>The [efsp]name: macros are used for validation, but are <strong>not</strong> expanded into
links.</p></div>
<div class="paragraph"><p>The [efs]text: macros are not used for validation, and are not expanded into
links.</p></div>
<div class="paragraph"><p>The supported macros are defined in <span class="monospaced">config/vkspec.conf</span> (for the API spec)
and <span class="monospaced">config/manpages.conf</span> (for the reference pages).</p></div>
<div class="paragraph"><p>The tags used are described in the style guide (<span class="monospaced">styleguide.txt</span>).</p></div>
<div class="paragraph"><p>We will eventually tool up the spec and ref pages to the point that anywhere
there&#8217;s a type or token referred to, you could click/hover on it in the HTML
view and be taken to the definition of that type/token. That will take some
more plumbing work to tag the stuff in the autogenerated include files, and
do something sensible in the spec (e.g. resolve links to internal
references).</p></div>
<div class="paragraph"><p>In that light, the [fs]name: vs. [fs]link: distinction seems mostly
unneeded. Probably the only time we would not want a tag to be a link to its
definition is when tagging a function name inside its own ref page. So once
the plumbing is done, most of the [fs]name: tags can turn into [fs]link:
tags.</p></div>
<div class="paragraph"><p>The ename: vs. elink: distinction is different since they&#8217;re referring to
different namespaces - individual enumerant names vs. "enum" type names -
rather than different ways of presenting the same command or struct name as
for the other tags.</p></div>
there&#8217;s a type or token referred to, clicking on (or perhaps hovering over)
it in the HTML view and be taken to the definition of that type/token. That
will take some more plumbing work to tag the stuff in the autogenerated
include files, and do something sensible in the spec (e.g. resolve links to
internal references).</p></div>
<div class="paragraph"><p>Most of these macros deeply need more intuitive names.</p></div>
</div>
</div>
<div class="sect1">
<h2 id="refpages">Reference Pages</h2>
<div class="sectionbody">
<div class="paragraph"><p>Prior to the 1.0.20 update of the API spec, the reference pages in <span class="monospaced">man/</span>
were handwritten, incomplete, and often way out of date with respect to the
spec.</p></div>
<div class="paragraph"><p>Our initial effort to address this was to tag the API spec to help identify
boundaries of language talking about different commands, structures,
enumerants, and other types, then use a set of Python scripts to
automatically extract that language into the corresponding ref page. Pages
without corresponding content in the API spec are generated automatically,
when possible.</p></div>
<div class="paragraph"><p>This has generated a semantically complete set of ref pages. Although they
are still far from ideal, they now fully document the API, and will stay in
sync with it. A significant drawback of this approach is that the only place
ref pages for extension interfaces can be generated is inside the
corresponding extension branches.</p></div>
<div class="paragraph"><p>If for some reason you want to regenerate the ref pages from scratch
yourself, you can do so by</p></div>
<div class="literalblock">
<div class="content monospaced">
<pre>$ rm man/apispec.txt
$ make apispec.txt</pre>
</div></div>
<div class="paragraph"><p>The <span class="monospaced">genRef.py</span> script will generate many warnings, but most are just
reminders that some pages are automatically generated. If everything is
working correctly, all the <span class="monospaced">man/*.txt</span> files will be regenerated, but their
contents will not change.</p></div>
</div>
</div>
<div class="sect1">
<h2 id="styles">Our stylesheets</h2>
<div class="sectionbody">
<div class="admonitionblock">
@ -1051,13 +984,13 @@ for the other tags.</p></div>
</tr></table>
</div>
<div class="paragraph"><p>This branch introduces a Vulkan-specific XHTML CSS stylesheet
in config/vkspec-xhtml.css. Mostly it just clones the default
in <span class="monospaced">config/vkspec-xhtml.css</span> . Mostly it just clones the default
Asciidoc stylesheet, but adds some new features:</p></div>
<div class="sect2">
<h3 id="_marking_changes">Marking Changes</h3>
<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
(<em>xhtml</em> and <em>chunked</em>), and <strong>only</strong> for paragraphs and spans of words.</p></div>
(<span class="monospaced">xhtml</span> and <span class="monospaced">chunked</span>), and <strong>only</strong> for paragraphs and spans of words.</p></div>
<div class="paragraph"><p>Added, removed, and changed material is marked with the asciidoc <strong>roles</strong>
named <em>added</em>, <em>removed</em>, and <em>changed</em> respectively. They can be used to
mark an entire paragraph, as follows:</p></div>
@ -1079,7 +1012,7 @@ text.</p></div>
<div class="sect2">
<h3 id="_marking_normative_language">Marking Normative Language</h3>
<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 (<em>xhtml</em> and <em>chunked</em>).</p></div>
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>.
It can be used to mark entire paragraphs or spans of words, in the
same fashion as change markings (described above). In addition, the
@ -1107,10 +1040,10 @@ for real-time rendering of equations) and to dblatex for PDF output.</p></div>
<div class="ulist"><ul>
<li>
<p>
The special characters &lt; &gt; &amp; can currently be used only in
The special characters <span class="monospaced">&lt;</span> , <span class="monospaced">&gt;</span> , and <span class="monospaced">&amp;</span> can currently be used only in
[latexmath] block macros, not in latexmath:[] inline macros.
Instead use \lt for &lt; and \gt for &gt;. &amp; is an alignment construct for
multiline equations, and should only appear in block macros anyway.
Instead use <span class="monospaced">\lt</span> for <span class="monospaced">&lt;</span> and <span class="monospaced">\gt</span> for <span class="monospaced">&gt;</span>. <span class="monospaced">&amp;</span> is an alignment construct
for multiline equations, and should only appear in block macros anyway.
</p>
</li>
<li>
@ -1145,7 +1078,7 @@ Arbitrary LaTeX constructs cannot be used with MathJax. It is an equation
following syntax. In general the anchor should immediately precede the
chapter or section title and should use the form
<em>[[chapter-section-label]]</em>. For example,</p></div>
<div class="paragraph"><p>For example, in chapter <em>synchronization.txt</em>:</p></div>
<div class="paragraph"><p>For example, in chapter <span class="monospaced">synchronization.txt</span>:</p></div>
<a id="synchronization-primitives"></a>
Synchronization Primitives
<div class="paragraph"><p>Cross-references to those anchors can then be generated with, for example,</p></div>
@ -1154,9 +1087,10 @@ of fences, semaphores, and events.
<div class="paragraph"><p>You can also add anchors on arbitrary paragraphs, using a similar naming
scheme.</p></div>
<div class="paragraph"><p>Anything whose definition comes from one of the autogenerated API include
files ({protos,flags,enums,structs}/*.txt) has a corresponding anchor whose
name is the name of the function, struct, etc. being defined. Therefore you
can say something like:</p></div>
files (<span class="monospaced">.txt</span> files in the directories <span class="monospaced">basetypes</span>, <span class="monospaced">enums</span>, <span class="monospaced">flags</span>,
<span class="monospaced">funcpointers</span>, <span class="monospaced">handles</span>, <span class="monospaced">protos</span>, and <span class="monospaced">structs</span>) has a corresponding
anchor whose name is the name of the function, struct, etc. being defined.
Therefore you can say something like:</p></div>
<div class="literalblock">
<div class="content monospaced">
<pre>Fences are used with the +++&lt;&lt;vkQueueSubmit&gt;&gt;+++ command...</pre>
@ -1172,10 +1106,10 @@ describes specific considerations for Windows environments using Cygin under
<a href="#depends-cygwin">Cygwin Dependencies</a></p></div>
<div class="sect2">
<h3 id="depends-general">General Dependencies</h3>
<div class="paragraph"><p>These are versions of required tools in Jon&#8217;s development environment
(Debian 8, shown as Debian package names). Earlier versions <strong>may</strong> work but
unless they are verified by someone else, there&#8217;s no way to know that. Later
versions should work.</p></div>
<div class="paragraph"><p>These are versions of required tools in one of the editors' development
environment (Debian 8, shown as Debian package names). Earlier versions
<strong>may</strong> work but unless they are verified by someone else, there&#8217;s no way to
know that. Later versions should work.</p></div>
<div class="ulist"><ul>
<li>
<p>
@ -1194,15 +1128,11 @@ Python 3 (python, version: 3.4.2)
</li>
<li>
<p>
Python LXML library (python-lxml, version: 3.4.0-1)
</p>
</li>
<li>
<p>
Git command-line client (git, version: 2.1.4)
Only needed if regenerating specversion.txt. Any version supporting the
operations <em>git symbolic-ref --short HEAD</em> and <em>git log -1
--format="%H"</em> should work).
operations
&#8201;&#8212;&#8201;<span class="monospaced">git symbolic-ref --short HEAD</span> and
&#8201;&#8212;&#8201;<span class="monospaced">git log -1 --format="%H"</span> should work).
</p>
</li>
<li>
@ -1292,6 +1222,11 @@ Devel/git (2.5.1-1) - Needed for updating specversion.txt
<div class="ulist"><ul>
<li>
<p>
2016/07/10 - Update for current state of spec and ref page generation.
</p>
</li>
<li>
<p>
2015/11/11 - Add new can: etc. macros and DBLATEXPREFIX variable.
</p>
</li>
@ -1326,7 +1261,7 @@ Devel/git (2.5.1-1) - Needed for updating specversion.txt
<div id="footer">
<div id="footer-text">
Last updated
2015-11-20 03:16:40 PST
2016-07-10 02:24:54 PDT
</div>
</div>
</body>

222
doc/specs/vulkan/README.txt
View File

@ -3,24 +3,27 @@
* <<intro,Introduction>>
* <<building,Building the spec>>
* <<macros,Our asciidoc macros>>
* <<refpages,Reference Pages>>
* <<styles,Our stylesheets>>
* <<equations,Imbedding equations>>
* <<anchors,Anchors and xrefs>>
* <<depends,Software dependencies>> (general and platform-specific)
* <<history,Revision history>>
[[intro]]
== Introduction ==
This README describes important stuff for getting the Vulkan API
specification and reference pages building properly.
[[building]]
== Building The Spec ==
Assuming you have all the right tools installed (see <<depends,Software
Dependencies>> below), you should be able to go to
...path-to-git-repo/vulkan/doc/specs/vulkan and:
+...path-to-git-repo/vulkan/doc/specs/vulkan+ and:
$ make all
@ -28,70 +31,69 @@ or equivalently:
$ make xhtml chunked pdf manhtml manpdf manpages manhtmlpages checkinc checklinks
This should generate a variety of targets under $(OUTDIR) (by default,
../../../out/). The checked-in file $(OUTDIR)/index.html links to them
all, or they can individually be found as follows:
This should generate a variety of targets under +$(OUTDIR)+ (by default,
+../../../out/1.0+). The checked-in file +$(OUTDIR)/index.html+ links to
them all, or they can individually be found as follows:
* API spec:
** Single-file XHTML (from a2x) - $(OUTDIR)/xhtml/vkspec.html
** Chunked HTML (from a2x) - $(OUTDIR)/vkspec.chunked/index.html
** PDF (from a2x) - $(OUTDIR)/pdf/vkspec.pdf
** Single-file XHTML (from a2x) - +$(OUTDIR)/xhtml/vkspec.html+
** Chunked HTML (from a2x) - +$(OUTDIR)/vkspec.chunked/index.html+
** PDF (from a2x) - +$(OUTDIR)/pdf/vkspec.pdf+
* Man pages:
** Single-file HTML - $(OUTDIR)/apispec.html
** File-per-entry-point HTML - $(OUTDIR)/man/html/*
** File-per-entry-point nroff source - $(OUTDIR)/man/3/*
** Single-file HTML - +$(OUTDIR)/apispec.html+
** File-per-entry-point HTML - +$(OUTDIR)/man/html/*+
** File-per-entry-point nroff source - +$(OUTDIR)/man/3/*+
* Validator output:
** List of commands, structs, etc. missing from the API spec -
$(OUTDIR)/checks/notInSpec.txt
** Validator script output for API spec - $(OUTDIR)/checks/specErrs.txt
+$(OUTDIR)/checks/notInSpec.txt+
** Validator script output for API spec - +$(OUTDIR)/checks/specErrs.txt
** Validator script output for reference pages -
$(OUTDIR)/checks/manErrs.txt
+$(OUTDIR)/checks/manErrs.txt+
We strongly sugges that once you have the basic build working, you use e.g.
'-j 8' (or other appropriate number depending on the number of cores in your
CPU) to parallelize the reference page builds, since there are so many of
them.
$ make -j 8
(or other appropriate number depending on the number of CPU cores you have)
to parallelize the reference page builds, since there are so many of them.
If your asciidoc installation does not put the stylesheets and xsl files in
the standard /etc/asciidoc/dblatex directory, set the environment variable
DBLATEXPREFIX to the path to that directory (the one containing the
asciidoc-dblatex.xsl and asciidoc-dblatex.sty installed with asciidoc).
the standard +/etc/asciidoc/dblatex+ directory, set the environment variable
+DBLATEXPREFIX+ to the path to that directory (the one containing the
+asciidoc-dblatex.xsl+ and +asciidoc-dblatex.sty+ files installed with
asciidoc).
[[building-test]]
=== Alternate and Test Builds ===
If you are just testing asciidoc formatting, macros, stylesheets, etc., you
can edit test.txt, which is a stripped-down version of vkspec.txt,
and build an alternate version of the spec with either
$ make TOPDOCHTML=test.txt xhtml
or the simpler
tmake xhtml
This example will generate the file $(OUTDIR)/xhtml/test.html . Note that
TOPDOCHTML only applies to the xhtml and chunked targets at present.
If you are just testing asciidoc formatting, macros, stylesheets, etc.,
we suggest editing +vkspec.txt+ to comment out most of the chapter
includes.
In addition to the XHTML and PDF targets, there is also a single-file HTML5
target, 'html', which generates output directly from asciidoc without going
target, +html+, which generates output directly from asciidoc without going
through Docbook. This is somewhat quicker to generate, but formatting and
section numbers aren't consistent with the other builds and it is not for
publication - just testing. The 'html' target will generate the file
$(OUTDIR)/html/vkspec.html .
publication - just testing. The +html+ target will generate the file
+$(OUTDIR)/html/vkspec.html+ .
=== Rebuilding The Generated Images ===
There are some images in the images/ directory which are maintained in one
There are some images in the +images/+ directory which are maintained in one
format but need to be converted to another format for corresponding types of
output. Most are SVG converted to PDF, some are PPT converted to PDF
converted to SVG. SVG and PDF forms are needed for the HTML and PDF output
formats, respectively.
These files are not automatically converted by the Makefile. Instead, all
output forms required are checked into images/ . On the rare occasions that
someone changes a source document and needs to regenerate the other forms,
go into images and 'make' in the directory.
output forms required are checked into +images/+ . On the rare occasions that
someone changes a source document and needs to regenerate the other forms:
cd images
make
[[macros]]
== Our Asciidoc Macros ==
@ -102,85 +104,68 @@ checks, and you should use the macros whenever referring to an API command,
struct, token, or enum name, so the documents are semantically tagged and
more easily verifiable.
The supported macros are defined in config/vkspec.conf (for the API spec)
and config/manpages.conf (for the reference pages).
The supported macros are defined in +config/vkspec.conf+ (for the API spec)
and +config/manpages.conf+ (for the reference pages).
Tags used in both the specification and reference pages:
* flink:vkBlah - the name of an API command.
* fname:vkBlah - the name of an API command.
* ftext:anything - the name of something that looks like an API command, but
isn't (wildcards like ftext:vkCmd*).
* slink:VkBlah - the name of an API C structure, handle, or scalar type. The
slink:VkBlah.membername syntax is *not* currently supported.
* sname:VkBlah - the name of an API C structure, handle, or scalar type. The
notation sname:VkBlah.membername is also allowed where that makes sense
(NOTE: VkBlah.membername is *not* properly validated at present).
* stext:anything - the name of something that looks like an API structure,
handle, or scalar type, but isn't (wildcards like stext:Vk*CreateInfo).
* elink:VkBlahFlags - the name of an API C "enum" type (bitmask or
enumeration).
* ename:VK_BLAH - the name of an API enumeration or #define token.
* etext:anything - the name of something that looks like an API "enum" type,
enumeration or #define token, but isn't (wildcards or partial token names,
like etext:BC5).
* pname:param - the name of a command parameter or struct member being
documented
* basetype:type - the name of a base scalar type, such as basetype:VkBool32.
* code:varname - the name of a shading language variable
Tags used only in the specification, at present:
* can:, cannot:, may:, maynot:, must:, mustnot:, optional:, recommend:,
required:, should:, and shouldnot: - used to tag places in the spec where
these terms are used in accordance with their definitions in section 1.3
"Terminology". They do not currently do anything but expand to their names
(adding a space for e.g. mustnot: -> must not), but may be used to
generate an index or some visual indicator in the future.
The [efs]link: macros are used for validation, and are also expanded into
xref links to the correspondingly named anchor.
The [efsp]name: macros are used for validation, but are *not* expanded into
links.
The [efs]text: macros are not used for validation, and are not expanded into
links.
The tags used are described in the style guide (+styleguide.txt+).
We will eventually tool up the spec and ref pages to the point that anywhere
there's a type or token referred to, you could click/hover on it in the HTML
view and be taken to the definition of that type/token. That will take some
more plumbing work to tag the stuff in the autogenerated include files, and
do something sensible in the spec (e.g. resolve links to internal
references).
In that light, the [fs]name: vs. [fs]link: distinction seems mostly
unneeded. Probably the only time we would not want a tag to be a link to its
definition is when tagging a function name inside its own ref page. So once
the plumbing is done, most of the [fs]name: tags can turn into [fs]link:
tags.
The ename: vs. elink: distinction is different since they're referring to
different namespaces - individual enumerant names vs. "enum" type names -
rather than different ways of presenting the same command or struct name as
for the other tags.
there's a type or token referred to, clicking on (or perhaps hovering over)
it in the HTML view and be taken to the definition of that type/token. That
will take some more plumbing work to tag the stuff in the autogenerated
include files, and do something sensible in the spec (e.g. resolve links to
internal references).
Most of these macros deeply need more intuitive names.
[[refpages]]
== Reference Pages ==
Prior to the 1.0.20 update of the API spec, the reference pages in +man/+
were handwritten, incomplete, and often way out of date with respect to the
spec.
Our initial effort to address this was to tag the API spec to help identify
boundaries of language talking about different commands, structures,
enumerants, and other types, then use a set of Python scripts to
automatically extract that language into the corresponding ref page. Pages
without corresponding content in the API spec are generated automatically,
when possible.
This has generated a semantically complete set of ref pages. Although they
are still far from ideal, they now fully document the API, and will stay in
sync with it. A significant drawback of this approach is that the only place
ref pages for extension interfaces can be generated is inside the
corresponding extension branches.
If for some reason you want to regenerate the ref pages from scratch
yourself, you can do so by
$ rm man/apispec.txt
$ make apispec.txt
The +genRef.py+ script will generate many warnings, but most are just
reminders that some pages are automatically generated. If everything is
working correctly, all the +man/*.txt+ files will be regenerated, but their
contents will not change.
[[styles]]
== Our stylesheets ==
NOTE: Section mostly TBD.
This branch introduces a Vulkan-specific XHTML CSS stylesheet
in config/vkspec-xhtml.css. Mostly it just clones the default
in +config/vkspec-xhtml.css+ . Mostly it just clones the default
Asciidoc stylesheet, but adds some new features:
=== Marking Changes ===
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.
(+xhtml+ and +chunked+), and *only* for paragraphs and spans of words.
Added, removed, and changed material is marked with the asciidoc *roles*
named _added_, _removed_, and _changed_ respectively. They can be used to
@ -198,10 +183,11 @@ The formatting of these roles text depends on the stylesheet. Currently it
all three roles are red text, and the "removed" role is also strike-through
text.
=== Marking Normative Language ===
There is support for marking normative language in the document. Currently
this is supported *only* in the XHTML targets ('xhtml' and 'chunked').
this is supported *only* in the XHTML targets (+xhtml+ and +chunked+).
Normative language is marked with the asciidoc *role* named _normative_.
It can be used to mark entire paragraphs or spans of words, in the
@ -213,6 +199,7 @@ The formatting of normative language depends on the stylesheet. Currently it
just comes out in purple. There will be some way to turn this on or off at
build time shortly.
[[equations]]
== Imbedding Equations
@ -229,10 +216,10 @@ for real-time rendering of equations) and to dblatex for PDF output.
The following caveats apply:
* The special characters < > & can currently be used only in
* The special characters +<+ , +>+ , and +&+ can currently be used only in
+++[latexmath]+++ block macros, not in +++latexmath:[]+++ inline macros.
Instead use \lt for < and \gt for >. & is an alignment construct for
multiline equations, and should only appear in block macros anyway.
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.
* When using AMSmath environments, do *not* also surround the equation block
@ -244,6 +231,7 @@ The following caveats apply:
pass:[\hbox{\tt\small VK\_FOO}] does not work in any of the HTML backends
and should be avoided.
[[anchors]]
== Asciidoc Anchors And Xrefs
@ -252,7 +240,7 @@ following syntax. In general the anchor should immediately precede the
chapter or section title and should use the form
'+++[[chapter-section-label]]+++'. For example,
For example, in chapter 'synchronization.txt':
For example, in chapter +synchronization.txt+:
++++
[[synchronization-primitives]]
@ -270,12 +258,14 @@ You can also add anchors on arbitrary paragraphs, using a similar naming
scheme.
Anything whose definition comes from one of the autogenerated API include
files ({protos,flags,enums,structs}/*.txt) has a corresponding anchor whose
name is the name of the function, struct, etc. being defined. Therefore you
can say something like:
files (+.txt+ files in the directories +basetypes+, +enums+, +flags+,
+funcpointers+, +handles+, +protos+, and +structs+) has a corresponding
anchor whose name is the name of the function, struct, etc. being defined.
Therefore you can say something like:
Fences are used with the +++<<vkQueueSubmit>>+++ command...
[[depends]]
== Software Dependencies ==
@ -284,26 +274,28 @@ toolchain. under the <<depends-general,General Dependencies>> below, then
describes specific considerations for Windows environments using Cygin under
<<depends-cygwin,Cygwin Dependencies>>
[[depends-general]]
=== General Dependencies ===
These are versions of required tools in Jon's development environment
(Debian 8, shown as Debian package names). Earlier versions *may* work but
unless they are verified by someone else, there's no way to know that. Later
versions should work.
These are versions of required tools in one of the editors' development
environment (Debian 8, shown as Debian package names). Earlier versions
*may* work but unless they are verified by someone else, there's no way to
know that. Later versions should work.
- GNU make (make version: 4.0.8-1; older versions probably OK)
- Asciidoc / a2x (asciidoc version: 8.6.9-3)
- Python 3 (python, version: 3.4.2)
- Python LXML library (python-lxml, version: 3.4.0-1)
- Git command-line client (git, version: 2.1.4)
Only needed if regenerating specversion.txt. Any version supporting the
operations 'git symbolic-ref --short HEAD' and 'git log -1
--format="%H"' should work).
operations
-- +git symbolic-ref --short HEAD+ and
-- +git log -1 --format="%H"+ 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)
[[depends-cygin]]
=== Cygwin Dependencies ===
@ -327,9 +319,11 @@ Optional Cygwin packages (current version):
* Devel/gcc-g++ (4.9.3-1) - Needed for validating generated headers
* Devel/git (2.5.1-1) - Needed for updating specversion.txt
[[history]]
== Revision History
* 2016/07/10 - Update for current state of spec and ref page generation.
* 2015/11/11 - Add new can: etc. macros and DBLATEXPREFIX variable.
* 2015/09/21 - Convert document to asciidoc and rename to README.md
in the hope the gitlab browser will render it in some fashion.

229
doc/specs/vulkan/appendices/boilerplate.txt Normal file
View File

@ -0,0 +1,229 @@
// Copyright (c) 2016 The Khronos Group Inc.
// Copyright notice at https://www.khronos.org/registry/speccopyright.html
[appendix]
[[boilerplate]]
= API Boilerplate
This appendix defines Vulkan API features that are infrastructure required
for a complete functional description of Vulkan, but do not logically belong
elsewhere in the Specification.
[[boilerplate-sType]]
== Structure Types
// refBegin VkStructureType Vulkan structure types (pname:stype)
Vulkan structures containing elink:VkStructureType::pname:sType members
must: have a value of pname:sType matching the type of the structure, as
described more fully in <<fundamentals-validusage-sType,Valid Usage for
Structure Types>>. Structure types supported by the Vulkan API include:
include::../enums/VkStructureType.txt[]
// refEnd VkStructureType
[[boilerplate-flags]]
== Flag Types
Vulkan flag types are all bitmasks aliasing the base type basetype:VkFlags and
with corresponding bit flag types defining the valid bits for that flag, as
described in <<fundamentals-validusage-flags, Valid Usage for Flags>>. Flag
types supported by the Vulkan API include:
// All of these types have autogenerated ref pages at present, although
// bringing that content into the spec (by adding // refBegin and // refEnd
// comments and explanatory text for the ref pages) would be more complete.
include::../flags/VkAccessFlags.txt[]
include::../flags/VkAttachmentDescriptionFlags.txt[]
include::../flags/VkBufferCreateFlags.txt[]
include::../flags/VkBufferUsageFlags.txt[]
include::../flags/VkBufferViewCreateFlags.txt[]
include::../flags/VkColorComponentFlags.txt[]
include::../flags/VkCommandBufferResetFlags.txt[]
include::../flags/VkCommandBufferUsageFlags.txt[]
include::../flags/VkCommandPoolCreateFlags.txt[]
include::../flags/VkCommandPoolResetFlags.txt[]
include::../flags/VkCullModeFlags.txt[]
include::../flags/VkDependencyFlags.txt[]
include::../flags/VkDescriptorPoolCreateFlags.txt[]
include::../flags/VkDescriptorPoolResetFlags.txt[]
include::../flags/VkDescriptorSetLayoutCreateFlags.txt[]
include::../flags/VkDeviceCreateFlags.txt[]
include::../flags/VkDeviceQueueCreateFlags.txt[]
include::../flags/VkEventCreateFlags.txt[]
include::../flags/VkFenceCreateFlags.txt[]
include::../flags/VkFormatFeatureFlags.txt[]
include::../flags/VkFramebufferCreateFlags.txt[]
include::../flags/VkImageAspectFlags.txt[]
include::../flags/VkImageCreateFlags.txt[]
include::../flags/VkImageUsageFlags.txt[]
include::../flags/VkImageViewCreateFlags.txt[]
include::../flags/VkInstanceCreateFlags.txt[]
include::../flags/VkMemoryHeapFlags.txt[]
include::../flags/VkMemoryMapFlags.txt[]
include::../flags/VkMemoryPropertyFlags.txt[]
include::../flags/VkPipelineCacheCreateFlags.txt[]
include::../flags/VkPipelineColorBlendStateCreateFlags.txt[]
include::../flags/VkPipelineCreateFlags.txt[]
include::../flags/VkPipelineDepthStencilStateCreateFlags.txt[]
include::../flags/VkPipelineDynamicStateCreateFlags.txt[]
include::../flags/VkPipelineInputAssemblyStateCreateFlags.txt[]
include::../flags/VkPipelineLayoutCreateFlags.txt[]
include::../flags/VkPipelineMultisampleStateCreateFlags.txt[]
include::../flags/VkPipelineRasterizationStateCreateFlags.txt[]
include::../flags/VkPipelineShaderStageCreateFlags.txt[]
include::../flags/VkPipelineStageFlags.txt[]
include::../flags/VkPipelineTessellationStateCreateFlags.txt[]
include::../flags/VkPipelineVertexInputStateCreateFlags.txt[]
include::../flags/VkPipelineViewportStateCreateFlags.txt[]
include::../flags/VkQueryControlFlags.txt[]
include::../flags/VkQueryPipelineStatisticFlags.txt[]
include::../flags/VkQueryPoolCreateFlags.txt[]
include::../flags/VkQueryResultFlags.txt[]
include::../flags/VkQueueFlags.txt[]
include::../flags/VkRenderPassCreateFlags.txt[]
include::../flags/VkSampleCountFlags.txt[]
include::../flags/VkSamplerCreateFlags.txt[]
include::../flags/VkSemaphoreCreateFlags.txt[]
include::../flags/VkShaderModuleCreateFlags.txt[]
include::../flags/VkShaderStageFlags.txt[]
include::../flags/VkSparseImageFormatFlags.txt[]
include::../flags/VkSparseMemoryBindFlags.txt[]
include::../flags/VkStencilFaceFlags.txt[]
include::../flags/VkSubpassDescriptionFlags.txt[]
[[boilerplate-macros]]
== Macro Definitions in +vulkan.h+
Vulkan is defined as a C API. The supplied +vulkan.h+ header defines a small
number of C preprocessor macros that are described below.
[[boilerplate-versions]]
=== Vulkan Version Number Macros
<<fundamentals-versionnum,API Version Numbers>> are packed into integers.
These macros manipulate version numbers in useful ways.
// refBegin VK_VERSION_MAJOR - Extract API major version number
dname:VK_VERSION_MAJOR extracts the API major version number
from a packed version number:
include::../defines/VK_VERSION_MAJOR.txt[]
// refEnd VK_VERSION_MAJOR
// refBegin VK_VERSION_MINOR - Extract API minor version number
dname:VK_VERSION_MINOR extracts the API minor version number
from a packed version number:
include::../defines/VK_VERSION_MINOR.txt[]
// refEnd VK_VERSION_MINOR
// refBegin VK_VERSION_PATCH - Extract API patch version number
dname:VK_VERSION_PATCH extracts the API patch version number
from a packed version number:
include::../defines/VK_VERSION_PATCH.txt[]
// refEnd VK_VERSION_PATCH
// refBegin VK_API_VERSION_1_0 - Return API version number for Vulkan 1.0
dname:VK_API_VERSION_1_0 returns the API version number for Vulkan 1.0. The
patch version number in this macro will always be zero. The required patch
version is specified by the application when creating an instance with
flink:vkCreateInstance, and the supported patch version for a physical
device can: be queried with flink:vkGetPhysicalDeviceProperties.
include::../defines/VK_API_VERSION_1_0.txt[]
// refEnd VK_API_VERSION_1_0 vkCreateInstance vkGetPhysicalDeviceProperties
// refBegin VK_API_VERSION - Deprecated version number macro
dname:VK_API_VERSION is deprecated and should: no longer be used.
include::../defines/VK_API_VERSION.txt[]
// refEnd VK_API_VERSION
// refBegin VK_MAKE_VERSION - Construct an API version number
dname:VK_MAKE_VERSION constructs an API version number.
include::../defines/VK_MAKE_VERSION.txt[]
* pname:major is the major version number.
* pname:minor is the minor version number.
* pname:patch is the patch version number.
This macro can: be used when constructing the
slink:VkApplicationInfo::pname:apiVersion parameter passed to
flink:vkCreateInstance.
// refEnd VK_MAKE_VERSION VkApplicationInfo vkCreateInstance
=== Vulkan Header File Version Number
// refBegin VK_HEADER_VERSION - Vulkan header file version number
dname:VK_HEADER_VERSION is the version number of the +vulkan.h+ header. This
value is currently kept synchronized with the release number of the
Specification. However, it is not guaranteed to remain synchronized, since
most Specification updates have no effect on +vulkan.h+.
include::../defines/VK_HEADER_VERSION.txt[]
// refEnd VK_HEADER_VERSION
=== Vulkan Handle macros
// refBegin VK_DEFINE_HANDLE - Declare a dispatchable object handle
dname:VK_DEFINE_HANDLE defines a <<fundamentals-objectmodel-overview,
dispatchable handle>> type.
include::../defines/VK_DEFINE_HANDLE.txt[]
* pname:object is the name of the resulting C type.
The only dispatchable handle types are those related to device and instance
management, such as slink:VkDevice.
// refEnd VK_DEFINE_HANDLE VkCommandBuffer VkDevice VkInstance VkPhysicalDevice VkQueue
// refBegin VK_DEFINE_NON_DISPATCHABLE_HANDLE - Declare a non-dispatchable object handle
dname:VK_DEFINE_NON_DISPATCHABLE_HANDLE defines a
<<fundamentals-objectmodel-overview, non-dispatchable handle>> type.
include::../defines/VK_DEFINE_NON_DISPATCHABLE_HANDLE.txt[]
* pname:object is the name of the resulting C type.
Most Vulkan handle types, such as slink:VkBuffer, are non-dispatchable.
Only one such type is listed in the See Also section below.
// refEnd VK_DEFINE_NON_DISPATCHABLE_HANDLE VkBuffer
// refBegin VK_NULL_HANDLE - Reserved non-valid object handle
dname:VK_NULL_HANDLE is a reserved value representing a non-valid object
handle. It may be passed to and returned from Vulkan commands only when
<<fundamentals-validusage-handles, specifically allowed>>.
include::../defines/VK_NULL_HANDLE.txt[]
// refEnd VK_NULL_HANDLE

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

@ -46,7 +46,7 @@ new paradigms that require rethinking the existing mechanisms:
* Layers, and with them a focus on a more open ecosystem where non-Khronos
members are expected to extend a Khronos API using the Layer mechanism.
* Namespaced constants (enumerations) that don't necessarily draw from a
* Namespaced constants (enumerations) that do not necessarily draw from a
single global set of token values.
@ -355,7 +355,7 @@ extensions. This includes the following:
* Each extension's appendix file is included by adding an +include+
statement to the +vkspec.txt+ file. Since most extensions will all put
their +include+ line at the same place in this file, they should: add
this statement on the master branch, even though the file won't actually
this statement on the master branch, even though the file will not actually
exist on the master branch. This will avoid merge conflicts when
multiple extensions' branches are merged in order to create the ``full''
branch specification.
@ -374,9 +374,9 @@ Extensions can: define their own enumeration types and assign any values to
their enumerants that they like. Each enumeration has a private namespace,
so collisions are not a problem. However, when extending existing
enumeration objects with new values, care must: be taken to preserve global
uniqueness of values. Enumerations which define new bitfields are treated
specially as described in <<extensions-reserving-bitfield-values,Reserving
Bitfield Values>> below.
uniqueness of values. Enumerations which define new bits in a bitmask are
treated specially as described in
<<extensions-reserving-bitmask-values,Reserving Bitmask Values>> below.
Each extension is assigned a range of values that can: be used to create
globally-unique enum values. Most values will be negative numbers, but
@ -410,7 +410,7 @@ The information needed to add new values to the XML are as follows:
* The **offset**, which is an integer between 0 and 999 relative to the
base being used for the extension.
* The **direction** may: be specified to indicate a negative value
(+dir="-"+) when needed for negative stext:VkResult values indicating
(+dir="-"+) when needed for negative elink:VkResult values indicating
errors, like etext:VK_ERROR_SURFACE_LOST_KHR. The default direction is
positive, if not specified.
@ -537,13 +537,13 @@ applications.
====
[[extensions-reserving-bitfield-values]]
=== Reserving Bitfield Values
[[extensions-reserving-bitmask-values]]
=== Reserving Bitmask Values
Enumerants which define bitfield values are a special case, since there are
Enumerants which define bitmask values are a special case, since there are
only a small number of unused bits available for extensions. For core Vulkan
API and KHR extension bitfield types, reservations must: be approved by a
vote of the Vulkan Working Group. For EXT and vendor extension bitfield
API and KHR extension bitmask types, reservations must: be approved by a
vote of the Vulkan Working Group. For EXT and vendor extension bitmask
types, reservations must: be approved by the listed contact of the
extension. Bits are not reserved, and mustnot: be used in a published
implementation or specification until the reservation is merged into
@ -552,10 +552,10 @@ implementation or specification until the reservation is merged into
[NOTE]
.Note
====
In reality the approving authority for EXT and vendor extension bitfield
In reality the approving authority for EXT and vendor extension bitmask
additions will probably be the owner of the github branch containing the
specification of that extension; however, until the github process is fully
defined and locked down, it's safest to refer to the listed contact.
defined and locked down, it is safest to refer to the listed contact.
====

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

@ -39,7 +39,7 @@ Aspect (Image)::
an image.
Others operations, like image/buffer copies, only operate on one
aspect at a time.
Attachment (Render Pass)::
A zero-based integer index name used in render pass creation to refer to
a framebuffer attachment that is accessed by one or more subpasses. The
@ -150,10 +150,10 @@ Compatible Queues::
Queues within a queue family. Compatible queues have identical
properties.
Component (Format)::
Component (Format)::
A distinct part of a format. Depth, stencil, and color channels
(e.g. R, G, B, A), are all separate components.
Compressed Texel Block::
An element of an image having a block-compressed format, comprising a
rectangular block of texel values that are encoded as a single value in
@ -590,13 +590,13 @@ Queue Operation::
submission command details the specific queue operations that occur as a
result of calling that command. Queue operations typically include work
that is specific to each command, and synchronization tasks.
Queue Submission::
Zero or more batches and an optional fence to be signaled, passed to a
command for execution on a queue.
See the <<devsandqueues-submission, Devices and Queues chapter>> for
more information.
Recording State (Command Buffer)::
A command buffer that is ready to record commands. See also Initial
State and Executable State.

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

@ -17,7 +17,7 @@ The obvious and most fundamental case is repeated issuance of a series of
Vulkan commands. For any given Vulkan and framebuffer state vector,
and for any Vulkan command, the resulting Vulkan and framebuffer state
must: be identical whenever the command is executed on that initial
Vulkan and framebuffer state. This repeatability requirement doesn't
Vulkan and framebuffer state. This repeatability requirement does not
apply when using shaders containing side effects (image and buffer variable
stores and atomic operations), because these memory operations are not
guaranteed to be processed in a defined order.

12
doc/specs/vulkan/basetypes/VkBool32.txt Normal file
View File

@ -0,0 +1,12 @@
// WARNING: DO NOT MODIFY! This file is automatically generated from the vk.xml registry
ifndef::doctype-manpage[]
[[VkBool32,VkBool32]]
["source","{basebackend@docbook:c++:cpp}",title=""]
endif::doctype-manpage[]
ifdef::doctype-manpage[]
["source","{basebackend@docbook:c++:cpp}"]
endif::doctype-manpage[]
------------------------------------------------------------------------------
typedef uint32_t VkBool32;
------------------------------------------------------------------------------

12
doc/specs/vulkan/basetypes/VkDeviceSize.txt Normal file
View File

@ -0,0 +1,12 @@
// WARNING: DO NOT MODIFY! This file is automatically generated from the vk.xml registry
ifndef::doctype-manpage[]
[[VkDeviceSize,VkDeviceSize]]
["source","{basebackend@docbook:c++:cpp}",title=""]
endif::doctype-manpage[]
ifdef::doctype-manpage[]
["source","{basebackend@docbook:c++:cpp}"]
endif::doctype-manpage[]
------------------------------------------------------------------------------
typedef uint64_t VkDeviceSize;
------------------------------------------------------------------------------

12
doc/specs/vulkan/basetypes/VkFlags.txt Normal file
View File

@ -0,0 +1,12 @@
// WARNING: DO NOT MODIFY! This file is automatically generated from the vk.xml registry
ifndef::doctype-manpage[]
[[VkFlags,VkFlags]]
["source","{basebackend@docbook:c++:cpp}",title=""]
endif::doctype-manpage[]
ifdef::doctype-manpage[]
["source","{basebackend@docbook:c++:cpp}"]
endif::doctype-manpage[]
------------------------------------------------------------------------------
typedef uint32_t VkFlags;
------------------------------------------------------------------------------

12
doc/specs/vulkan/basetypes/VkSampleMask.txt Normal file
View File

@ -0,0 +1,12 @@
// WARNING: DO NOT MODIFY! This file is automatically generated from the vk.xml registry
ifndef::doctype-manpage[]
[[VkSampleMask,VkSampleMask]]
["source","{basebackend@docbook:c++:cpp}",title=""]
endif::doctype-manpage[]
ifdef::doctype-manpage[]
["source","{basebackend@docbook:c++:cpp}"]
endif::doctype-manpage[]
------------------------------------------------------------------------------
typedef uint32_t VkSampleMask;
------------------------------------------------------------------------------

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

@ -2,6 +2,8 @@
=== Android Platform
// refBegin vkCreateAndroidSurfaceKHR - Create a slink:VkSurfaceKHR object for an Android native window
To create a sname:VkSurfaceKHR object for an Android native window, call:
include::../../protos/vkCreateAndroidSurfaceKHR.txt[]
@ -16,21 +18,6 @@ include::../../protos/vkCreateAndroidSurfaceKHR.txt[]
* pname:pSurface points to a sname:VkSurfaceKHR handle in which the
created surface object is returned.
include::../../validity/protos/vkCreateAndroidSurfaceKHR.txt[]
The sname:VkAndroidSurfaceCreateInfoKHR structure is defined as:
include::../../structs/VkAndroidSurfaceCreateInfoKHR.txt[]
* pname:sType is the type of this structure and must: be
ename:VK_STRUCTURE_TYPE_ANDROID_SURFACE_CREATE_INFO_KHR.
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
* pname:flags is reserved for future use.
* pname:window is a pointer to the ANativeWindow to associate the surface
with.
include::../../validity/structs/VkAndroidSurfaceCreateInfoKHR.txt[]
During the lifetime of a surface created using a particular ANativeWindow
handle any attempts to create another surface for the same ANativeWindow and
any attempts to connect to the same ANativeWindow through other platform
@ -54,3 +41,21 @@ surface's dimensions during presentation. pname:minImageExtent is
latexmath:[$(1, 1)$], and pname:maxImageExtent is the maximum image size
supported by the consumer. For the system compositor, pname:currentExtent is
the window size (i.e. the consumer's preferred size).
include::../../validity/protos/vkCreateAndroidSurfaceKHR.txt[]
// refBegin VkAndroidSurfaceCreateInfoKHR - Structure specifying parameters of a newly created Android surface object
The sname:VkAndroidSurfaceCreateInfoKHR structure is defined as:
include::../../structs/VkAndroidSurfaceCreateInfoKHR.txt[]
* pname:sType is the type of this structure and must: be
ename:VK_STRUCTURE_TYPE_ANDROID_SURFACE_CREATE_INFO_KHR.
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
* pname:flags is reserved for future use.
* pname:window is a pointer to the ANativeWindow to associate the surface
with.
include::../../validity/structs/VkAndroidSurfaceCreateInfoKHR.txt[]

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

@ -13,6 +13,8 @@ displays.
=== Display Enumeration
// refBegin vkGetPhysicalDeviceDisplayPropertiesKHR - Query information about the available displays
Various functions are provided for enumerating the available display
devices present on a Vulkan physical device. To query information about
the available displays, call:
@ -40,6 +42,8 @@ were returned.
include::../../validity/protos/vkGetPhysicalDeviceDisplayPropertiesKHR.txt[]
// refBegin VkDisplayPropertiesKHR - Structure describing an available display device
The sname:VkDisplayPropertiesKHR structure is defined as:
include::../../structs/VkDisplayPropertiesKHR.txt[]
@ -83,9 +87,13 @@ the screen content is updated infrequently, or when only a portion of the
screen needs to be updated in most frames.
====
include::../../validity/structs/VkDisplayPropertiesKHR.txt[]
==== Display Planes
// refBegin vkGetPhysicalDeviceDisplayPlanePropertiesKHR - Query the plane properties
Images are presented to individual planes on a display. Devices must:
support at least one plane on each display. Planes can: be stacked and
blended to composite multiple images on one display. Devices may: support
@ -113,6 +121,8 @@ pname:pPropertyCount structures will be written.
include::../../validity/protos/vkGetPhysicalDeviceDisplayPlanePropertiesKHR.txt[]
// refBegin VkDisplayPlanePropertiesKHR - Structure describing display plane properties
The sname:VkDisplayPlanePropertiesKHR structure is defined as:
include::../../structs/VkDisplayPlanePropertiesKHR.txt[]
@ -125,6 +135,10 @@ include::../../structs/VkDisplayPlanePropertiesKHR.txt[]
fname:vkGetPhysicalDeviceDisplayPlanePropertiesKHR() in
pname:pPropertyCount.
include::../../validity/structs/VkDisplayPlanePropertiesKHR.txt[]
// refBegin vkGetDisplayPlaneSupportedDisplaysKHR - Query the list of displays a plane supports
To determine which displays a plane is usable with, call
include::../../protos/vkGetDisplayPlaneSupportedDisplaysKHR.txt[]
@ -159,6 +173,8 @@ functions.
==== Display Modes
// refBegin vkGetDisplayModePropertiesKHR - Query the set of mode properties supported by the display
Each display has one or more supported modes associated with it
by default. These built-in modes are queried by calling:
@ -187,6 +203,8 @@ that not all the available values were returned.
include::../../validity/protos/vkGetDisplayModePropertiesKHR.txt[]
// refBegin VkDisplayModePropertiesKHR - Structure describing display mode properties
The sname:VkDisplayModePropertiesKHR structure is defined as:
include::../../structs/VkDisplayModePropertiesKHR.txt[]
@ -197,6 +215,10 @@ include::../../structs/VkDisplayModePropertiesKHR.txt[]
* pname:parameters is a sname:VkDisplayModeParametersKHR structure
describing the display parameters associated with pname:displayMode.
include::../../validity/structs/VkDisplayModePropertiesKHR.txt[]
// refBegin VkDisplayModeParametersKHR - Structure describing display parameters associated with a display mode
The sname:VkDisplayModeParametersKHR structure is defined as:
include::../../structs/VkDisplayModeParametersKHR.txt[]
@ -211,6 +233,10 @@ include::../../structs/VkDisplayModeParametersKHR.txt[]
For example, a 60Hz display mode would report a pname:refreshRate of 60,000.
====
include::../../validity/structs/VkDisplayModeParametersKHR.txt[]
// refBegin vkCreateDisplayModeKHR - Create a display mode
Additional modes may: also be created by calling:
include::../../protos/vkCreateDisplayModeKHR.txt[]
@ -227,6 +253,8 @@ include::../../protos/vkCreateDisplayModeKHR.txt[]
include::../../validity/protos/vkCreateDisplayModeKHR.txt[]
// refBegin VkDisplayModeCreateInfoKHR - Structure specifying parameters of a newly created display mode object
The sname:VkDisplayModeCreateInfoKHR structure is defined as:
include::../../structs/VkDisplayModeCreateInfoKHR.txt[]
@ -240,6 +268,8 @@ include::../../structs/VkDisplayModeCreateInfoKHR.txt[]
include::../../validity/structs/VkDisplayModeCreateInfoKHR.txt[]
// refBegin vkGetDisplayPlaneCapabilitiesKHR - Query capabilities of a mode and plane combination
Applications that wish to present directly to a display must: select which
layer, or "plane" of the display they wish to target, and a mode to use with
the display. Each display supports at least one plane. The capabilities of
@ -259,26 +289,17 @@ include::../../protos/vkGetDisplayPlaneCapabilitiesKHR.txt[]
slink:VkDisplayPlaneCapabilitiesKHR structure in which the capabilities
are returned.
include::../../validity/protos/vkGetDisplayPlaneCapabilitiesKHR.txt[]
// refBegin VkDisplayPlaneCapabilitiesKHR - Structure describing capabilities of a mode and plane combination
The sname:VkDisplayPlaneCapabilitiesKHR structure is defined as:
include::../../structs/VkDisplayPlaneCapabilitiesKHR.txt[]
* pname:supportedAlpha is a bitmask describing the supported alpha
blending modes. Possible values of pname:supportedAlpha are arbitrary
combinations of the following values:
** ename:VK_DISPLAY_PLANE_ALPHA_OPAQUE_BIT_KHR: The source image will be
treated as opaque.
** ename:VK_DISPLAY_PLANE_ALPHA_GLOBAL_BIT_KHR: A global alpha value must:
be specified that will be applied to all pixels in the source image.
** ename:VK_DISPLAY_PLANE_ALPHA_PER_PIXEL_BIT_KHR: The alpha value will be
determined by the alpha channel of the source image's pixels. If the
source format contains no alpha values, no blending will be applied.
The source alpha values are not premultiplied into the source image's
other color channels.
** ename:VK_DISPLAY_PLANE_ALPHA_PER_PIXEL_PREMULTIPLIED_BIT_KHR: This is
equivalent to ename:VK_DISPLAY_PLANE_ALPHA_PER_PIXEL_BIT_KHR except the
source alpha values are assumed to be premultiplied into the source
image's other color channels.
* pname:supportedAlpha is a bitmask of
elink:VkDisplayPlaneAlphaFlagBitsKHR describing the supported alpha
blending modes.
* pname:minSrcPosition is the minimum source rect offset supported by this
plane using the specified mode.
* pname:maxSrcPosition is the maximum source rect offset supported by this
@ -326,9 +347,13 @@ all combinations of values within the offset and extent ranges returned in
sname:VkDisplayPlaneCapabilitiesKHR are guaranteed to be supported. Vendors
may: still fail presentation requests that specify unsupported combinations.
include::../../validity/structs/VkDisplayPlaneCapabilitiesKHR.txt[]
=== Display Surfaces
// refBegin vkCreateDisplayPlaneSurfaceKHR - Create a slink:VkSurfaceKHR structure representing a display plane and mode
To create a sname:VkSurfaceKHR structure representing a display plane and
mode, call
@ -345,6 +370,10 @@ include::../../protos/vkCreateDisplayPlaneSurfaceKHR.txt[]
* pname:pSurface points to a sname:VkSurfaceKHR handle in which the
created surface is returned.
include::../../validity/protos/vkCreateDisplayPlaneSurfaceKHR.txt[]
// refBegin VkDisplaySurfaceCreateInfoKHR - Structure specifying parameters of a newly created display plane surface object
The sname:VkDisplaySurfaceCreateInfoKHR structure is defined as:
include::../../structs/VkDisplaySurfaceCreateInfoKHR.txt[]
@ -363,3 +392,31 @@ include::../../structs/VkDisplaySurfaceCreateInfoKHR.txt[]
* pname:alphaMode is the type of alpha blending to use.
* pname:imageSize The size of the presentable images to use with the
surface.
include::../../validity/structs/VkDisplaySurfaceCreateInfoKHR.txt[]
// refBegin VkDisplayPlaneAlphaFlagBitsKHR - alpha blending type
Types of alpha blending supported by or used on a display are defined by the
bitmask ename:VkDisplayPlaneAlphaFlagBitsKHR, which contains the following
values:
include::../../enums/VkDisplayPlaneAlphaFlagBitsKHR.txt[]
These values are described as follows:
* ename:VK_DISPLAY_PLANE_ALPHA_OPAQUE_BIT_KHR: The source image will be
treated as opaque.
* ename:VK_DISPLAY_PLANE_ALPHA_GLOBAL_BIT_KHR: A global alpha value must:
be specified that will be applied to all pixels in the source image.
* ename:VK_DISPLAY_PLANE_ALPHA_PER_PIXEL_BIT_KHR: The alpha value will be
determined by the alpha channel of the source image's pixels. If the
source format contains no alpha values, no blending will be applied.
The source alpha values are not premultiplied into the source image's
other color channels.
* ename:VK_DISPLAY_PLANE_ALPHA_PER_PIXEL_PREMULTIPLIED_BIT_KHR: This is
equivalent to ename:VK_DISPLAY_PLANE_ALPHA_PER_PIXEL_BIT_KHR except the
source alpha values are assumed to be premultiplied into the source
image's other color channels.
// refEnd VkDisplayPlaneAlphaFlagBitsKHR

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

@ -1,5 +1,7 @@
[[create_shared_swapchains,create_shared_swapchains]]
// refBegin vkCreateSharedSwapchainsKHR - Create multiple swapchains that share presentable images
When the VK_KHR_display_swapchain extension is enabled, multiple swapchains
that share presentable images are created by calling:

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

@ -5,6 +5,8 @@ can: be specified when presenting an image to a swapchain by setting
slink:VkPresentInfoKHR::pname:pNext to point to an instance of the
slink:VkDisplayPresentInfoKHR structure.
// refBegin VkDisplayPresentInfoKHR - Structure describing parameters of a queue presentation to a swapchain
The sname:VkDisplayPresentInfoKHR structure is defined as:
include::../../structs/VkDisplayPresentInfoKHR.txt[]

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

@ -2,6 +2,8 @@
=== Mir Platform
// refBegin vkCreateMirSurfaceKHR - Create a slink:VkSurfaceKHR object for a Mir window
To create a sname:VkSurfaceKHR object for a Mir window, call:
include::../../protos/vkCreateMirSurfaceKHR.txt[]
@ -18,6 +20,8 @@ include::../../protos/vkCreateMirSurfaceKHR.txt[]
include::../../validity/protos/vkCreateMirSurfaceKHR.txt[]
// refBegin VkMirSurfaceCreateInfoKHR - Structure specifying parameters of a newly created Mir surface object
The sname:VkMirSurfaceCreateInfoKHR structure is defined as:
include::../../structs/VkMirSurfaceCreateInfoKHR.txt[]

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

@ -2,6 +2,8 @@
=== Mir Platform
// refBegin vkGetPhysicalDeviceMirPresentationSupportKHR - Query physical device for presentation to Mir
To determine whether a queue family of a physical device supports presentation
to the Mir compositor, call:
@ -12,6 +14,6 @@ include::../../protos/vkGetPhysicalDeviceMirPresentationSupportKHR.txt[]
* pname:connection is a pointer to the sname:MirConnection, and identifies
the desired Mir compositor.
This platform-specific function can: be called prior to creating a surface
This platform-specific function can: be called prior to creating a surface.
include::../../validity/protos/vkGetPhysicalDeviceMirPresentationSupportKHR.txt[]

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

@ -91,6 +91,8 @@ such re-creation will succeed is platform-dependent and may: depend on the
reason the surface became unavailable. A lost surface does not otherwise
cause devices to be <<devsandqueues-lost-device,lost>>.
// refBegin vkDestroySurfaceKHR - Destroy a VkSurfaceKHR object
To destroy a sname:VkSurfaceKHR object, call:
include::../../protos/vkDestroySurfaceKHR.txt[]
@ -121,6 +123,8 @@ additionally may: be determined in platform-specific manners (which
determine support for presentation on the specified physical device but
don't guarantee support for presentation to a particular surface object).
// refBegin vkGetPhysicalDeviceSurfaceSupportKHR - Query if presentation is supported
To determine whether a queue family of a physical device supports
presentation to a given surface, call:
@ -144,6 +148,8 @@ include::../VK_KHR_xlib_surface/platformQuerySupport_xlib.txt[]
== Surface Queries
// refBegin vkGetPhysicalDeviceSurfaceCapabilitiesKHR - Query surface capabilities
To query the basic capabilities of a surface, needed in order to create a
swapchain, call:
@ -159,6 +165,8 @@ include::../../protos/vkGetPhysicalDeviceSurfaceCapabilitiesKHR.txt[]
include::../../validity/protos/vkGetPhysicalDeviceSurfaceCapabilitiesKHR.txt[]
// refBegin VkSurfaceCapabilitiesKHR - Structure describing capabilities of a surface
The sname:VkSurfaceCapabilitiesKHR structure is defined as:
include::../../structs/VkSurfaceCapabilitiesKHR.txt[]
@ -200,6 +208,8 @@ include::../../structs/VkSurfaceCapabilitiesKHR.txt[]
include::../../validity/structs/VkSurfaceCapabilitiesKHR.txt[]
// refBegin VkSurfaceTransformFlagBitsKHR - presentation transforms supported on a device
The pname:supportedTransforms and pname:currentTransform members are of type
ename:VkSurfaceTransformFlagBitsKHR, which contains the following values:
@ -207,28 +217,32 @@ include::../../enums/VkSurfaceTransformFlagBitsKHR.txt[]
These values are described as follows:
- ename:VK_SURFACE_TRANSFORM_IDENTITY_BIT_KHR: The image content is
presented without being transformed.
- ename:VK_SURFACE_TRANSFORM_ROTATE_90_BIT_KHR: The image content is
rotated 90 degrees clockwise.
- ename:VK_SURFACE_TRANSFORM_ROTATE_180_BIT_KHR: The image content is
rotated 180 degrees clockwise.
- ename:VK_SURFACE_TRANSFORM_ROTATE_270_BIT_KHR: The image content is
rotated 270 degrees clockwise.
- ename:VK_SURFACE_TRANSFORM_HORIZONTAL_MIRROR_BIT_KHR: The image
content is mirrored horizontally.
- ename:VK_SURFACE_TRANSFORM_HORIZONTAL_MIRROR_ROTATE_90_BIT_KHR: The
image content is mirrored horizontally, then rotated 90 degrees
clockwise.
- ename:VK_SURFACE_TRANSFORM_HORIZONTAL_MIRROR_ROTATE_180_BIT_KHR: The
image content is mirrored horizontally, then rotated 180 degrees
clockwise.
- ename:VK_SURFACE_TRANSFORM_HORIZONTAL_MIRROR_ROTATE_270_BIT_KHR: The
image content is mirrored horizontally, then rotated 270 degrees
clockwise.
- ename:VK_SURFACE_TRANSFORM_INHERIT_BIT_KHR: The presentation transform
is not specified, and is instead determined by platform-specific
considerations and mechanisms outside Vulkan.
* ename:VK_SURFACE_TRANSFORM_IDENTITY_BIT_KHR: The image content is
presented without being transformed.
* ename:VK_SURFACE_TRANSFORM_ROTATE_90_BIT_KHR: The image content is
rotated 90 degrees clockwise.
* ename:VK_SURFACE_TRANSFORM_ROTATE_180_BIT_KHR: The image content is
rotated 180 degrees clockwise.
* ename:VK_SURFACE_TRANSFORM_ROTATE_270_BIT_KHR: The image content is
rotated 270 degrees clockwise.
* ename:VK_SURFACE_TRANSFORM_HORIZONTAL_MIRROR_BIT_KHR: The image
content is mirrored horizontally.
* ename:VK_SURFACE_TRANSFORM_HORIZONTAL_MIRROR_ROTATE_90_BIT_KHR: The
image content is mirrored horizontally, then rotated 90 degrees
clockwise.
* ename:VK_SURFACE_TRANSFORM_HORIZONTAL_MIRROR_ROTATE_180_BIT_KHR: The
image content is mirrored horizontally, then rotated 180 degrees
clockwise.
* ename:VK_SURFACE_TRANSFORM_HORIZONTAL_MIRROR_ROTATE_270_BIT_KHR: The
image content is mirrored horizontally, then rotated 270 degrees
clockwise.
* ename:VK_SURFACE_TRANSFORM_INHERIT_BIT_KHR: The presentation transform
is not specified, and is instead determined by platform-specific
considerations and mechanisms outside Vulkan.
// refEnd VkSurfaceTransformFlagBitsKHR
// refBegin VkCompositeAlphaFlagBitsKHR - alpha compositing modes supported on a device
The pname:supportedCompositeAlpha member is of type
ename:VkCompositeAlphaFlagBitsKHR, which contains the following values:
@ -237,25 +251,29 @@ include::../../enums/VkCompositeAlphaFlagBitsKHR.txt[]
These values are described as follows:
- ename:VK_COMPOSITE_ALPHA_OPAQUE_BIT_KHR: The alpha channel, if it
exists, of the images is ignored in the compositing process. Instead,
the image is treated as if it has a constant alpha of 1.0.
- ename:VK_COMPOSITE_ALPHA_PRE_MULTIPLIED_BIT_KHR: The alpha channel, if
it exists, of the images is respected in the compositing process. The
non-alpha channels of the image are expected to already be multiplied
by the alpha channel by the application.
- ename:VK_COMPOSITE_ALPHA_POST_MULTIPLIED_BIT_KHR: The alpha channel,
if it exists, of the images is respected in the compositing process.
The non-alpha channels of the image are not expected to already be
multiplied by the alpha channel by the application; instead, the
compositor will multiply the non-alpha channels of the image by the
alpha channel during compositing.
- ename:VK_COMPOSITE_ALPHA_INHERIT_BIT_KHR: The way in which the
presentation engine treats the alpha channel in the images is unknown
to the Vulkan API. Instead, the application is responsible for setting
the composite alpha blending mode using native window system commands.
If the application does not set the blending mode using native window
system commands, then a platform-specific default will be used.
* ename:VK_COMPOSITE_ALPHA_OPAQUE_BIT_KHR: The alpha channel, if it
exists, of the images is ignored in the compositing process. Instead,
the image is treated as if it has a constant alpha of 1.0.
* ename:VK_COMPOSITE_ALPHA_PRE_MULTIPLIED_BIT_KHR: The alpha channel, if
it exists, of the images is respected in the compositing process. The
non-alpha channels of the image are expected to already be multiplied
by the alpha channel by the application.
* ename:VK_COMPOSITE_ALPHA_POST_MULTIPLIED_BIT_KHR: The alpha channel,
if it exists, of the images is respected in the compositing process.
The non-alpha channels of the image are not expected to already be
multiplied by the alpha channel by the application; instead, the
compositor will multiply the non-alpha channels of the image by the
alpha channel during compositing.
* ename:VK_COMPOSITE_ALPHA_INHERIT_BIT_KHR: The way in which the
presentation engine treats the alpha channel in the images is unknown
to the Vulkan API. Instead, the application is responsible for setting
the composite alpha blending mode using native window system commands.
If the application does not set the blending mode using native window
system commands, then a platform-specific default will be used.
// refEnd VkCompositeAlphaFlagBitsKHR
// refBegin vkGetPhysicalDeviceSurfaceFormatsKHR - Query color formats supported by surface
To query the supported swapchain format-colorspace pairs for a surface,
call:
@ -286,6 +304,8 @@ were returned.
include::../../validity/protos/vkGetPhysicalDeviceSurfaceFormatsKHR.txt[]
// refBegin VkSurfaceFormatKHR - Structure describing a supported swapchain format-colorspace pair
The sname:VkSurfaceFormatKHR structure is defined as:
include::../../structs/VkSurfaceFormatKHR.txt[]
@ -306,6 +326,8 @@ chromaticities of its primaries and a whitepoint in CIE Lab), and a transfer
function that is applied before storing or transmitting color data in the
given colorspace.
// refBegin VkColorSpaceKHR - supported colorspace of the presentation engine
The ename:VkColorSpaceKHR is defined as follows:
include::../../enums/VkColorSpaceKHR.txt[]
@ -334,6 +356,10 @@ Vulkan naming rules. The older enum is still available for backwards
compatibility.
====
// refEnd VkColorSpaceKHR
// refBegin vkGetPhysicalDeviceSurfacePresentModesKHR - Query supported presentation modes
To query the supported presentation modes for a surface, call:
include::../../protos/vkGetPhysicalDeviceSurfacePresentModesKHR.txt[]
@ -345,16 +371,16 @@ include::../../protos/vkGetPhysicalDeviceSurfacePresentModesKHR.txt[]
* pname:pPresentModeCount is a pointer to an integer related to the
number of presentation modes available or queried, as described below.
* pname:pPresentModes is either `NULL` or a pointer to an array
of sname:VkPresentModeKHR structures.
of elink:VkPresentModeKHR structures.
If pname:pPresentModes is `NULL`, then the number of presentation modes
supported for the given pname:surface is returned in
pname:pPresentModeCount. Otherwise, pname:pPresentModeCount must: point to a
variable set by the user to the number of elements in the
pname:pPresentModes array, and on return the variable is overwritten with
the number of structures actually written to pname:pPresentModes. If the
the number of values actually written to pname:pPresentModes. If the
value of pname:pPresentModeCount is less than the number of presentation
modes supported, at most pname:pPresentModeCount structures will be written.
modes supported, at most pname:pPresentModeCount values will be written.
If pname:pPresentModeCount is smaller than the number of presentation modes
supported for the given pname:surface, ename:VK_INCOMPLETE will be returned
instead of ename:VK_SUCCESS to indicate that not all the available values
@ -362,6 +388,8 @@ were returned.
include::../../validity/protos/vkGetPhysicalDeviceSurfacePresentModesKHR.txt[]
// refBegin VkPresentModeKHR - presentation mode supported for a surface
The definition of ename:VkPresentModeKHR is:
include::../../enums/VkPresentModeKHR.txt[]
@ -413,4 +441,6 @@ equivalent to the behavior of {wgl|glX}SwapBuffers with a swap interval
of -1 (from the {WGL|GLX}_EXT_swap_control_tear extensions).
====
// refEnd VkPresentModeKHR
include::../VK_KHR_swapchain/wsi.txt[]

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

@ -54,6 +54,8 @@ swapchain at initialization time, rather than in its main loop.
How this all works is described below.
// refBegin vkCreateSwapchainKHR - Create a swapchain
To create a swapchain, call:
include::../../protos/vkCreateSwapchainKHR.txt[]
@ -70,6 +72,8 @@ include::../../protos/vkCreateSwapchainKHR.txt[]
include::../../validity/protos/vkCreateSwapchainKHR.txt[]
// refBegin VkSwapchainCreateInfoKHR - Structure specifying parameters of a newly created swapchain object
The sname:VkSwapchainCreateInfoKHR structure is defined as:
include::../../structs/VkSwapchainCreateInfoKHR.txt[]
@ -117,19 +121,18 @@ include::../../structs/VkSwapchainCreateInfoKHR.txt[]
* pname:clipped indicates whether the Vulkan implementation is allowed
to discard rendering operations that affect regions of the surface which
aren't visible.
- If set to ename:VK_TRUE, the presentable images associated with the
swapchain may: not own all of their pixels. Pixels in the presentable
images that correspond to regions of the target surface obscured by
another window on the desktop or subject to some other clipping
mechanism will have undefined content when read back. Pixel shaders
maynot: execute for these pixels, and thus any side affects they would
have had will not occur.
- If set to ename:VK_FALSE, presentable images associated with the
swapchain will own all the pixels they contain.
- Setting this value to ename:VK_TRUE does not guarantee any clipping
will occur, but allows more optimal presentation methods to be used on
some platforms.
** If set to ename:VK_TRUE, the presentable images associated with the
swapchain may: not own all of their pixels. Pixels in the presentable
images that correspond to regions of the target surface obscured by
another window on the desktop or subject to some other clipping
mechanism will have undefined content when read back. Pixel shaders
maynot: execute for these pixels, and thus any side affects they would
have had will not occur.
** If set to ename:VK_FALSE, presentable images associated with the
swapchain will own all the pixels they contain.
Setting this value to ename:VK_TRUE does not guarantee any clipping
will occur, but allows more optimal presentation methods to be used on
some platforms.
[NOTE]
.Note
@ -187,6 +190,8 @@ application must: query the surface capabilities again, because they may:
differ on a per-physical device basis.
====
// refBegin vkDestroySwapchainKHR - Destroy a swapchain object
To destroy a swapchain object call:
include::../../protos/vkDestroySwapchainKHR.txt[]
@ -210,6 +215,8 @@ include::../../validity/protos/vkDestroySwapchainKHR.txt[]
include::../VK_KHR_display_swapchain/create_shared_swapchains.txt[]
// refBegin vkGetSwapchainImagesKHR - Obtain the array of presentable images associated with a swapchain
To obtain the array of presentable images associated with a swapchain,
call:
@ -259,6 +266,8 @@ implementation so destroying a presentable image with flink:vkDestroyImage
results in undefined behavior. See flink:vkDestroySwapchainKHR for further
details on the lifetime of presentable images.
// refBegin vkAcquireNextImageKHR - Retrieve the index of the next available presentable image
To acquire an available presentable image to use, and retrieve the
index of that image, call:
@ -344,7 +353,7 @@ of presentable images that the application has currently acquired
(i.e. images acquired with fname:vkAcquireNextImageKHR, but not yet
presented with fname:vkQueuePresentKHR). fname:vkAcquireNextImageKHR can:
always succeed if latexmath:[$a \leq n - m$] at the time fname:vkAcquireNextImageKHR is
called.
called.
fname:vkAcquireNextImageKHR shouldnot: be called if latexmath:[$a > n - m$]
with a pname:timeout of code:UINT64_MAX; in such a case,
fname:vkAcquireNextImageKHR may: block indefinitely.
@ -481,6 +490,8 @@ pname:dstStageMask is valid, but should: be set to
ename:VK_PIPELINE_STAGE_BOTTOM_OF_PIPE_BIT to avoid delaying subsequent
commands that don't access the image.
// refBegin vkQueuePresentKHR - Queue an image for presentation
After queueing all rendering commands and transitioning the image to the
correct layout, to queue an image for presentation, call:
@ -494,6 +505,8 @@ include::../../protos/vkQueuePresentKHR.txt[]
include::../../validity/protos/vkQueuePresentKHR.txt[]
// refBegin VkPresentInfoKHR - Structure describing parameters of a queue presentation
The sname:VkPresentInfoKHR structure is defined as:
include::../../structs/VkPresentInfoKHR.txt[]

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

@ -2,6 +2,8 @@
=== Wayland Platform
// refBegin vkCreateWaylandSurfaceKHR - Create a slink:VkSurfaceKHR object for a Wayland window
To create a sname:VkSurfaceKHR object for a Wayland surface, call:
include::../../protos/vkCreateWaylandSurfaceKHR.txt[]
@ -18,6 +20,8 @@ include::../../protos/vkCreateWaylandSurfaceKHR.txt[]
include::../../validity/protos/vkCreateWaylandSurfaceKHR.txt[]
// refBegin VkWaylandSurfaceCreateInfoKHR - Structure specifying parameters of a newly created Wayland surface object
The sname:VkWaylandSurfaceCreateInfoKHR structure is defined as:
include::../../structs/VkWaylandSurfaceCreateInfoKHR.txt[]

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

@ -2,6 +2,8 @@
=== Wayland Platform
// refBegin vkGetPhysicalDeviceWaylandPresentationSupportKHR - Query physical device for presentation to Wayland
To determine whether a queue family of a physical device supports presentation
to a Wayland compositor, call:

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

@ -2,6 +2,8 @@
=== Win32 Platform
// refBegin vkCreateWin32SurfaceKHR - Create a slink:VkSurfaceKHR object for an Win32 native window
To create a sname:VkSurfaceKHR object for a Win32 window, call:
include::../../protos/vkCreateWin32SurfaceKHR.txt[]
@ -18,6 +20,8 @@ include::../../protos/vkCreateWin32SurfaceKHR.txt[]
include::../../validity/protos/vkCreateWin32SurfaceKHR.txt[]
// refBegin VkWin32SurfaceCreateInfoKHR - Structure specifying parameters of a newly created Win32 surface object
The sname:VkWin32SurfaceCreateInfoKHR structure is defined as:
include::../../structs/VkWin32SurfaceCreateInfoKHR.txt[]

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

@ -2,6 +2,8 @@
=== Win32 Platform
// refBegin vkGetPhysicalDeviceWin32PresentationSupportKHR - query queue family support for presentation on a Win32 display
To determine whether a queue family of a physical device supports presentation
to the Microsoft Windows desktop, call:

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

@ -2,6 +2,8 @@
=== XCB Platform
// refBegin vkCreateXcbSurfaceKHR - Create a slink:VkSurfaceKHR object for a X11 window, using the XCB client-side library
To create a sname:VkSurfaceKHR object for an X11 window, using the XCB
client-side library, call:
@ -19,6 +21,8 @@ include::../../protos/vkCreateXcbSurfaceKHR.txt[]
include::../../validity/protos/vkCreateXcbSurfaceKHR.txt[]
// refBegin VkXcbSurfaceCreateInfoKHR - Structure specifying parameters of a newly created Xcb surface object
The sname:VkXcbSurfaceCreateInfoKHR structure is defined as:
include::../../structs/VkXcbSurfaceCreateInfoKHR.txt[]

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

@ -2,6 +2,8 @@
=== XCB Platform
// refBegin vkGetPhysicalDeviceXcbPresentationSupportKHR - Query physical device for presentation to X11 server using XCB
To determine whether a queue family of a physical device supports
presentation to an X11 server, using the XCB client-side library, call:
@ -12,6 +14,6 @@ include::../../protos/vkGetPhysicalDeviceXcbPresentationSupportKHR.txt[]
* pname:connection is a pointer to an sname:xcb_connection_t to the X
server. pname:visual_id is an X11 visual (sname:xcb_visualid_t).
This platform-specific function can: be called prior to creating a surface
This platform-specific function can: be called prior to creating a surface.
include::../../validity/protos/vkGetPhysicalDeviceXcbPresentationSupportKHR.txt[]

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

@ -2,6 +2,8 @@
=== Xlib Platform
// refBegin vkCreateXlibSurfaceKHR - Create a slink:VkSurfaceKHR object for an X11 window, using the Xlib client-side library
To create a sname:VkSurfaceKHR object for an X11 window, using the Xlib
client-side library, call:
@ -19,6 +21,8 @@ include::../../protos/vkCreateXlibSurfaceKHR.txt[]
include::../../validity/protos/vkCreateXlibSurfaceKHR.txt[]
// refBegin VkXlibSurfaceCreateInfoKHR - Structure specifying parameters of a newly created Xlib surface object
The sname:VkXlibSurfaceCreateInfoKHR structure is defined as:
include::../../structs/VkXlibSurfaceCreateInfoKHR.txt[]

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

@ -2,6 +2,8 @@
=== Xlib Platform
// refBegin vkGetPhysicalDeviceXlibPresentationSupportKHR - Query physical device for presentation to X11 server using Xlib
To determine whether a queue family of a physical device supports presentation
to an X11 server, using the Xlib client-side library, call:
@ -12,6 +14,6 @@ include::../../protos/vkGetPhysicalDeviceXlibPresentationSupportKHR.txt[]
* pname:dpy is a pointer to an Xlib sname:Display connection to the server.
* pname:visualId is an X11 visual (VisualID).
This platform-specific function can: be called prior to creating a surface
This platform-specific function can: be called prior to creating a surface.
include::../../validity/protos/vkGetPhysicalDeviceXlibPresentationSupportKHR.txt[]

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

@ -13,6 +13,8 @@ instance using flink:vkCmdClearColorImage or
flink:vkCmdClearDepthStencilImage, respectively. These commands are only
allowed outside of a render pass instance.
// refBegin vkCmdClearColorImage Clear regions of a color image.
To clear one or more subranges of a color image, call:
include::../protos/vkCmdClearColorImage.txt[]
@ -39,6 +41,8 @@ pname:pColor.
include::../validity/protos/vkCmdClearColorImage.txt[]
// refBegin vkCmdClearDepthStencilImage Fill regions of a combined depth-stencil image.
To clear one or more subranges of a depth/stencil image, call:
include::../protos/vkCmdClearDepthStencilImage.txt[]
@ -74,6 +78,8 @@ the purposes of memory barriers.
[[clears-inside]]
== Clearing Images Inside A Render Pass Instance
// refBegin vkCmdClearAttachments Clear regions within currently bound framebuffer attachments.
To clear one or more regions of color and depth/stencil attachments inside a
render pass instance, call:
@ -98,6 +104,8 @@ parameters.
include::../validity/protos/vkCmdClearAttachments.txt[]
// refBegin VkClearRect - Structure specifying a clear rectangle
The sname:VkClearRect structure is defined as:
include::../structs/VkClearRect.txt[]
@ -111,6 +119,8 @@ counting from the base layer of the attachment image view are cleared.
include::../validity/structs/VkClearRect.txt[]
// refBegin VkClearAttachment - Structure specifying a clear attachment
The sname:VkClearAttachment structure is defined as:
include::../structs/VkClearAttachment.txt[]
@ -151,24 +161,26 @@ include::../validity/structs/VkClearAttachment.txt[]
[[clears-values]]
== Clear Values
// refBegin VkClearColorValue - Structure specifying a clear color value
The sname:VkClearColorValue structure is defined as:
include::../structs/VkClearColorValue.txt[]
Color clear values are taken from the sname:VkClearColorValue union based on
the format of the image or attachment. Floating point, unorm, snorm,
uscaled, packed float, and sRGB images use the pname:float32 member,
unsigned integer formats use the pname:uint32 member, and signed integer
formats use the pname:int32 member. Floating point values are automatically
converted to the format of the image, with the clear value being treated as
linear if the image is sRGB.
Unsigned integer values are converted to the format of the image by casting
to the integer type with fewer bits. Signed integer values are converted to
the format of the image by casting to the smaller type (with negative 32-bit
values mapping to negative values in the smaller type). If the integer clear
value is not representable in the target type (e.g. would overflow in
conversion to that type), the clear value is undefined.
* pname:float32 are the color clear values when the format of the image or
attachment is floating point, unorm, snorm, uscaled, packed float, or
sRGB. Floating point values are automatically converted to the format of
the image, with the clear value being treated as linear if the image is
sRGB.
* pname:int32 are the color clear values when the format of the image or
attachment is signed integer. Signed integer values are converted to the
format of the image by casting to the smaller type (with negative 32-bit
values mapping to negative values in the smaller type). If the integer
clear value is not representable in the target type (e.g. would overflow
in conversion to that type), the clear value is undefined.
* pname:uint32 are the color clear values when the format of the image or
attachment is unsigned integer. Unsigned integer values are converted to
the format of the image by casting to the integer type with fewer bits.
The four array elements of the clear color map to R, G, B, and A components
of image formats, in order.
@ -178,6 +190,8 @@ samples for any pixels being cleared.
include::../validity/structs/VkClearColorValue.txt[]
// refBegin VkClearDepthStencilValue - Structure specifying a clear depth stencil value
The sname:VkClearDepthStencilValue structure is defined as:
include::../structs/VkClearDepthStencilValue.txt[]
@ -192,9 +206,7 @@ include::../structs/VkClearDepthStencilValue.txt[]
include::../validity/structs/VkClearDepthStencilValue.txt[]
Some parts of the API require either color or depth/stencil clear values,
depending on the attachment. The sname:VkClearValue union represents such
values.
// refBegin VkClearValue - Structure specifying a clear value
The sname:VkClearValue union is defined as:
@ -205,8 +217,9 @@ include::../structs/VkClearValue.txt[]
* pname:depthStencil specifies the depth and stencil clear values to use
when clearing a depth/stencil image or attachment.
This union is used to define the initial clear values in the
sname:VkRenderPassBeginInfo structure.
This union is used where part of the API requires either color or
depth/stencil clear values, depending on the attachment, and defines the
initial clear values in the slink:VkRenderPassBeginInfo structure.
include::../validity/structs/VkClearValue.txt[]
@ -214,6 +227,8 @@ include::../validity/structs/VkClearValue.txt[]
[[clears-filling-buffers]]
== Filling Buffers
// refBegin vkCmdFillBuffer Fill a region of a buffer with a fixed value.
To clear buffer data, call:
include::../protos/vkCmdFillBuffer.txt[]
@ -243,6 +258,8 @@ include::../validity/protos/vkCmdFillBuffer.txt[]
[[clears-updating-buffers]]
== Updating Buffers
// refBegin vkCmdUpdateBuffer Update a buffer's contents from host memory.
To update buffer data inline in a command buffer, call:
include::../protos/vkCmdUpdateBuffer.txt[]
@ -266,7 +283,7 @@ the command is called.
fname:vkCmdUpdateBuffer is only allowed outside of a render pass. This
command is treated as ``transfer'' operation, for the purposes of
synchronization barriers. The ename:VK_BUFFER_USAGE_TRANSFER_DST_BIT must:
be specified in pname:usage of sname:VkBufferCreateInfo in order for the
be specified in pname:usage of slink:VkBufferCreateInfo in order for the
buffer to be compatible with fname:vkCmdUpdateBuffer.
include::../validity/protos/vkCmdUpdateBuffer.txt[]
@ -276,8 +293,6 @@ include::../validity/protos/vkCmdUpdateBuffer.txt[]
====
The pname:pData parameter was of type basetype:uint32_t* instead of
basetype:void* prior to revision 1.0.19 of the Specification and
ename:VK_HEADER_VERSION 19 of +vulkan.h+. This was a
dlink:VK_HEADER_VERSION 19 of +vulkan.h+. This was a
historical anomaly, as the source data may be of other types.
====
[[clears-end]]

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

@ -4,6 +4,8 @@
[[commandbuffers]]
= Command Buffers
// refBegin VkCommandBuffer - Opaque handle to a command buffer object
Command buffers are objects used to record commands which can: be
subsequently submitted to a device queue for execution. There are two levels
of command buffers - _primary command buffers_, which can: execute secondary
@ -11,6 +13,12 @@ command buffers, and which are submitted to queues, and _secondary command
buffers_, which can: be executed by primary command buffers, and which are
not directly submitted to queues.
Command buffers are represented by sname:VkCommandBuffer handles:
include::../handles/VkCommandBuffer.txt[]
// refEnd VkCommandBuffer
Recorded commands include commands to bind pipelines and descriptor sets to
the command buffer, commands to modify dynamic state, commands to draw (for
graphics rendering), commands to dispatch (for compute), commands to execute
@ -66,6 +74,8 @@ additionally puts the command buffer in the recording state).
[[commandbuffers-pools]]
== Command Pools
// refBegin VkCommandPool - Opaque handle to a command pool object
Command pools are opaque objects that command buffer memory is allocated
from, and which allow the implementation to amortize the cost of resource
creation across multiple command buffers. Command pools are
@ -74,6 +84,14 @@ concurrently in multiple threads. That includes use via recording commands
on any command buffers allocated from the pool, as well as operations that
allocate, free, and reset command buffers or the pool itself.
Command pools are represented by sname:VkCommandPool handles:
include::../handles/VkCommandPool.txt[]
// refEnd VkCommandPool
// refBegin vkCreateCommandPool Create a new command pool object.
To create a command pool, call:
include::../protos/vkCreateCommandPool.txt[]
@ -87,6 +105,8 @@ include::../protos/vkCreateCommandPool.txt[]
include::../validity/protos/vkCreateCommandPool.txt[]
// refBegin VkCommandPoolCreateInfo - Structure specifying parameters of a newly created command pool
The sname:VkCommandPoolCreateInfo structure is defined as:
include::../structs/VkCommandPoolCreateInfo.txt[]
@ -97,22 +117,23 @@ include::../structs/VkCommandPoolCreateInfo.txt[]
command buffers allocated from it. Bits which can: be set include:
+
--
// refBegin VkCommandPoolCreateFlagBits - Bitmask specifying usage behavior for a command pool
include::../enums/VkCommandPoolCreateFlagBits.txt[]
** ename:VK_COMMAND_POOL_CREATE_TRANSIENT_BIT indicates that command buffers
allocated from the pool will be short-lived, meaning that they will be
reset or freed in a relatively short timeframe. This flag may: be used by
the implementation to control memory allocation behavior within the pool.
** ename:VK_COMMAND_POOL_CREATE_RESET_COMMAND_BUFFER_BIT controls whether
command buffers allocated from the pool can: be individually reset. If
this flag is set, individual command buffers allocated from the pool can:
be reset either explicitly, by calling fname:vkResetCommandBuffer, or
implicitly, by calling fname:vkBeginCommandBuffer on an executable
command buffer. If this flag is not set, then fname:vkResetCommandBuffer
and fname:vkBeginCommandBuffer (on an executable command buffer) mustnot:
be called on the command buffers allocated from the pool, and they can:
only be reset in bulk by calling fname:vkResetCommandPool.
--
+
** ename:VK_COMMAND_POOL_CREATE_TRANSIENT_BIT indicates that command buffers
allocated from the pool will be short-lived, meaning that they will be
reset or freed in a relatively short timeframe. This flag may: be used by
the implementation to control memory allocation behavior within the pool.
** ename:VK_COMMAND_POOL_CREATE_RESET_COMMAND_BUFFER_BIT controls whether
command buffers allocated from the pool can: be individually reset. If
this flag is set, individual command buffers allocated from the pool can:
be reset either explicitly, by calling fname:vkResetCommandBuffer, or
implicitly, by calling fname:vkBeginCommandBuffer on an executable
command buffer. If this flag is not set, then fname:vkResetCommandBuffer
and fname:vkBeginCommandBuffer (on an executable command buffer) mustnot:
be called on the command buffers allocated from the pool, and they can:
only be reset in bulk by calling fname:vkResetCommandPool.
* pname:queueFamilyIndex designates a queue family as described in section
<<devsandqueues-queueprops,Queue Family Properties>>. All command
buffers created from this command pool must: be submitted on queues
@ -120,30 +141,34 @@ include::../enums/VkCommandPoolCreateFlagBits.txt[]
include::../validity/structs/VkCommandPoolCreateInfo.txt[]
Reset a command pool by calling:
// refBegin vkResetCommandPool Reset a command pool.
To reset a command pool, call:
include::../protos/vkResetCommandPool.txt[]
* pname:device is the logical device that owns the command pool.
* pname:commandPool is the command pool to reset.
* pname:flags contains additional flags controlling the behavior of the
reset.
include::../validity/protos/vkResetCommandPool.txt[]
reset. Bits which can: be set include:
+
--
// refBegin VkCommandPoolResetFlagBits - Bitmask controlling behavior of a command pool reset
include::../enums/VkCommandPoolResetFlagBits.txt[]
--
+
If pname:flags includes ename:VK_COMMAND_POOL_RESET_RELEASE_RESOURCES_BIT,
resetting a command pool recycles all of the resources from the command pool
back to the system.
Resetting a command pool recycles all of the resources from all of the
command buffers allocated from the command pool back to the command pool.
All command buffers that have been allocated from the command pool are put
in the initial state.
pname:flags is a bitmask controlling the operation. Bits which can: be
set include:
include::../validity/protos/vkResetCommandPool.txt[]
include::../enums/VkCommandPoolResetFlagBits.txt[]
If pname:flags includes ename:VK_COMMAND_POOL_RESET_RELEASE_RESOURCES_BIT,
resetting a command pool recycles all of the resources from the command pool
back to the system.
// refBegin vkDestroyCommandPool Destroy a command pool object
To destroy a command pool, call:
@ -154,17 +179,19 @@ include::../protos/vkDestroyCommandPool.txt[]
* pname:pAllocator controls host memory allocation as described in the
<<memory-allocation, Memory Allocation>> chapter.
include::../validity/protos/vkDestroyCommandPool.txt[]
When a pool is destroyed, all command buffers allocated from the pool are
implicitly freed and become invalid. Command buffers allocated from a given
pool do not need to be freed before destroying that command pool.
include::../validity/protos/vkDestroyCommandPool.txt[]
[[commandbuffer-allocation]]
== Command Buffer Allocation and Management
Command buffers are allocated by calling:
// refBegin vkAllocateCommandBuffers Allocate command buffers from an existing command pool
To allocate command buffers, call:
include::../protos/vkAllocateCommandBuffers.txt[]
@ -180,6 +207,8 @@ include::../protos/vkAllocateCommandBuffers.txt[]
include::../validity/protos/vkAllocateCommandBuffers.txt[]
// refBegin VkCommandBufferAllocateInfo Structure specifying the allocation parameters for command buffer object.
The sname:VkCommandBufferAllocateInfo structure is defined as:
include::../structs/VkCommandBufferAllocateInfo.txt[]
@ -191,13 +220,19 @@ include::../structs/VkCommandBufferAllocateInfo.txt[]
* pname:level determines whether the command buffers are primary or
secondary command buffers. Possible values include:
+
--
// refBegin VkCommandBufferLevel - Structure specifying a command buffer level
include::../enums/VkCommandBufferLevel.txt[]
--
+
* pname:commandBufferCount is the number of command buffers to allocate
from the pool.
include::../validity/structs/VkCommandBufferAllocateInfo.txt[]
Command buffers are reset by calling:
// refBegin vkResetCommandBuffer Reset a command buffer.
To reset command buffers, call:
include::../protos/vkResetCommandBuffer.txt[]
@ -207,18 +242,21 @@ include::../protos/vkResetCommandBuffer.txt[]
can: be set include:
+
--
// refBegin VkCommandBufferResetFlagBits - Bitmask controlling behavior of a command buffer reset
include::../enums/VkCommandBufferResetFlagBits.txt[]
--
+
If pname:flags includes ename:VK_COMMAND_BUFFER_RESET_RELEASE_RESOURCES_BIT,
then most or all memory resources currently owned by the command buffer
should: be returned to the parent command pool. If this flag is not set,
then the command buffer may: hold onto memory resources and reuse them when
recording commands.
--
include::../validity/protos/vkResetCommandBuffer.txt[]
Command buffers are freed by calling:
// refBegin vkFreeCommandBuffers Free command buffers.
To free command buffers, call:
include::../protos/vkFreeCommandBuffers.txt[]
@ -235,6 +273,8 @@ include::../validity/protos/vkFreeCommandBuffers.txt[]
[[commandbuffers-recording]]
== Command Buffer Recording
// refBegin vkBeginCommandBuffer Start recording a command buffer
To begin recording a command buffer, call:
include::../protos/vkBeginCommandBuffer.txt[]
@ -247,6 +287,8 @@ include::../protos/vkBeginCommandBuffer.txt[]
include::../validity/protos/vkBeginCommandBuffer.txt[]
// refBegin VkCommandBufferBeginInfo - Structure specifying a command buffer begin operation
The sname:VkCommandBufferBeginInfo structure is defined as:
include::../structs/VkCommandBufferBeginInfo.txt[]
@ -257,18 +299,19 @@ include::../structs/VkCommandBufferBeginInfo.txt[]
buffer. Bits which can: be set include:
+
--
// refBegin VkCommandBufferUsageFlagBits - Bitmask specifying usage behavior for command buffer
include::../enums/VkCommandBufferUsageFlagBits.txt[]
** ename:VK_COMMAND_BUFFER_USAGE_ONE_TIME_SUBMIT_BIT indicates that each
recording of the command buffer will only be submitted once, and the
command buffer will be reset and recorded again between each submission.
** ename:VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT indicates that
a secondary command buffer is considered to be entirely inside a render
pass. If this is a primary command buffer, then this bit is ignored.
** Setting ename:VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT allows the
command buffer to be resubmitted to a queue or recorded into a primary
command buffer while it is pending execution.
--
+
** ename:VK_COMMAND_BUFFER_USAGE_ONE_TIME_SUBMIT_BIT indicates that each
recording of the command buffer will only be submitted once, and the
command buffer will be reset and recorded again between each submission.
** ename:VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT indicates that
a secondary command buffer is considered to be entirely inside a render
pass. If this is a primary command buffer, then this bit is ignored.
** Setting ename:VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT allows the
command buffer to be resubmitted to a queue or recorded into a primary
command buffer while it is pending execution.
* pname:pInheritanceInfo is a pointer to a
sname:VkCommandBufferInheritanceInfo structure, which is used if
pname:commandBuffer is a secondary command buffer. If this is a primary
@ -276,6 +319,8 @@ include::../enums/VkCommandBufferUsageFlagBits.txt[]
include::../validity/structs/VkCommandBufferBeginInfo.txt[]
// refBegin VkCommandBufferInheritanceInfo - Structure specifying command buffer inheritance info
If the command buffer is a secondary command buffer, then the
sname:VkCommandBufferInheritanceInfo structure defines any state that will
be inherited from the primary command buffer:
@ -293,7 +338,7 @@ include::../structs/VkCommandBufferInheritanceInfo.txt[]
* pname:framebuffer refers to the sname:VkFramebuffer object that the
sname:VkCommandBuffer will be rendering to if it was allocated with
the ename:VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT set. It can:
be code:VK_NULL_HANDLE if the framebuffer is not known.
be dlink:VK_NULL_HANDLE if the framebuffer is not known.
+
[NOTE]
.Note
@ -368,6 +413,8 @@ Once recording starts, an application records a sequence of commands
(ftext:vkCmd*) to set state in the command buffer, draw, dispatch, and other
commands.
// refBegin vkEndCommandBuffer Finish recording a command buffer
To complete recording of a command buffer, call:
include::../protos/vkEndCommandBuffer.txt[]
@ -376,13 +423,13 @@ include::../protos/vkEndCommandBuffer.txt[]
command buffer must: have been in the recording state, and is moved to
the executable state.
include::../validity/protos/vkEndCommandBuffer.txt[]
If there was an error during recording, the application will be notified by
an unsuccessful return code returned by fname:vkEndCommandBuffer. If the
application wishes to further use the command buffer, the command buffer
must: be reset.
include::../validity/protos/vkEndCommandBuffer.txt[]
When a command buffer is in the executable state, it can: be submitted to a
queue for execution.
@ -390,7 +437,9 @@ queue for execution.
[[commandbuffers-submission]]
== Command Buffer Submission
Command buffers are submitted to a queue by calling:
// refBegin vkQueueSubmit Submits a sequence of semaphores or command buffers to a queue.
To submit command buffers to a queue, call:
include::../protos/vkQueueSubmit.txt[]
@ -399,11 +448,9 @@ include::../protos/vkQueueSubmit.txt[]
* pname:pSubmits is a pointer to an array of slink:VkSubmitInfo structures,
each specifying a command buffer submission batch.
* pname:fence is an optional handle to a fence to be signaled. If
pname:fence is not code:VK_NULL_HANDLE, it defines a
pname:fence is not dlink:VK_NULL_HANDLE, it defines a
<<synchronization-fences-signaling, fence signal operation>>.
include::../validity/protos/vkQueueSubmit.txt[]
[NOTE]
.Note
====
@ -417,6 +464,23 @@ fname:vkQueueSubmit is a
defined by an element of pname:pSubmits as an instance of the
slink:VkSubmitInfo structure.
Fence and semaphore operations submitted with flink:vkQueueSubmit have
additional ordering constraints compared to other submission commands,
with dependencies involving previous and subsequent queue operations.
Information about these additional constraints can be found in the
<<synchronization-semaphores, semaphore>> and
<<synchronization-semaphores, fence>> sections of
<<synchronization, the synchronization chapter>>.
Details on the interaction of pname:pWaitDstStageMask with synchronization
are described in the
<<synchronization-semaphores-waiting, semaphore wait operation>> section of
<<synchronization, the synchronization chapter>>.
include::../validity/protos/vkQueueSubmit.txt[]
// refBegin VkSubmitInfo - Structure specifying a queue submit operation
The sname:VkSubmitInfo structure is defined as:
include::../structs/VkSubmitInfo.txt[]
@ -447,18 +511,6 @@ include::../structs/VkSubmitInfo.txt[]
include::../validity/structs/VkSubmitInfo.txt[]
Fence and semaphore operations submitted with flink:vkQueueSubmit have
additional ordering constraints compared to other submission commands,
with dependencies involving previous and subsequent queue operations.
Information about these additional constraints can be found in the
<<synchronization-semaphores, semaphore>> and
<<synchronization-semaphores, fence>> sections of
<<synchronization, the synchronization chapter>>.
Details on the interaction of pname:pWaitDstStageMask with synchronization
are described in the
<<synchronization-semaphores-waiting, semaphore wait operation>> section of
<<synchronization, the synchronization chapter>>.
[[commandbuffers-submission-progress]]
== Queue Forward Progress
@ -466,22 +518,24 @@ are described in the
The application must: ensure that command buffer submissions will be able to
complete without any subsequent operations by the application on any queue.
After any call to fname:vkQueueSubmit, for every queued wait on a semaphore
there must: be a prior signal of that semaphore that won't be consumed by a
there must: be a prior signal of that semaphore that will not be consumed by a
different wait on the semaphore.
Command buffers in the submission can: include flink:vkCmdWaitEvents
commands that wait on events that won't be signaled by earlier commands in
commands that wait on events that will not be signaled by earlier commands in
the queue. Such events must: be signaled by the application using
flink:vkSetEvent, and the fname:vkCmdWaitEvents commands that wait upon them
mustnot: be inside a render pass instance. Implementations may: have limits
on how long the command buffer will wait, in order to avoid interfering with
progress of other clients of the device. If the event isn't signaled within
progress of other clients of the device. If the event is not signaled within
these limits, results are undefined and may: include device loss.
[[commandbuffers-secondary]]
== Secondary Command Buffer Execution
// refBegin vkCmdExecuteCommands Execute a secondary command buffer from a primary command buffer.
A secondary command buffer mustnot: be directly submitted to a queue.
Instead, secondary command buffers are recorded to execute as part of a
primary command buffer with the command:
@ -497,10 +551,10 @@ include::../protos/vkCmdExecuteCommands.txt[]
which are recorded to execute in the primary command buffer in the order
they are listed in the array.
include::../validity/protos/vkCmdExecuteCommands.txt[]
Once fname:vkCmdExecuteCommands has been called, any prior executions of the
secondary command buffers specified by pname:pCommandBuffers in any other
primary command buffer become invalidated, unless those secondary command
buffers were recorded with
ename:VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT.
include::../validity/protos/vkCmdExecuteCommands.txt[]

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

@ -53,6 +53,8 @@ synchronization barriers.
[[copies-buffers]]
== Copying Data Between Buffers
// refBegin vkCmdCopyBuffer Copy data between buffer regions.
To copy data between buffer objects, call:
include::../protos/vkCmdCopyBuffer.txt[]
@ -72,6 +74,8 @@ the copy regions overlap in memory.
include::../validity/protos/vkCmdCopyBuffer.txt[]
// refBegin VkBufferCopy - Structure specifying a buffer copy operation
The sname:VkBufferCopy structure is defined as:
include::../structs/VkBufferCopy.txt[]
@ -95,6 +99,8 @@ Rather, it simply copies raw image data. fname:vkCmdCopyImage can: copy
between images with different formats, provided the formats are compatible
as defined below.
// refBegin vkCmdCopyImage Copy data between images.
To copy data between image objects, call:
include::../protos/vkCmdCopyImage.txt[]
@ -115,39 +121,6 @@ Each region in pname:pRegions is copied from the source image to the same
region of the destination image. pname:srcImage and pname:dstImage can: be
the same image or alias the same memory.
include::../validity/protos/vkCmdCopyImage.txt[]
The sname:VkImageCopy structure is defined as:
include::../structs/VkImageCopy.txt[]
* pname:srcSubresource and pname:dstSubresource are
slink:VkImageSubresourceLayers structures specifying the image
subresources of the images used for the source and destination image
data, respectively.
* pname:srcOffset and pname:dstOffset select the initial x, y, and z
offsets in texels of the sub-regions of the source and destination image
data.
* pname:extent is the size in texels of the source image to copy in
pname:width, pname:height and pname:depth. 1D images use only pname:x
and pname:width. 2D images use pname:x, pname:y, pname:width and
pname:height. 3D images use pname:x, pname:y, pname:z, pname:width,
pname:height and pname:depth.
include::../validity/structs/VkImageCopy.txt[]
The sname:VkImageSubresourceLayers structure is defined as:
include::../structs/VkImageSubresourceLayers.txt[]
* pname:aspectMask is a combination of elink:VkImageAspectFlagBits,
selecting the color, depth and/or stencil aspects to be copied.
* pname:mipLevel is the mipmap level to copy from.
* pname:baseArrayLayer and pname:layerCount are the starting layer and
number of layers to copy.
include::../validity/structs/VkImageSubresourceLayers.txt[]
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.
@ -211,10 +184,49 @@ be included as a source or destination of the copy.
fname:vkCmdCopyImage can: be used to copy image data between multisample
images, but both images must: have the same number of samples.
include::../validity/protos/vkCmdCopyImage.txt[]
// refBegin VkImageCopy - Structure specifying an image copy operation
The sname:VkImageCopy structure is defined as:
include::../structs/VkImageCopy.txt[]
* pname:srcSubresource and pname:dstSubresource are
slink:VkImageSubresourceLayers structures specifying the image
subresources of the images used for the source and destination image
data, respectively.
* pname:srcOffset and pname:dstOffset select the initial x, y, and z
offsets in texels of the sub-regions of the source and destination image
data.
* pname:extent is the size in texels of the source image to copy in
pname:width, pname:height and pname:depth. 1D images use only pname:x
and pname:width. 2D images use pname:x, pname:y, pname:width and
pname:height. 3D images use pname:x, pname:y, pname:z, pname:width,
pname:height and pname:depth.
include::../validity/structs/VkImageCopy.txt[]
// refBegin VkImageSubresourceLayers - Structure specifying a image subresource layers
The sname:VkImageSubresourceLayers structure is defined as:
include::../structs/VkImageSubresourceLayers.txt[]
* pname:aspectMask is a combination of elink:VkImageAspectFlagBits,
selecting the color, depth and/or stencil aspects to be copied.
* pname:mipLevel is the mipmap level to copy from.
* pname:baseArrayLayer and pname:layerCount are the starting layer and
number of layers to copy.
include::../validity/structs/VkImageSubresourceLayers.txt[]
[[copies-buffers-images]]
== Copying Data Between Buffers and Images
// refBegin vkCmdCopyBufferToImage Copy data from a buffer into an image.
To copy data from a buffer object to an image object, call:
include::../protos/vkCmdCopyBufferToImage.txt[]
@ -234,6 +246,8 @@ source buffer to the specified region of the destination image.
include::../validity/protos/vkCmdCopyBufferToImage.txt[]
// refBegin vkCmdCopyImageToBuffer Copy image data into a buffer.
To copy data from an image object to a buffer object, call:
include::../protos/vkCmdCopyImageToBuffer.txt[]
@ -253,6 +267,8 @@ source image to the specified region of the destination buffer.
include::../validity/protos/vkCmdCopyImageToBuffer.txt[]
// refBegin VkBufferImageCopy - Structure specifying a buffer image copy operation
For both flink:vkCmdCopyBufferToImage and flink:vkCmdCopyImageToBuffer, each
element of pname:pRegions is a structure defined as:
@ -380,6 +396,8 @@ destination of the copy.
[[copies-imagescaling]]
== Image Copies with Scaling
// refBegin vkCmdBlitImage - Copy regions of an image, potentially performing format conversion,
To copy regions of a source image into a destination image, potentially
performing format conversion, arbitrary scaling, and filtering, call:
@ -399,23 +417,9 @@ include::../protos/vkCmdBlitImage.txt[]
* pname:filter is a elink:VkFilter specifying the filter to apply if the
blits require scaling.
include::../validity/protos/vkCmdBlitImage.txt[]
fname:vkCmdBlitImage mustnot: be used for multisampled source or destination
images. Use flink:vkCmdResolveImage for this purpose.
The sname:VkImageBlit structure is defined as:
include::../structs/VkImageBlit.txt[]
For each element of the pname:pRegions array, a blit operation is performed
between the region of pname:srcSubresource of pname:srcImage (bounded by
pname:srcOffsets[0] and pname:srcOffsets[1]) and a region of
pname:dstSubresource of pname:dstImage (bounded by pname:dstOffsets[0] and
pname:dstOffsets[1]).
include::../validity/structs/VkImageBlit.txt[]
If sizes of source and destination extents do not match, scaling is
performed by applying the filtering mode specified by pname:filter
parameter. ename:VK_FILTER_LINEAR uses bilinear interpolation, and
@ -468,10 +472,33 @@ The following filtering and conversion rules apply:
Signed and unsigned integers are converted by first clamping to the
representable range of the destination format, then casting the value.
include::../validity/protos/vkCmdBlitImage.txt[]
// refBegin VkImageBlit - Structure specifying an image blit operation
The sname:VkImageBlit structure is defined as:
include::../structs/VkImageBlit.txt[]
* pname:srcSubresource is the subresource to blit from.
* pname:srcOffsets is an array of two slink:VkOffset3D structures
specifying the bounds of the source region within pname:srcSubresource.
* pname:dstSubresource is the subresource to blit into.
* pname:dstOffsets is an array of two slink:VkOffset3D structures
specifying the bounds of the destination region within
pname:dstSubresource.
For each element of the pname:pRegions array, a blit operation is performed
the specified source and destination regions.
include::../validity/structs/VkImageBlit.txt[]
[[copies-resolve]]
== Resolving Multisample Images
// refBegin vkCmdResolveImage Resolve regions of an image.
To resolve a multisample image to a non-multisample image, call:
include::../protos/vkCmdResolveImage.txt[]
@ -488,8 +515,29 @@ include::../protos/vkCmdResolveImage.txt[]
* pname:pRegions is a pointer to an array of slink:VkImageResolve
structures specifying the regions to resolve.
During the resolve the samples corresponding to each pixel location in the
source are converted to a single sample before being written to the
destination. If the source formats are floating-point or normalized types,
the sample values for each pixel are resolved in an implementation-dependent
manner. If the source formats are integer types, a single sample's value is
selected for each pixel.
pname:srcOffset and pname:dstOffset select the initial x, y, and z
offsets in texels of the sub-regions of the source and destination image
data. pname:extent is the size in texels of the source
image to resolve in pname:width, pname:height and pname:depth. 1D images use
only pname:x and pname:width. 2D images use pname:x, pname:y, pname:width
and pname:height. 3D images use pname:x, pname:y, pname:z, pname:width,
pname:height and pname:depth.
Resolves 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 resolved to the destination image.
include::../validity/protos/vkCmdResolveImage.txt[]
// refBegin VkImageResolve - Structure specifying an image resolve operation
The sname:VkImageResolve structure is defined as:
include::../structs/VkImageResolve.txt[]
@ -509,21 +557,3 @@ include::../structs/VkImageResolve.txt[]
include::../validity/structs/VkImageResolve.txt[]
During the resolve the samples corresponding to each pixel location in the
source are converted to a single sample before being written to the
destination. If the source formats are floating-point or normalized types,
the sample values for each pixel are resolved in an implementation-dependent
manner. If the source formats are integer types, a single sample's value is
selected for each pixel.
pname:srcOffset and pname:dstOffset select the initial x, y, and z
offsets in texels of the sub-regions of the source and destination image
data. pname:extent is the size in texels of the source
image to resolve in pname:width, pname:height and pname:depth. 1D images use
only pname:x and pname:width. 2D images use pname:x, pname:y, pname:width
and pname:height. 3D images use pname:x, pname:y, pname:z, pname:width,
pname:height and pname:depth.
Resolves 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 resolved to the destination image.

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

@ -138,7 +138,7 @@ pname:shaderStorageImageWriteWithoutFormat>> feature is not enabled,
storage image declarations must: specify the image format in the
shader if the variable is used for store operations.
Storage images are declared in GLSL shader source using uniform ``image''
Storage images are declared in GLSL shader source using uniform code:image
variables of the appropriate dimensionality as well as a format layout
qualifier (if necessary):
@ -173,7 +173,7 @@ parameters which control address calculations, filtering behavior, and other
properties, that can: be used to perform filtered loads from _sampled
images_ (see <<descriptorsets-sampledimage, Sampled Image>>).
Samplers are declared in GLSL shader source using uniform ``sampler''
Samplers are declared in GLSL shader source using uniform code:sampler
variables, where the sampler type has no associated texture dimensionality:
.GLSL Example
@ -211,7 +211,7 @@ performed. The same sampler can: be used to sample from multiple images, and
it is possible to sample from the same sampled image with multiple samplers,
each containing a different set of sampling parameters.
Sampled images are declared in GLSL shader source using uniform ``texture''
Sampled images are declared in GLSL shader source using uniform code:texture
variables of the appropriate dimensionality:
.GLSL example
@ -254,7 +254,7 @@ the descriptor set in a combined descriptor.
====
Combined image samplers are declared in GLSL shader source using uniform
``sampler'' variables of the appropriate dimensionality:
code:sampler variables of the appropriate dimensionality:
.GLSL example
[source,{basebackend@docbook:c:glsl}]
@ -299,7 +299,7 @@ formatted data that is stored in a buffer and is made accessible to shaders.
Uniform texel buffers are read-only.
Uniform texel buffers are declared in GLSL shader source using uniform
``samplerBuffer'' variables:
code:samplerBuffer variables:
.GLSL example
[source,{basebackend@docbook:c:glsl}]
@ -337,7 +337,7 @@ operations in shaders, may: support a different maximum length, and may:
have different performance characteristics.
Storage texel buffers are declared in GLSL shader source using uniform
``imageBuffer'' variables:
code:imageBuffer variables:
.GLSL example
[source,{basebackend@docbook:c:glsl}]
@ -541,14 +541,24 @@ between shader stages and shader resources.
[[descriptorsets-setlayout]]
=== Descriptor Set Layout
// refBegin VkDescriptorSetLayout - Opaque handle to a descriptor set layout object
A descriptor set layout object is defined by an array of zero or more
descriptor bindings. Each individual descriptor binding is specified by a
descriptor type, a count (array size) of the number of descriptors in the
binding, a set of shader stages that can: access the binding, and (if using
immutable samplers) an array of sampler descriptors.
Descriptor set layouts are represented by sname:VkDescriptorSetLayout
objects which are created by calling:
Descriptor set layout objects are represented by sname:VkDescriptorSetLayout
handles:
include::../handles/VkDescriptorSetLayout.txt[]
// refEnd VkDescriptorSetLayout
// refBegin vkCreateDescriptorSetLayout Create a new descriptor set layout.
To create descriptor set layout objects, call:
include::../protos/vkCreateDescriptorSetLayout.txt[]
@ -564,6 +574,8 @@ include::../protos/vkCreateDescriptorSetLayout.txt[]
include::../validity/protos/vkCreateDescriptorSetLayout.txt[]
// refBegin VkDescriptorSetLayoutCreateInfo - Structure specifying parameters of a newly created descriptor set layout
Information about the descriptor set layout is passed in an instance of the
sname:VkDescriptorSetLayoutCreateInfo structure:
@ -578,6 +590,8 @@ include::../structs/VkDescriptorSetLayoutCreateInfo.txt[]
include::../validity/structs/VkDescriptorSetLayoutCreateInfo.txt[]
// refBegin VkDescriptorSetLayoutBinding - Structure specifying a descriptor set layout binding
The sname:VkDescriptorSetLayoutBinding structure is defined as:
include::../structs/VkDescriptorSetLayoutBinding.txt[]
@ -591,18 +605,19 @@ include::../structs/VkDescriptorSetLayoutBinding.txt[]
zero this binding entry is reserved and the resource mustnot: be
accessed from any stage via this binding within any pipeline using the
set layout.
* pname:stageFlags member is a bitfield of elink:VkShaderStageFlagBits
* pname:stageFlags member is a bitmask of elink:VkShaderStageFlagBits
specifying which pipeline shader stages can: access a resource for this
binding. ename:VK_SHADER_STAGE_ALL is a shorthand specifying that all
defined shader stages, including any additional stages defined by
extensions, can: access the resource.
+
--
If a shader stage is not included in pname:stageFlags, then a resource
mustnot: be accessed from that stage via this binding within any pipeline
using the set layout. There are no limitations on what combinations of
stages can: be used by a descriptor binding, and in particular a binding
can: be used by both graphics stages and the compute stage.
--
* pname:pImmutableSamplers affects initialization of samplers. If
pname:descriptorType specifies a ename:VK_DESCRIPTOR_TYPE_SAMPLER or
ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER type descriptor, then
@ -775,6 +790,8 @@ myResult = vkCreateDescriptorSetLayout(
&myDescriptorSetLayout[1]);
-------------------------------------------------------------------------------
// refBegin vkDestroyDescriptorSetLayout Destroy a descriptor set layout object
To destroy a descriptor set layout, call:
include::../protos/vkDestroyDescriptorSetLayout.txt[]
@ -791,6 +808,8 @@ include::../validity/protos/vkDestroyDescriptorSetLayout.txt[]
[[descriptorsets-pipelinelayout]]
=== Pipeline Layouts
// refBegin VkPipelineLayout - Opaque handle to a pipeline layout object
Access to descriptor sets from a pipeline is accomplished through a
_pipeline layout_. Zero or more descriptor set layouts and zero or more push
constant ranges are combined to form a
@ -800,7 +819,15 @@ descriptor sets with each having a specific layout. This sequence of layouts
is used to determine the interface between shader stages and shader
resources. Each pipeline is created using a pipeline layout.
A pipeline layout is created by calling:
Pipeline layout objects are represented by sname:VkPipelineLayout handles:
include::../handles/VkPipelineLayout.txt[]
// refEnd VkPipelineLayout
// refBegin vkCreatePipelineLayout Creates a new pipeline layout object.
To create a pipeline layout, call:
include::../protos/vkCreatePipelineLayout.txt[]
@ -815,6 +842,8 @@ include::../protos/vkCreatePipelineLayout.txt[]
include::../validity/protos/vkCreatePipelineLayout.txt[]
// refBegin VkPipelineLayoutCreateInfo Structure specifying the parameters of a newly created pipeline layout object.
The slink:VkPipelineLayoutCreateInfo structure is defined as:
include::../structs/VkPipelineLayoutCreateInfo.txt[]
@ -843,6 +872,8 @@ pipelines that is expected to outperform memory-backed resource updates.
include::../validity/structs/VkPipelineLayoutCreateInfo.txt[]
// refBegin VkPushConstantRange - Structure specifying a push constant range
The sname:VkPushConstantRange structure is defined as:
include::../structs/VkPushConstantRange.txt[]
@ -922,6 +953,8 @@ type of resource that can: be used in any pipeline stage as described in
|=============================
// refBegin vkDestroyPipelineLayout Destroy a pipeline layout object
To destroy a pipeline layout, call:
include::../protos/vkDestroyPipelineLayout.txt[]
@ -1031,12 +1064,22 @@ myResult = vkCreatePipelineLayout(
[[descriptorsets-allocation]]
=== Allocation of Descriptor Sets
Descriptor sets are allocated from _descriptor pool_ objects. A descriptor
pool maintains a pool of descriptors, from which sets are allocated.
// refBegin VkDescriptorPool - Opaque handle to a descriptor pool object
A _descriptor pool_
maintains a pool of descriptors, from which descriptor sets are allocated.
Descriptor pools are externally synchronized, meaning that the application
mustnot: allocate and/or free descriptor sets from the same pool in multiple
threads simultaneously.
Descriptor pools are represented by sname:VkDescriptorPool handles:
include::../handles/VkDescriptorPool.txt[]
// refEnd VkDescriptorPool
// refBegin vkCreateDescriptorPool Creates a descriptor pool object.
To create a descriptor pool object, call:
include::../protos/vkCreateDescriptorPool.txt[]
@ -1057,6 +1100,8 @@ The created descriptor pool is returned in pname:pDescriptorPool.
include::../validity/protos/vkCreateDescriptorPool.txt[]
// refBegin VkDescriptorPoolCreateInfo - Structure specifying parameters of a newly created descriptor pool
Additional information about the pool is passed in an instance of the
sname:VkDescriptorPoolCreateInfo structure:
@ -1064,8 +1109,23 @@ include::../structs/VkDescriptorPoolCreateInfo.txt[]
* pname:sType is the type of this structure.
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
* pname:flags specifies certain supported operations on the pool, with
possible values defined below.
* pname:flags specifies certain supported operations on the pool.
Bits which can: be set include:
+
--
// refBegin VkDescriptorPoolCreateFlagBits - Bitmask specifying certain supported operations on a descriptor pool
include::../enums/VkDescriptorPoolCreateFlagBits.txt[]
--
+
If pname:flags includes
ename:VK_DESCRIPTOR_POOL_CREATE_FREE_DESCRIPTOR_SET_BIT, then descriptor
sets can: return their individual allocations to the pool, i.e. all of
fname:vkAllocateDescriptorSets, fname:vkFreeDescriptorSets, and
fname:vkResetDescriptorPool are allowed. Otherwise, descriptor sets
allocated from the pool mustnot: be individually freed back to the pool,
i.e. only fname:vkAllocateDescriptorSets and fname:vkResetDescriptorPool are
allowed.
+
* pname:maxSets is the maximum number of descriptor sets that can:
be allocated from the pool.
* pname:poolSizeCount is the number of elements in pname:pPoolSizes.
@ -1073,8 +1133,6 @@ include::../structs/VkDescriptorPoolCreateInfo.txt[]
structures, each containing a descriptor type and number of descriptors
of that type to be allocated in the pool.
include::../validity/structs/VkDescriptorPoolCreateInfo.txt[]
If multiple sname:VkDescriptorPoolSize structures appear in the
pname:pPoolSizes array then the pool will be created with enough storage
for the total number of descriptors of each type.
@ -1100,19 +1158,9 @@ If an allocation failure occurs due to fragmentation, an application can:
create an additional descriptor pool to perform further descriptor set
allocations.
The pname:flags member of sname:VkDescriptorPoolCreateInfo can: include the
following values:
include::../validity/structs/VkDescriptorPoolCreateInfo.txt[]
include::../enums/VkDescriptorPoolCreateFlagBits.txt[]
If pname:flags includes
ename:VK_DESCRIPTOR_POOL_CREATE_FREE_DESCRIPTOR_SET_BIT, then descriptor
sets can: return their individual allocations to the pool, i.e. all of
fname:vkAllocateDescriptorSets, fname:vkFreeDescriptorSets, and
fname:vkResetDescriptorPool are allowed. Otherwise, descriptor sets
allocated from the pool mustnot: be individually freed back to the pool,
i.e. only fname:vkAllocateDescriptorSets and fname:vkResetDescriptorPool are
allowed.
// refBegin VkDescriptorPoolSize - Structure specifying descriptor pool size
The sname:VkDescriptorPoolSize structure is defined as:
@ -1124,6 +1172,8 @@ include::../structs/VkDescriptorPoolSize.txt[]
include::../validity/structs/VkDescriptorPoolSize.txt[]
// refBegin vkDestroyDescriptorPool Destroy a descriptor pool object
To destroy a descriptor pool, call:
include::../protos/vkDestroyDescriptorPool.txt[]
@ -1133,13 +1183,24 @@ include::../protos/vkDestroyDescriptorPool.txt[]
* pname:pAllocator controls host memory allocation as described in the
<<memory-allocation, Memory Allocation>> chapter.
include::../validity/protos/vkDestroyDescriptorPool.txt[]
When a pool is destroyed, all descriptor sets allocated from the pool are
implicitly freed and become invalid. Descriptor sets allocated from a given
pool do not need to be freed before destroying that descriptor pool.
Descriptor sets are allocated from a descriptor pool by calling:
include::../validity/protos/vkDestroyDescriptorPool.txt[]
// refBegin VkDescriptorSet - Opaque handle to a descriptor set object
Descriptor sets are allocated from descriptor pool objects, and
are represented by sname:VkDescriptorSet handles:
include::../handles/VkDescriptorSet.txt[]
// refEnd VkDescriptorSet
// refBegin vkAllocateDescriptorSets Allocate one or more descriptor sets.
To allocate descriptor sets from a descriptor pool, call:
include::../protos/vkAllocateDescriptorSets.txt[]
@ -1152,24 +1213,8 @@ include::../protos/vkAllocateDescriptorSets.txt[]
array must: be at least the length specified by the
pname:descriptorSetCount member of pname:pAllocateInfo.
include::../validity/protos/vkAllocateDescriptorSets.txt[]
The sname:VkDescriptorSetAllocateInfo structure is defined as:
include::../structs/VkDescriptorSetAllocateInfo.txt[]
* pname:sType is the type of this structure.
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
* pname:descriptorPool is the pool which the sets will be allocated from.
* pname:descriptorSetCount determines the number of descriptor sets to be
allocated from the pool.
* pname:pSetLayouts is an array of descriptor set layouts, with each
member specifying how the corresponding descriptor set is allocated.
The allocated descriptor sets are returned in pname:pDescriptorSets.
include::../validity/structs/VkDescriptorSetAllocateInfo.txt[]
When a descriptor set is allocated, the initial state is largely
uninitialized and all descriptors are undefined. However,
the descriptor set can: be bound
@ -1182,7 +1227,27 @@ a draw or dispatch with such a descriptor set bound does not cause undefined
behavior. This means applications need not populate unused entries with dummy
descriptors.
Allocated descriptor sets are freed by calling:
include::../validity/protos/vkAllocateDescriptorSets.txt[]
// refBegin VkDescriptorSetAllocateInfo Structure specifying the allocation parameters for descriptor sets.
The sname:VkDescriptorSetAllocateInfo structure is defined as:
include::../structs/VkDescriptorSetAllocateInfo.txt[]
* pname:sType is the type of this structure.
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
* pname:descriptorPool is the pool which the sets will be allocated from.
* pname:descriptorSetCount determines the number of descriptor sets to be
allocated from the pool.
* pname:pSetLayouts is an array of descriptor set layouts, with each
member specifying how the corresponding descriptor set is allocated.
include::../validity/structs/VkDescriptorSetAllocateInfo.txt[]
// refBegin vkFreeDescriptorSets Free one or more descriptor sets
To free allocated descriptor sets, call:
include::../protos/vkFreeDescriptorSets.txt[]
@ -1192,45 +1257,36 @@ include::../protos/vkFreeDescriptorSets.txt[]
* pname:descriptorSetCount is the number of elements in the
pname:pDescriptorSets array.
* pname:pDescriptorSets is an array of handles to sname:VkDescriptorSet
objects. All elements of pname:pDescriptorSets must: have been allocated
from pname:descriptorPool.
In order to free individual descriptor sets, pname:descriptorPool must: have
been created with the
ename:VK_DESCRIPTOR_POOL_CREATE_FREE_DESCRIPTOR_SET_BIT flag.
ifdef::editing-notes[]
[NOTE]
.editing-note
====
(Jon) Several comments above seem like they belong in validity XML.
====
endif::editing-notes[]
include::../validity/protos/vkFreeDescriptorSets.txt[]
objects.
After a successful call to fname:vkFreeDescriptorSets, all descriptor sets
in pname:pDescriptorSets are invalid.
Rather than freeing individual descriptor sets, all descriptor sets
allocated from a given pool can: be returned to the pool by calling:
include::../validity/protos/vkFreeDescriptorSets.txt[]
// refBegin vkResetDescriptorPool Resets a descriptor pool object.
To return all descriptor sets allocated from a given pool to the pool,
rather than freeing individual descriptor sets, call:
include::../protos/vkResetDescriptorPool.txt[]
* pname:device is the logical device that owns the descriptor pool.
* pname:descriptorPool is the descriptor pool to be reset.
* pname:flags is currently unused and must: be zero.
include::../validity/protos/vkResetDescriptorPool.txt[]
* pname:flags is reserved for future use.
Resetting a descriptor pool recycles all of the resources from all of the
descriptor sets allocated from the descriptor pool back to the descriptor
pool, and the descriptor sets are implicitly freed.
include::../validity/protos/vkResetDescriptorPool.txt[]
[[descriptorsets-updates]]
=== Descriptor Set Updates
// refBegin vkUpdateDescriptorSets Update the contents of a descriptor set object.
Once allocated, descriptor sets can: be updated with a combination of write
and copy operations. To update descriptor sets, call:
@ -1253,12 +1309,18 @@ followed by the operations described by pname:pDescriptorCopies. Within
each array, the operations are performed in the order they appear in the
array.
include::../validity/protos/vkUpdateDescriptorSets.txt[]
Each element in the pname:pDescriptorWrites array describes an operation
updating the descriptor set using descriptors for resources specified in the
structure.
Each element in the pname:pDescriptorCopies array is a
slink:VkCopyDescriptorSet structure describing an operation copying
descriptors between sets.
include::../validity/protos/vkUpdateDescriptorSets.txt[]
// refBegin VkWriteDescriptorSet Structure specifying the parameters of a descriptor set write operation.
The sname:VkWriteDescriptorSet structure is defined as:
include::../structs/VkWriteDescriptorSet.txt[]
@ -1271,35 +1333,72 @@ include::../structs/VkWriteDescriptorSet.txt[]
* pname:descriptorCount is the number of descriptors to update (the
number of elements in pname:pImageInfo, pname:pBufferInfo, or
pname:pTexelBufferView).
* pname:descriptorType is the type of each descriptor in pname:pImageInfo,
pname:pBufferInfo, or pname:pTexelBufferView, and must: be the same type
as what was specified in sname:VkDescriptorSetLayoutBinding for
* pname:descriptorType is a elink:VkDescriptorType
specifying the type of each descriptor in pname:pImageInfo,
pname:pBufferInfo, or pname:pTexelBufferView, as described below.
It must: be the same type
as that specified in sname:VkDescriptorSetLayoutBinding for
pname:dstSet at pname:dstBinding. The type of the descriptor also
controls which array the descriptors are taken from.
pname:descriptorType can: take on values including:
include::../enums/VkDescriptorType.txt[]
* pname:pImageInfo points to an array of sname:VkDescriptorImageInfo
* pname:pImageInfo points to an array of slink:VkDescriptorImageInfo
structures or is ignored, as described below.
* pname:pBufferInfo points to an array of sname:VkDescriptorBufferInfo
* pname:pBufferInfo points to an array of slink:VkDescriptorBufferInfo
structures or is ignored, as described below.
* pname:pTexelBufferView points to an array of sname:VkBufferView
handles or is ignored, as described below.
include::../validity/structs/VkWriteDescriptorSet.txt[]
* pname:pTexelBufferView points to an array of slink:VkBufferView handles
as described in the <<resources-buffer-views,Buffer Views>> section or
is ignored, as described below.
Only one of pname:pImageInfo, pname:pBufferInfo, or pname:pTexelBufferView
members is used according to the descriptor type specified in the
pname:descriptorType member of the containing sname:VkWriteDescriptorSet
structure, as specified below.
[[descriptorsets-updates-consecutive, consecutive binding updates]]
If the pname:dstBinding has fewer than pname:descriptorCount array elements
remaining starting from pname:dstArrayElement, then the remainder will be
used to update the subsequent binding - pname:dstBinding+1 starting at array
element zero. This behavior applies recursively, with the update affecting
consecutive bindings as needed to update all pname:descriptorCount
descriptors. All consecutive bindings updated via a single
sname:VkWriteDescriptorSet structure must: have identical
pname:descriptorType and pname:stageFlags, and must: all either use
immutable samplers or must: all not use immutable samplers.
include::../validity/structs/VkWriteDescriptorSet.txt[]
// refBegin VkDescriptorType Specifies the type of a descriptor in a descriptor set.
The type of descriptors in a descriptor set is specified by
slink:VkWriteDescriptorSet::pname:descriptorType, which must: be one of the
values:
include::../enums/VkDescriptorType.txt[]
If pname:descriptorType is ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER,
ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER,
ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC, or
ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC, the elements of the
pname:pBufferInfo array of sname:VkDescriptorBufferInfo structures will be
used to update the descriptors, and other arrays will be ignored.
slink:VkWriteDescriptorSet::pname:pBufferInfo array of
slink:VkDescriptorBufferInfo structures will be used to update the
descriptors, and other arrays will be ignored.
If pname:descriptorType is ename:VK_DESCRIPTOR_TYPE_UNIFORM_TEXEL_BUFFER or
ename:VK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFER, the
slink:VkWriteDescriptorSet::pname:pTexelBufferView array will be used to
update the descriptors, and other arrays will be ignored.
If pname:descriptorType is ename:VK_DESCRIPTOR_TYPE_SAMPLER,
ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER,
ename:VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE,
ename:VK_DESCRIPTOR_TYPE_STORAGE_IMAGE, or
ename:VK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT, the elements of the
slink:VkWriteDescriptorSet::pname:pImageInfo array of
slink:VkDescriptorImageInfo structures will be used to update the
descriptors, and other arrays will be ignored.
// refEnd VkDescriptorType
// refBegin VkDescriptorBufferInfo - Structure specifying descriptor buffer info
The sname:VkDescriptorBufferInfo structure is defined as:
@ -1313,25 +1412,14 @@ include::../structs/VkDescriptorBufferInfo.txt[]
update, or ename:VK_WHOLE_SIZE to use the range from pname:offset to the
end of the buffer.
include::../validity/structs/VkDescriptorBufferInfo.txt[]
For ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC and
ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC descriptor types,
pname:offset is the base offset from which the dynamic offset is applied and
pname:range is the static size used for all dynamic offsets.
If pname:descriptorType is ename:VK_DESCRIPTOR_TYPE_UNIFORM_TEXEL_BUFFER or
ename:VK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFER, the pname:pTexelBufferView
array will be used to update the descriptors, and other arrays will be
ignored.
include::../validity/structs/VkDescriptorBufferInfo.txt[]
If pname:descriptorType is ename:VK_DESCRIPTOR_TYPE_SAMPLER,
ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER,
ename:VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE,
ename:VK_DESCRIPTOR_TYPE_STORAGE_IMAGE, or
ename:VK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT, the elements of the
pname:pImageInfo array of sname:VkDescriptorImageInfo structures will be
used to update the descriptors, and other arrays will be ignored.
// refBegin VkDescriptorImageInfo - Structure specifying descriptor image info
The sname:VkDescriptorImageInfo structure is defined as:
@ -1353,25 +1441,12 @@ include::../structs/VkDescriptorImageInfo.txt[]
ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, and
ename:VK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT.
include::../validity/structs/VkDescriptorImageInfo.txt[]
Members of sname:VkDescriptorImageInfo that are not used in an update (as
described above) are ignored.
[[descriptorsets-updates-consecutive, consecutive binding updates]]
If the pname:dstBinding has fewer than pname:descriptorCount array elements
remaining starting from pname:dstArrayElement, then the remainder will be
used to update the subsequent binding - pname:dstBinding+1 starting at array
element zero. This behavior applies recursively, with the update affecting
consecutive bindings as needed to update all pname:descriptorCount
descriptors. All consecutive bindings updated via a single
sname:VkWriteDescriptorSet structure must: have identical
pname:descriptorType and pname:stageFlags, and must: all either use
immutable samplers or must: all not use immutable samplers.
include::../validity/structs/VkDescriptorImageInfo.txt[]
Each element in the pname:pDescriptorCopies array is a
slink:VkCopyDescriptorSet structure describing an operation copying
descriptors between sets.
// refBegin VkCopyDescriptorSet - Structure specifying a copy descriptor set operation
The sname:VkCopyDescriptorSet structure is defined as:
@ -1395,8 +1470,9 @@ include::../validity/structs/VkCopyDescriptorSet.txt[]
[[descriptorsets-binding]]
=== Descriptor Set Binding
Once descriptor sets have been allocated, one or more descriptor sets can:
be bound to the command buffer by calling:
// refBegin vkCmdBindDescriptorSets Binds descriptor sets to a command buffer.
To bind one or more descriptor sets to a command buffer, call:
include::../protos/vkCmdBindDescriptorSets.txt[]
@ -1488,8 +1564,11 @@ Push constants represent a high speed path to modify constant data in
pipelines that is expected to outperform memory-backed resource updates.
====
The contents of the push constants are undefined at the start of a command
buffer. Push constants are updated by calling:
The values of push constants are undefined at the start of a command buffer.
// refBegin vkCmdPushConstants Update the values of push constants.
To update push constants, call:
include::../protos/vkCmdPushConstants.txt[]

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

@ -7,15 +7,26 @@
Once Vulkan is initialized, devices and queues are the primary objects
used to interact with a Vulkan implementation.
// refBegin VkPhysicalDevice - Opaque handle to a physical device object
Vulkan separates the concept of _physical_ and _logical_ devices. A
physical device usually represents a single device in a system (perhaps made
up of several individual hardware devices working together), of which there
are a finite number. A logical device represents an application's view of
the device.
Physical devices are represented by sname:VkPhysicalDevice handles:
include::../handles/VkPhysicalDevice.txt[]
// refEnd VkPhysicalDevice
[[devsandqueues-physical-device-enumeration]]
== Physical Devices
// refBegin vkEnumeratePhysicalDevices Enumerates the physical devices accessible to a Vulkan instance.
To retrieve a list of physical device objects representing the
physical devices installed in the system, call:
@ -43,8 +54,9 @@ were returned.
include::../validity/protos/vkEnumeratePhysicalDevices.txt[]
Once enumerated, general properties of the physical devices are queried by
calling:
// refBegin vkGetPhysicalDeviceProperties Returns properties of a physical device.
To query general properties of physical devices once enumerated, call:
include::../protos/vkGetPhysicalDeviceProperties.txt[]
@ -56,6 +68,8 @@ include::../protos/vkGetPhysicalDeviceProperties.txt[]
include::../validity/protos/vkGetPhysicalDeviceProperties.txt[]
// refBegin VkPhysicalDeviceProperties - Structure specifying physical device properties
The sname:VkPhysicalDeviceProperties structure is defined as:
include::../structs/VkPhysicalDeviceProperties.txt[]
@ -83,8 +97,6 @@ include::../structs/VkPhysicalDeviceProperties.txt[]
physical device. See <<sparsememory-physicalprops,Sparse Properties>>
for details.
include::../validity/structs/VkPhysicalDeviceProperties.txt[]
The pname:vendorID and pname:deviceID fields are provided to allow
applications to adapt to device characteristics that are not
adequately exposed by other Vulkan queries. These may: include
@ -121,6 +133,10 @@ constraints and guidelines:
specific silicon IP GPU version and configuration should use the
same device ID, even if those uses occur in different SoCs.
include::../validity/structs/VkPhysicalDeviceProperties.txt[]
// refBegin VkPhysicalDeviceType supported physical device types
The physical devices types are:
include::../enums/VkPhysicalDeviceType.txt[]
@ -141,7 +157,11 @@ does not directly affect the operation of the system. However, the device
type may: correlate with other advertised properties or capabilities of the
system, such as how many memory heaps there are.
Properties of queues available on a physical device are queried by calling:
// refEnd VkPhysicalDeviceType
// refBegin vkGetPhysicalDeviceQueueFamilyProperties Reports properties of the queues of the specified physical device.
To query properties of queues available on a physical device, call:
include::../protos/vkGetPhysicalDeviceQueueFamilyProperties.txt[]
@ -164,6 +184,8 @@ written.
include::../validity/protos/vkGetPhysicalDeviceQueueFamilyProperties.txt[]
// refBegin VkQueueFamilyProperties Structure providing information about a queue family.
The sname:VkQueueFamilyProperties structure is defined as:
include::../structs/VkQueueFamilyProperties.txt[]
@ -182,6 +204,8 @@ include::../structs/VkQueueFamilyProperties.txt[]
family.
The bits specified in pname:queueFlags are:
// refBegin VkQueueFlagBits - Bitmask specifying capabilities of queues in a queue family
include::../enums/VkQueueFlagBits.txt[]
* if ename:VK_QUEUE_GRAPHICS_BIT is set, then the queues in this queue
@ -212,8 +236,6 @@ reporting the ename:VK_QUEUE_TRANSFER_BIT capability separately for that
queue family is optional:.
====
include::../validity/structs/VkQueueFamilyProperties.txt[]
For further details see <<devsandqueues-queues,Queues>>.
The value returned in pname:minImageTransferGranularity has a unit of
@ -266,11 +288,14 @@ transfer operations are only required: to support whole mip level
transfers, thus pname:minImageTransferGranularity for
queues belonging to such queue families may: be latexmath:[$(0,0,0)$].
include::../validity/structs/VkQueueFamilyProperties.txt[]
The <<memory-device,Device Memory>> section describes memory properties
queried from the physical device.
For physical device feature queries see the <<features, Features>> chapter.
[[devsandqueues-devices]]
== Devices
@ -296,6 +321,18 @@ section above.
[[devsandqueues-device-creation]]
=== Device Creation
// refBegin VkDevice - Opaque handle to a device object
Logical devices are represented by sname:VkDevice handles:
Logical devices are represented by sname:VkDevice handles:
include::../handles/VkDevice.txt[]
// refEnd VkDevice
// refBegin vkCreateDevice Create a new device instance.
A logical device is created as a _connection_ to a physical device. To
create a logical device, call:
@ -312,8 +349,15 @@ include::../protos/vkCreateDevice.txt[]
* pname:pDevice points to a handle in which the created sname:VkDevice is
returned.
Multiple logical devices can: be created from the same physical device.
Logical device creation may: fail due to lack of device-specific resources
(in addition to the other errors). If that occurs, fname:vkCreateDevice will
return ename:VK_ERROR_TOO_MANY_OBJECTS.
include::../validity/protos/vkCreateDevice.txt[]
// refBegin VkDeviceCreateInfo - Structure specifying parameters of a newly created device
The sname:VkDeviceCreateInfo structure is defined as:
include::../structs/VkDeviceCreateInfo.txt[]
@ -347,10 +391,6 @@ include::../structs/VkDeviceCreateInfo.txt[]
include::../validity/structs/VkDeviceCreateInfo.txt[]
Multiple logical devices can: be created from the same physical device.
Logical device creation may: fail due to lack of device-specific resources
(in addition to the other errors). If that occurs, fname:vkCreateDevice will
return ename:VK_ERROR_TOO_MANY_OBJECTS.
[[devsandqueues-use]]
=== Device Use
@ -445,7 +485,7 @@ ifdef::editing-notes[]
[NOTE]
.editing-note
====
TODO (piman) - I don't think we're very clear about what ``in-use by the
TODO (piman) - I do not think we are very clear about what ``in-use by the
device'' means.
====
endif::editing-notes[]
@ -454,6 +494,8 @@ endif::editing-notes[]
[[devsandqueues-destruction]]
=== Device Destruction
// refBegin vkDestroyDevice Destroy a logical device.
To destroy a device, call:
include::../protos/vkDestroyDevice.txt[]
@ -462,8 +504,6 @@ include::../protos/vkDestroyDevice.txt[]
* pname:pAllocator controls host memory allocation as described in the
<<memory-allocation, Memory Allocation>> chapter.
include::../validity/protos/vkDestroyDevice.txt[]
To ensure that no work is active on the device, flink:vkDeviceWaitIdle
can: be used to gate the destruction of the device. Prior to destroying a
device, an application is responsible for destroying/freeing any Vulkan
@ -479,6 +519,8 @@ that an application explicitly free all of these resources prior to calling
fname:vkDestroyDevice.
====
include::../validity/protos/vkDestroyDevice.txt[]
[[devsandqueues-queues]]
== Queues
@ -520,11 +562,21 @@ device. This is described in the following section.
[[devsandqueues-queue-creation]]
=== Queue Creation
// refBegin VkQueue - Opaque handle to a queue object
Creating a logical device also creates the queues associated with that
device. The queues to create are described by a set of
slink:VkDeviceQueueCreateInfo structures that are passed to
flink:vkCreateDevice in pname:pQueueCreateInfos.
Queues are represented by sname:VkQueue handles:
include::../handles/VkQueue.txt[]
// refEnd VkQueue
// refBegin VkDeviceQueueCreateInfo - Structure specifying parameters of a newly created device queue
The sname:VkDeviceQueueCreateInfo structure is defined as:
include::../structs/VkDeviceQueueCreateInfo.txt[]
@ -547,6 +599,8 @@ include::../structs/VkDeviceQueueCreateInfo.txt[]
include::../validity/structs/VkDeviceQueueCreateInfo.txt[]
// refBegin vkGetDeviceQueue Get a queue handle from a device.
To retrieve a handle to a VkQueue object, call:
include::../protos/vkGetDeviceQueue.txt[]
@ -629,12 +683,16 @@ Submission commands take as parameters a target queue, zero or more
_batches_ of work, and an optional fence to signal upon completion.
Each batch consists of three distinct parts:
. Zero or more semaphores to wait on before execution of the rest of the batch.
** If present, these describe a <<synchronization-semaphores-waiting, semaphore wait operation>>.
. Zero or more work items to execute.
** If present, these describe a _queue operation_ matching the work described.
. Zero or more semaphores to signal upon completion of the work items.
** If present, these describe a <<synchronization-semaphores-signaling, semaphore signal operation>>.
. Zero or more semaphores to wait on before execution of the rest of the
batch.
** If present, these describe a <<synchronization-semaphores-waiting,
semaphore wait operation>>.
. Zero or more work items to execute.
** If present, these describe a _queue operation_ matching the work
described.
. Zero or more semaphores to signal upon completion of the work items.
** If present, these describe a <<synchronization-semaphores-signaling,
semaphore signal operation>>.
If a fence is present in a queue submission, it describes a
<<synchronization-fences-signaling, fence signal operation>>.
@ -642,6 +700,7 @@ If a fence is present in a queue submission, it describes a
All work described by a queue submission command must: be submitted to the
queue before the command returns.
[[devsandqueues-sparsebinding]]
==== Sparse Memory Binding

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

@ -4,13 +4,15 @@
[[dispatch]]
= Dispatching Commands
_Dispatching commands_ (commands with ``Dispatch'' in the name) provoke work
_Dispatching commands_ (commands with ftext:Dispatch in the name) provoke work
in a compute pipeline. Dispatching commands are recorded into a command
buffer and when executed by a queue, will produce work which executes
according to the currently bound compute pipeline. A compute pipeline must:
be bound to a command buffer before any dispatch commands are recorded in
that command buffer.
// refBegin vkCmdDispatch Dispatch compute work items.
To record a dispatch, call:
include::../protos/vkCmdDispatch.txt[]
@ -26,7 +28,9 @@ latexmath:[$x \times y \times z$] local workgroups is assembled.
include::../validity/protos/vkCmdDispatch.txt[]
An indirect dispatch is recorded by calling:
// refBegin vkCmdDispatchIndirect Dispatch compute work items using indirect parameters.
To record an indirect command dispatch, call:
include::../protos/vkCmdDispatchIndirect.txt[]
@ -44,11 +48,19 @@ at pname:offset.
include::../validity/protos/vkCmdDispatchIndirect.txt[]
// refBegin VkDispatchIndirectCommand - Structure specifying a dispatch indirect command
The sname:VkDispatchIndirectCommand structure is defined as:
include::../structs/VkDispatchIndirectCommand.txt[]
* pname:x is the number of local workgroups to dispatch in the X dimension.
* pname:y is the number of local workgroups to dispatch in the Y dimension.
* pname:z is the number of local workgroups to dispatch in the Z dimension.
The members of sname:VkDispatchIndirectCommand structure have the same
meaning as the similarly named parameters of flink:vkCmdDispatch.
include::../validity/structs/VkDispatchIndirectCommand.txt[]
// refEnd VkDispatchIndirectCommand vkCmdDispatchIndirect

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

@ -11,6 +11,8 @@ currently bound graphics pipeline. A graphics pipeline must: be bound to a
command buffer before any drawing commands are recorded in that command
buffer.
// refBegin VkPipelineInputAssemblyStateCreateInfo - Structure specifying parameters of a newly created pipeline input assembly state
Each draw is made up of zero or more vertices and zero or more instances,
which are processed by the device and result in the assembly of
primitives. Primitives are assembled according to the
@ -33,8 +35,6 @@ include::../structs/VkPipelineInputAssemblyStateCreateInfo.txt[]
* pname:topology is a elink:VkPrimitiveTopology defining the primitive
topology, as described below.
include::../validity/structs/VkPipelineInputAssemblyStateCreateInfo.txt[]
Restarting the assembly of primitives discards the most recent index values
if those elements formed an incomplete primitive, and restarts the primitive
assembly using the subsequent indices, but only assembling the immediately
@ -42,10 +42,14 @@ following element through the end of the originally specified elements. The
primitive restart index value comparison is performed before adding the
pname:vertexOffset value to the index value.
include::../validity/structs/VkPipelineInputAssemblyStateCreateInfo.txt[]
[[drawing-primitive-topologies]]
== Primitive Topologies
// refBegin VkPrimitiveTopology supported primitive topologies
_Primitive topology_ determines how consecutive vertices are organized into
primitives, and determines the type of primitive that is used at the
beginning of the graphics pipeline. The effective topology for later stages
@ -55,6 +59,8 @@ topologies are defined by elink:VkPrimitiveTopology and include:
include::../enums/VkPrimitiveTopology.txt[]
// refEnd VkPrimitiveTopology
Each primitive topology, and its construction from a list of vertices, is
summarized below.
@ -108,9 +114,9 @@ ifdef::editing-notes[]
====
TODO: Add full caption:
* (a) A triangle strip.
* (b) A triangle fan.
* (c) Independent triangles.
* (a) A triangle strip.
* (b) A triangle fan.
* (c) Independent triangles.
The numbers give the sequencing of the vertices in order within the vertex
arrays. Note that in (a) and (b) triangle edge ordering is determined by the
@ -364,7 +370,9 @@ Drawing commands fall roughly into two categories:
fname:vkCmdDrawIndexedIndirect) read index values from an _index buffer_ and use
this to compute the code:vertexIndex value for the vertex shader.
An index buffer is bound to a command buffer by calling:
// refBegin vkCmdBindIndexBuffer Bind an index buffer to a command buffer.
To bind an index buffer to a command buffer, call:
include::../protos/vkCmdBindIndexBuffer.txt[]
@ -376,7 +384,10 @@ include::../protos/vkCmdBindIndexBuffer.txt[]
* pname:indexType selects whether indices are treated as 16 bits or 32
bits. Possible values include:
+
--
// refBegin VkIndexType - type of index buffer indices
include::../enums/VkIndexType.txt[]
--
include::../validity/protos/vkCmdBindIndexBuffer.txt[]
@ -397,6 +408,8 @@ For non-indexed draws, primitives with lower numbered code:vertexIndex
values are earlier in API order. For indexed draws, primitives assembled
from lower index buffer addresses are earlier in API order.
// refBegin vkCmdDraw Draw primitives.
To record a non-indexed draw, call:
include::../protos/vkCmdDraw.txt[]
@ -417,6 +430,8 @@ assembled primitives execute the currently bound graphics pipeline.
include::../validity/protos/vkCmdDraw.txt[]
// refBegin vkCmdDrawIndexed Issue an indexed draw into a command buffer.
To record an indexed draw, call:
include::../protos/vkCmdDrawIndexed.txt[]
@ -454,7 +469,9 @@ pipeline.
include::../validity/protos/vkCmdDrawIndexed.txt[]
A non-indexed indirect draw is recorded by calling:
// refBegin vkCmdDrawIndirect Issue an indirect draw into a command buffer.
To record a non-indexed indirect draw, call:
include::../protos/vkCmdDrawIndirect.txt[]
@ -477,16 +494,27 @@ less than or equal to one, pname:stride is ignored.
include::../validity/protos/vkCmdDrawIndirect.txt[]
// refBegin VkDrawIndirectCommand - Structure specifying a draw indirect command
The sname:VkDrawIndirectCommand structure is defined as:
include::../structs/VkDrawIndirectCommand.txt[]
* pname:vertexCount is the number of vertices to draw.
* pname:instanceCount is the number of instances to draw.
* pname:firstVertex is the index of the first vertex to draw.
* pname:firstInstance is the instance ID of the first instance to draw.
The members of sname:VkDrawIndirectCommand have the same meaning as the
similarly named parameters of flink:vkCmdDraw.
include::../validity/structs/VkDrawIndirectCommand.txt[]
An indexed indirect draw is recorded by calling:
// refEnd VkDrawIndirectCommand vkCmdDrawIndirect
// refBegin vkCmdDrawIndexedIndirect Perform an indexed indirect draw.
To record an indexed indirect draw, call:
include::../protos/vkCmdDrawIndexedIndirect.txt[]
@ -509,11 +537,22 @@ pname:drawCount is less than or equal to one, pname:stride is ignored.
include::../validity/protos/vkCmdDrawIndexedIndirect.txt[]
// refBegin VkDrawIndexedIndirectCommand - Structure specifying a draw indexed indirect command
The sname:VkDrawIndexedIndirectCommand structure is defined as:
include::../structs/VkDrawIndexedIndirectCommand.txt[]
* pname:indexCount is the number of vertices to draw.
* pname:instanceCount is the number of instances to draw.
* pname:firstIndex is the base index within the index buffer.
* pname:vertexOffset is the value added to the vertex index before indexing
into the vertex buffer.
* pname:firstInstance is the instance ID of the first instance to draw.
The members of sname:VkDrawIndexedIndirectCommand have the same meaning as
the similarly named parameters of flink:vkCmdDrawIndexed.
include::../validity/structs/VkDrawIndexedIndirectCommand.txt[]
// refEnd VkDrawIndexedIndirectCommand vkCmdDrawIndexedIndirect

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

@ -38,6 +38,8 @@ allowed ranges. Instead, a validation layer would do those checks and flag
issues. This avoids a performance penalty during production use of the
application because those layers would not be enabled in production.
// refBegin vkEnumerateInstanceLayerProperties Returns up to requested number of global layer properties.
To query the available layers, call:
include::../protos/vkEnumerateInstanceLayerProperties.txt[]
@ -47,8 +49,6 @@ include::../protos/vkEnumerateInstanceLayerProperties.txt[]
* pname:pProperties is either `NULL` or a pointer to an array of
slink:VkLayerProperties structures.
include::../validity/protos/vkEnumerateInstanceLayerProperties.txt[]
If pname:pProperties is `NULL`, then the number of layer properties available
is returned in pname:pPropertyCount. Otherwise, pname:pPropertyCount must:
point to a variable set by the user to the number of elements in the
@ -60,6 +60,10 @@ is smaller than the number of layers available, ename:VK_INCOMPLETE will be
returned instead of ename:VK_SUCCESS, to indicate that not all the available
layer properties were returned.
include::../validity/protos/vkEnumerateInstanceLayerProperties.txt[]
// refBegin VkLayerProperties - Structure specifying layer properties
The sname:VkLayerProperties structure is defined as:
include::../structs/VkLayerProperties.txt[]
@ -115,7 +119,9 @@ valid usage of the pname:ppEnabledLayerNames member of sname:VkDeviceCreateInfo
maximizes compatibility with applications written to work with the previous
requirements.
Device layers can: be enumerated by calling:
// refBegin vkEnumerateDeviceLayerProperties Returns properties of available physical device layers.
To enumerate device layers, call:
include::../protos/vkEnumerateDeviceLayerProperties.txt[]
@ -124,8 +130,6 @@ include::../protos/vkEnumerateDeviceLayerProperties.txt[]
* pname:pProperties is either `NULL` or a pointer to an array of
slink:VkLayerProperties structures.
include::../validity/protos/vkEnumerateDeviceLayerProperties.txt[]
If pname:pProperties is `NULL`, then the number of layer properties available
is returned in pname:pPropertyCount. Otherwise, pname:pPropertyCount must:
point to a variable set by the user to the number of elements in the
@ -143,6 +147,8 @@ sname:VkLayerProperties for each enumerated layer must: be the same as the
properties when the layer was enumerated by
fname:vkEnumerateInstanceLayerProperties.
include::../validity/protos/vkEnumerateDeviceLayerProperties.txt[]
The pname:ppEnabledLayerNames and pname:enabledLayerCount members of
sname:VkDeviceCreateInfo are deprecated and their values must: be ignored by
implementations. However, for compatibility, only an empty list of layers or a
@ -167,6 +173,8 @@ commands should: be queried at runtime as described in
<<initialization-functionpointers>>. Extensions may: be provided by layers
as well as by a Vulkan implementation.
// refBegin vkEnumerateInstanceExtensionProperties Returns up to requested number of global extension properties.
To query the available instance extensions, call:
include::../protos/vkEnumerateInstanceExtensionProperties.txt[]
@ -178,42 +186,12 @@ include::../protos/vkEnumerateInstanceExtensionProperties.txt[]
* pname:pProperties is either `NULL` or a pointer to an array of
slink:VkExtensionProperties structures.
include::../validity/protos/vkEnumerateInstanceExtensionProperties.txt[]
When pLayerName parameter is NULL, only extensions provided by the Vulkan
When pname:pLayerName parameter is NULL, only extensions provided by the Vulkan
implementation or by implicitly enabled layers are returned.
When pname:pLayerName is the name of a layer, the instance extensions
provided by that layer are returned.
To enable an instance extension, the name of the extension should be added to
the pname:ppEnabledExtensionNames member of slink:VkInstanceCreateInfo when
creating a sname:VkInstance.
Enabling an extension does not change behavior of functionality exposed by
the core Vulkan API or any other extension, other than making valid the use
of the commands, enums and structures defined by that extension.
To query the extensions available to a given physical device, call:
include::../protos/vkEnumerateDeviceExtensionProperties.txt[]
* pname:physicalDevice is the physical device that will be queried.
* pname:pLayerName is either `NULL` or a pointer to a null-terminated
UTF-8 string naming the layer to retrieve extensions from.
* pname:pPropertyCount is a pointer to an integer related to the number of
extension properties available or queried, as described below.
* pname:pProperties is either `NULL` or a pointer to an array of
slink:VkExtensionProperties structures.
include::../validity/protos/vkEnumerateDeviceExtensionProperties.txt[]
When pLayerName parameter is NULL, only extensions provided by the Vulkan
implementation or by implicitly enabled layers are returned.
When pname:pLayerName is the name of a layer, the device extensions
provided by that layer are returned.
For both flink:vkEnumerateInstanceExtensionProperties and
flink:vkEnumerateDeviceExtensionProperties, if pname:pProperties is `NULL`,
If pname:pProperties is `NULL`,
then the number of extensions properties available is returned in
pname:pPropertyCount. Otherwise, pname:pPropertyCount must: point to a
variable set by the user to the number of elements in the pname:pProperties
@ -225,6 +203,42 @@ pname:pPropertyCount is smaller than the number of extensions available,
ename:VK_INCOMPLETE will be returned instead of ename:VK_SUCCESS, to
indicate that not all the available properties were returned.
include::../validity/protos/vkEnumerateInstanceExtensionProperties.txt[]
To enable an instance extension, the name of the extension should be added to
the pname:ppEnabledExtensionNames member of slink:VkInstanceCreateInfo when
creating a sname:VkInstance.
Enabling an extension does not change behavior of functionality exposed by
the core Vulkan API or any other extension, other than making valid the use
of the commands, enums and structures defined by that extension.
// refBegin vkEnumerateDeviceExtensionProperties Returns properties of available physical device extensions.
To query the extensions available to a given physical device, call:
include::../protos/vkEnumerateDeviceExtensionProperties.txt[]
* pname:physicalDevice is the physical device that will be queried.
* pname:pLayerName is either `NULL` or a pointer to a null-terminated
UTF-8 string naming the layer to retrieve extensions from.
* pname:pPropertyCount is a pointer to an integer related to the number of
extension properties available or queried, and is treated in the same
fashion as the
flink:vkEnumerateInstanceExtensionProperties::pname:pPropertyCount
parameter.
* pname:pProperties is either `NULL` or a pointer to an array of
slink:VkExtensionProperties structures.
When pname:pLayerName parameter is NULL, only extensions provided by the Vulkan
implementation or by implicitly enabled layers are returned.
When pname:pLayerName is the name of a layer, the device extensions
provided by that layer are returned.
include::../validity/protos/vkEnumerateDeviceExtensionProperties.txt[]
// refBegin VkExtensionProperties - Structure specifying a extension properties
The sname:VkExtensionProperties structure is defined as:
include::../structs/VkExtensionProperties.txt[]
@ -236,6 +250,7 @@ include::../structs/VkExtensionProperties.txt[]
include::../validity/structs/VkExtensionProperties.txt[]
[[extended-functionality-instance-extensions-and-devices]]
=== Instance Extensions and Device Extensions
@ -252,38 +267,38 @@ and commands, or both.
In some cases, the decision is clear:
* Functionality that is restricted to the instance-level must: be
implemented as an instance extension.
* Functionality that is restricted to the device-level must: be
implemented as an device extension.
* Functionality that is restricted to the instance-level must: be
implemented as an instance extension.
* Functionality that is restricted to the device-level must: be
implemented as an device extension.
In other cases, the decision is not so clear:
* Global functionality that affects the entire Vulkan API, including
instance and device-level objects and commands, should: be an instance
extension.
* Device-level functionality that contains physical-device queries, can: be
implemented as an instance extension.
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.
* 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 extensions--one
for the instance-level functionality, and one for the device-specific
functionality.
In this latter case, it is generally recommended that the two extensions have
unique names.
* Global functionality that affects the entire Vulkan API, including
instance and device-level objects and commands, should: be an instance
extension.
* Device-level functionality that contains physical-device queries, can: be
implemented as an instance extension.
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.
* 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 extensions--one
for the instance-level functionality, and one for the device-specific
functionality.
In this latter case, it is generally recommended that the two extensions have
unique names.
Examples of instance extensions include:
* Logging of debug messages by any enabled layers for all Vulkan commands.
* Functionality creating new objects which are direct children of an instance.
* Functionality creating new objects which are direct children of a
physical device and intended to work with any logical device created
from the physical device.
* Functionality adding new instance-level Vulkan commands that do not affect
any device-level commands.
* Logging of debug messages by any enabled layers for all Vulkan commands.
* Functionality creating new objects which are direct children of an instance.
* Functionality creating new objects which are direct children of a
physical device and intended to work with any logical device created
from the physical device.
* Functionality adding new instance-level Vulkan commands that do not affect
any device-level commands.
[NOTE]
.Note
@ -293,9 +308,9 @@ This is especially true for commands that are dispatched from
instances and physical devices.
Additional information about supporting instance-level commands may be found
in the "Vulkan Loader Specification and Architecture Overview" document,
which may be found at the following web page:
located at URL
* https://github.com/KhronosGroup/Vulkan-LoaderAndValidationLayers/blob/sdk-1.0.13/loader/LoaderAndLayerInterface.md
https://github.com/KhronosGroup/Vulkan-LoaderAndValidationLayers/blob/sdk-1.0.13/loader/LoaderAndLayerInterface.md
Please see the "Architectural overview of layers and loader" section for
information about how both instance-level and device-level commands are

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

@ -34,6 +34,8 @@ required:, but may: be supported by a Vulkan implementation. Support for
features is reported and enabled on a per-feature basis. Features are
properties of the physical device.
// refBegin vkGetPhysicalDeviceFeatures Reports capabilities of a physical device.
To query supported features, call:
include::../protos/vkGetPhysicalDeviceFeatures.txt[]
@ -77,6 +79,8 @@ performance cost. Application writers should: carefully consider the
implications of enabling all supported features.
====
// refBegin VkPhysicalDeviceFeatures Structure describing the fine-grained features that can be supported by an implementation.
The sname:VkPhysicalDeviceFeatures structure is defined as:
include::../structs/VkPhysicalDeviceFeatures.txt[]
@ -250,10 +254,11 @@ following features:
* ename:VK_FORMAT_EAC_R11_SNORM_BLOCK
* ename:VK_FORMAT_EAC_R11G11_UNORM_BLOCK
* ename:VK_FORMAT_EAC_R11G11_SNORM_BLOCK
--
+
flink:vkGetPhysicalDeviceFormatProperties is used to
check for the supported properties of individual formats.
--
+
* [[features-features-textureCompressionASTC_LDR]]
pname:textureCompressionASTC_LDR indicates whether the ASTC LDR
compressed texture formats are supported. If this feature is not
@ -288,10 +293,11 @@ check for the supported properties of individual formats.
* ename:VK_FORMAT_ASTC_12x10_SRGB_BLOCK
* ename:VK_FORMAT_ASTC_12x12_UNORM_BLOCK
* ename:VK_FORMAT_ASTC_12x12_SRGB_BLOCK
--
+
flink:vkGetPhysicalDeviceFormatProperties is used to
check for the supported properties of individual formats.
--
+
* [[features-features-textureCompressionBC]] pname:textureCompressionBC
indicates whether the BC compressed texture formats are supported. If
this feature is not enabled, the following formats mustnot: be used to
@ -314,10 +320,11 @@ check for the supported properties of individual formats.
* ename:VK_FORMAT_BC6H_SFLOAT_BLOCK
* ename:VK_FORMAT_BC7_UNORM_BLOCK
* ename:VK_FORMAT_BC7_SRGB_BLOCK
--
+
flink:vkGetPhysicalDeviceFormatProperties is used to
check for the supported properties of individual formats.
--
+
* [[features-features-occlusionQueryPrecise]] pname:occlusionQueryPrecise
indicates whether occlusion queries returning actual sample counts are
supported. Occlusion queries are created in a sname:VkQueryPool by
@ -582,13 +589,12 @@ device. These are available in the pname:limits member of the
slink:VkPhysicalDeviceProperties structure which is returned from
flink:vkGetPhysicalDeviceProperties.
// refBegin VkPhysicalDeviceLimits Structure
The sname:VkPhysicalDeviceLimits structure is defined as:
include::../structs/VkPhysicalDeviceLimits.txt[]
The members of the sname:VkPhysicalDeviceLimits describe the following
properties of the physical device:
* [[features-limits-maxImageDimension1D]] pname:maxImageDimension1D is the
maximum dimension (pname:width) of an image created with an
pname:imageType of ename:VK_IMAGE_TYPE_1D.
@ -1010,7 +1016,6 @@ range using the smalled possible number of bits, ends up with the specified
range.
====
--
* [[features-limits-viewportSubPixelBits]] pname:viewportSubPixelBits is
the number of bits of subpixel precision for viewport bounds. The
subpixel precision that floating-point viewport bounds are interpreted
@ -1212,12 +1217,14 @@ range.
// End of list
1::
For all bitmasks of type ename:VkSampleCountFlags above, possible
For all bitmasks of type elink:VkSampleCountFlags above, possible
values include:
+
--
// refBegin VkSampleCountFlagBits - Bitmask specifying sample counts supported for an image used for storage operations
include::../enums/VkSampleCountFlagBits.txt[]
--
+
The sample count limits defined above represent the minimum
supported sample counts for each image type. Individual images may: support
additional sample counts, which are queried using
@ -1225,7 +1232,6 @@ flink:vkGetPhysicalDeviceImageFormatProperties. The sample
count limits for images only apply to images created with the pname:tiling
set to ename:VK_IMAGE_TILING_OPTIMAL. For ename:VK_IMAGE_TILING_LINEAR
images the only supported sample count is ename:VK_SAMPLE_COUNT_1_BIT.
--
include::../validity/structs/VkPhysicalDeviceLimits.txt[]
@ -1469,7 +1475,7 @@ the same whether or not the feature is enabled.
1::
The *Limit Type* column indicates the limit is either the minimum limit all
implementations must: support or the maximum limit all implementations
must: support. For bitfields a minimum limit is the least
must: support. For bitmasks a minimum limit is the least
bits all implementations must: set, but they may: have
additional bits set beyond this minimum.
@ -1528,8 +1534,9 @@ flink:vkGetPhysicalDeviceFormatProperties command.
[[features-formats-definition]]
=== Format Definition
The available formats available are defined by the elink:VkFormat
enumeration:
// refBegin VkFormat available image formats
The available formats are defined by the elink:VkFormat enumeration:
include::../enums/VkFormat.txt[]
@ -2568,6 +2575,8 @@ ename:VK_FORMAT_ASTC_12x12_SRGB_BLOCK::
texel block encodes a 12x12 rectangle of unsigned normalized RGBA texel
data with sRGB nonlinear encoding applied to the RGB components.
// refEnd VkFormat
[[features-formats-packed]]
==== Packed Formats
@ -2759,7 +2768,7 @@ endianness.
^| latexmath:[$B_4$] ^| latexmath:[$B_3$] ^| latexmath:[$B_2$] ^| latexmath:[$B_1$] ^| latexmath:[$B_0$]
|===============
// N.B. This table is slightly too wide to fit - we cheat by not drawing the grid lines so we can't see...
// N.B. This table is slightly too wide to fit - we cheat by not drawing the grid lines so we cannot see...
[[features-formats-packed-32-bit]]
.Bit mappings for packed 32-bit formats
[cols="32*1",frame="none",grid="rows",options="header"]
@ -3034,6 +3043,8 @@ all the formats in the same row are compatible.
[[features-formats-properties]]
=== Format Properties
// refBegin vkGetPhysicalDeviceFormatProperties Lists physical device's format capabilities.
To query supported format features which are properties of the physical
device, call:
@ -3048,12 +3059,21 @@ include::../protos/vkGetPhysicalDeviceFormatProperties.txt[]
include::../validity/protos/vkGetPhysicalDeviceFormatProperties.txt[]
fname:vkGetPhysicalDeviceFormatProperties returns sname:VkFormatProperties:
// refBegin VkFormatProperties - Structure specifying image format properties
The sname:VkPhysicalDeviceLimits structure is defined as:
include::../structs/VkFormatProperties.txt[]
The features are described as a set of elink:VkFormatFeatureFlagBits:
* pname:linearTilingFeatures describes the features supported by
ename:VK_IMAGE_TILING_LINEAR.
* pname:optimalTilingFeatures describes the features supported by
ename:VK_IMAGE_TILING_OPTIMAL.
* pname:bufferFeatures describes the features supported by buffers.
Supported features are described as a set of elink:VkFormatFeatureFlagBits:
// refBegin VkFormatFeatureFlagBits - Bitmask specifying features supported by a buffer
include::../enums/VkFormatFeatureFlagBits.txt[]
The pname:linearTilingFeatures and pname:optimalTilingFeatures members of
@ -3061,8 +3081,10 @@ the sname:VkFormatProperties structure describe what features are supported
by ename:VK_IMAGE_TILING_LINEAR and ename:VK_IMAGE_TILING_OPTIMAL images,
respectively.
The following features may: be supported by images or image views created
with pname:format:
The following bits may: be set in pname:linearTilingFeatures and
pname:optimalTilingFeatures, indicating they are supported by images or
image views created with the queried
flink:vkGetPhysicalDeviceFormatProperties::pname:format:
ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_BIT::
sname:VkImageView can: be sampled from. See
@ -3120,11 +3142,9 @@ If the format being queried is a depth/stencil format, this bit only indicates
range latexmath:[$[0,1\]$] and should: be proportional to, or a weighted
average of, the number of comparison passes or failures.
The pname:bufferFeatures member of the sname:VkFormatProperties structure
describes what features are supported by buffers.
The following features may: be supported by buffers or buffer views created
with pname:format:
The following features may: appear in pname:bufferFeatures, indicating they
are supported by buffers or buffer views created with the queried
flink:vkGetPhysicalDeviceFormatProperties::pname:format:
ename:VK_FORMAT_FEATURE_UNIFORM_TEXEL_BUFFER_BIT::
Format can: be used to create a sname:VkBufferView that can: be bound to
@ -3631,6 +3651,8 @@ images. For example, larger dimensions or additional sample counts for
certain image types, or additional capabilities for _linear_ tiling format
images.
// refBegin vkGetPhysicalDeviceImageFormatProperties Lists physical device's image format capabilities.
To query additional capabilities specific to image types, call:
include::../protos/vkGetPhysicalDeviceImageFormatProperties.txt[]
@ -3645,7 +3667,7 @@ include::../protos/vkGetPhysicalDeviceImageFormatProperties.txt[]
slink:VkImageCreateInfo.tiling.
* pname:usage is the intended usage of the image, corresponding to
slink:VkImageCreateInfo.usage.
* pname:flags is a bitfield describing additional parameters of the image,
* pname:flags is a bitmask describing additional parameters of the image,
corresponding to slink:VkImageCreateInfo.flags.
* pname:pImageFormatProperties points to an instance of the
slink:VkImageFormatProperties structure in which capabilities are
@ -3655,8 +3677,25 @@ The pname:format, pname:type, pname:tiling, pname:usage, and pname:flags
parameters correspond to parameters that would be consumed by
flink:vkCreateImage.
If pname:format is not a supported image format, or if the combination of
pname:format, pname:type, pname:tiling, pname:usage, and pname:flags is not
supported for images, then fname:vkGetPhysicalDeviceImageFormatProperties
returns ename:VK_ERROR_FORMAT_NOT_SUPPORTED.
The limitations on an image format that are reported by
fname:vkGetPhysicalDeviceImageFormatProperties have the following property:
if code:usage1 and code:usage2 of type elink:VkImageUsageFlags are such that
the bits set in code:usage1 are a subset of the bits set in code:usage2, and
code:flags1 and code:flags2 of type elink:VkImageCreateFlags are such that
the bits set in code:flags1 are a subset of the bits set in code:flags2,
then the limitations for code:usage1 and code:flags1 must: be no more strict
than the limitations for code:usage2 and code:flags2, for all values of
pname:format, pname:type, and pname:tiling.
include::../validity/protos/vkGetPhysicalDeviceImageFormatProperties.txt[]
// refBegin VkImageFormatProperties - Structure specifying a image format properties
The sname:VkImageFormatProperties structure is defined as:
include::../structs/VkImageFormatProperties.txt[]
@ -3718,20 +3757,6 @@ sname:VkImageFormatProperties will be filled with zero.
include::../validity/structs/VkImageFormatProperties.txt[]
If pname:format is not a supported image format, or if the combination of
pname:format, pname:type, pname:tiling, pname:usage, and pname:flags is not
supported for images, then fname:vkGetPhysicalDeviceImageFormatProperties
returns ename:VK_ERROR_FORMAT_NOT_SUPPORTED.
The limitations on an image format that are reported by
fname:vkGetPhysicalDeviceImageFormatProperties have the following property:
if code:usage1 and code:usage2 of type ename:VkImageUsageFlags are such that
the bits set in code:usage1 are a subset of the bits set in code:usage2, and
code:flags1 and code:flags2 of type ename:VkImageCreateFlags are such that
the bits set in code:flags1 are a subset of the bits set in code:flags2,
then the limitations for code:usage1 and code:flags1 must: be no more strict
than the limitations for code:usage2 and code:flags2, for all values of
pname:format, pname:type, and pname:tiling.
[[features-extentperimagetype]]
=== Allowed Extent Values Based On Image Type

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

@ -32,6 +32,8 @@ order:
[[fragops-scissor]]
== Scissor Test
// refBegin vkCmdSetScissor Set the dynamic scissor rectangles on a command buffer.
The scissor test determines if a fragment's framebuffer coordinates
latexmath:[$(x_f,y_f)$] lie within the scissor rectangle corresponding to
the viewport index (see <<vertexpostproc-viewport,Controlling the
@ -93,7 +95,7 @@ pname:pSampleMask array member of
slink:VkPipelineMultisampleStateCreateInfo, as described previously in
section <<pipelines-graphics>>.
pname:pSampleMask contains a bitmask of static coverage information that is
pname:pSampleMask contains a array of static coverage information that is
code:ANDed with the coverage information generated during rasterization.
Bits that are zero disable coverage for the corresponding sample. Bit B of
mask word M corresponds to sample latexmath:[$32 \times M + B$]. The array
@ -101,6 +103,15 @@ is sized to a length of latexmath:[$\lceil{rasterizationSamples /
32}\rceil$] words. If pname:pSampleMask is `NULL`, it is treated as if the
mask has all bits enabled, i.e. no coverage is removed from fragments.
// refBegin VkSampleMask - Mask of sample coverage information
The elements of the sample mask array are of type basetype:VkSampleMask,
each representing 32 bits of coverage information:
include::../basetypes/VkSampleMask.txt[]
// refEnd VkSampleMask VkPipelineMultisampleStateCreateInfo
[[fragops-early-mode]]
== Early Fragment Test Mode
@ -151,7 +162,7 @@ ifdef::editing-notes[]
There used to be a sentence of form "These operations are diagrammed in
figure ((fig-fragops,Fragment Operations)), in the order in which they are
performed" following "described in this chapter." above, but the referred
figure doesn't yet exist.
figure does not yet exist.
==================
endif::editing-notes[]
@ -232,6 +243,8 @@ Pipeline state controlling the <<fragops-dbt,depth bounds tests>>,
specified through the members of the
sname:VkPipelineDepthStencilStateCreateInfo structure.
// refBegin VkPipelineDepthStencilStateCreateInfo - Structure specifying parameters of a newly created pipeline depth stencil state
The sname:VkPipelineDepthStencilStateCreateInfo structure is defined as:
include::../structs/VkPipelineDepthStencilStateCreateInfo.txt[]
@ -259,6 +272,8 @@ include::../validity/structs/VkPipelineDepthStencilStateCreateInfo.txt[]
[[fragops-dbt]]
== Depth Bounds Test
// refBegin vkCmdSetDepthBounds Set the depth bounds test values for a command buffer.
The depth bounds test conditionally disables coverage of a sample based on
the outcome of a comparison between the value latexmath:[$z_a$] in the depth
attachment at location latexmath:[$(x_f,y_f)$] (for the appropriate sample)
@ -307,6 +322,8 @@ The stencil test is controlled with the pname:front and pname:back members
of sname:VkPipelineDepthStencilStateCreateInfo which are of type
sname:VkStencilOpState.
// refBegin VkStencilOpState - Structure specifying stencil operation state
The sname:VkStencilOpState structure is defined as:
include::../structs/VkStencilOpState.txt[]
@ -348,6 +365,8 @@ ename:VK_DYNAMIC_STATE_STENCIL_WRITE_MASK, and
ename:VK_DYNAMIC_STATE_STENCIL_REFERENCE dynamic states enabled,
respectively.
// refBegin vkCmdSetStencilCompareMask Set the stencil compare mask dynamic state.
If the pipeline state object is created with the
ename:VK_DYNAMIC_STATE_STENCIL_COMPARE_MASK dynamic state enabled, then to
dynamically set the stencil compare mask call:
@ -360,8 +379,9 @@ include::../protos/vkCmdSetStencilCompareMask.txt[]
which to update the compare mask. Bits which can: be set include:
+
--
// refBegin VkStencilFaceFlagBits - Bitmask specifying sets of stencil state for which to update the compare mask
include::../enums/VkStencilFaceFlagBits.txt[]
--
** ename:VK_STENCIL_FACE_FRONT_BIT indicates that only the front set of
stencil state is updated.
** ename:VK_STENCIL_FACE_BACK_BIT indicates that only the back set of
@ -369,12 +389,12 @@ include::../enums/VkStencilFaceFlagBits.txt[]
** ename:VK_STENCIL_FRONT_AND_BACK is the combination of
ename:VK_STENCIL_FACE_FRONT_BIT and ename:VK_STENCIL_FACE_BACK_BIT and
indicates that both sets of stencil state are updated.
--
* pname:compareMask is the new value to use as the stencil compare mask.
include::../validity/protos/vkCmdSetStencilCompareMask.txt[]
// refBegin vkCmdSetStencilWriteMask Set the stencil write mask dynamic state.
If the pipeline state object is created with the
ename:VK_DYNAMIC_STATE_STENCIL_WRITE_MASK dynamic state enabled, then to
dynamically set the stencil write mask call:
@ -390,6 +410,8 @@ include::../protos/vkCmdSetStencilWriteMask.txt[]
include::../validity/protos/vkCmdSetStencilWriteMask.txt[]
// refBegin vkCmdSetStencilReference Set the stencil reference dynamic state.
If the pipeline state object is created with the
ename:VK_DYNAMIC_STATE_STENCIL_REFERENCE dynamic state enabled, then to
dynamically set the stencil reference value call:
@ -414,6 +436,9 @@ both the reference and the stored stencil value, and the resulting masked
values are those that participate in the comparison controlled by
pname:compareOp. Let latexmath:[$R$] be the masked reference value
and latexmath:[$S$] be the masked stored stencil value.
// refBegin VkCompareOp stencil comparison function
pname:compareOp is a symbolic constant that determines the stencil
comparison function:
@ -431,6 +456,10 @@ include::../enums/VkCompareOp.txt[]
\geq S$].
* ename:VK_COMPARE_OP_ALWAYS: the test always passes.
// refEnd VkCompareOp
// refBegin VkStencilOp stencil comparison function
As described earlier, the pname:failOp, pname:passOp, and pname:depthFailOp
members of slink:VkStencilOpState indicate what happens to the stored
stencil value if this or certain subsequent tests fail or pass. Each enum is
@ -474,6 +503,8 @@ based on the facing-ness of the fragment. Fragments generated by
front-facing primitives use the front mask and fragments generated by
back-facing primitives use the back mask.
// refEnd VkStencilOp
[[fragops-depth]]
== Depth Test

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

@ -37,6 +37,8 @@ The pipeline blend state is included in the
sname:VkPipelineColorBlendStateCreateInfo structure during graphics pipeline
creation:
// refBegin VkPipelineColorBlendStateCreateInfo - Structure specifying parameters of a newly created pipeline color blend state
The sname:VkPipelineColorBlendStateCreateInfo structure is defined as:
include::../structs/VkPipelineColorBlendStateCreateInfo.txt[]
@ -52,13 +54,11 @@ include::../structs/VkPipelineColorBlendStateCreateInfo.txt[]
pname:pAttachments. This value must: equal the
pname:colorAttachmentCount for the subpass in which this pipeline is
used.
* pname:pAttachments: pointer to array of per target attachment states.
* pname:pAttachments: is a pointer to array of per target attachment states.
* pname:blendConstants is an array of four values used as the R, G, B, and
A components of the blend constant that are used in blending, depending
on the <<framebuffer-blendfactors,blend factor>>.
include::../validity/structs/VkPipelineColorBlendStateCreateInfo.txt[]
Each element of the pname:pAttachments array is a
slink:VkPipelineColorBlendAttachmentState structure specifying per-target
blending state for each individual color attachment. If the
@ -66,6 +66,10 @@ blending state for each individual color attachment. If the
enabled on the device, all slink:VkPipelineColorBlendAttachmentState
elements in the pname:pAttachments array must: be identical.
include::../validity/structs/VkPipelineColorBlendStateCreateInfo.txt[]
// refBegin VkPipelineColorBlendAttachmentState - Structure specifying a pipeline color blend attachment state
The sname:VkPipelineColorBlendAttachmentState structure is defined as:
include::../structs/VkPipelineColorBlendAttachmentState.txt[]
@ -95,6 +99,8 @@ include::../validity/structs/VkPipelineColorBlendAttachmentState.txt[]
[[framebuffer-blendfactors]]
=== Blend Factors
// refBegin VkBlendFactor framebuffer blending factors
The source and destination color and alpha blending factors are selected
from the enum:
@ -143,13 +149,17 @@ In this table, the following conventions are used:
- latexmath:[$R_c,G_c,B_c$] and latexmath:[$A_c$] represent the blend
constant R, G, B, and A components, respectively.
// refEnd VkBlendFactor
[[framebuffer-blendconstants]]
If the pipeline state object is created without the
ename:VK_DYNAMIC_STATE_BLEND_CONSTANTS dynamic state enabled then the
``blend constant'' latexmath:[$(R_c,G_c,B_c,A_c)$] is specified via the
pname:blendConstants member of slink:VkPipelineColorBlendStateCreateInfo.
Otherwise the blend constant is dynamically set and changed by calling the
command:
// refBegin vkCmdSetBlendConstants Set the values of blend constants.
Otherwise, to dynamically set and change the blend constant, call:
include::../protos/vkCmdSetBlendConstants.txt[]
@ -194,6 +204,8 @@ blender, the result of the blending operation is not defined.
[[framebuffer-blendoperations]]
=== Blend Operations
// refBegin VkBlendOp framebuffer blending operations
Once the source and destination blend factors have been selected, they along
with the source and destination components are passed to the blending
operation. The blending operations are selected from the following enum,
@ -266,6 +278,10 @@ normalized or signed normalized color attachment prior to evaluating the
blend operations. If the color attachment is floating-point, no clamping
occurs.
// refEnd VkBlendOp
// refBegin VkColorComponentFlagBits - Bitmask controlling which components are written to the framebuffer
The pname:colorWriteMask member of slink:VkPipelineColorBlendAttachmentState
determines whether the final color values latexmath:[$R, G, B$] and
latexmath:[$A$] are written to the framebuffer attachment.
@ -281,6 +297,8 @@ similarly control writing of the latexmath:[$G, B,$] and latexmath:[$A$]
values. The pname:colorWriteMask is applied regardless of whether blending
is enabled.
// refEnd VkColorComponentFlagBits
If the numeric format of a framebuffer attachment uses sRGB encoding, the R,
G, and B destination color values (after conversion from fixed-point to
floating-point) are considered to be encoded for the sRGB color space and
@ -305,6 +323,7 @@ are performed through that attachment. Framebuffer color attachments greater
than or equal to sname:VkSubpassDescription::pname:colorAttachmentCount
perform no writes.
[[framebuffer-logicop]]
== Logical Operations
@ -315,6 +334,8 @@ Logical operations are applied only for signed and unsigned integer and
normalized integer framebuffers. Logical operations are not applied to
floating-point or sRGB format color attachments.
// refBegin VkLogicOp framebuffer logical operations
Logical operations are controlled by the pname:logicOpEnable and
pname:logicOp members of slink:VkPipelineColorBlendStateCreateInfo. If
pname:logicOpEnable is ename:VK_TRUE, then a logical operation selected by
@ -369,3 +390,4 @@ The result of the logical operation is then written to the color attachment
as controlled by the component write mask, described in
<<framebuffer-blendoperations,Blend Operations>>.
// refEnd VkLogicOp

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

@ -18,15 +18,14 @@ remainder of the Specification.
Vulkan is designed for, and the API is written for, CPU, GPU, and other
hardware accelerator architectures with the following properties:
* Runtime support for 8, 16, 32 and 64-bit signed and unsigned
twos-complement integers, all addressable at the granularity of their size
in bytes.
* Runtime support for 32- and 64-bit floating-point types satisfying the
range and precision constraints in the
<<fundamentals-floatingpoint,Floating Point Computation>> section.
* The representation and endianness of these types must: be identical for
the host and the physical devices.
* Runtime support for 8, 16, 32 and 64-bit signed and unsigned
twos-complement integers, all addressable at the granularity of their
size in bytes.
* Runtime support for 32- and 64-bit floating-point types satisfying the
range and precision constraints in the
<<fundamentals-floatingpoint,Floating Point Computation>> section.
* The representation and endianness of these types must: be identical for
the host and the physical devices.
[NOTE]
.Note
@ -146,7 +145,7 @@ Additional explicit ordering constraints between queue submissions and
individual batches can be expressed with
<<synchronization-semaphores,semaphores>> and
<<synchronization-fences,fences>>.
Before a fence or semaphore is signaled, it is guaranteed that any
previously submitted queue operations have completed execution, and that
memory writes from those queue operations are
@ -168,7 +167,7 @@ into a single primary command buffer, except that the current state is
constraints can be expressed with <<synchronization-events,events>> and
<<synchronization-pipeline-barriers,pipeline barriers>>.
There are a few
There are a few
<<fundamentals-queueoperation-apiorder, implicit ordering constraints>>
between commands within a command buffer, but only covering a subset of
execution. Additional explicit ordering constraints can be expressed with
@ -411,12 +410,26 @@ using C99 syntax. Language bindings for other languages such as C++ and
Javascript may: allow for stricter parameter passing, or object-oriented
interfaces.
With few exceptions, Vulkan uses the standard C types for parameters (int
types from stdint.h, etc). Exceptions to this are using basetype:VkResult
for return values, using basetype:VkBool32 for boolean values,
basetype:VkDeviceSize for sizes and offsets pertaining to device address
space, and basetype:VkFlags for passing bits or sets of bits of predefined
values.
Vulkan uses the standard C types for the base type of scalar parameters
(e.g. types from +stdint.h+), with exceptions described below, or elsewhere
in the text when appropriate:
// refBegin VkBool32 - Vulkan boolean type
basetype:VkBool32 represents boolean code:True and code:False values, since
C does not have a sufficiently portable built-in boolean type:
include::../basetypes/VkBool32.txt[]
// refEnd VkBool32
// refBegin VkDeviceSize - Vulkan device memory size and offsets
basetype:VkDeviceSize represents device memory size and offset values:
include::../basetypes/VkDeviceSize.txt[]
// refEnd VkDeviceSize
Commands that create Vulkan objects are of the form ftext:vkCreate* and
take stext:Vk*CreateInfo structures with the parameters needed to create the
@ -587,6 +600,10 @@ valid - at the draw command.
Certain usage rules apply to all commands in the API unless explicitly
denoted differently for a command. These rules are as follows.
[[fundamentals-validusage-handles]]
==== Valid Usage for Object Handles
Any input parameter to a command that is an object handle must: be a valid
object handle, unless otherwise specified. An object handle is valid if:
@ -597,19 +614,27 @@ object handle, unless otherwise specified. An object handle is valid if:
* Any objects used by that object, either as part of creation or
execution, must: also be valid.
The reserved handle code:VK_NULL_HANDLE can: be passed in place of valid
The reserved handle dlink:VK_NULL_HANDLE can: be passed in place of valid
object handles when _explicitly called out in the specification_. Any
command that creates an object successfully mustnot: return
code:VK_NULL_HANDLE. It is valid to pass code:VK_NULL_HANDLE to any
dlink:VK_NULL_HANDLE. It is valid to pass dlink:VK_NULL_HANDLE to any
ftext:vkDestroy* or ftext:vkFree* command, which will silently ignore these
values.
[[fundamentals-validusage-pointers]]
==== Valid Usage for Pointers
Any parameter that is a pointer must: be a valid pointer. A pointer is valid
if it points at memory containing values of the number and type(s) expected
by the command, and all fundamental types accessed through the pointer (e.g.
as elements of an array or as members of a structure) satisfy the alignment
requirements of the host processor.
[[fundamentals-validusage-enums]]
==== Valid Usage for Enumerated Types
Any parameter of an enumerated type must: be a valid enumerant for that
type. A enumerant is valid if:
@ -618,34 +643,65 @@ type. A enumerant is valid if:
enumerated type, which are suffixed with etext:_BEGIN_RANGE,
etext:_END_RANGE, etext:_RANGE_SIZE or etext:_MAX_ENUM.
Any parameter that is a flag value must: be a valid combination of bit
[[fundamentals-validusage-flags]]
==== Valid Usage for Flags
// refBegin VkFlags - Vulkan bitmasks
A collection of flags is represented by a bitmask using the type
basetype:VkFlags:
include::../basetypes/VkFlags.txt[]
Bitmasks are passed to many commands and structures to compactly represent
options, but basetype:VkFlags is not used directly in the API. Instead, a
etext:Vk*Flags type which is an alias of basetype:VkFlags, and whose name
matches the corresponding etext:Vk*FlagBits that are valid for that type, is
used. These aliases are described in the <<boilerplate-flags,Flag Types>>
appendix of the Specification.
// refEnd VkFlags VkColorComponentFlags
Any etext:Vk*Flags member or parameter used in the API must: be a valid combination of bit
flags. A valid combination is either zero or the bitwise OR of valid bit
flags. A bit flag is valid if:
* The flag is defined as part of the bits type, where the bits type is
* The bit flag is defined as part of the etext:Vk*FlagBits type, where the bits type is
obtained by taking the flag type and replacing the trailing etext:Flags
with etext:FlagBits. For example, a flag value of type
ename:VkColorComponentFlags must: contain only values selected from the
bit flags in elink:VkColorComponentFlagBits.
elink:VkColorComponentFlags must: contain only bit flags defined by
elink:VkColorComponentFlagBits.
* The flag is allowed in the context in which it is being used. For
example, in some cases, certain bit flags or combinations of bit flags
are mutually exclusive.
Any parameter that is a structure containing a etext:VkStructureType
ptext:sType member must: have a value of ptext:sType matching the type of
the structure. The correct value is described for each structure type, but
as a general rule, the name of this value is obtained by taking the
[[fundamentals-validusage-sType]]
==== Valid Usage for Structure Types
Any parameter that is a structure containing a
elink:VkStructureType::pname:sType member must: have a value of ptext:sType
matching the type of the structure.
As a general rule, the name of this value is obtained by taking the
structure name, stripping the leading etext:Vk, prefixing each capital
letter with etext:_, converting the entire resulting string to upper case,
and prefixing it with etext:VK_STRUCTURE_TYPE. For example, structures of
and prefixing it with etext:VK_STRUCTURE_TYPE_. For example, structures of
type sname:VkImageCreateInfo must: have a ptext:sType value of
ename:VK_STRUCTURE_TYPE_IMAGE_CREATE_INFO.
The values ename:VK_STRUCTURE_TYPE_LOADER_INSTANCE_CREATE_INFO and
ename:VK_STRUCTURE_TYPE_LOADER_DEVICE_CREATE_INFO are reserved for internal
use by the loader, and don't have corresponding Vulkan structures in this
use by the loader, and do not have corresponding Vulkan structures in this
specification.
The list of supported <<boilerplate-sType,structure types>> is defined in
an appendix.
[[fundamentals-validusage-pNext]]
==== Valid Usage for Structure Pointer Chains
Any parameter that is a structure containing a basetype:void* ptext:pNext
member must: have a value of ptext:pNext that is either `NULL`, or points to
a valid structure defined by an extension, containing ptext:sType and
@ -661,6 +717,10 @@ Extension structures are not described in the base Vulkan specification,
but either in layered specifications incorporating those extensions,
or in separate vendor-provided documents.
[[fundamentals-validusage-nested-structs]]
==== Valid Usage for Nested Structures
The above rules also apply recursively to members of structures provided as
input to a command, either as a direct argument to the command, or
themselves a member of another structure.
@ -672,6 +732,8 @@ sections.
[[fundamentals-returncodes]]
=== Return Codes
// refBegin VkResult Vulkan command return codes
While the core Vulkan API is not designed to capture incorrect usage,
some circumstances still require return codes. Commands in Vulkan return
their status via return codes that are in one of two categories:
@ -748,6 +810,9 @@ the error until a specified point. For commands that record into
command buffers (ftext:vkCmd*) run time errors are reported by
fname:vkEndCommandBuffer.
// refEnd VkResult TBD
[[fundamentals-numerics]]
== Numeric Representation and Computation
@ -1041,6 +1106,10 @@ replacement of any feature, and is thus very likely to break any and all
compatibility. Differences in this version will typically require
significant modification to an application in order for it to function.
C language macros for manipulating version numbers are defined in the
<<boilerplate-versions,Version Number Macros>> appendix.
[[fundamentals-common-objects]]
== Common Object Types
@ -1053,13 +1122,20 @@ _extents_, and _rectangles_.
Offsets are used to describe a pixel location within an image or
framebuffer, as an (x,y) location for two-dimensional images, or an (x,y,z)
location for three-dimensional images. Two- and three-dimensional offsets
are respectively defined by the structures
location for three-dimensional images.
// refBegin VkOffset2D - Structure specifying a two-dimensional offset
A two-dimensional offsets is defined by the structure:
include::../structs/VkOffset2D.txt[]
include::../validity/structs/VkOffset2D.txt[]
// refBegin VkOffset3D - Structure specifying a three-dimensional offset
A three-dimensional offset is defined by the structure:
include::../structs/VkOffset3D.txt[]
include::../validity/structs/VkOffset3D.txt[]
@ -1069,13 +1145,20 @@ include::../validity/structs/VkOffset3D.txt[]
Extents are used to describe the size of a rectangular region of pixels within
an image or framebuffer, as (width,height) for two-dimensional images, or as
(width,height,depth) for three-dimensional images. Two- and
three-dimensional extents are respectively defined by the structures
(width,height,depth) for three-dimensional images.
// refBegin VkExtent2D - Structure specifying a two-dimensional extent
A two-dimensional extent is defined by the structure:
include::../structs/VkExtent2D.txt[]
include::../validity/structs/VkExtent2D.txt[]
// refBegin VkExtent3D - Structure specifying a three-dimensional extent
A three-dimensional extent is defined by the structure:
include::../structs/VkExtent3D.txt[]
include::../validity/structs/VkExtent3D.txt[]
@ -1083,19 +1166,13 @@ include::../validity/structs/VkExtent3D.txt[]
=== Rectangles
// refBegin VkRect2D - Structure specifying a two-dimensional subregion
Rectangles are used to describe a specified rectangular region of pixels
within an image or framebuffer. Rectangles include both an offset and an
extent of the same dimensionality, as described above. Two-dimensional
rectangles are defined by the structure
// Comment out until SubresourceRectangle-style structure proposed
// Two- and three-dimensional rectangles are respectively defined by the
// structures
include::../structs/VkRect2D.txt[]
include::../validity/structs/VkRect2D.txt[]
// include::../structs/VkRect3D.txt[]
// include::../validity/structs/VkRect3D.txt[]

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

@ -262,6 +262,8 @@ descriptions as part of graphics pipeline creation. The
slink:VkGraphicsPipelineCreateInfo::pname:pVertexInputState points to a
structure of type sname:VkPipelineVertexInputStateCreateInfo.
// refBegin VkPipelineVertexInputStateCreateInfo - Structure specifying parameters of a newly created pipeline vertex input state
The sname:VkPipelineVertexInputStateCreateInfo structure is defined as:
include::../structs/VkPipelineVertexInputStateCreateInfo.txt[]
@ -283,6 +285,8 @@ include::../validity/structs/VkPipelineVertexInputStateCreateInfo.txt[]
Each vertex input binding is specified by an instance of the
sname:VkVertexInputBindingDescription structure.
// refBegin VkVertexInputBindingDescription - Structure specifying vertex input binding description
The sname:VkVertexInputBindingDescription structure is defined as:
include::../structs/VkVertexInputBindingDescription.txt[]
@ -291,26 +295,26 @@ include::../structs/VkVertexInputBindingDescription.txt[]
describes.
* pname:stride is the distance in bytes between two
consecutive elements within the buffer.
* pname:inputRate is a elink:VkVertexInputRate value that specifies
* pname:inputRate specifies
whether vertex attribute addressing is a function of the vertex index or
of the instance index.
of the instance index. Possible values include:
+
--
// refBegin VkVertexInputRate - specify rate at which vertex attributes are pulled from buffers
include::../enums/VkVertexInputRate.txt[]
--
** ename:VK_VERTEX_INPUT_RATE_VERTEX indicates that vertex attribute
addressing is a function of the vertex index.
** ename:VK_VERTEX_INPUT_RATE_INSTANCE indicates that vertex attribute
addressing is a function of the instance index.
include::../validity/structs/VkVertexInputBindingDescription.txt[]
elink:VkVertexInputRate is defined as:
include::../enums/VkVertexInputRate.txt[]
The values of elink:VkVertexInputRate have the following meanings:
* ename:VK_VERTEX_INPUT_RATE_VERTEX indicates that vertex attribute
addressing is a function of the vertex index.
* ename:VK_VERTEX_INPUT_RATE_INSTANCE indicates that vertex attribute
addressing is a function of the instance index.
Each vertex input attribute is specified by an instance of the
sname:VkVertexInputAttributeDescription structure.
// refBegin VkVertexInputAttributeDescription - Structure specifying vertex input attribute description
The sname:VkVertexInputAttributeDescription structure is defined as:
include::../structs/VkVertexInputAttributeDescription.txt[]
@ -325,8 +329,10 @@ include::../structs/VkVertexInputAttributeDescription.txt[]
include::../validity/structs/VkVertexInputAttributeDescription.txt[]
Vertex buffers are bound to a command buffer for use in subsequent draw
commands by calling:
// refBegin vkCmdBindVertexBuffers Bind vertex buffers to a command buffer
To bind vertex buffers to a command buffer for use in subsequent draw
commands, call:
include::../protos/vkCmdBindVertexBuffers.txt[]

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

@ -10,6 +10,8 @@ Vulkan commands, and creating a sname:VkInstance object.
[[initialization-functionpointers]]
== Command Function Pointers
// refBegin vkGetInstanceProcAddr Return a function pointer for a command
Vulkan commands are not necessarily exposed statically on a platform.
Function pointers for all Vulkan commands can: be obtained with the
command:
@ -20,8 +22,6 @@ include::../protos/vkGetInstanceProcAddr.txt[]
compatible with.
* pname:pName is the name of the command to obtain.
include::../validity/protos/vkGetInstanceProcAddr.txt[]
fname:vkGetInstanceProcAddr itself is obtained in a platform- and loader-
specific manner. Typically, the loader library will export this command as a
function symbol, so applications can: link against the loader library, or
@ -30,7 +30,7 @@ Loaders are encouraged to export function symbols for all other core
Vulkan commands as well; if this is done, then applications that use only
the core Vulkan commands have no need to use fname:vkGetInstanceProcAddr.
Function pointers to commands that don't operate on a specific instance can:
Function pointers to commands that do not operate on a specific instance can:
be obtained by using this command with pname:instance equal to `NULL`. The
following commands can: be accessed this way:
@ -38,6 +38,9 @@ following commands can: be accessed this way:
* flink:vkEnumerateInstanceLayerProperties
* flink:vkCreateInstance
The returned function pointer is of type tlink:PFN_vkVoidFunction, and must
be cast to the type of the command being queried.
If pname:instance is a valid sname:VkInstance, function pointers to any
commands that operate on pname:instance or a child of pname:instance can: be
obtained. The returned function pointer must: only be called with a
@ -58,14 +61,20 @@ to be dynamically loaded. If this decision is upheld by the group as a
whole, it would probably be encoded in the previous paragraph, in the WSI
extensions branch of the Specification.
However, this decision hasn't been fully signed off on by the entire Vulkan
WG yet AFAIK. Note that implementations typically won't support many of the
WSI extensions, so ``static entry points'' doesn't relieve apps of the
However, this decision has not been fully signed off on by the entire Vulkan
WG yet AFAIK. Note that implementations typically will not support many of the
WSI extensions, so ``static entry points'' do not relieve apps of the
neccessity of runtime enabling and testing of each extension before using
it.
====
endif::editing-notes[]
include::../validity/protos/vkGetInstanceProcAddr.txt[]
// refEnd vkGetInstanceProcAddr PFN_vkVoidFunction
// refBegin vkGetDeviceProcAddr Return a function pointer for a command
In order to support systems with multiple Vulkan implementations
comprising heterogeneous collections of hardware and software, the function
pointers returned by fname:vkGetInstanceProcAddr may: point to dispatch
@ -85,20 +94,46 @@ include::../protos/vkGetDeviceProcAddr.txt[]
** sname:VkQueue
** sname:VkCommandBuffer
The returned function pointer is of type tlink:PFN_vkVoidFunction, and must
be cast to the type of the command being queried.
If pname:pName is not the name of one of these Vulkan commands, and is
not the name of an extension command belonging to an extension enabled for
pname:device, then fname:vkGetDeviceProcAddr will return `NULL`.
include::../validity/protos/vkGetDeviceProcAddr.txt[]
// refEnd vkGetInstanceProcAddr PFN_vkVoidFunction
// refBegin PFN_vkVoidFunction Dummy function pointer type returned by queries
The function pointer type returned from the flink:vkGetInstanceProcAddr and
flink:vkGetDeviceProcAddr is a dummy type not corresponding to any actual
Vulkan function:
include::../funcpointers/PFN_vkVoidFunction.txt[]
// refEnd PFN_vkVoidFunction vkGetDeviceProcAddr vkGetInstanceProcAddr
[[initialization-instances]]
== Instances
// refBegin VkInstance - Opaque handle to a instance object
There is no global state in Vulkan and all per-application state is
stored in a sname:VkInstance object. Creating a sname:VkInstance object
initializes the Vulkan library and allows the application to pass
information about itself to the implementation.
Instances are represented by sname:VkInstance handles:
include::../handles/VkInstance.txt[]
// refEnd VkInstance
// refBegin vkCreateInstance Create a new Vulkan instance
To create an instance object, call:
include::../protos/vkCreateInstance.txt[]
@ -110,8 +145,18 @@ include::../protos/vkCreateInstance.txt[]
* pname:pInstance points a sname:VkInstance handle in which the resulting
instance is returned.
fname:vkCreateInstance creates the instance, then enables and initializes
global layers and extensions requested by the application. If an extension
is provided by a layer, both the layer and extension must: be specified at
fname:vkCreateInstance time. If a specified layer cannot be found, no
sname:VkInstance will be created and the function will return
ename:VK_ERROR_LAYER_NOT_PRESENT. Likewise, if a specified extension cannot
be found the call will return ename:VK_ERROR_EXTENSION_NOT_PRESENT.
include::../validity/protos/vkCreateInstance.txt[]
// refBegin VkInstanceCreateInfo - Structure specifying parameters of a newly created instance
The sname:VkInstanceCreateInfo structure is defined as:
include::../structs/VkInstanceCreateInfo.txt[]
@ -136,17 +181,11 @@ include::../structs/VkInstanceCreateInfo.txt[]
include::../validity/structs/VkInstanceCreateInfo.txt[]
fname:vkCreateInstance creates the instance, then enables and initializes
global layers and extensions requested by the application. If an extension
is provided by a layer, both the layer and extension must: be specified at
fname:vkCreateInstance time. If a specified layer cannot be found, no
sname:VkInstance will be created and the function will return
ename:VK_ERROR_LAYER_NOT_PRESENT. Likewise, if a specified extension cannot be found
the call will return ename:VK_ERROR_EXTENSION_NOT_PRESENT.
The pname:pApplicationInfo member of slink:VkInstanceCreateInfo can: point
to an instance of sname:VkApplicationInfo.
// refBegin VkApplicationInfo - Structure specifying application info
The sname:VkApplicationInfo structure is defined as:
include::../structs/VkApplicationInfo.txt[]
@ -175,6 +214,8 @@ include::../structs/VkApplicationInfo.txt[]
include::../validity/structs/VkApplicationInfo.txt[]
// refBegin vkDestroyInstance Destroy an instance of Vulkan.
To destroy an instance, call:
include::../protos/vkDestroyInstance.txt[]

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

@ -626,26 +626,23 @@ out according to the following rules.
* The code:Offset Decoration must: be a multiple of its base alignment,
computed recursively as follows:
+
** a scalar of size latexmath:[$N$] has a base alignment of
latexmath:[$N$]
** a two-component vector, with components of size latexmath:[$N$], has
a base alignment of latexmath:[$2N$]
** a three- or four-component vector, with components of size
latexmath:[$N$], has a base alignment of latexmath:[$4N$]
** an array has a base alignment equal to the base alignment of its
element type, rounded up to a multiple of latexmath:[$16$]
** a structure has a base alignment equal to the largest base alignment
of any of its members, rounded up to a multiple of latexmath:[$16$]
** a row-major matrix of latexmath:[$C$] columns has a base alignment
equal to the base alignment of vector of latexmath:[$C$] matrix
components
** a column-major matrix has a base alignment equal to the base
alignment of the matrix column type
+
** a scalar of size latexmath:[$N$] has a base alignment of
latexmath:[$N$]
** a two-component vector, with components of size latexmath:[$N$], has
a base alignment of latexmath:[$2N$]
** a three- or four-component vector, with components of size
latexmath:[$N$], has a base alignment of latexmath:[$4N$]
** an array has a base alignment equal to the base alignment of its
element type, rounded up to a multiple of latexmath:[$16$]
** a structure has a base alignment equal to the largest base alignment
of any of its members, rounded up to a multiple of latexmath:[$16$]
** a row-major matrix of latexmath:[$C$] columns has a base alignment
equal to the base alignment of vector of latexmath:[$C$] matrix
components
** a column-major matrix has a base alignment equal to the base
alignment of the matrix column type
* Any code:ArrayStride or code:MatrixStride decoration must: be an integer
multiple of the base alignment of the array or matrix from above.
+
* The code:Offset Decoration of a member immediately following a structure or
an array must: be greater than or equal to the next multiple of the base
alignment of that structure or array.
@ -922,7 +919,7 @@ code:LocalInvocationId.y and code:LocalInvocationId.z will be zero.
code:NumWorkgroups::
The code:NumWorkgroups built-in decoration can: be applied to a variable that
represents the number of local workgroups that are part of the dispatch that the
represents the number of local workgroups that are part of the dispatch that the
invocation belongs to. Each component is equal to the values of the parameters
passed into flink:vkCmdDispatch or read from the sname:VkDispatchIndirectCommand
structure read through a call to flink:vkCmdDispatchIndirect.

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

@ -24,6 +24,8 @@ performance feature. Rather, this can: be useful for certain embedded
systems, for debugging purposes (e.g. putting a guard page after all host
allocations), or for memory allocation logging.
// refBegin VkAllocationCallbacks Structure containing callback function pointers for memory allocation.
Allocators are provided by the application as a pointer to a
sname:VkAllocationCallbacks structure:
@ -52,6 +54,8 @@ include::../structs/VkAllocationCallbacks.txt[]
include::../validity/structs/VkAllocationCallbacks.txt[]
// refBegin PFN_vkAllocationFunction application-defined memory allocation function
The type of pname:pfnAllocation is:
include::../funcpointers/PFN_vkAllocationFunction.txt[]
@ -75,7 +79,7 @@ with the pointer value being a multiple of pname:alignment.
[NOTE]
.Note
====
Correct Vulkan operation cannot: be assumed if the application doesn't
Correct Vulkan operation cannot: be assumed if the application does not
follow these rules.
For example, pname:pfnAllocation (or pname:pfnReallocation) could cause
@ -99,6 +103,10 @@ command without the requested allocation, then it may: do so, and must:
not generate ename:VK_ERROR_OUT_OF_HOST_MEMORY as a result of this failed
allocation.
// refEnd PFN_vkAllocationFunction VkAllocationCallbacks
// refBegin PFN_vkReallocationFunction application-defined memory reallocation function
The type of pname:pfnReallocation is:
include::../funcpointers/PFN_vkReallocationFunction.txt[]
@ -141,6 +149,10 @@ must: not free the old allocation.
pname:pfnReallocation must: follow the same <<vkAllocationFunction_return_rules,
rules for return values as tname:PFN_vkAllocationFunction>>.
// refEnd PFN_vkReallocationFunction VkAllocationCallbacks
// refBegin PFN_vkFreeFunction application-defined memory free function
The type of pname:pfnFree is:
include::../funcpointers/PFN_vkFreeFunction.txt[]
@ -155,6 +167,10 @@ pname:pMemory is non-`NULL`, it must: be a pointer previously allocated by
pname:pfnAllocation or pname:pfnReallocation. The application should: free
this memory.
// refEnd PFN_vkFreeFunction VkAllocationCallbacks
// refBegin PFN_vkInternalAllocationNotification application-defined memory allocation notification function
The type of pname:pfnInternalAllocation is:
include::../funcpointers/PFN_vkInternalAllocationNotification.txt[]
@ -170,6 +186,10 @@ include::../funcpointers/PFN_vkInternalAllocationNotification.txt[]
This is a purely informational callback.
// refEnd PFN_vkInternalAllocationNotification VkAllocationCallbacks
// refBegin PFN_vkInternalFreeNotification application-defined memory free notification function
The type of pname:pfnInternalFree is:
include::../funcpointers/PFN_vkInternalFreeNotification.txt[]
@ -183,10 +203,16 @@ include::../funcpointers/PFN_vkInternalFreeNotification.txt[]
specifying the scope of the lifetime of the allocation, as described
<<memory-host-allocation-scope,here>>.
// refEnd PFN_vkInternalFreeNotification VkAllocationCallbacks
// refBegin VkSystemAllocationScope allocation scope
[[memory-host-allocation-scope]]
Each allocation has a _scope_ which defines its lifetime and which object it
is associated with. The scope is provided in the pname:allocationScope
parameter and takes a value of type elink:VkSystemAllocationScope:
parameter passed to callbacks defined in slink:VkAllocationCallbacks.
Possible values for this parameter are defined by
elink:VkSystemAllocationScope:
include::../enums/VkSystemAllocationScope.txt[]
@ -235,6 +261,8 @@ application using the most specific allocator and scope available:
* Otherwise an implementation will allocate memory through an alternative
mechanism that is unspecified.
// refEnd VkSystemAllocationScope VkAllocationCallbacks
Objects that are allocated from pools do not specify their own allocator.
When an implementation requires host memory for such an object, that memory
is sourced from the object's parent pool's allocator.
@ -249,6 +277,8 @@ Upon freeing executable memory, pname:pfnInternalFree will be called. An
implementation will only call an informational callback for executable
memory allocations and frees.
// refBegin VkInternalAllocationType allocation type
The pname:allocationType parameter to the pname:pfnInternalAllocation and
pname:pfnInternalFree functions may: be one of the following values:
@ -257,6 +287,8 @@ include::../enums/VkInternalAllocationType.txt[]
* ename:VK_INTERNAL_ALLOCATION_TYPE_EXECUTABLE - The allocation is
intended for execution by the host.
// refEnd VkInternalAllocationType PFN_vkInternalAllocationNotification PFN_vkInternalFreeNotification
An implementation must: only make calls into an application-provided
allocator from within the scope of an API command. An implementation must:
only make calls into an application-provided allocator from the same thread
@ -357,9 +389,12 @@ Device memory is memory that is visible to the device, for example the
contents of opaque images that can: be natively used by the device, or
uniform buffer objects that reside in on-device memory.
The memory properties of the physical device describe the memory heaps and
memory types available to a physical device. These can: be queried by
calling:
Memory properties of a physical device describe the memory heaps and memory
types available.
// refBegin vkGetPhysicalDeviceMemoryProperties Reports memory information for the specified physical device.
To query memory properties, call:
include::../protos/vkGetPhysicalDeviceMemoryProperties.txt[]
@ -370,19 +405,21 @@ include::../protos/vkGetPhysicalDeviceMemoryProperties.txt[]
include::../validity/protos/vkGetPhysicalDeviceMemoryProperties.txt[]
// refBegin VkPhysicalDeviceMemoryProperties - Structure specifying physical device memory properties
The sname:VkPhysicalDeviceMemoryProperties structure is defined as:
include::../structs/VkPhysicalDeviceMemoryProperties.txt[]
ifdef::editing-notes[]
[NOTE]
.editing-note
====
TODO (Jon) - Need to restructure description like other structures.
====
endif::editing-notes[]
include::../validity/structs/VkPhysicalDeviceMemoryProperties.txt[]
* pname:memoryTypeCount is the number of valid elements in the
pname:pMemoryRanges array.
* pname:memoryTypes is an array of slink:VkMemoryType structures
describing the _memory types_ that can: be used to access memory
allocated from the heaps specified by pname:memoryHeaps.
* pname:memoryHeapCount is the number of valid elements in the
pname:pMemoryRanges array.
* pname:memoryHeaps is an array of slink:VkMemoryHeap structures
describing the _memory heaps_ from which memory can: be allocated.
The sname:VkPhysicalDeviceMemoryProperties structure describes a number of
_memory heaps_ as well as a number of _memory types_ that can: be used to
@ -404,72 +441,13 @@ pname:memoryTypeCount and is less than or equal to
ename:VK_MAX_MEMORY_TYPES. Each memory type is described by an element of
the pname:memoryTypes array, as a sname:VkMemoryType structure.
The sname:VkMemoryHeap structure is defined as:
include::../structs/VkMemoryHeap.txt[]
* pname:size is the total memory size in bytes in the heap.
* pname:flags is a bitmask of attribute flags for the heap. The bits
specified in pname:flags are:
+
include::../enums/VkMemoryHeapFlagBits.txt[]
** if pname:flags contains ename:VK_MEMORY_HEAP_DEVICE_LOCAL_BIT, it means
the heap corresponds to device local memory. Device local memory may:
have different performance characteristics than host local memory, and
may: support different memory property flags.
include::../validity/structs/VkMemoryHeap.txt[]
At least one heap must: include ename:VK_MEMORY_HEAP_DEVICE_LOCAL_BIT in
pname:flags. If there are multiple heaps that all have similar performance
slink:VkMemoryHeap::pname:flags. If there are multiple heaps that all have similar performance
characteristics, they may: all include ename:VK_MEMORY_HEAP_DEVICE_LOCAL_BIT.
In a unified memory architecture (UMA) system, there is often only a single
memory heap which is considered to be equally ``local'' to the host and to the
device, and such an implementation must: advertise the heap as device-local.
The sname:VkMemoryType structure is defined as:
include::../structs/VkMemoryType.txt[]
* pname:heapIndex describes which memory heap this memory type
corresponds to, and must: be less than pname:memoryHeapCount from the
sname:VkPhysicalDeviceMemoryProperties structure.
* pname:propertyFlags is a bitmask of properties for this memory type. The
bits specified in pname:propertyFlags are:
+
include::../enums/VkMemoryPropertyFlagBits.txt[]
** if pname:propertyFlags has the
ename:VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT bit set, memory allocated
with this type is the most efficient for device access. This property
will only be set for memory types belonging to heaps with the
ename:VK_MEMORY_HEAP_DEVICE_LOCAL_BIT set.
** if pname:propertyFlags has the
ename:VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT bit set, memory allocated
with this type can: be mapped using flink:vkMapMemory so that it can:
be accessed on the host.
** if pname:propertyFlags has the
ename:VK_MEMORY_PROPERTY_HOST_COHERENT_BIT bit set, host cache
management commands fname:vkFlushMappedMemoryRanges and
fname:vkInvalidateMappedMemoryRanges are not needed to make host writes
visible to the device or device writes visible to the host,
respectively.
** if pname:propertyFlags has the
ename:VK_MEMORY_PROPERTY_HOST_CACHED_BIT bit set, memory allocated
with this type is cached on the host. Host memory accesses to
uncached memory are slower than to cached memory, however uncached
memory is always host coherent.
** if pname:propertyFlags has the
ename:VK_MEMORY_PROPERTY_LAZILY_ALLOCATED_BIT bit set, the memory type
only allows device access to the memory. Memory types must: not have
both ename:VK_MEMORY_PROPERTY_LAZILY_ALLOCATED_BIT and
ename:VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT set. Additionally,
the object's backing memory may: be provided by the implementation
lazily as specified in <<memory-device-lazy_allocation, Lazily
Allocated Memory>>.
include::../validity/structs/VkMemoryType.txt[]
Each memory type returned by flink:vkGetPhysicalDeviceMemoryProperties must:
have its pname:propertyFlags set to one of the following values:
@ -540,9 +518,90 @@ accesses, as appropriate for the intended usage, and if such a memory type is
not present can: fallback to searching for a less optimal but guaranteed set of
properties such as "0" or "host-visible and coherent".
include::../validity/structs/VkPhysicalDeviceMemoryProperties.txt[]
// refBegin VkMemoryHeap - Structure specifying a memory heap
The sname:VkMemoryHeap structure is defined as:
include::../structs/VkMemoryHeap.txt[]
* pname:size is the total memory size in bytes in the heap.
* pname:flags is a bitmask of attribute flags for the heap. The bits
specified in pname:flags are:
+
--
// refBegin VkMemoryHeapFlagBits - Bitmask specifying attribute flags for a heap
include::../enums/VkMemoryHeapFlagBits.txt[]
--
** if pname:flags contains ename:VK_MEMORY_HEAP_DEVICE_LOCAL_BIT, it means
the heap corresponds to device local memory. Device local memory may:
have different performance characteristics than host local memory, and
may: support different memory property flags.
include::../validity/structs/VkMemoryHeap.txt[]
// refBegin VkMemoryType - Structure specifying memory type
The sname:VkMemoryType structure is defined as:
include::../structs/VkMemoryType.txt[]
* pname:heapIndex describes which memory heap this memory type
corresponds to, and must: be less than pname:memoryHeapCount from the
sname:VkPhysicalDeviceMemoryProperties structure.
* pname:propertyFlags is a bitmask of properties for this memory type. The
bits specified in pname:propertyFlags are:
+
--
// refBegin VkMemoryPropertyFlagBits - Bitmask specifying properties for a memory type
include::../enums/VkMemoryPropertyFlagBits.txt[]
--
** if pname:propertyFlags has the
ename:VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT bit set, memory allocated
with this type is the most efficient for device access. This property
will only be set for memory types belonging to heaps with the
ename:VK_MEMORY_HEAP_DEVICE_LOCAL_BIT set.
** if pname:propertyFlags has the
ename:VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT bit set, memory allocated
with this type can: be mapped using flink:vkMapMemory so that it can:
be accessed on the host.
** if pname:propertyFlags has the
ename:VK_MEMORY_PROPERTY_HOST_COHERENT_BIT bit set, host cache
management commands fname:vkFlushMappedMemoryRanges and
fname:vkInvalidateMappedMemoryRanges are not needed to make host writes
visible to the device or device writes visible to the host,
respectively.
** if pname:propertyFlags has the
ename:VK_MEMORY_PROPERTY_HOST_CACHED_BIT bit set, memory allocated
with this type is cached on the host. Host memory accesses to
uncached memory are slower than to cached memory, however uncached
memory is always host coherent.
** if pname:propertyFlags has the
ename:VK_MEMORY_PROPERTY_LAZILY_ALLOCATED_BIT bit set, the memory type
only allows device access to the memory. Memory types must: not have
both ename:VK_MEMORY_PROPERTY_LAZILY_ALLOCATED_BIT and
ename:VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT set. Additionally,
the object's backing memory may: be provided by the implementation
lazily as specified in <<memory-device-lazy_allocation, Lazily
Allocated Memory>>.
include::../validity/structs/VkMemoryType.txt[]
// refBegin VkDeviceMemory - Opaque handle to a device memory object
A Vulkan device operates on data in device memory via memory objects that
are represented in the API by a sname:VkDeviceMemory handle. Memory objects
are allocated by calling fname:vkAllocateMemory:
are represented in the API by a sname:VkDeviceMemory handle.
Memory objects are represented by sname:VkDeviceMemory handles:
include::../handles/VkDeviceMemory.txt[]
// refEnd VkDeviceMemory
// refBegin vkAllocateMemory Allocate GPU memory.
To allocate memory objects, call:
include::../protos/vkAllocateMemory.txt[]
@ -556,21 +615,6 @@ include::../protos/vkAllocateMemory.txt[]
* pname:pMemory is a pointer to a sname:VkDeviceMemory handle in which
information about the allocated memory is returned.
include::../validity/protos/vkAllocateMemory.txt[]
The sname:VkMemoryAllocateInfo structure is defined as:
include::../structs/VkMemoryAllocateInfo.txt[]
* pname:sType is the type of this structure.
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
* pname:allocationSize is the size of the allocation in bytes
* pname:memoryTypeIndex is the memory type index, which selects the
properties of the memory to be allocated, as well as the heap the memory
will come from.
include::../validity/structs/VkMemoryAllocateInfo.txt[]
Allocations returned by fname:vkAllocateMemory are guaranteed to meet any
alignment requirement by the implementation. For example, if an
implementation requires 128 byte alignment for images and 64 byte alignment
@ -598,7 +642,26 @@ if such a failure occurs then the error ename:VK_ERROR_OUT_OF_DEVICE_MEMORY
should: be returned.
====
A memory object is freed by calling:
include::../validity/protos/vkAllocateMemory.txt[]
// refBegin VkMemoryAllocateInfo Structure containing parameters of a memory allocation.
The sname:VkMemoryAllocateInfo structure is defined as:
include::../structs/VkMemoryAllocateInfo.txt[]
* pname:sType is the type of this structure.
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
* pname:allocationSize is the size of the allocation in bytes
* pname:memoryTypeIndex is the memory type index, which selects the
properties of the memory to be allocated, as well as the heap the memory
will come from.
include::../validity/structs/VkMemoryAllocateInfo.txt[]
// refBegin vkFreeMemory Free GPU memory
To free a memory object, call:
include::../protos/vkFreeMemory.txt[]
@ -607,8 +670,6 @@ include::../protos/vkFreeMemory.txt[]
* pname:pAllocator controls host memory allocation as described in
the <<memory-allocation, Memory Allocation>> chapter.
include::../validity/protos/vkFreeMemory.txt[]
Before freeing a memory object, an application must: ensure the
memory object is no longer in use by the device--for example by command
buffers queued for execution. The memory can: remain bound to images or
@ -626,6 +687,9 @@ the <<resources-association, Resource Memory Association>> section.
If a memory object is mapped at the time it is freed, it is implicitly
unmapped.
include::../validity/protos/vkFreeMemory.txt[]
[[memory-device-hostaccess]]
=== Host Access to Device Memory Objects
@ -634,9 +698,12 @@ accessible.
Memory objects created with the memory property
ename:VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT are considered _mappable_. Memory
objects must: be mappable in order to be successfully mapped on the host. An
application retrieves a host virtual address pointer to a region of a
mappable memory object by calling:
objects must: be mappable in order to be successfully mapped on the host.
// refBegin vkMapMemory Map a memory object into application address space.
To retrieve a host virtual address pointer to a region of a mappable memory
object, call:
include::../protos/vkMapMemory.txt[]
@ -647,14 +714,12 @@ include::../protos/vkMapMemory.txt[]
* pname:size is the size of the memory range to map, or
ename:VK_WHOLE_SIZE to map from pname:offset to the end of the
allocation.
* pname:flags is reserved for future use, and must: be zero.
* pname:flags is reserved for future use.
* pname:ppData points to a pointer in which is returned a host-accessible
pointer to the beginning of the mapped range. This pointer minus
pname:offset must: be aligned to at least
sname:VkPhysicalDeviceLimits::pname:minMemoryMapAlignment.
include::../validity/protos/vkMapMemory.txt[]
It is an application error to call fname:vkMapMemory on a memory object that
is already mapped.
@ -687,10 +752,23 @@ familiar with all of the mechanisms described in the chapter on
to maintaining memory access ordering.
====
include::../validity/protos/vkMapMemory.txt[]
Two commands are provided to enable applications to work with
non-coherent memory allocations: fname:vkFlushMappedMemoryRanges and
fname:vkInvalidateMappedMemoryRanges.
[NOTE]
.Note
====
If the memory object was created with the
ename:VK_MEMORY_PROPERTY_HOST_COHERENT_BIT set,
fname:vkFlushMappedMemoryRanges and fname:vkInvalidateMappedMemoryRanges are
unnecessary and may: have performance cost.
====
// refBegin vkFlushMappedMemoryRanges Flush mapped memory ranges.
To flush ranges of non-coherent memory from the host caches, call:
include::../protos/vkFlushMappedMemoryRanges.txt[]
@ -701,13 +779,15 @@ include::../protos/vkFlushMappedMemoryRanges.txt[]
slink:VkMappedMemoryRange structures describing the memory ranges to
flush.
include::../validity/protos/vkFlushMappedMemoryRanges.txt[]
fname:vkFlushMappedMemoryRanges must: be used to guarantee that host writes to
non-coherent memory are visible to the device. It must: be called after the host
writes to non-coherent memory have completed and before command buffers that will
read or write any of those memory locations are submitted to a queue.
include::../validity/protos/vkFlushMappedMemoryRanges.txt[]
// refBegin vkInvalidateMappedMemoryRanges Invalidate ranges of mapped memory objects.
To invalidate ranges of non-coherent memory from the host caches, call:
include::../protos/vkInvalidateMappedMemoryRanges.txt[]
@ -718,8 +798,17 @@ include::../protos/vkInvalidateMappedMemoryRanges.txt[]
slink:VkMappedMemoryRange structures describing the memory ranges to
invalidate.
fname:vkInvalidateMappedMemoryRanges must: be used to guarantee that device writes to
non-coherent memory are visible to the host. It must: be called after command buffers
that execute and flush (via memory barriers) the device writes have completed, and
before the host will read or write any of those locations. If a range of non-coherent
memory is written by the host and then invalidated without first being flushed, its
contents are undefined.
include::../validity/protos/vkInvalidateMappedMemoryRanges.txt[]
// refBegin VkMappedMemoryRange - Structure specifying a mapped memory range
The sname:VkMappedMemoryRange structure is defined as:
include::../structs/VkMappedMemoryRange.txt[]
@ -735,22 +824,6 @@ include::../structs/VkMappedMemoryRange.txt[]
include::../validity/structs/VkMappedMemoryRange.txt[]
[NOTE]
.Note
====
If the memory object was created with the
ename:VK_MEMORY_PROPERTY_HOST_COHERENT_BIT set,
fname:vkFlushMappedMemoryRanges and fname:vkInvalidateMappedMemoryRanges are
unnecessary and may: have performance cost.
====
fname:vkInvalidateMappedMemoryRanges must: be used to guarantee that device writes to
non-coherent memory are visible to the host. It must: be called after command buffers
that execute and flush (via memory barriers) the device writes have completed, and
before the host will read or write any of those locations. If a range of non-coherent
memory is written by the host and then invalidated without first being flushed, its
contents are undefined.
ifdef::editing-notes[]
[NOTE]
.editing-note
@ -778,8 +851,10 @@ the host wrote some data after submission). For device writes to be seen by
subsequent host reads, a pipeline barrier is required: to
<<synchronization-fences-devicewrites,make the writes visible>>.
Once host access to a memory object is no longer needed by the application,
it can: be unmapped by calling:
// refBegin vkUnmapMemory Unmap a previously mapped memory object.
To unmap a memory object once host access to it is no longer needed by the
application, call:
include::../protos/vkUnmapMemory.txt[]
@ -811,8 +886,10 @@ are not needed once a render pass instance has completed may: allow some
implementations to never allocate memory for such attachments.
====
Determining the amount of lazily-allocated memory that is currently
committed for a memory object is achieved by calling:
// refBegin vkGetDeviceMemoryCommitment Query the current commitment for a VkDeviceMemory
To determine the amount of lazily-allocated memory that is currently
committed for a memory object, call:
include::../protos/vkGetDeviceMemoryCommitment.txt[]
@ -822,8 +899,6 @@ include::../protos/vkGetDeviceMemoryCommitment.txt[]
value in which the number of bytes currently committed is returned, on
success.
include::../validity/protos/vkGetDeviceMemoryCommitment.txt[]
The implementation may: update the commitment at any time, and the
value returned by this query may: be out of date.
@ -831,3 +906,5 @@ The implementation guarantees to allocate any committed memory from the
heapIndex indicated by the memory type that the memory object was created
with.
include::../validity/protos/vkGetDeviceMemoryCommitment.txt[]

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

@ -75,6 +75,15 @@ object with that same state as dynamic, the new pipeline object state will
override the dynamic state. Modifying dynamic state that is not set as
dynamic by the pipeline state object will lead to undefined results.
// refBegin VkPipeline - Opaque handle to a pipeline object
Compute and graphics pipelines are each represented by sname:VkPipeline
handles:
include::../handles/VkPipeline.txt[]
// refEnd VkPipeline
[[pipelines-compute]]
== Compute Pipelines
@ -82,18 +91,20 @@ dynamic by the pipeline state object will lead to undefined results.
Compute pipelines consist of a single static compute shader stage and the
pipeline layout.
The compute pipeline encapsulates a compute shader and is created by calling
The compute pipeline represents a compute shader and is created by calling
fname:vkCreateComputePipelines with pname:module and pname:pName selecting
an entry point from a shader module, where that entry point defines a valid
compute shader, in the sname:VkPipelineShaderStageCreateInfo structure
contained within the sname:VkComputePipelineCreateInfo structure.
Compute pipelines are created by calling:
// refBegin vkCreateComputePipelines Creates a new compute pipeline object.
To create compute pipelines, call:
include::../protos/vkCreateComputePipelines.txt[]
* pname:device is the logical device that creates the compute pipelines.
* pname:pipelineCache is either code:VK_NULL_HANDLE, indicating that
* pname:pipelineCache is either dlink:VK_NULL_HANDLE, indicating that
pipeline caching is disabled; or the handle of a valid
<<pipelines-cache,pipeline cache>> object, in which case use of that
cache is enabled for the duration of the command.
@ -120,6 +131,8 @@ endif::editing-notes[]
include::../validity/protos/vkCreateComputePipelines.txt[]
// refBegin VkComputePipelineCreateInfo - Structure specifying parameters of a newly created compute pipeline
The sname:VkComputePipelineCreateInfo structure is defined as:
include::../structs/VkComputePipelineCreateInfo.txt[]
@ -136,8 +149,6 @@ include::../structs/VkComputePipelineCreateInfo.txt[]
* pname:basePipelineIndex is an index into the pname:pCreateInfos
parameter to use as a pipeline to derive from
include::../validity/structs/VkComputePipelineCreateInfo.txt[]
The parameters pname:basePipelineHandle and pname:basePipelineIndex are
described in more detail in
<<pipelines-pipeline-derivatives,Pipeline Derivatives>>.
@ -145,6 +156,10 @@ described in more detail in
pname:stage points to a structure of type
sname:VkPipelineShaderStageCreateInfo.
include::../validity/structs/VkComputePipelineCreateInfo.txt[]
// refBegin VkPipelineShaderStageCreateInfo - Structure specifying parameters of a newly created pipeline shader stage
The sname:VkPipelineShaderStageCreateInfo structure is defined as:
include::../structs/VkPipelineShaderStageCreateInfo.txt[]
@ -152,7 +167,13 @@ include::../structs/VkPipelineShaderStageCreateInfo.txt[]
* pname:sType is the type of this structure.
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
* pname:flags is reserved for future use.
* pname:stage is a elink:VkShaderStageFlagBits naming the pipeline stage.
* pname:stage names a single pipeline stage. Bits which can:
be set include:
+
--
// refBegin VkShaderStageFlagBits - Bitmask specifying a pipeline stage
include::../enums/VkShaderStageFlagBits.txt[]
--
* pname:module is a sname:VkShaderModule object that contains the
shader for this stage.
* pname:pName is a pointer to a null-terminated UTF-8 string specifying
@ -163,22 +184,21 @@ include::../structs/VkPipelineShaderStageCreateInfo.txt[]
include::../validity/structs/VkPipelineShaderStageCreateInfo.txt[]
The elink:VkShaderStageFlagBits flags are defined as:
include::../enums/VkShaderStageFlagBits.txt[]
[[pipelines-graphics]]
== Graphics Pipelines
Graphics pipelines consist of multiple shader stages, multiple
fixed-function pipeline stages, and a pipeline layout, and are created by
calling fname:vkCreateGraphicsPipelines:
fixed-function pipeline stages, and a pipeline layout.
// refBegin vkCreateGraphicsPipelines Create graphics pipelines.
To create graphics pipelines, call:
include::../protos/vkCreateGraphicsPipelines.txt[]
* pname:device is the logical device that creates the graphics pipelines.
* pname:pipelineCache is either code:VK_NULL_HANDLE, indicating that
* pname:pipelineCache is either dlink:VK_NULL_HANDLE, indicating that
pipeline caching is disabled; or the handle of a valid
<<pipelines-cache,pipeline cache>> object, in which case use of that
cache is enabled for the duration of the command.
@ -191,20 +211,22 @@ include::../protos/vkCreateGraphicsPipelines.txt[]
* pname:pPipelines is a pointer to an array in which the resulting
graphics pipeline objects are returned.
include::../validity/protos/vkCreateGraphicsPipelines.txt[]
The sname:VkGraphicsPipelineCreateInfo structure includes an array of shader
The slink:VkGraphicsPipelineCreateInfo structure includes an array of shader
create info structures containing all the desired active shader stages, as
well as creation info to define all relevant fixed-function stages, and a
pipeline layout.
include::../validity/protos/vkCreateGraphicsPipelines.txt[]
// refBegin VkGraphicsPipelineCreateInfo - Structure specifying parameters of a newly created graphics pipeline
The sname:VkGraphicsPipelineCreateInfo structure is defined as:
include::../structs/VkGraphicsPipelineCreateInfo.txt[]
* pname:sType is the type of this structure.
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
* pname:flags is a bitfield of elink:VkPipelineCreateFlagBits controlling
* pname:flags is a bitmask of elink:VkPipelineCreateFlagBits controlling
how the pipeline will be generated, as described below.
* pname:stageCount is the number of entries in the pname:pStages array.
* pname:pStages is an array of size pname:stageCount structures of type
@ -253,8 +275,6 @@ include::../structs/VkGraphicsPipelineCreateInfo.txt[]
* pname:basePipelineIndex is an index into the pname:pCreateInfos
parameter to use as a pipeline to derive from.
include::../validity/structs/VkGraphicsPipelineCreateInfo.txt[]
The parameters pname:basePipelineHandle and pname:basePipelineIndex are
described in more detail in
<<pipelines-pipeline-derivatives,Pipeline Derivatives>>.
@ -265,6 +285,7 @@ structures, which were previously described in
Bits which can: be set in pname:flags are:
// refBegin VkPipelineCreateFlagBits - Bitmask controlling how a pipeline is generated
include::../enums/VkPipelineCreateFlagBits.txt[]
* ename:VK_PIPELINE_CREATE_DISABLE_OPTIMIZATION_BIT specifies that the
@ -285,6 +306,10 @@ information.
pname:pDynamicState points to a structure of type
sname:VkPipelineDynamicStateCreateInfo.
include::../validity/structs/VkGraphicsPipelineCreateInfo.txt[]
// refBegin VkPipelineDynamicStateCreateInfo - Structure specifying parameters of a newly created pipeline dynamic state
The sname:VkPipelineDynamicStateCreateInfo structure is defined as:
include::../structs/VkPipelineDynamicStateCreateInfo.txt[]
@ -300,7 +325,11 @@ include::../structs/VkPipelineDynamicStateCreateInfo.txt[]
include::../validity/structs/VkPipelineDynamicStateCreateInfo.txt[]
The elink:VkDynamicState enumerants are defined as:
// refBegin VkDynamicState - indicate which dynamic state is taken from dynamic state commands
The source of difference pieces of dynamic state is determined by the
slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates property of the
currently active pipeline, which takes the following values:
include::../enums/VkDynamicState.txt[]
@ -364,6 +393,11 @@ include::../enums/VkDynamicState.txt[]
sname:VkPipelineDepthStencilStateCreateInfo member
pname:stencilTestEnable set to ename:VK_TRUE
// refEnd VkDynamicState
=== Valid Combinations of Stages for Graphics Pipelines
If tessellation shader stages are omitted, the tessellation shading and
fixed-function stages of the pipeline are skipped.
@ -427,6 +461,8 @@ Tessellation Control and Tessellation Evaluation shaders.
[[pipelines-destruction]]
== Pipeline destruction
// refBegin vkDestroyPipeline Destroy a pipeline object
To destroy a graphics or compute pipeline, call:
include::../protos/vkDestroyPipeline.txt[]
@ -453,10 +489,10 @@ group-create.
When an application attempts to create many pipelines in a single command,
it is possible that some subset may: fail creation. In that case, the
corresponding entries in the pname:pPipelines output array will be filled
with code:VK_NULL_HANDLE values. If any pipeline fails creation (for
with dlink:VK_NULL_HANDLE values. If any pipeline fails creation (for
example, due to out of memory errors), the ftext:vkCreate*Pipelines commands
will return an error code. The implementation will attempt to create all
pipelines, and only return code:VK_NULL_HANDLE values for those that
pipelines, and only return dlink:VK_NULL_HANDLE values for those that
actually failed.
@ -476,7 +512,7 @@ pname:basePipelineHandle or pname:basePipelineIndex members of the structure
must: have a valid handle/index, and indicates the parent pipeline. If
pname:basePipelineHandle is used, the parent pipeline must: have already
been created. If pname:basePipelineIndex is used, then the parent is being
created in the same command. code:VK_NULL_HANDLE acts as the invalid handle
created in the same command. dlink:VK_NULL_HANDLE acts as the invalid handle
for pname:basePipelineHandle, and -1 is the invalid index for
pname:basePipelineIndex. If pname:basePipelineIndex is used, the base
pipeline must: appear earlier in the array. The base pipeline must: have
@ -487,6 +523,8 @@ set.
[[pipelines-cache]]
== Pipeline Cache
// refBegin VkPipelineCache - Opaque handle to a pipeline cache object
Pipeline cache objects allow the result of pipeline construction to be
reused between pipelines and between runs of an application. Reuse between
pipelines is achieved by passing the same pipeline cache object when
@ -498,7 +536,15 @@ managed by the implementation. Applications can: manage the host memory
consumed by a pipeline cache object and control the amount of data
retrieved from a pipeline cache object.
Pipeline cache objects are created by calling:
Pipeline cache objects are represented by sname:VkPipelineCache handles:
include::../handles/VkPipelineCache.txt[]
// refEnd VkPipelineCache
// refBegin vkCreatePipelineCache Creates a new pipeline cache
To create pipeline cache objects, call:
include::../protos/vkCreatePipelineCache.txt[]
@ -517,13 +563,32 @@ include::../protos/vkCreatePipelineCache.txt[]
====
Applications can: track and manage the total host memory size of a pipeline
cache object using the pname:pAllocator. Applications can: limit the amount
of data retrieved from a pipeline cache object in fname:vkGetPipeineCacheData.
of data retrieved from a pipeline cache object in fname:vkGetPipelineCacheData.
Implementations shouldnot: internally limit the total number of entries added to a
pipeline cache object or the total host memory consumed.
====
Once created, a pipeline cache can: be passed to the
fname:vkCreateGraphicsPipelines and fname:vkCreateComputePipelines commands.
If the pipeline cache passed into these commands is not
dlink:VK_NULL_HANDLE, the implementation will query it for possible reuse
opportunities and update it with new content. The use of the pipeline cache
object in these commands is internally synchronized, and the same pipeline
cache object can: be used in multiple threads simultaneously.
[NOTE]
.Note
====
Implementations should: make every effort to limit any critical sections
to the actual accesses to the cache, which is expected to be significantly
shorter than the duration of the fname:vkCreateGraphicsPipelines and
fname:vkCreateComputePipelines commands.
====
include::../validity/protos/vkCreatePipelineCache.txt[]
// refBegin VkPipelineCacheCreateInfo - Structure specifying parameters of a newly created pipeline cache
The sname:VkPipelineCacheCreateInfo structure is defined as:
include::../structs/VkPipelineCacheCreateInfo.txt[]
@ -541,22 +606,7 @@ include::../structs/VkPipelineCacheCreateInfo.txt[]
include::../validity/structs/VkPipelineCacheCreateInfo.txt[]
Once created, a pipeline cache can: be passed to the
fname:vkCreateGraphicsPipelines and fname:vkCreateComputePipelines commands.
If the pipeline cache passed into these commands is not
code:VK_NULL_HANDLE, the implementation will query it for possible reuse
opportunities and update it with new content. The use of the pipeline cache
object in these commands is internally synchronized, and the same pipeline
cache object can: be used in multiple threads simultaneously.
[NOTE]
.Note
====
Implementations should: make every effort to limit any critical sections
to the actual accesses to the cache, which is expected to be significantly
shorter than the duration of the fname:vkCreateGraphicsPipelines and
fname:vkCreateComputePipelines commands.
====
// refBegin vkMergePipelineCaches Combine the data stores of pipeline caches.
Pipeline cache objects can: be merged using the command:
@ -570,8 +620,6 @@ include::../protos/vkMergePipelineCaches.txt[]
merged into pname:dstCache. The previous contents of pname:dstCache are
included after the merge.
include::../validity/protos/vkMergePipelineCaches.txt[]
[NOTE]
.Note
====
@ -580,6 +628,10 @@ implementations should: merge the contents of the specified pipelines and
prune duplicate entries.
====
include::../validity/protos/vkMergePipelineCaches.txt[]
// refBegin vkGetPipelineCacheData Get the data store from a pipeline cache
Data can: be retrieved from a pipeline cache object using the command:
include::../protos/vkGetPipelineCacheData.txt[]
@ -597,7 +649,7 @@ size of the buffer, in bytes, pointed to by pname:pData, and on return the
variable is overwritten with the amount of data actually written to
pname:pData.
If pname:dataSize is less than the maximum size that can: be
If pname:pDataSize is less than the maximum size that can: be
retrieved by the pipeline cache, at most pname:pDataSize bytes will be
written to pname:pData, and fname:vkGetPipelineCacheData will return
ename:VK_INCOMPLETE. Any data written to pname:pData is valid and can: be
@ -605,8 +657,6 @@ provided as the pname:pInitialData member of the
sname:VkPipelineCacheCreateInfo structure passed to
fname:vkCreatePipelineCache.
include::../validity/protos/vkGetPipelineCacheData.txt[]
[[pipelines-cache-header]]
Applications can: store the data retrieved from the pipeline cache, and use
these data, possibly in a future run of the application, to populate new
@ -642,6 +692,8 @@ The first four bytes encode the length of the entire pipeline header, in
bytes. This value includes all fields in the header including the pipeline
cache version field and the size of the length field.
// refBegin VkPipelineCacheHeaderVersion Encode pipeline cache version
The next four bytes encode the pipeline cache version. This field is
interpreted as a elink:VkPipelineCacheHeaderVersion value, and must:
have one of the following values:
@ -651,9 +703,15 @@ include::../enums/VkPipelineCacheHeaderVersion.txt[]
A consumer of the pipeline cache should use the cache version to interpret
the remainder of the cache header.
If pname:dataSize is less than what is necessary to store this
// refEnd VkPipelineCacheHeaderVersion vkCreatePipelineCache vkGetPipelineCacheData
If pname:pDataSize is less than what is necessary to store this
header, nothing will be written to pname:pData and zero will be written to
pname:dataSize.
pname:pDataSize.
include::../validity/protos/vkGetPipelineCacheData.txt[]
// refBegin vkDestroyPipelineCache Destroy a pipeline cache object
To destroy a pipeline cache, call:
@ -689,6 +747,8 @@ contains a parameter pname:pSpecializationInfo, which can: be `NULL` to
indicate no specialization constants, or point to a
sname:VkSpecializationInfo structure.
// refBegin VkSpecializationInfo - Structure specifying specialization info
The sname:VkSpecializationInfo structure is defined as:
include::../structs/VkSpecializationInfo.txt[]
@ -701,26 +761,28 @@ include::../structs/VkSpecializationInfo.txt[]
* pname:dataSize is the byte size of the pname:pData buffer.
* pname:pData contains the actual constant values to specialize with.
pname:pMapEntries points to a structure of type
slink:VkSpecializationMapEntry.
include::../validity/structs/VkSpecializationInfo.txt[]
pname:pMapEntries points to a structure of type
sname:VkSpecializationMapEntry.
// refBegin VkSpecializationMapEntry - Structure specifying a specialization map entry
The sname:VkSpecializationMapEntry structure is defined as:
include::../structs/VkSpecializationMapEntry.txt[]
* pname:constantID ID of the specialization constant in SPIR-V.
* pname:offset byte offset of the specialization constant value within the
* pname:constantID is the ID of the specialization constant in SPIR-V.
* pname:offset is the byte offset of the specialization constant value within the
supplied data buffer.
* pname:size byte size of the specialization constant value within the
* pname:size is the byte size of the specialization constant value within the
supplied data buffer.
include::../validity/structs/VkSpecializationMapEntry.txt[]
If a pname:constantID value is not a specialization constant ID used in the
shader, that map entry does not affect the behavior of the pipeline.
include::../validity/structs/VkSpecializationMapEntry.txt[]
In human readable SPIR-V:
[source,glsl]
@ -774,9 +836,9 @@ const VkSpecializationInfo info =
};
---------------------------------------------------
Then when calling fname:vkCreateComputePipelines, and passing the
Then when calling flink:vkCreateComputePipelines, and passing the
sname:VkSpecializationInfo we defined as the pname:pSpecializationInfo
parameter of sname:VkPipelineShaderStageCreateInfo, we will create a compute
parameter of slink:VkPipelineShaderStageCreateInfo, we will create a compute
pipeline with the runtime specified local workgroup size.
Another example would be that an application has a SPIR-V module that has
@ -846,6 +908,8 @@ default values encoded within the OpSpecConstant declarations.
[[pipelines-binding]]
== Pipeline Binding
// refBegin vkCmdBindPipeline Bind a pipeline object to a command buffer.
Once a pipeline has been created, it can: be bound to the command buffer
using the command:
@ -857,18 +921,18 @@ include::../protos/vkCmdBindPipeline.txt[]
the values
+
--
// refBegin VkPipelineBindPoint - specify the bind point of a pipeline object to a command buffer
include::../enums/VkPipelineBindPoint.txt[]
--
+
specifying whether pname:pipeline will be bound as a compute
(ename:VK_PIPELINE_BIND_POINT_COMPUTE) or graphics
(ename:VK_PIPELINE_BIND_POINT_GRAPHICS) pipeline. There are separate bind
points for each of graphics and compute, so binding one does not disturb the
other.
--
+
* pname:pipeline is the pipeline to be bound.
include::../validity/protos/vkCmdBindPipeline.txt[]
Once bound, a pipeline binding affects subsequent graphics or compute
commands in the command buffer until a different pipeline is bound to the
bind point. The pipeline bound to ename:VK_PIPELINE_BIND_POINT_COMPUTE
@ -878,3 +942,6 @@ ename:VK_PIPELINE_BIND_POINT_GRAPHICS controls the behavior of
flink:vkCmdDraw, flink:vkCmdDrawIndexed, flink:vkCmdDrawIndirect, and
flink:vkCmdDrawIndexedIndirect. No other commands are affected by the
pipeline state.
include::../validity/protos/vkCmdBindPipeline.txt[]

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

@ -34,6 +34,8 @@ Several factors affect rasterization, including the members of
sname:VkPipelineRasterizationStateCreateInfo and
sname:VkPipelineMultisampleStateCreateInfo.
// refBegin VkPipelineRasterizationStateCreateInfo - Structure specifying parameters of a newly created pipeline rasterization state
The sname:VkPipelineRasterizationStateCreateInfo structure is defined as:
include::../structs/VkPipelineRasterizationStateCreateInfo.txt[]
@ -63,6 +65,8 @@ include::../structs/VkPipelineRasterizationStateCreateInfo.txt[]
include::../validity/structs/VkPipelineRasterizationStateCreateInfo.txt[]
// refBegin VkPipelineMultisampleStateCreateInfo - Structure specifying parameters of a newly created pipeline multisample state
The sname:VkPipelineMultisampleStateCreateInfo structure is defined as:
include::../structs/VkPipelineMultisampleStateCreateInfo.txt[]
@ -311,6 +315,8 @@ A line is drawn by generating a set of fragments overlapping a rectangle
centered on the line segment. Each line segment has an associated width that
controls the width of that rectangle.
// refBegin vkCmdSetLineWidth Set the dynamic line width state.
The line width is set by the pname:lineWidth property of
slink:VkPipelineRasterizationStateCreateInfo in the currently active
pipeline if the pipeline was not created with
@ -449,6 +455,8 @@ slink:VkPipelineRasterizationStateCreateInfo structure.
[[primsrast-polygons-basic]]
=== Basic Polygon Rasterization
// refBegin VkFrontFace interpret polygon front-facing orientation
The first step of polygon rasterization is to determine whether the triangle
is _back-facing_ or _front-facing_. This determination is made based on the
sign of the (clipped or unclipped) polygon's area computed in framebuffer
@ -467,23 +475,29 @@ where latexmath:[$x_f^i$] and latexmath:[$y_f^i$] are the latexmath:[$x$]
and latexmath:[$y$] framebuffer coordinates of the latexmath:[$i$]th vertex
of the latexmath:[$n$]-vertex polygon (vertices are numbered starting at
zero for the purposes of this computation) and latexmath:[$i \oplus 1$] is
latexmath:[$(i + 1)~ \textrm{mod}~ n$]. The interpretation of the sign of
this value is determined by the pname:frontFace property of the
slink:VkPipelineRasterizationStateCreateInfo in the currently active
pipeline, which takes the following values:
latexmath:[$(i + 1)~ \textrm{mod}~ n$].
The interpretation of the sign of latexmath:[$a$]
is determined by the
slink:VkPipelineRasterizationStateCreateInfo::pname:frontFace property of
the currently active pipeline, which takes the following values:
include::../enums/VkFrontFace.txt[]
When this is set to ename:VK_FRONT_FACE_COUNTER_CLOCKWISE, a triangle with
positive area is considered front-facing. When it is set to
If pname:frontFace is set to ename:VK_FRONT_FACE_COUNTER_CLOCKWISE, a triangle with
positive area is considered front-facing. If it is set to
ename:VK_FRONT_FACE_CLOCKWISE, a triangle with negative area is considered
front-facing. Any triangle which is not front-facing is back-facing,
including zero-area triangles.
// refEnd VkFrontFace
// refBegin VkCullModeFlagBits - Bitmask controlling triangle culling
Once the orientation of triangles is determined, they are culled according
to the setting of pname:cullMode property in the
slink:VkPipelineRasterizationStateCreateInfo of the currently active
pipeline, which takes the following values:
to the setting of the
slink:VkPipelineRasterizationStateCreateInfo::pname:cullMode property of the
currently active pipeline, which takes the following values:
include::../enums/VkCullModeFlagBits.txt[]
@ -495,6 +509,8 @@ ename:VK_CULL_MODE_FRONT_AND_BACK then all triangles are discarded.
Following culling, fragments are produced for any triangles which have not
been discarded.
// refEnd VkCullModeFlagBits
The rule for determining which fragments are produced by polygon
rasterization is called _point sampling_. The two-dimensional projection
obtained by taking the x and y framebuffer coordinates of the polygon's
@ -618,9 +634,11 @@ a division performed for each fragment).
[[primsrast-polygonmode]]
=== Polygon Mode
The interpretation of polygons for rasterization is controlled using the
pname:polygonMode member of slink:VkPipelineRasterizationStateCreateInfo,
which takes the following values:
// refBegin VkPolygonMode control polygon rasterization mode
The method of rasterization for polygons is determined by the
slink:VkPipelineRasterizationStateCreateInfo::pname:polygonMode property of
the currently active pipeline, which takes the following values:
include::../enums/VkPolygonMode.txt[]
@ -635,10 +653,14 @@ Note that these modes affect only the final rasterization of polygons: in
particular, a polygon's vertices are shaded and the polygon is clipped and
possibly culled before these modes are applied.
// refEnd VkPolygonMode
[[primsrast-depthbias]]
=== Depth Bias
// refBegin vkCmdSetDepthBias Set the depth bias dynamic state.
The depth values of all fragments generated by the rasterization of a
polygon can: be offset by a single value that is computed for that polygon.
This behavior is controlled by the pname:depthBiasEnable,
@ -659,8 +681,6 @@ include::../protos/vkCmdSetDepthBias.txt[]
* pname:depthBiasSlopeFactor is a scalar factor applied to a fragment's
slope in depth bias calculations.
include::../validity/protos/vkCmdSetDepthBias.txt[]
If pname:depthBiasEnable is ename:VK_FALSE, no depth bias is applied and the
fragment's depth values are unchanged.
@ -748,3 +768,6 @@ For fixed-point depth buffers, fragment depth values are always limited to
the range latexmath:[$[0,1\]$] by clamping after depth bias addition is
performed. Fragment depth values are clamped even when the depth buffer uses
a floating-point representation.
include::../validity/protos/vkCmdSetDepthBias.txt[]

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

@ -19,9 +19,19 @@ The supported query types are <<queries-occlusion,Occlusion Queries>>,
[[queries-pools]]
== Query Pools
// refBegin VkQueryPool - Opaque handle to a query pool object
Queries are managed using _query pool_ objects. Each query pool is a
collection of a specific number of queries of a particular type.
Query pools are represented by sname:VkQueryPool handles:
include::../handles/VkQueryPool.txt[]
// refEnd VkQueryPool
// refBegin vkCreateQueryPool Create a new query pool object.
To create a query pool, call:
include::../protos/vkCreateQueryPool.txt[]
@ -37,6 +47,8 @@ include::../protos/vkCreateQueryPool.txt[]
include::../validity/protos/vkCreateQueryPool.txt[]
// refBegin VkQueryPoolCreateInfo - Structure specifying parameters of a newly created query pool
The sname:VkQueryPoolCreateInfo structure is defined as:
include::../structs/VkQueryPoolCreateInfo.txt[]
@ -47,7 +59,10 @@ include::../structs/VkQueryPoolCreateInfo.txt[]
* pname:queryType is the type of queries managed by the pool,
and must: be one of the values
+
--
// refBegin VkQueryType - specify the type of queries managed by a query pool
include::../enums/VkQueryType.txt[]
--
* pname:queryCount is the number of queries managed by the pool.
* pname:pipelineStatistics is a bitmask indicating which counters will
be returned in queries on the new pool, as described below in
@ -56,6 +71,8 @@ include::../enums/VkQueryType.txt[]
include::../validity/structs/VkQueryPoolCreateInfo.txt[]
// refBegin vkDestroyQueryPool Destroy a query pool object
To destroy a query pool, call:
include::../protos/vkDestroyQueryPool.txt[]
@ -105,6 +122,8 @@ After query pool creation, each query is in an undefined state and must: be
reset prior to use. Queries must: also be reset between uses. Using a
query that has not been reset will result in undefined behavior.
// refBegin vkCmdResetQueryPool Reset queries in a query pool.
To reset a range of queries in a query pool, call:
include::../protos/vkCmdResetQueryPool.txt[]
@ -142,7 +161,9 @@ must: either begin and end inside the same subpass of a render pass
instance, or must: both begin and end outside of a render pass instance
(i.e. contain entire render pass instances).
Begin a query by calling:
// refBegin vkCmdBeginQuery Begin a query.
To begin a query, call:
include::../protos/vkCmdBeginQuery.txt[]
@ -153,8 +174,9 @@ include::../protos/vkCmdBeginQuery.txt[]
* pname:query is the query index within the query pool that will contain
the results.
* pname:flags is a bitmask indicating constraints on the types of queries
that can: be performed. Valid bits in pname:flags include:
that can: be performed. Bits which can: be set include:
+
// refBegin VkQueryControlFlagBits - Bitmask specifying constraints on a query
include::../enums/VkQueryControlFlagBits.txt[]
If the pname:queryType of the pool is ename:VK_QUERY_TYPE_OCCLUSION and
@ -162,15 +184,18 @@ pname:flags contains ename:VK_QUERY_CONTROL_PRECISE_BIT, an implementation
must: return a result that matches the actual number of samples passed. This
is described in more detail in <<queries-occlusion,Occlusion Queries>>.
include::../validity/protos/vkCmdBeginQuery.txt[]
[[queries-operation-active]]
After beginning a query, that query is considered active within the command
After beginning a query, that query is considered _active_ within the command
buffer it was called in until that same query is ended. Queries active in a
primary command buffer when secondary command buffers are executed are
considered active for those secondary command buffers.
After the set of desired draw or dispatch commands, end a query by calling:
include::../validity/protos/vkCmdBeginQuery.txt[]
// refBegin vkCmdEndQuery Ends a query.
To end a query after the set of desired draw or dispatch commands is
executed, call:
include::../protos/vkCmdEndQuery.txt[]
@ -181,8 +206,6 @@ include::../protos/vkCmdEndQuery.txt[]
* pname:query is the query index within the query pool where the result is
stored.
include::../validity/protos/vkCmdEndQuery.txt[]
[[queries-operation-finished]]
As queries operate asynchronously, ending a query does not immediately set
the query's status to available. A query is considered _finished_
@ -194,6 +217,8 @@ Once a query is ended the query must: finish in finite time, unless the
state of the query is changed using other commands, e.g. by issuing a reset
of the query.
include::../validity/protos/vkCmdEndQuery.txt[]
[[queries-operation-memorylayout]]
An application can: retrieve results either by requesting they be written
into application-provided memory, or by requesting they be copied into a
@ -218,6 +243,8 @@ sname:VkBuffer. In either case, the layout in memory is defined as follows:
large as the size of the array of integers corresponding to a single
query, the values written to memory are undefined.
// refBegin vkGetQueryPoolResults Copy results of queries in a query pool to a host memory region.
To retrieve status and results for a set of queries, call:
include::../protos/vkGetQueryPoolResults.txt[]
@ -235,23 +262,22 @@ include::../protos/vkGetQueryPoolResults.txt[]
* pname:stride is the stride in bytes between results for individual
queries within pname:pData.
* pname:flags is a bitmask of elink:VkQueryResultFlagBits specifying how
and when results are returned.
Valid bits in pname:flags include:
and when results are returned. Bits which can: be set include:
+
--
// refBegin VkQueryResultFlagBits - Bitmask specifying how and when query results are returned
include::../enums/VkQueryResultFlagBits.txt[]
These bits have the following meanings:
* ename:VK_QUERY_RESULT_64_BIT indicates the results will be written as an
array of 64-bit unsigned integer values. If this bit is not set, the
results will be written as an array of 32-bit unsigned integer values.
* ename:VK_QUERY_RESULT_WAIT_BIT indicates that Vulkan will wait for
each query's status to become available before retrieving its results.
* ename:VK_QUERY_RESULT_WITH_AVAILABILITY_BIT indicates that the
availability status accompanies the results.
* ename:VK_QUERY_RESULT_PARTIAL_BIT indicates that returning partial
results is acceptable.
--
+
** ename:VK_QUERY_RESULT_64_BIT indicates the results will be written as an
array of 64-bit unsigned integer values. If this bit is not set, the
results will be written as an array of 32-bit unsigned integer values.
** ename:VK_QUERY_RESULT_WAIT_BIT indicates that Vulkan will wait for
each query's status to become available before retrieving its results.
** ename:VK_QUERY_RESULT_WITH_AVAILABILITY_BIT indicates that the
availability status accompanies the results.
** ename:VK_QUERY_RESULT_PARTIAL_BIT indicates that returning partial
results is acceptable.
If no bits are set in pname:flags, and all requested queries are
in the available state, results are written as an array of
@ -334,6 +360,8 @@ e.g. to read the availability status before reading the results.
include::../validity/protos/vkGetQueryPoolResults.txt[]
// refBegin vkCmdCopyQueryPoolResults Copy the results of queries in a query pool to a buffer object.
To copy query statuses and numerical results directly to buffer memory,
call:
@ -482,8 +510,9 @@ The pipeline statistic counters are individually enabled for query pools with
sname:VkQueryPoolCreateInfo::pname:pipelineStatistics, and for secondary command
buffers with sname:VkCommandBufferInheritanceInfo::pname:pipelineStatistics.
Valid bits in pname:pipelineStatistics include:
// refBegin VkQueryPipelineStatisticFlagBits - Bitmask specifying queried pipeline statistics
Bits which can: be set in pname:pipelineStatistics include:
include::../enums/VkQueryPipelineStatisticFlagBits.txt[]
@ -555,7 +584,6 @@ These bits have the following meanings:
invocations for implementation-dependent reasons as long as the results
of rendering otherwise remain unchanged.
These values are intended to measure relative statistics on one
implementation. Various device architectures will count these values
differently. Any or all counters may: be affected by the issues described in
@ -578,6 +606,8 @@ marked as available. The application can: copy the result to a
buffer (via fname:vkCmdCopyQueryPoolResults), or request it be put into host
memory (via fname:vkGetQueryPoolResults).
// refEnd VkQueryPipelineStatisticFlagBits
[[queries-timestamps]]
== Timestamp Queries
@ -608,7 +638,9 @@ incremented by 1 can: be obtained from
sname:VkPhysicalDeviceLimits::pname:timestampPeriod after a call to
fname:vkGetPhysicalDeviceProperties.
A timestamp is requested by calling:
// refBegin vkCmdWriteTimestamp Write a device timestamp into a query object.
To request a timestamp, call:
include::../protos/vkCmdWriteTimestamp.txt[]

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

@ -4,11 +4,19 @@
[[renderpass]]
= Render Pass
// refBegin VkRenderPass - Opaque handle to a render pass object
A _render pass_ represents a collection of attachments, subpasses, and
dependencies between the subpasses, and describes how the attachments
are used over the course of the subpasses. The use of a render pass
in a command buffer is a _render pass instance_.
Render passes are represented by sname:VkRenderPass handles:
include::../handles/VkRenderPass.txt[]
// refEnd VkRenderPass
An _attachment description_ describes the properties of an attachment
including its format, sample count, and how its contents are
treated at the beginning and end of each render pass instance.
@ -85,7 +93,9 @@ per-sample operations are performed in
[[renderpass-creation]]
== Render Pass Creation
A render pass is created by calling:
// refBegin vkCreateRenderPass Create a new render pass object.
To create a render pass, call:
include::../protos/vkCreateRenderPass.txt[]
@ -100,6 +110,8 @@ include::../protos/vkCreateRenderPass.txt[]
include::../validity/protos/vkCreateRenderPass.txt[]
// refBegin VkRenderPassCreateInfo - Structure specifying parameters of a newly created render pass
The sname:VkRenderPassCreateInfo structure is defined as:
include::../structs/VkRenderPassCreateInfo.txt[]
@ -127,6 +139,8 @@ include::../structs/VkRenderPassCreateInfo.txt[]
include::../validity/structs/VkRenderPassCreateInfo.txt[]
// refBegin VkAttachmentDescription - Structure specifying an attachment description
The sname:VkAttachmentDescription structure is defined as:
include::../structs/VkAttachmentDescription.txt[]
@ -140,34 +154,34 @@ include::../structs/VkAttachmentDescription.txt[]
first used:
+
--
// refBegin VkAttachmentLoadOp - specify how contents of an attachment are treated at the beginning of a subpass
include::../enums/VkAttachmentLoadOp.txt[]
** ename:VK_ATTACHMENT_LOAD_OP_LOAD means the contents within the render
area will be preserved.
** ename:VK_ATTACHMENT_LOAD_OP_CLEAR means the contents within the render
area will be cleared to a uniform value, which is specified when a render
pass instance is begun.
** ename:VK_ATTACHMENT_LOAD_OP_DONT_CARE means the contents within the area
need not be preserved; the contents of the attachment will be undefined
inside the render area.
--
** ename:VK_ATTACHMENT_LOAD_OP_LOAD means the contents within the render
area will be preserved.
** ename:VK_ATTACHMENT_LOAD_OP_CLEAR means the contents within the render
area will be cleared to a uniform value, which is specified when a render
pass instance is begun.
** ename:VK_ATTACHMENT_LOAD_OP_DONT_CARE means the contents within the area
need not be preserved; the contents of the attachment will be undefined
inside the render area.
* pname:storeOp specifies how the contents of color and depth components
of the attachment are treated at the end of the subpass where it is last
used:
+
--
// refBegin VkAttachmentStoreOp - specify how contents of an attachment are treated at the end of a subpass
include::../enums/VkAttachmentStoreOp.txt[]
** ename:VK_ATTACHMENT_STORE_OP_STORE means the contents within the render
area are written to memory and will be available for reading after the
render pass instance completes once the writes have been synchronized
with ename:VK_ACCESS_COLOR_ATTACHMENT_WRITE_BIT (for color attachments)
or ename:VK_ACCESS_DEPTH_STENCIL_ATTACHMENT_WRITE_BIT (for depth/stencil
attachments).
** ename:VK_ATTACHMENT_STORE_OP_DONT_CARE means the contents within the
render area are not needed after rendering, and may: be discarded; the
contents of the attachment will be undefined inside the render area.
--
** ename:VK_ATTACHMENT_STORE_OP_STORE means the contents within the render
area are written to memory and will be available for reading after the
render pass instance completes once the writes have been synchronized
with ename:VK_ACCESS_COLOR_ATTACHMENT_WRITE_BIT (for color attachments)
or ename:VK_ACCESS_DEPTH_STENCIL_ATTACHMENT_WRITE_BIT (for depth/stencil
attachments).
** ename:VK_ATTACHMENT_STORE_OP_DONT_CARE means the contents within the
render area are not needed after rendering, and may: be discarded; the
contents of the attachment will be undefined inside the render area.
* pname:stencilLoadOp specifies how the contents of stencil components of
the attachment are treated at the beginning of the subpass where it
is first used, and must: be one of the same values allowed for
@ -182,12 +196,13 @@ include::../enums/VkAttachmentStoreOp.txt[]
transitioned to when a render pass instance ends. During a render pass
instance, an attachment can: use a different layout in each subpass, if
desired.
* pname:flags is a bitfield of elink:VkAttachmentDescriptionFlagBits
describing additional properties of the attachment:
* pname:flags is a bitmask describing additional properties of the
attachment. Bits which can: be set include:
+
--
// refBegin VkAttachmentDescriptionFlagBits - Bitmask specifying additional properties of an attachment
include::../enums/VkAttachmentDescriptionFlagBits.txt[]
include::../validity/structs/VkAttachmentDescription.txt[]
--
If the attachment uses a color format, then pname:loadOp and pname:storeOp
are used, and pname:stencilLoadOp and pname:stencilStoreOp are ignored. If
@ -219,6 +234,17 @@ and the pname:loadOp) such that it is not improperly reordered against
other uses of the same physical memory via a different attachment. This is
described in more detail below.
include::../validity/structs/VkAttachmentDescription.txt[]
ifdef::editing-notes[]
[NOTE]
.editing-note
====
TODO (Jon) - the following text may need to be moved back to combine with
flink:vkCreateRenderPass above for automatic ref page generation.
====
endif::editing-notes[]
If a render pass uses multiple attachments that alias the same device
memory, those attachments must: each include the
ename:VK_ATTACHMENT_DESCRIPTION_MAY_ALIAS_BIT bit in their attachment
@ -271,6 +297,8 @@ until a framebuffer is created using the render pass, so the above
conditions cannot: be validated at render pass creation time.
====
// refBegin VkSubpassDescription - Structure specifying a subpass description
The sname:VkSubpassDescription structure is defined as:
include::../structs/VkSubpassDescription.txt[]
@ -337,6 +365,8 @@ those subpasses use or preserve the attachment.
include::../validity/structs/VkSubpassDescription.txt[]
// refBegin VkAttachmentReference - Structure specifying an attachment reference
The sname:VkAttachmentReference structure is defined as:
include::../structs/VkAttachmentReference.txt[]
@ -353,6 +383,8 @@ include::../structs/VkAttachmentReference.txt[]
include::../validity/structs/VkAttachmentReference.txt[]
// refBegin VkSubpassDependency - Structure specifying a subpass dependency
The sname:VkSubpassDependency structure is defined as:
include::../structs/VkSubpassDependency.txt[]
@ -372,12 +404,14 @@ include::../structs/VkSubpassDependency.txt[]
dependency>> between subpasses. The bits that can: be included in
pname:dependencyFlags are:
+
--
// refBegin VkDependencyFlagBits - Bitmask specifying dependencies between subpasses
include::../enums/VkDependencyFlagBits.txt[]
** If pname:dependencyFlags contains ename:VK_DEPENDENCY_BY_REGION_BIT,
then the dependency is by-region as defined in
<<synchronization-execution-and-memory-dependencies,Execution And Memory
Dependencies>>.
--
** If pname:dependencyFlags contains ename:VK_DEPENDENCY_BY_REGION_BIT,
then the dependency is by-region as defined in
<<synchronization-execution-and-memory-dependencies,Execution And Memory
Dependencies>>.
Each subpass dependency defines an execution and memory dependency
between two sets of commands, with the second set depending on the first
@ -588,6 +622,8 @@ ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL layout. Since an
attachment in the ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL
layout is read-only, this situation is not a feedback loop.
// refBegin vkDestroyRenderPass Destroy a render pass object
To destroy a render pass, call:
include::../protos/vkDestroyRenderPass.txt[]
@ -633,10 +669,20 @@ same render pass or a compatible render pass.
== Framebuffers
Render passes operate in conjunction with framebuffers, which represent a
// refBegin VkFramebuffer - Opaque handle to a framebuffer object
Render passes operate in conjunction with _framebuffers_. Framebuffers represent a
collection of specific memory attachments that a render pass instance uses.
An application creates a framebuffer by calling:
Framebuffers are represented by sname:VkFramebuffer handles:
include::../handles/VkFramebuffer.txt[]
// refEnd VkFramebuffer
// refBegin vkCreateFramebuffer Create a new framebuffer object.
To create a framebuffer, call:
include::../protos/vkCreateFramebuffer.txt[]
@ -650,6 +696,8 @@ include::../protos/vkCreateFramebuffer.txt[]
include::../validity/protos/vkCreateFramebuffer.txt[]
// refBegin VkFramebufferCreateInfo - Structure specifying parameters of a newly created framebuffer
The sname:VkFramebufferCreateInfo structure is defined as:
include::../structs/VkFramebufferCreateInfo.txt[]
@ -667,8 +715,6 @@ include::../structs/VkFramebufferCreateInfo.txt[]
* pname:width, pname:height and pname:layers define the dimensions of the
framebuffer.
include::../validity/structs/VkFramebufferCreateInfo.txt[]
Image subresources used as attachments mustnot: be used via any
non-attachment usage for the duration of a render pass instance.
@ -694,6 +740,10 @@ code:VK_FALSE, then all pipelines to be bound with a given zero-attachment
subpass must: have the same value for
slink:VkPipelineMultisampleStateCreateInfo::pname:rasterizationSamples.
include::../validity/structs/VkFramebufferCreateInfo.txt[]
// refBegin vkDestroyFramebuffer Destroy a framebuffer object
To destroy a framebuffer, call:
include::../protos/vkDestroyFramebuffer.txt[]
@ -714,6 +764,8 @@ at a time, by beginning a render pass instance, iterating over the subpasses
to record commands for that subpass, and then ending the render pass
instance.
// refBegin vkCmdBeginRenderPass Begin a new render pass.
To begin a render pass instance, call:
include::../protos/vkCmdBeginRenderPass.txt[]
@ -727,8 +779,10 @@ include::../protos/vkCmdBeginRenderPass.txt[]
provided, and is one of the values:
+
--
// refBegin VkSubpassContents - specify how commands in the first subpass of a render pass are provided
include::../enums/VkSubpassContents.txt[]
--
+
If pname:contents is ename:VK_SUBPASS_CONTENTS_INLINE, the contents of the
subpass will be recorded inline in the primary command buffer, and secondary
command buffers mustnot: be executed within the subpass. If pname:contents
@ -736,13 +790,14 @@ is ename:VK_SUBPASS_CONTENTS_SECONDARY_COMMAND_BUFFERS, the contents are
recorded in secondary command buffers that will be called from the primary
command buffer, and fname:vkCmdExecuteCommands is the only valid command on
the command buffer until fname:vkCmdNextSubpass or fname:vkCmdEndRenderPass.
--
include::../validity/protos/vkCmdBeginRenderPass.txt[]
After beginning a render pass instance, the command buffer is ready to
record the commands for the first subpass of that render pass.
include::../validity/protos/vkCmdBeginRenderPass.txt[]
// refBegin VkRenderPassBeginInfo - Structure specifying render pass begin info
The sname:VkRenderPassBeginInfo structure is defined as:
include::../structs/VkRenderPassBeginInfo.txt[]
@ -761,8 +816,6 @@ include::../structs/VkRenderPassBeginInfo.txt[]
indexed by attachment number. Only elements corresponding to cleared
attachments are used. Other elements of pname:pClearValues are ignored.
include::../validity/structs/VkRenderPassBeginInfo.txt[]
pname:renderArea is the render area that is affected by the render pass
instance. The effects of attachment load, store and resolve operations are
restricted to the pixels whose x and y coordinates fall within the render
@ -781,7 +834,11 @@ framebuffer, unless it matches the render area granularity for the render
pass.
====
The render area granularity is queried by calling:
include::../validity/structs/VkRenderPassBeginInfo.txt[]
// refBegin vkGetRenderAreaGranularity Returns the granularity for optimal render area.
To query the render area granularity, call:
include::../protos/vkGetRenderAreaGranularity.txt[]
@ -790,8 +847,6 @@ include::../protos/vkGetRenderAreaGranularity.txt[]
* pname:pGranularity points to a slink:VkExtent2D structure in which the
granularity is returned.
include::../validity/protos/vkGetRenderAreaGranularity.txt[]
The conditions leading to an optimal pname:renderArea are:
* the pname:offset.x member in pname:renderArea is a multiple of the
@ -813,8 +868,12 @@ Subpass dependencies are not affected by the render area, and apply to the
entire image subresources attached to the framebuffer. Similarly, pipeline
barriers are valid even if their effect extends outside the render area.
After recording the commands for a subpass, an application transitions to
the next subpass in the render pass instance by calling:
include::../validity/protos/vkGetRenderAreaGranularity.txt[]
// refBegin vkCmdNextSubpass Transition to the next subpass of a render pass.
To transition to the next subpass in the render pass instance after
recording the commands for a subpass, call:
include::../protos/vkCmdNextSubpass.txt[]
@ -824,8 +883,6 @@ include::../protos/vkCmdNextSubpass.txt[]
provided, in the same fashion as the corresponding parameter of
flink:vkCmdBeginRenderPass.
include::../validity/protos/vkCmdNextSubpass.txt[]
The subpass index for a render pass begins at zero when
fname:vkCmdBeginRenderPass is recorded, and increments each time
fname:vkCmdNextSubpass is recorded.
@ -845,15 +902,20 @@ needed.
After transitioning to the next subpass, the application can: record the
commands for that subpass.
After recording the commands for the last subpass, an application records a
command to end a render pass instance by calling:
include::../validity/protos/vkCmdNextSubpass.txt[]
// refBegin vkCmdEndRenderPass End the current render pass.
To record a command to end a render pass instance after recording the
commands for the last subpass, call:
include::../protos/vkCmdEndRenderPass.txt[]
* pname:commandBuffer is the command buffer in which to end the current
render pass instance.
include::../validity/protos/vkCmdEndRenderPass.txt[]
Ending a render pass instance performs any multisample resolve operations on
the final subpass.
include::../validity/protos/vkCmdEndRenderPass.txt[]

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

@ -14,12 +14,22 @@ metadata.
[[resources-buffers]]
== Buffers
// refBegin VkBuffer - Opaque handle to a buffer object
Buffers represent linear arrays of data which are used for various
purposes by binding them to a graphics or compute pipeline via descriptor
sets or via certain commands, or by directly specifying them as parameters
to certain commands.
Buffers are created by calling:
Buffers are represented by sname:VkBuffer handles:
include::../handles/VkBuffer.txt[]
// refEnd VkBuffer
// refBegin vkCreateBuffer Create a new buffer object.
To create buffers, call:
include::../protos/vkCreateBuffer.txt[]
@ -34,17 +44,19 @@ include::../protos/vkCreateBuffer.txt[]
include::../validity/protos/vkCreateBuffer.txt[]
// refBegin VkBufferCreateInfo Structure specifying the parameters of a newly created buffer object.
The sname:VkBufferCreateInfo structure is defined as:
include::../structs/VkBufferCreateInfo.txt[]
* pname:sType is the type of this structure.
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
* pname:flags is a bitfield describing additional parameters of the
* pname:flags is a bitmask describing additional parameters of the
buffer. See elink:VkBufferCreateFlagBits below for a description of the
supported bits.
* pname:size is the size in bytes of the buffer to be created.
* pname:usage is a bitfield describing the allowed usages of the buffer.
* pname:usage is a bitmask describing the allowed usages of the buffer.
See elink:VkBufferUsageFlagBits below for a description of the supported
bits.
* pname:sharingMode is the sharing mode of the buffer when it will be
@ -57,10 +69,9 @@ include::../structs/VkBufferCreateInfo.txt[]
access this buffer (ignored if pname:sharingMode is not
ename:VK_SHARING_MODE_CONCURRENT).
include::../validity/structs/VkBufferCreateInfo.txt[]
Bits which may: be set in pname:usage are:
Bits which can: be set in pname:usage are:
// refBegin VkBufferUsageFlagBits - Bitmask specifying allowed usage of a buffer
include::../enums/VkBufferUsageFlagBits.txt[]
* ename:VK_BUFFER_USAGE_TRANSFER_SRC_BIT indicates that the buffer can: be
@ -100,11 +111,12 @@ include::../enums/VkBufferUsageFlagBits.txt[]
Any combination of bits can: be specified for pname:usage, but at least one
of the bits must: be set in order to create a valid buffer.
Bits which may: be set in pname:flags are:
Bits which can: be set in pname:flags are:
// refBegin VkBufferCreateFlagBits - Bitmask specifying additional parameters of a buffer
include::../enums/VkBufferCreateFlagBits.txt[]
These bitfields have the following meanings:
These bits have the following meanings:
* ename:VK_BUFFER_CREATE_SPARSE_BINDING_BIT indicates that the buffer will
be backed using sparse memory binding.
@ -122,6 +134,10 @@ See <<sparsememory-sparseresourcefeatures,Sparse Resource Features>> and
<<features-features,Physical Device Features>> for details of the sparse
memory features supported on a device.
include::../validity/structs/VkBufferCreateInfo.txt[]
// refBegin vkDestroyBuffer Destroy a buffer object
To destroy a buffer, call:
include::../protos/vkDestroyBuffer.txt[]
@ -137,6 +153,8 @@ include::../validity/protos/vkDestroyBuffer.txt[]
[[resources-buffer-views]]
== Buffer Views
// refBegin VkBufferView - Opaque handle to a buffer view object
A _buffer view_ represents a contiguous range of a buffer and a specific
format to be used to interpret the data. Buffer views are used to enable
shaders to access buffer contents interpreted as formatted data. In order to
@ -146,7 +164,15 @@ one of the following usage flags:
* ename:VK_BUFFER_USAGE_UNIFORM_TEXEL_BUFFER_BIT
* ename:VK_BUFFER_USAGE_STORAGE_TEXEL_BUFFER_BIT
A buffer view is created by calling:
Buffer views are represented by sname:VkBufferView handles:
include::../handles/VkBufferView.txt[]
// refEnd VkBufferView
// refBegin vkCreateBufferView Create a new buffer view object.
To create a buffer view, call:
include::../protos/vkCreateBufferView.txt[]
@ -161,6 +187,8 @@ include::../protos/vkCreateBufferView.txt[]
include::../validity/protos/vkCreateBufferView.txt[]
// refBegin VkBufferViewCreateInfo - Structure specifying parameters of a newly created buffer view
The sname:VkBufferViewCreateInfo structure is defined as:
include::../structs/VkBufferViewCreateInfo.txt[]
@ -182,6 +210,8 @@ include::../structs/VkBufferViewCreateInfo.txt[]
include::../validity/structs/VkBufferViewCreateInfo.txt[]
// refBegin vkDestroyBufferView Destroy a buffer view object
To destroy a buffer view, call:
include::../protos/vkDestroyBufferView.txt[]
@ -197,12 +227,22 @@ include::../validity/protos/vkDestroyBufferView.txt[]
[[resources-images]]
== Images
// refBegin VkImage - Opaque handle to a image object
Images represent multidimensional - up to 3 - arrays of data which can: be
used for various purposes (e.g. attachments, textures), by binding them to a
graphics or compute pipeline via descriptor sets, or by directly specifying
them as parameters to certain commands.
Images are created by calling:
Images are represented by sname:VkImage handles:
include::../handles/VkImage.txt[]
// refEnd VkImage
// refBegin vkCreateImage Create a new image object.
To create images, call:
include::../protos/vkCreateImage.txt[]
@ -217,25 +257,20 @@ include::../protos/vkCreateImage.txt[]
include::../validity/protos/vkCreateImage.txt[]
// refBegin VkImageCreateInfo Structure specifying the parameters of a newly created image object.
The sname:VkImageCreateInfo structure is defined as:
include::../structs/VkImageCreateInfo.txt[]
* pname:sType is the type of this structure.
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
* pname:flags is a bitfield describing additional parameters of the image.
* pname:flags is a bitmask describing additional parameters of the image.
See elink:VkImageCreateFlagBits below for a description of the supported
bits.
* pname:imageType is the basic dimensionality of the image, and must: be
one of the values
+
--
include::../enums/VkImageType.txt[]
specifying one-, two-, or three-dimensionality, respectively. Layers in
array textures do not count as a dimension for the purposes of the image
type.
--
* pname:imageType is a elink:VkImageType specifying the basic
dimensionality of the image, as described below. Layers in array
textures do not count as a dimension for the purposes of the image type.
* pname:format is a elink:VkFormat describing the format and type of the
data elements that will be contained in the image.
* pname:extent is a slink:VkExtent3D describing the number of data
@ -246,18 +281,9 @@ type.
* pname:samples is the number of sub-data element samples in the image as
defined in elink:VkSampleCountFlagBits. See
<<primsrast-multisampling,Multisampling>>.
* pname:tiling is the tiling arrangement of the data elements in
memory, and must: have one of the values:
+
--
include::../enums/VkImageTiling.txt[]
ename:VK_IMAGE_TILING_OPTIMAL specifies optimal tiling (texels are laid out
in an implementation-dependent arrangement, for more optimal memory access),
and ename:VK_IMAGE_TILING_LINEAR specifies linear tiling (texels are laid
out in memory in row-major order, possibly with some padding on each row).
--
* pname:usage is a bitfield describing the intended usage of the image.
* pname:tiling is a elink:VkImageTiling specifying the tiling arrangement
of the data elements in memory, as described below.
* pname:usage is a bitmask describing the intended usage of the image.
See elink:VkImageUsageFlagBits below for a description of the supported
bits.
* pname:sharingMode is the sharing mode of the image when it will be
@ -274,8 +300,6 @@ out in memory in row-major order, possibly with some padding on each row).
Layouts>>. pname:initialLayout must: be ename:VK_IMAGE_LAYOUT_UNDEFINED
or ename:VK_IMAGE_LAYOUT_PREINITIALIZED.
include::../validity/structs/VkImageCreateInfo.txt[]
Valid limits for the image pname:extent, pname:mipLevels, pname:arrayLayers
and pname:samples members are queried with the
flink:vkGetPhysicalDeviceImageFormatProperties command.
@ -301,11 +325,16 @@ flink:vkGetPhysicalDeviceFormatProperties and the valid limits for
pname:mipLevels and pname:arrayLayers by calling
flink:vkGetPhysicalDeviceImageFormatProperties.
Bits which may: be set in pname:usage are:
include::../validity/structs/VkImageCreateInfo.txt[]
// refBegin VkImageUsageFlagBits - Bitmask specifying intended usage of an image
The intended usage of an image is specified by the bitmask
slink:VkImageCreateInfo::pname:usage. Bits which can: be set include:
include::../enums/VkImageUsageFlagBits.txt[]
These bitfields have the following meanings:
These bits have the following meanings:
* ename:VK_IMAGE_USAGE_TRANSFER_SRC_BIT indicates that the image can: be
used as the source of a transfer command.
@ -340,11 +369,16 @@ These bitfields have the following meanings:
ename:VK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT; be read from a shader as an
input attachment; and be used as an input attachment in a framebuffer.
Bits which may: be set in pname:flags are:
// refEnd VkImageUsageFlagBits
// refBegin VkImageCreateFlagBits - Bitmask specifying additional parameters of an image
Additional parameters of an image are specified by
slink:VkImageCreateInfo::pname:flags. Bits which can: be set include:
include::../enums/VkImageCreateFlagBits.txt[]
These bitfields have the following meanings:
These bits have the following meanings:
* ename:VK_IMAGE_CREATE_SPARSE_BINDING_BIT indicates that the image will
be backed using sparse memory binding.
@ -357,14 +391,6 @@ These bitfields have the following meanings:
simultaneously be backing another image (or another portion of the same
image). Images created with this flag must: also be created with the
ename:VK_IMAGE_CREATE_SPARSE_BINDING_BIT flag
If any of these three bits are set,
ename:VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT mustnot: also be set.
See <<sparsememory-sparseresourcefeatures,Sparse Resource Features>> and
<<sparsememory-physicalfeatures,Sparse Physical Device Features>> for
more details.
* ename:VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT indicates that the image can:
be used to create a sname:VkImageView with a different format from the
image.
@ -372,6 +398,44 @@ more details.
be used to create a sname:VkImageView of type
ename:VK_IMAGE_VIEW_TYPE_CUBE or ename:VK_IMAGE_VIEW_TYPE_CUBE_ARRAY.
If any of the bits ename:VK_IMAGE_CREATE_SPARSE_BINDING_BIT,
ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT, or
ename:VK_IMAGE_CREATE_SPARSE_ALIASED_BIT are set,
ename:VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT mustnot: also be set.
See <<sparsememory-sparseresourcefeatures,Sparse Resource Features>> and
<<sparsememory-physicalfeatures,Sparse Physical Device Features>> for
more details.
// refEnd VkImageCreateFlagBits
// refBegin VkImageType Specifies the type of an image object.
The basic dimensionality of an image is specified by
slink:VkImageCreateInfo::pname:imageType, which must: be one of the values
include::../enums/VkImageType.txt[]
These values specify one-, two-, or three-dimensional images, respectively.
// refEnd VkImageType
// refBegin VkImageTiling specifies the tiling arrangement of data in an image
The tiling arrangement of data elements in an image is specified by
slink:VkImageCreateInfo::pname:tiling, which must: be one of the values
include::../enums/VkImageTiling.txt[]
ename:VK_IMAGE_TILING_OPTIMAL specifies optimal tiling (texels are laid out
in an implementation-dependent arrangement, for more optimal memory access),
and ename:VK_IMAGE_TILING_LINEAR specifies linear tiling (texels are laid
out in memory in row-major order, possibly with some padding on each row).
// refEnd VkImageTiling
// refBegin vkGetImageSubresourceLayout Retrieve information about an image subresource.
To query the host access layout of an image subresource, for an image
created with linear tiling, call:
@ -384,22 +448,26 @@ include::../protos/vkGetImageSubresourceLayout.txt[]
* pname:pLayout points to a slink:VkSubresourceLayout structure in which
the layout is returned.
include::../validity/protos/vkGetImageSubresourceLayout.txt[]
flink:vkGetImageSubresourceLayout is invariant for the lifetime of a single
image.
include::../validity/protos/vkGetImageSubresourceLayout.txt[]
// refBegin VkImageSubresource - Structure specifying a image subresource
The sname:VkImageSubresource structure is defined as:
include::../structs/VkImageSubresource.txt[]
* pname:aspectMask is a ename:VkImageAspectFlags selecting the image
* pname:aspectMask is a elink:VkImageAspectFlags selecting the image
_aspect_.
* pname:mipLevel selects the mipmap level.
* pname:arrayLayer selects the array layer.
include::../validity/structs/VkImageSubresource.txt[]
// refBegin VkSubresourceLayout - Structure specifying subresource layout
Information about the layout of the image subresource is returned in a
sname:VkSubresourceLayout structure:
@ -416,8 +484,6 @@ include::../structs/VkSubresourceLayout.txt[]
* pname:depthPitch describes the number of bytes between each slice of 3D
image.
include::../validity/structs/VkSubresourceLayout.txt[]
For images created with linear tiling, pname:rowPitch, pname:arrayPitch and
pname:depthPitch describe the layout of the image subresource in linear
memory. For uncompressed formats, pname:rowPitch is the number of bytes
@ -460,6 +526,10 @@ of memory used for that aspect. On implementations that store depth and
stencil aspects interleaved, the same pname:offset and pname:size are
returned and represent the interleaved memory allocation.
include::../validity/structs/VkSubresourceLayout.txt[]
// refBegin vkDestroyImage Destroy an image object
To destroy an image, call:
include::../protos/vkDestroyImage.txt[]
@ -527,6 +597,8 @@ layout. Calling flink:vkGetImageSubresourceLayout for a linear image returns
a subresource layout mapping that is valid for either of those image
layouts.
// refBegin VkImageLayout - Layout of image and image subresources
The set of image layouts consists of:
include::../enums/VkImageLayout.txt[]
@ -600,16 +672,28 @@ that the contents of the image subresource need not be preserved). The new
layout used in a transition mustnot: be ename:VK_IMAGE_LAYOUT_UNDEFINED or
ename:VK_IMAGE_LAYOUT_PREINITIALIZED.
// refEnd VkImageLayout
[[resources-image-views]]
== Image Views
// refBegin VkImageView - Opaque handle to a image view object
Image objects are not directly accessed by pipeline shaders for reading or
writing image data. Instead, _image views_ representing contiguous ranges of
the image subresources and containing additional metadata are used for that
purpose. Views must: be created on images of compatible types, and must:
represent a valid subset of image subresources.
Image views are represented by sname:VkImageView handles:
include::../handles/VkImageView.txt[]
// refEnd VkImageView
// refBegin VkImageViewType - Image view types
The types of image views that can: be created are:
include::../enums/VkImageViewType.txt[]
@ -620,6 +704,10 @@ the <<resources-image-views-compatibility,table below>>. This table also
shows which SPIR-V OpTypeImage Dim and Arrayed parameters correspond to each
image view type.
// refEnd VkImageViewType
// refBegin vkCreateImageView Create an image view from an existing image.
To create an image view, call:
include::../protos/vkCreateImageView.txt[]
@ -638,6 +726,8 @@ remaining parameters are contained in the pname:pCreateInfo.
include::../validity/protos/vkCreateImageView.txt[]
// refBegin VkImageViewCreateInfo - Structure specifying parameters of a newly created image view
The sname:VkImageViewCreateInfo structure is defined as:
include::../structs/VkImageViewCreateInfo.txt[]
@ -655,8 +745,6 @@ include::../structs/VkImageViewCreateInfo.txt[]
* pname:subresourceRange selects the set of mipmap levels and array layers
to be accessible to the view.
include::../validity/structs/VkImageViewCreateInfo.txt[]
If pname:image was created with the ename:VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT
flag, pname:format can: be different from the image's format, but if they
are not equal they must: be _compatible_. Image format compatibility is
@ -762,7 +850,11 @@ baseArrayLayer = 0 +
arrayLayers = 1
|========================================
The pname:subresourceRange member is of type sname:VkImageSubresourceRange.
The pname:subresourceRange member is of type slink:VkImageSubresourceRange.
include::../validity/structs/VkImageViewCreateInfo.txt[]
// refBegin VkImageSubresourceRange - Structure specifying a image subresource range
The sname:VkImageSubresourceRange structure is defined as:
@ -777,8 +869,6 @@ include::../structs/VkImageSubresourceRange.txt[]
* pname:layerCount is the number of array layers (starting from
pname:baseArrayLayer) accessible to the view.
include::../validity/structs/VkImageSubresourceRange.txt[]
The number of mip-map levels and array layers must: be a subset of the
image subresources in the image. If an application wants to use all
mip-levels or layers in an image after the pname:baseMipLevel or
@ -799,6 +889,7 @@ multiple of 6, behavior when indexing the last cube is undefined.
pname:aspectMask is a bitmask indicating the format being used. Bits which
may: be set include:
// refBegin VkImageAspectFlagBits - Bitmask specifying which aspects of an image are included in a view
include::../enums/VkImageAspectFlagBits.txt[]
The mask must: be only ename:VK_IMAGE_ASPECT_COLOR_BIT,
@ -819,19 +910,32 @@ depth/stencil image is used as a depth/stencil framebuffer attachment, the
pname:aspectMask is ignored and both depth and stencil image subresources
are used.
The pname:components member is of type sname:VkComponentMapping.
The pname:components member is of type slink:VkComponentMapping, and
describes a remapping from components of the image to components of the
vector returned by shader image instructions. This remapping must: be
identity for storage image descriptors, input attachment descriptors, and
framebuffer attachments.
include::../validity/structs/VkImageSubresourceRange.txt[]
// refBegin VkComponentMapping - Structure specifying a color component mapping
The sname:VkComponentMapping structure is defined as:
include::../structs/VkComponentMapping.txt[]
and describes a remapping from components of the image to components of the
vector returned by shader image instructions. This remapping must: be
identity for storage image descriptors, input attachment descriptors, and
framebuffer attachments. The pname:r, pname:g, pname:b, and pname:a members
of pname:components are the values placed in the corresponding components of
the output vector:
* pname:r determines the component value placed in the R component of the
output vector.
* pname:g determines the component value placed in the G component of the
output vector.
* pname:b determines the component value placed in the B component of the
output vector.
* pname:a determines the component value placed in the A component of the
output vector.
Each of pname:r, pname:g, pname:b, and pname:a is one of the values:
// refBegin VkComponentSwizzle - specify how a component is swizzled
include::../enums/VkComponentSwizzle.txt[]
* ename:VK_COMPONENT_SWIZZLE_IDENTITY: the component is set to the
@ -851,12 +955,9 @@ include::../enums/VkComponentSwizzle.txt[]
* ename:VK_COMPONENT_SWIZZLE_A: the component is set to the value
of the A component of the image.
include::../validity/structs/VkComponentMapping.txt[]
Setting the identity swizzle on a component is equivalent to setting the
identity mapping on that component. That is:
[[resources-image-views-identity-mappings]]
.Component Mappings Equivalent To ename:VK_COMPONENT_SWIZZLE_IDENTITY
[options="header"]
@ -868,6 +969,10 @@ identity mapping on that component. That is:
| pname:components.a | ename:VK_COMPONENT_SWIZZLE_A
|====
include::../validity/structs/VkComponentMapping.txt[]
// refBegin vkDestroyImageView Destroy an image view object
To destroy an image view, call:
include::../protos/vkDestroyImageView.txt[]
@ -904,6 +1009,8 @@ any of the following operations:
Once bound, the memory binding is immutable for the lifetime of the
resource.
// refBegin vkGetBufferMemoryRequirements Returns the memory requirements for specified Vulkan object.
To determine the memory requirements for a buffer resource, call:
include::../protos/vkGetBufferMemoryRequirements.txt[]
@ -916,6 +1023,8 @@ include::../protos/vkGetBufferMemoryRequirements.txt[]
include::../validity/protos/vkGetBufferMemoryRequirements.txt[]
// refBegin vkGetImageMemoryRequirements Returns the memory requirements for specified Vulkan object.
To determine the memory requirements for an image resource, call:
include::../protos/vkGetImageMemoryRequirements.txt[]
@ -928,6 +1037,8 @@ include::../protos/vkGetImageMemoryRequirements.txt[]
include::../validity/protos/vkGetImageMemoryRequirements.txt[]
// refBegin VkMemoryRequirements - Structure specifying memory requirements
The sname:VkMemoryRequirements structure is defined as:
include::../structs/VkMemoryRequirements.txt[]
@ -936,7 +1047,7 @@ include::../structs/VkMemoryRequirements.txt[]
the resource.
* pname:alignment is the alignment, in bytes, of the offset within the
allocation required: for the resource.
* pname:memoryTypeBits is a bitfield and contains one bit set for every
* pname:memoryTypeBits is a bitmask and contains one bit set for every
supported memory type for the resource. Bit `i` is set if and only if
the memory type `i` in the sname:VkPhysicalDeviceMemoryProperties
structure for the physical device is supported for the resource.
@ -964,7 +1075,7 @@ flink:vkGetImageMemoryRequirements:
objects created with the same value for the pname:flags and pname:usage
members in the sname:VkBufferCreateInfo structure passed to
fname:vkCreateBuffer. Further, if code:usage1 and code:usage2 of type
ename:VkBufferUsageFlags are such that the bits set in code:usage2 are a
elink:VkBufferUsageFlags are such that the bits set in code:usage2 are a
subset of the bits set in code:usage1, and they have the same
pname:flags, then the bits set in pname:memoryTypeBits returned for
code:usage1 must: be a subset of the bits set in pname:memoryTypeBits
@ -1001,6 +1112,8 @@ disallowed for buffers in all cases.
====
--
// refBegin vkBindBufferMemory Bind device memory to a buffer object
To attach memory to a buffer object, call:
include::../protos/vkBindBufferMemory.txt[]
@ -1016,6 +1129,8 @@ include::../protos/vkBindBufferMemory.txt[]
include::../validity/protos/vkBindBufferMemory.txt[]
// refBegin vkBindImageMemory Bind device memory to an image object
To attach memory to an image object, call:
include::../protos/vkBindImageMemory.txt[]
@ -1091,6 +1206,8 @@ pname:bufferImageGranularity.
[[resources-sharing]]
== Resource Sharing Mode
// refBegin VkSharingMode - Buffer and image sharing modes
Buffer and image objects are created with a _sharing mode_ controlling how
they can: be accessed from queues. The supported sharing modes are:
@ -1155,6 +1272,8 @@ way as for a resource that was just created, however doing so means any
contents written by other queue families or via incompatible aliases are
undefined.
// refEnd VkSharingMode
[[resources-memory-aliasing]]
== Memory Aliasing

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

@ -4,10 +4,20 @@
[[samplers]]
= Samplers
sname:VkSampler objects encapsulate the state of an image sampler which is
// refBegin VkSampler - Opaque handle to a sampler object
sname:VkSampler objects represent the state of an image sampler which is
used by the implementation to read image data and apply filtering and other
transformations for the shader.
Samplers are represented by sname:VkSampler handles:
include::../handles/VkSampler.txt[]
// refEnd VkSampler
// refBegin vkCreateSampler Create a new sampler object
To create a sampler object, call:
include::../protos/vkCreateSampler.txt[]
@ -23,6 +33,8 @@ include::../protos/vkCreateSampler.txt[]
include::../validity/protos/vkCreateSampler.txt[]
// refBegin VkSamplerCreateInfo - Structure specifying parameters of a newly created sampler
The sname:VkSamplerCreateInfo structure is defined as:
include::../structs/VkSamplerCreateInfo.txt[]
@ -34,6 +46,7 @@ include::../structs/VkSamplerCreateInfo.txt[]
is of type:
+
--
// refBegin VkFilter - specify filters used for texture lookups
include::../enums/VkFilter.txt[]
--
+
@ -44,6 +57,7 @@ include::../enums/VkFilter.txt[]
type:
+
--
// refBegin VkSamplerMipmapMode - specify mipmap mode used for texture lookups
include::../enums/VkSamplerMipmapMode.txt[]
--
+
@ -78,6 +92,7 @@ include::../enums/VkSamplerMipmapMode.txt[]
section, and is of type:
+
--
// refBegin VkBorderColor - specify border color used for texture lookups
include::../enums/VkBorderColor.txt[]
--
+
@ -135,15 +150,14 @@ while still always rounding down to the base level. If the pname:minFilter
and pname:magFilter are equal, then using a pname:maxLod of zero also works.
==================
include::../validity/structs/VkSamplerCreateInfo.txt[]
pname:addressModeU, pname:addressModeV, and pname:addressModeW must: each
have one of the following values:
// refBegin VkSamplerAddressMode - specify behavior of sampling with texture coordinates outside an image
include::../enums/VkSamplerAddressMode.txt[]
These values control the behavior of sampling with coordinates outside the
range [0,1] for the respective u, v, or w coordinate as defined in the
range latexmath:[$[0,1\]$] for the respective u, v, or w coordinate as defined in the
<<textures-wrapping-operation, Wrapping Operation>> section.
* ename:VK_SAMPLER_ADDRESS_MODE_REPEAT indicates that the repeat wrap mode
@ -170,6 +184,10 @@ may: return the same handle for sampler state vectors that are identical. In
such cases, all such objects would only count once against the
pname:maxSamplerAllocationCount limit.
include::../validity/structs/VkSamplerCreateInfo.txt[]
// refBegin vkDestroySampler Destroy a sampler object
To destroy a sampler, call:
include::../protos/vkDestroySampler.txt[]

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

@ -36,6 +36,8 @@ decorations for each stage are documented in the following subsections.
[[shader-modules]]
== Shader Modules
// refBegin VkShaderModule - Opaque handle to a shader module object
_Shader modules_ contain _shader code_ and one or more entry points. Shaders
are selected from a shader module by specifying an entry point as part of
<<pipelines,pipeline>> creation. The stages of a pipeline can: use shaders
@ -43,7 +45,15 @@ that come from different modules. The shader code defining a shader module
must: be in the SPIR-V format, as described by the <<spirvenv,Vulkan
Environment for SPIR-V>> appendix.
A shader module is created by calling:
Shader modules are represented by sname:VkShaderModule handles:
include::../handles/VkShaderModule.txt[]
// refEnd VkShaderModule
// refBegin vkCreateShaderModule Creates a new shader module object.
To create a shader module, call:
include::../protos/vkCreateShaderModule.txt[]
@ -55,8 +65,14 @@ include::../protos/vkCreateShaderModule.txt[]
* pname:pShaderModule points to a sname:VkShaderModule handle in which the
resulting shader module object is returned.
Once a shader module has been created, any entry points it contains can: be
used in pipeline shader stages as described in <<pipelines-compute,Compute
Pipelines>> and <<pipelines-graphics,Graphics Pipelines>>.
include::../validity/protos/vkCreateShaderModule.txt[]
// refBegin VkShaderModuleCreateInfo - Structure specifying parameters of a newly created shader module
The sname:VkShaderModuleCreateInfo structure is defined as:
include::../structs/VkShaderModuleCreateInfo.txt[]
@ -72,9 +88,7 @@ include::../structs/VkShaderModuleCreateInfo.txt[]
include::../validity/structs/VkShaderModuleCreateInfo.txt[]
Once a shader module has been created, any entry points it contains can: be
used in pipeline shader stages as described in <<pipelines-compute,Compute
Pipelines>> and <<pipelines-graphics,Graphics Pipelines>>.
// refBegin vkDestroyShaderModule Destroy a shader module module
To destroy a shader module, call:

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

@ -621,12 +621,12 @@ endif::implementation-guide[]
The APIs related to sparse resources are grouped into the following
categories:
* <<sparsememory-physicalfeatures,Physical Device Features>>
* <<sparsememory-physicalprops,Physical Device Sparse Properties>>
* <<sparsememory-format-props,Sparse Image Format Properties>>
* <<sparsememory-resource-creation,Sparse Resource Creation>>
* <<sparsememory-memory-requirements,Sparse Resource Memory Requirements>>
* <<sparsememory-resource-binding,Binding Resource Memory>>
* <<sparsememory-physicalfeatures,Physical Device Features>>
* <<sparsememory-physicalprops,Physical Device Sparse Properties>>
* <<sparsememory-format-props,Sparse Image Format Properties>>
* <<sparsememory-resource-creation,Sparse Resource Creation>>
* <<sparsememory-memory-requirements,Sparse Resource Memory Requirements>>
* <<sparsememory-resource-binding,Binding Resource Memory>>
[[sparsememory-physicalfeatures]]
@ -673,6 +673,8 @@ accordingly. These read-only capabilites are reported in the
slink:VkPhysicalDeviceProperties::pname:sparseProperties member, which is a
structure of type sname:VkPhysicalDeviceSparseProperties.
// refBegin VkPhysicalDeviceSparseProperties - Structure specifying physical device sparse memory properties
The sname:VkPhysicalDeviceSparseProperties structure is defined as:
include::../structs/VkPhysicalDeviceSparseProperties.txt[]
@ -737,6 +739,10 @@ supported and what the sparse image block shape will be.
==== Sparse Image Format Properties API
// refBegin VkSparseImageFormatProperties - Structure specifying sparse image format properties
The sname:VkSparseImageFormatProperties structure is defined as:
include::../structs/VkSparseImageFormatProperties.txt[]
* pname:aspectMask is a bitmask of elink:VkImageAspectFlagBits specifying
@ -747,8 +753,9 @@ include::../structs/VkSparseImageFormatProperties.txt[]
sparse resource. Bits which can: be set include:
+
--
// refBegin VkSparseImageFormatFlagBits - Bitmask specifying additional information about a sparse image resource
include::../enums/VkSparseImageFormatFlagBits.txt[]
--
** If ename:VK_SPARSE_IMAGE_FORMAT_SINGLE_MIPTAIL_BIT is set, the image
uses a single mip tail region for all array layers.
** If ename:VK_SPARSE_IMAGE_FORMAT_ALIGNED_MIP_SIZE_BIT is set, the first
@ -758,12 +765,13 @@ include::../enums/VkSparseImageFormatFlagBits.txt[]
image uses non-standard sparse image block dimensions, and the
pname:imageGranularity values do not match the standard sparse image
block dimensions for the given pixel format.
--
include::../validity/structs/VkSparseImageFormatProperties.txt[]
// refBegin vkGetPhysicalDeviceSparseImageFormatProperties Retrieve properties of an image format applied to sparse images.
fname:vkGetPhysicalDeviceSparseImageFormatProperties returns an
array of sname:VkSparseImageFormatProperties. Each element will describe
array of slink:VkSparseImageFormatProperties. Each element will describe
properties for one set of image aspects that are bound simultaneously in the
image. This is usually one element for each aspect in the image, but for
interleaved depth/stencil images there is only one element describing the
@ -777,7 +785,7 @@ include::../protos/vkGetPhysicalDeviceSparseImageFormatProperties.txt[]
* pname:type is the dimensionality of image.
* pname:samples is the number of samples per pixel as defined in
elink:VkSampleCountFlagBits.
* pname:usage is a bitfield describing the intended usage of the image.
* pname:usage is a bitmask describing the intended usage of the image.
* pname:tiling is the tiling arrangement of the data elements in memory.
* pname:pPropertyCount is a pointer to an integer related to the number of
sparse format properties available or queried, as described below.
@ -793,8 +801,6 @@ pname:pProperties. If pname:pPropertyCount is less than the
number of sparse format properties available, at most pname:pPropertyCount
structures will be written.
include::../validity/protos/vkGetPhysicalDeviceSparseImageFormatProperties.txt[]
If ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT is not supported for the given
arguments, pname:pPropertyCount will be set to zero upon return, and no data
will be written to pname:pProperties.
@ -808,6 +814,8 @@ plane will return a single sname:VkSparseImageFormatProperties structure
with the pname:aspectMask set to ename:VK_IMAGE_ASPECT_DEPTH_BIT |
ename:VK_IMAGE_ASPECT_STENCIL_BIT.
include::../validity/protos/vkGetPhysicalDeviceSparseImageFormatProperties.txt[]
[[sparsememory-resource-creation]]
=== Sparse Resource Creation
@ -870,6 +878,10 @@ image memory requirements.
==== Sparse Image Memory Requirements
// refBegin VkSparseImageMemoryRequirements - Structure specifying sparse image memory requirements
The sname:VkSparseImageMemoryRequirements structure is defined as:
include::../structs/VkSparseImageMemoryRequirements.txt[]
* pname:formatProperties.aspectMask is the set of aspects of the image
@ -912,7 +924,9 @@ include::../structs/VkSparseImageMemoryRequirements.txt[]
include::../validity/structs/VkSparseImageMemoryRequirements.txt[]
Query sparse memory requirements for an image by calling:
// refBegin vkGetImageSparseMemoryRequirements Query the memory requirements for a sparse image.
To query sparse memory requirements for an image, call:
include::../protos/vkGetImageSparseMemoryRequirements.txt[]
@ -940,8 +954,6 @@ If the image was not created with ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT
then pname:pSparseMemoryRequirementCount will be set to zero and
pname:pSparseMemoryRequirements will not be written to.
include::../validity/protos/vkGetImageSparseMemoryRequirements.txt[]
[NOTE]
.Note
====
@ -953,6 +965,8 @@ hardware requires unused padding in the address range describing the
resource.
====
include::../validity/protos/vkGetImageSparseMemoryRequirements.txt[]
[[sparsememory-resource-binding]]
=== Binding Resource Memory
@ -1039,25 +1053,30 @@ structures.
[[sparsemem-memory-binding]]
==== Sparse Memory Binding Functions
include::../enums/VkSparseMemoryBindFlagBits.txt[]
include::../flags/VkSparseMemoryBindFlags.txt[]
// refBegin VkSparseMemoryBind - Structure specifying a sparse memory bind operation
* ename:VK_SPARSE_MEMORY_BIND_METADATA_BIT is used to indicate
that the memory being bound is only for the metadata aspect.
The sname:VkSparseMemoryBind structure is defined as:
include::../structs/VkSparseMemoryBind.txt[]
* pname:resourceOffset is the offset into the resource.
* pname:size is the size of the memory region to be bound.
* pname:memory is the sname:VkDeviceMemory object that the range of the
resource is bound to. If pname:memory is code:VK_NULL_HANDLE, the range
resource is bound to. If pname:memory is dlink:VK_NULL_HANDLE, the range
is unbound.
* pname:memoryOffset is the offset into the sname:VkDeviceMemory object to
bind the resource range to. If pname:memory is code:VK_NULL_HANDLE,
bind the resource range to. If pname:memory is dlink:VK_NULL_HANDLE,
this value is ignored.
* pname:flags are sparse memory binding flags.
include::../validity/structs/VkSparseMemoryBind.txt[]
* pname:flags is a bitmask specifying usage of the binding operation. Bits
which can: be set include:
+
--
// refBegin VkSparseMemoryBindFlagBits - Bitmask specifying usage of a sparse memory binding operation
include::../enums/VkSparseMemoryBindFlagBits.txt[]
--
+
** ename:VK_SPARSE_MEMORY_BIND_METADATA_BIT indicates that the memory
being bound is only for the metadata aspect.
The _binding range_ latexmath:[$[\mathit{resourceOffset},
\mathit{resourceOffset} + \mathit{size})$] has different constraints based
@ -1090,6 +1109,10 @@ If pname:flags does not contain ename:VK_SPARSE_MEMORY_BIND_METADATA_BIT,
the binding range must: be within the range
latexmath:[$[0, {\mathit{VkMemoryRequirements}::\mathit{size}})$].
include::../validity/structs/VkSparseMemoryBind.txt[]
// refBegin VkSparseBufferMemoryBindInfo - Structure specifying a sparse buffer memory bind operation
Memory is bound to sname:VkBuffer objects created with the
ename:VK_BUFFER_CREATE_SPARSE_BINDING_BIT flag using the following
structure:
@ -1104,6 +1127,8 @@ include::../structs/VkSparseBufferMemoryBindInfo.txt[]
include::../validity/structs/VkSparseBufferMemoryBindInfo.txt[]
// refBegin VkSparseImageOpaqueMemoryBindInfo - Structure specifying sparse image opaque memory bind info
Memory is bound to opaque regions of sname:VkImage objects created with the
ename:VK_IMAGE_CREATE_SPARSE_BINDING_BIT flag using the following
structure:
@ -1146,6 +1171,18 @@ the metadata aspect. See slink:VkSparseMemoryBind for the full constraints
on binding region with this flag present.
==================
ifdef::editing-notes[]
[NOTE]
.editing-note
====
(Jon) The preceding NOTE refers to pname:flags, which is presumably a
reference to slink:VkSparseMemoryBind above, even though that is not
contextually clear.
====
endif::editing-notes[]
// refBegin VkSparseImageMemoryBindInfo - Structure specifying sparse image memory bind info
Memory can: be bound to sparse image blocks of sname:VkImage objects created
with the ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT flag using the following
structure:
@ -1160,6 +1197,8 @@ include::../structs/VkSparseImageMemoryBindInfo.txt[]
include::../validity/structs/VkSparseImageMemoryBindInfo.txt[]
// refBegin VkSparseImageMemoryBind - Structure specifying sparse image memory bind
The sname:VkSparseImageMemoryBind structure is defined as:
include::../structs/VkSparseImageMemoryBind.txt[]
@ -1174,15 +1213,17 @@ include::../structs/VkSparseImageMemoryBind.txt[]
latexmath:[$\mathit{offset} + \mathit{extent}$] equals the corresponding
dimensions of the image subresource.
* pname:memory is the sname:VkDeviceMemory object that the sparse image
blocks of the image are bound to. If pname:memory is code:VK_NULL_HANDLE,
blocks of the image are bound to. If pname:memory is dlink:VK_NULL_HANDLE,
the sparse image blocks are unbound.
* pname:memoryOffset is an offset into sname:VkDeviceMemory object. If
pname:memory is code:VK_NULL_HANDLE, this value is ignored.
pname:memory is dlink:VK_NULL_HANDLE, this value is ignored.
* pname:flags are sparse memory binding flags.
include::../validity/structs/VkSparseImageMemoryBind.txt[]
Sparse binding operations are submitted to a queue by calling:
// refBegin vkQueueBindSparse Bind device memory to a sparse resource object.
To submit sparse binding operations to a queue, call:
include::../protos/vkQueueBindSparse.txt[]
@ -1191,11 +1232,9 @@ include::../protos/vkQueueBindSparse.txt[]
* pname:pBindInfo is an array of slink:VkBindSparseInfo structures,
each specifying a sparse binding submission batch.
* pname:fence is an optional handle to a fence to be signaled. If
pname:fence is not code:VK_NULL_HANDLE, it defines a
pname:fence is not dlink:VK_NULL_HANDLE, it defines a
<<synchronization-fences-signaling, fence signal operation>>.
include::../validity/protos/vkQueueBindSparse.txt[]
fname:vkQueueBindSparse is a
<<devsandqueues-submission,queue submission command>>, with each batch
defined by an element of pname:pBindInfo as an instance of the
@ -1208,6 +1247,17 @@ guarantee (usually using semaphores) that the binding operations are
executed in the correct order, as well as to order binding operations
against the execution of command buffer submissions.
As no operation to flink:vkQueueBindSparse causes any pipeline stage to
access memory, synchronization primitives used in this command effectively
only define execution dependencies.
Additional information about fence and semaphore operation is described in
<<synchronization, the synchronization chapter>>.
include::../validity/protos/vkQueueBindSparse.txt[]
// refBegin VkBindSparseInfo - Structure specifying a sparse binding operation
The sname:VkBindSparseInfo structure is defined as:
include::../structs/VkBindSparseInfo.txt[]
@ -1244,13 +1294,6 @@ include::../structs/VkBindSparseInfo.txt[]
include::../validity/structs/VkBindSparseInfo.txt[]
As no operation to flink:vkQueueBindSparse causes any pipeline stage to
access memory, synchronization primitives used in this command effectively
only define execution dependencies.
Additional information about fence and semaphore operation is described in
<<synchronization, the synchronization chapter>>.
[[sparsememory-examples]]
== Examples

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

@ -37,6 +37,8 @@ sets of commands.
[[synchronization-fences]]
== Fences
// refBegin VkFence - Opaque handle to a fence object
Fences can: be used by the host to determine completion of execution of
_queue operations_.
@ -44,6 +46,14 @@ A fence's status is always either _signaled_ or _unsignaled_. The host can:
poll the status of a single fence, or wait for any or all of a group of
fences to become signaled.
Fences are represented by sname:VkFence handles:
include::../handles/VkFence.txt[]
// refEnd VkFence
// refBegin vkCreateFence Create a new fence object.
To create a new fence object, use the command
include::../protos/vkCreateFence.txt[]
@ -58,22 +68,28 @@ include::../protos/vkCreateFence.txt[]
include::../validity/protos/vkCreateFence.txt[]
// refBegin VkFenceCreateInfo - Structure specifying parameters of a newly created fence
The sname:VkFenceCreateInfo structure is defined as:
include::../structs/VkFenceCreateInfo.txt[]
The pname:flags member of the sname:VkFenceCreateInfo structure pointed to
by pname:pCreateInfo contains flags defining the initial state and behavior
of the fence. The flags are:
* pname:flags defines the initial state and behavior of the fence. Bits
which can: be set include:
+
--
// refBegin VkFenceCreateFlagBits - Bitmask specifying initial state and behavior of a fence
include::../enums/VkFenceCreateFlagBits.txt[]
--
+
If pname:flags contains ename:VK_FENCE_CREATE_SIGNALED_BIT then the fence
object is created in the signaled state. Otherwise it is created in the
unsignaled state.
include::../validity/structs/VkFenceCreateInfo.txt[]
// refBegin vkDestroyFence Destroy a fence object
To destroy a fence, call:
include::../protos/vkDestroyFence.txt[]
@ -85,6 +101,8 @@ include::../protos/vkDestroyFence.txt[]
include::../validity/protos/vkDestroyFence.txt[]
// refBegin vkGetFenceStatus Return the status of a fence.
To query the status of a fence from the host, use the command
include::../protos/vkGetFenceStatus.txt[]
@ -92,14 +110,16 @@ include::../protos/vkGetFenceStatus.txt[]
* pname:device is the logical device that owns the fence.
* pname:fence is the handle of the fence to query.
include::../validity/protos/vkGetFenceStatus.txt[]
Upon success, fname:vkGetFenceStatus returns the status of the fence,
which is one of:
* ename:VK_SUCCESS indicates that the fence is signaled.
* ename:VK_NOT_READY indicates that the fence is unsignaled.
include::../validity/protos/vkGetFenceStatus.txt[]
// refBegin vkResetFences Resets one or more fence objects.
To reset the status of one or more fences to the unsignaled state, use the
command:
@ -110,11 +130,11 @@ include::../protos/vkResetFences.txt[]
* pname:pFences is a pointer to an array of pname:fenceCount fence
handles to reset.
include::../validity/protos/vkResetFences.txt[]
If a fence is already in the unsignaled state, then resetting it has no
effect.
include::../validity/protos/vkResetFences.txt[]
[[synchronization-fences-signaling]]
Fences can: be signaled by including them in a
<<devsandqueues-submission, queue submission>> command, defining a
@ -131,6 +151,8 @@ Fence signal operations for flink:vkQueueSubmit additionally include all
queue operations previously submitted via flink:vkQueueSubmit in their half
of a memory dependency.
// refBegin vkWaitForFences Wait for one or more fences to become signaled.
To cause the host to wait until any one or all of a group of fences
is signaled, use the command:
@ -150,8 +172,6 @@ include::../protos/vkWaitForFences.txt[]
longer than one nanosecond, and may: be longer than the requested
period.
include::../validity/protos/vkWaitForFences.txt[]
If the condition is satisfied when fname:vkWaitForFences is called, then
fname:vkWaitForFences returns immediately. If the condition is not satisfied
at the time fname:vkWaitForFences is called, then fname:vkWaitForFences will
@ -185,14 +205,26 @@ fname:vkInvalidateMappedMemoryRanges must: be called after the fence is
signaled in order to ensure the writes are visible to the host, as described
in <<memory-device-hostaccess,Host Access to Device Memory Objects>>.
include::../validity/protos/vkWaitForFences.txt[]
[[synchronization-semaphores]]
== Semaphores
// refBegin VkSemaphore - Opaque handle to a semaphore object
Semaphores are used to coordinate queue operations both within a queue and
between different queues. A semaphore's status is always either _signaled_
or _unsignaled_.
Semaphores are represented by sname:VkSemaphore handles:
include::../handles/VkSemaphore.txt[]
// refEnd VkSemaphore
// refBegin vkCreateSemaphore Create a new queue semaphore object.
To create a new semaphore object, use the command
include::../protos/vkCreateSemaphore.txt[]
@ -208,6 +240,8 @@ include::../protos/vkCreateSemaphore.txt[]
include::../validity/protos/vkCreateSemaphore.txt[]
// refBegin VkSemaphoreCreateInfo - Structure specifying parameters of a newly created semaphore
The sname:VkSemaphoreCreateInfo structure is defined as:
include::../structs/VkSemaphoreCreateInfo.txt[]
@ -216,10 +250,10 @@ include::../structs/VkSemaphoreCreateInfo.txt[]
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
* pname:flags is reserved for future use.
// @include::../enums/VkSemaphoreCreateFlagBits.txt[]
include::../validity/structs/VkSemaphoreCreateInfo.txt[]
// refBegin vkDestroySemaphore Destroy a semaphore object
To destroy a semaphore, call:
include::../protos/vkDestroySemaphore.txt[]
@ -322,6 +356,8 @@ is not defined in the core Vulkan specification.)
[[synchronization-events]]
== Events
// refBegin VkEvent - Opaque handle to a event object
Events represent a fine-grained synchronization primitive that can: be used
to gauge progress through a sequence of commands executed on a queue by
Vulkan. An event is initially in the unsignaled state. It can: be
@ -330,6 +366,14 @@ the host. It can: also be reset to the unsignaled state by a device or the
host. The host can: query the state of an event. A device can: wait for one
or more events to become signaled.
Events are represented by sname:VkEvent handles:
include::../handles/VkEvent.txt[]
// refEnd VkEvent
// refBegin vkCreateEvent Create a new event object.
To create an event, call:
include::../protos/vkCreateEvent.txt[]
@ -343,19 +387,22 @@ include::../protos/vkCreateEvent.txt[]
* pname:pEvent points to a handle in which the resulting event object is
returned.
When created, the event object is in the unsignaled state.
include::../validity/protos/vkCreateEvent.txt[]
// refBegin VkEventCreateInfo - Structure specifying parameters of a newly created event
The sname:VkEventCreateInfo structure is defined as:
include::../structs/VkEventCreateInfo.txt[]
The pname:flags member of the sname:VkEventCreateInfo structure pointed to
by pname:pCreateInfo contains flags defining the behavior of the event.
Currently, no flags are defined.
When created, the event object is in the unsignaled state.
* pname:flags is reserved for future use.
include::../validity/structs/VkEventCreateInfo.txt[]
// refBegin vkDestroyEvent Destroy an event object
To destroy an event, call:
include::../protos/vkDestroyEvent.txt[]
@ -367,6 +414,8 @@ include::../protos/vkDestroyEvent.txt[]
include::../validity/protos/vkDestroyEvent.txt[]
// refBegin vkGetEventStatus Retrieve the status of an event object.
To query the state of an event from the host, call:
include::../protos/vkGetEventStatus.txt[]
@ -374,8 +423,6 @@ include::../protos/vkGetEventStatus.txt[]
* pname:device is the logical device that owns the event.
* pname:event is the handle of the event to query.
include::../validity/protos/vkGetEventStatus.txt[]
Upon success, fname:vkGetEventStatus returns the state of the event object
with the following return codes:
@ -391,6 +438,10 @@ immediately changed, and subsequent calls to fname:vkGetEventStatus will
return the new state. If an event is already in the requested state, then
updating it to the same state has no effect.
include::../validity/protos/vkGetEventStatus.txt[]
// refBegin vkSetEvent Set an event to signaled state.
To set the state of an event to signaled from the host, call:
include::../protos/vkSetEvent.txt[]
@ -400,6 +451,8 @@ include::../protos/vkSetEvent.txt[]
include::../validity/protos/vkSetEvent.txt[]
// refBegin vkResetEvent Reset an event to non-signaled state.
To set the state of an event to unsignaled from the host, call:
include::../protos/vkResetEvent.txt[]
@ -409,6 +462,8 @@ include::../protos/vkResetEvent.txt[]
include::../validity/protos/vkResetEvent.txt[]
// refBegin vkCmdSetEvent Set an event object to signaled state.
The state of an event can: also be updated on the device by commands
inserted in command buffers. To set the state of an event to signaled from
a device, call:
@ -423,6 +478,8 @@ include::../protos/vkCmdSetEvent.txt[]
include::../validity/protos/vkCmdSetEvent.txt[]
// refBegin vkCmdResetEvent Reset an event object to non-signaled state.
To set the state of an event to unsignaled from a device, call:
include::../protos/vkCmdResetEvent.txt[]
@ -441,6 +498,8 @@ pname:event is updated once the pipeline stages specified by pname:stageMask
prior commands. The command modifying the event is passed through the
pipeline bound to the command buffer at time of execution.
// refBegin vkCmdWaitEvents Wait for one or more events and insert a set of memory
To wait for one or more events to enter the signaled state on a device,
call:
@ -463,8 +522,6 @@ include::../protos/vkCmdWaitEvents.txt[]
<<synchronization-memory-barriers>> for more details about memory
barriers.
include::../validity/protos/vkCmdWaitEvents.txt[]
fname:vkCmdWaitEvents waits for events set by either fname:vkSetEvent or
fname:vkCmdSetEvent to become signaled. Logically, it has three phases:
@ -497,6 +554,8 @@ events. For example, an event should: only be reset if no
fname:vkCmdWaitEvents command is executing that waits upon that event.
====
include::../validity/protos/vkCmdWaitEvents.txt[]
An act of setting or resetting an event in one queue may: not affect or be
visible to other queues. For cross-queue synchronization, semaphores can: be
used.
@ -716,8 +775,11 @@ read-after-read hazards only require execution dependencies to synchronize.
A _pipeline barrier_ inserts an execution dependency and a set of memory
dependencies between a set of commands earlier in the command buffer and a
set of commands later in the command buffer. A pipeline barrier is recorded
by calling:
set of commands later in the command buffer.
// refBegin vkCmdPipelineBarrier Insert a set of execution and memory barriers.
To record a pipeline barrier, call:
include::../protos/vkCmdPipelineBarrier.txt[]
@ -734,7 +796,7 @@ work performed by the set of pipeline stages included in
pname:srcStageMask of the first set of commands completes before any
work performed by the set of pipeline stages included in
pname:dstStageMask of the second set of commands begins.
+
* pname:dependencyFlags is a bitmask of elink:VkDependencyFlagBits. The
execution dependency is by-region if the mask includes
ename:VK_DEPENDENCY_BY_REGION_BIT.
@ -805,10 +867,12 @@ pname:dstQueueFamilyIndex must: be ename:VK_QUEUE_FAMILY_IGNORED.
[[synchronization-pipeline-stage-flags]]
=== Pipeline Stage Flags
// refBegin VkPipelineStageFlagBits - Bitmask specifying pipeline stages
Several of the event commands, fname:vkCmdPipelineBarrier, and
sname:VkSubpassDependency depend on being able to specify where in the
logical pipeline events can: be signaled or the source and destination of an
execution dependency. These pipeline stages are specified with the bitfield:
logical pipeline events can: be signaled, or the source and destination of an
execution dependency. These pipeline stages are specified using a bitmask:
include::../enums/VkPipelineStageFlagBits.txt[]
@ -877,7 +941,7 @@ will. Similarly, when defining a memory dependency, if the stage mask(s)
refer to all stages, then the indicated access types from all stages will be
made available and/or visible, but using only
ename:VK_PIPELINE_STAGE_BOTTOM_OF_PIPE_BIT would not make any accesses
available and/or visible because this stage doesn't access memory. The
available and/or visible because this stage does not access memory. The
ename:VK_PIPELINE_STAGE_BOTTOM_OF_PIPE_BIT is useful for accomplishing
memory barriers and layout transitions when the next accesses will be done
in a different queue or by a presentation engine; in these cases subsequent
@ -886,6 +950,8 @@ transition must: complete before semaphores associated with the batch
signal.
====
// refEnd VkPipelineStageFlagBits
[NOTE]
.Note
====
@ -959,6 +1025,8 @@ sname:VkMemoryBarrier structure. This type of barrier applies to memory
accesses involving all memory objects that exist at the time of its
execution.
// refBegin VkMemoryBarrier - Structure specifying a memory barrier
The sname:VkMemoryBarrier structure is defined as:
include::../structs/VkMemoryBarrier.txt[]
@ -972,8 +1040,6 @@ include::../structs/VkMemoryBarrier.txt[]
performed by the second set of commands that will participate in
the dependency.
include::../validity/structs/VkMemoryBarrier.txt[]
pname:srcAccessMask and pname:dstAccessMask, along with pname:srcStageMask
and pname:dstStageMask from flink:vkCmdPipelineBarrier, define the two
halves of a memory dependency and an execution dependency. Memory accesses
@ -997,14 +1063,14 @@ also express write-after-read dependencies and write-after-write
dependencies, and are even useful to express read-after-read dependencies
across an image layout change.
pname:srcAccessMask and pname:dstAccessMask are each masks of the following
bitfield:
// refBegin VkAccessFlagBits - Bitmask specifying classes of memory access the will participate in a memory barrier dependency
Bits which can: be set in slink:VkMemoryBarrier::pname:srcAccessMask and
slink:VkMemoryBarrier::pname:dstAccessMask include:
[[synchronization-access-flags]]
include::../enums/VkAccessFlagBits.txt[]
elink:VkAccessFlagBits has the following meanings:
* ename:VK_ACCESS_INDIRECT_COMMAND_READ_BIT indicates that the access is
an indirect command structure read as part of an indirect drawing
command.
@ -1104,6 +1170,8 @@ and <<devsandqueues-queues,Queues>>.
|ename:VK_ACCESS_MEMORY_WRITE_BIT | None
|========================================
include::../validity/structs/VkMemoryBarrier.txt[]
[[synchronization-buffer-memory-barrier]]
=== Buffer Memory Barriers
@ -1117,6 +1185,8 @@ specified range of the buffer. It is also used to transfer ownership of a
buffer range from one queue family to another, as described in the
<<resources-sharing,Resource Sharing>> section.
// refBegin VkBufferMemoryBarrier Structure specifying the parameters of a buffer memory barrier.
The sname:VkBufferMemoryBarrier structure is defined as:
include::../structs/VkBufferMemoryBarrier.txt[]
@ -1161,6 +1231,8 @@ layout transition for an image subresource range, or to transfer ownership
of an image subresource range from one queue family to another as described
in the <<resources-sharing,Resource Sharing>> section.
// refBegin VkImageMemoryBarrier Structure specifying the parameters of an image memory barrier.
The sname:VkImageMemoryBarrier structure is defined as:
include::../structs/VkImageMemoryBarrier.txt[]
@ -1189,8 +1261,6 @@ include::../structs/VkImageMemoryBarrier.txt[]
sname:VkImageSubresourceRange), as well as the set of image subresources
whose image layouts are modified.
include::../validity/structs/VkImageMemoryBarrier.txt[]
If pname:oldLayout differs from pname:newLayout, a layout transition occurs
as part of the image memory barrier, affecting the data contained in the
region of the image defined by the pname:subresourceRange. If
@ -1215,32 +1285,39 @@ See <<resources-image-layouts>> for details on available image layouts
and their usages.
====
include::../validity/structs/VkImageMemoryBarrier.txt[]
[[synchronization-waitidle]]
=== Wait Idle Operations
// refBegin vkQueueWaitIdle Wait for a queue to become idle.
To wait on the host for the completion of outstanding queue operations for a given queue, call:
include::../protos/vkQueueWaitIdle.txt[]
* pname:queue is the queue on which to wait.
include::../validity/protos/vkQueueWaitIdle.txt[]
fname:vkQueueWaitIdle is equivalent to submitting a fence to a queue and
waiting with an infinite timeout for that fence to signal.
include::../validity/protos/vkQueueWaitIdle.txt[]
// refBegin vkDeviceWaitIdle Wait for a device to become idle.
To wait on the host for the completion of outstanding queue operations for all queues on a given logical device, call:
include::../protos/vkDeviceWaitIdle.txt[]
* pname:device is the logical device to idle.
include::../validity/protos/vkDeviceWaitIdle.txt[]
fname:vkDeviceWaitIdle is equivalent to calling fname:vkQueueWaitIdle for
all queues owned by pname:device.
include::../validity/protos/vkDeviceWaitIdle.txt[]
[[synchronization-implicit-ordering-hostwrites]]
== Host Write Ordering Guarantees

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

@ -426,6 +426,8 @@ segment are both implementation-dependent.
The pname:pTessellationState member of slink:VkGraphicsPipelineCreateInfo
points to a structure of type sname:VkPipelineTessellationStateCreateInfo.
// refBegin VkPipelineTessellationStateCreateInfo - Structure specifying parameters of a newly created pipeline tessellation state
The sname:VkPipelineTessellationStateCreateInfo structure is defined as:
include::../structs/VkPipelineTessellationStateCreateInfo.txt[]

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

@ -569,10 +569,10 @@ pname:borderColor of the sampler. The border color is:
[NOTE]
.Note
====
The names etext:TRANSPARENT_BLACK, etext:OPAQUE_BLACK, and etext:OPAQUE_WHITE
The names etext:VK_BORDER_COLOR_*_TRANSPARENT_BLACK, etext:VK_BORDER_COLOR_*_OPAQUE_BLACK, and etext:VK_BORDER_COLOR_*_OPAQUE_WHITE
are meant to describe which components are zeros and ones in the vocabulary of
compositing, and are not meant to imply that the numerical value of
etext:WHITE is a saturating value for integers.
etext:VK_BORDER_COLOR_INT_OPAQUE_WHITE is a saturating value for integers.
====
This is substituted for the texel value by replacing the number of components
@ -1197,9 +1197,9 @@ coordinates) rather than u,v,w (unnormalized texel coordinates) as in OpenGL
and OpenGL ES specifications. (I know, u,v,w is the way it has been
documented since OpenGL V1.0.)
Also there's no reason to have conditional application of
Also there is no reason to have conditional application of
latexmath:[$w_{base} , h_{base} , d_{base}$] for rectangle textures either,
since they don't support implicit derivatives.
since they do not support implicit derivatives.
==================
endif::editing-notes[]
@ -1530,7 +1530,7 @@ pname:addressModeW parameters of the sampler, respectively.
SPIR-V instructions with code:Gather in the name return a vector derived
from a 2x2 rectangular region of texels in the base level of the image view.
The rules for the etext:LINEAR minification filter are applied to identify the
The rules for the ename:VK_FILTER_LINEAR minification filter are applied to identify the
four selected texels. Each texel is then converted to an RGBA value according
to <<textures-conversion-to-rgba,conversion to RGBA>> and then
<<textures-component-swizzle,swizzled>>. A four-component vector is then
@ -1573,7 +1573,7 @@ pname:magFilter in the sampler. If latexmath:[$\lambda$] is greater than
zero, the texture is said to be _minified_, and the filter mode within a mip
level is selected by the pname:minFilter in the sampler.
Within a miplevel, etext:NEAREST filtering selects a single value using the
Within a miplevel, ename:VK_FILTER_NEAREST filtering selects a single value using the
latexmath:[$(i,j,k)$] texel coordinates, with all texels taken from layer l.
[latexmath]
@ -1588,7 +1588,7 @@ latexmath:[$(i,j,k)$] texel coordinates, with all texels taken from layer l.
\end{align*}
++++++++++++++++++++++++
Within a miplevel, etext:LINEAR filtering computes a weighted average of 8
Within a miplevel, ename:VK_FILTER_LINEAR filtering computes a weighted average of 8
(for 3D), 4 (for 2D or Cube), or 2 (for 1D) texel values, using the weights
computed earlier:
@ -1653,6 +1653,7 @@ computes a weighted average between neighboring miplevels:
[[textures-texel-anisotropic-filtering]]
=== Texel Anisotropic Filtering
Anisotropic filtering is enabled by the pname:anisotropyEnable in the
sampler. When enabled, the image filtering scheme accounts for a degree of
anisotropy.
@ -1666,13 +1667,13 @@ should: consider pname:minLod and pname:maxLod of the sampler.
The following describes one particular approach to implementing anisotropic
filtering for the 2D Image case, implementations may: choose other methods:
Given a pname:magFilter, pname:minFilter of etext:LINEAR and a
pname:mipmapMode of etext:NEAREST,
Given a pname:magFilter, pname:minFilter of ename:VK_FILTER_LINEAR and a
pname:mipmapMode of ename:VK_SAMPLER_MIPMAP_MODE_NEAREST:
Instead of a single isotropic sample, N isotropic samples are be sampled
within the image footprint of the image level d to approximate an
within the image footprint of the image level latexmath:[$d$] to approximate an
anisotropic filter. The sum latexmath:[$\tau_{2Daniso}$] is defined using
the single isotropic latexmath:[$\tau_{2D}$](u,v) at level d.
the single isotropic latexmath:[$\tau_{2D}$](u,v) at level latexmath:[$d$].
[latexmath]
++++++++++++++++++++++++
@ -1704,7 +1705,7 @@ ifdef::editing-notes[]
except for ES extension number (2007) and a minor speeling (sic) correction
(2014), neither of which are functional changes. It is showing its age.
In particular, there's an open issue about 3D textures.
In particular, there is an open issue about 3D textures.
There are no interactions with ARB_texture_cube_map (approved 1999, promoted
to core OpenGL 1.3 in 2001), let alone interactions with

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

@ -290,6 +290,8 @@ viewports used by a pipeline is controlled by the pname:viewportCount member
of the sname:VkPipelineViewportStateCreateInfo structure used in pipeline
creation.
// refBegin VkPipelineViewportStateCreateInfo - Structure specifying parameters of a newly created pipeline viewport state
The sname:VkPipelineViewportStateCreateInfo structure is defined as:
include::../structs/VkPipelineViewportStateCreateInfo.txt[]
@ -325,6 +327,8 @@ A single vertex can: be used in more than one individual primitive, in
primitives such as ename:VK_PRIMITIVE_TOPOLOGY_TRIANGLE_STRIP. In this case,
the viewport transformation is applied separately for each primitive.
// refBegin vkCmdSetViewport Set the viewport on a command buffer.
If the bound pipeline state object was not created with the
ename:VK_DYNAMIC_STATE_VIEWPORT dynamic state enabled, viewport
transformation parameters are specified using the pname:pViewports
@ -351,8 +355,12 @@ latexmath:[$[0, viewportCount)$].
include::../validity/protos/vkCmdSetViewport.txt[]
Either of these methods of setting the viewport transformation parameters
use the sname:VkViewport struct:
Both slink:VkPipelineViewportStateCreateInfo and flink:vkCmdSetViewport use
sname:VkViewport to set the viewport transformation parameters.
// refBegin VkViewport - Structure specifying a viewport
The sname:VkViewport structure is defined as:
include::../structs/VkViewport.txt[]
@ -364,8 +372,6 @@ include::../structs/VkViewport.txt[]
It is valid for pname:minDepth to be greater than or equal to
pname:maxDepth.
include::../validity/structs/VkViewport.txt[]
The framebuffer depth coordinate latexmath:[$z_f$] may: be represented using
either a fixed-point or floating-point representation. However, a
floating-point representation must: be used if the depth/stencil attachment
@ -398,4 +404,6 @@ created and attached to a framebuffer.
The floating-point viewport bounds are represented with an
<<features-limits-viewportSubPixelBits,implementation-dependent precision>>.
include::../validity/structs/VkViewport.txt[]

9
doc/specs/vulkan/checkLinks.py
View File

@ -90,6 +90,8 @@ def foundError(errType, tag, value):
checkTag(tag, value, flags, 'flags', 'elink')
checkTag(tag, value, enums, 'enums', 'elink')
checkTag(tag, value, structs, 'structs', 'slink/sname')
checkTag(tag, value, handles, 'handles', 'slink/sname')
checkTag(tag, value, defines, 'defines', 'slink/sname')
checkTag(tag, value, consts, 'consts', 'ename')
checkTag(tag, value, protos, 'protos', 'flink/fname')
checkTag(tag, value, funcpointers, 'funcpointers', 'tlink/tname')
@ -246,10 +248,11 @@ def checkLinks(infile, follow = False, included = False):
if (value not in protos.keys()):
foundError('function', tag, value)
elif (tag == 'sname' or tag == 'slink'):
if (value not in structs.keys()):
foundError('aggregate/scalar type', tag, value)
if (value not in structs.keys() and
value not in handles.keys()):
foundError('aggregate/scalar/handle/define type', tag, value)
elif (tag == 'ename'):
if (value not in consts.keys()):
if (value not in consts.keys() and value not in defines.keys()):
foundError('enumerant/constant', tag, value)
elif (tag == 'elink'):
if (value not in enums.keys() and value not in flags.keys()):

150
doc/specs/vulkan/config/manpages.conf
View File

@ -1,5 +1,27 @@
# Copyright (c) 2015-2016 The Khronos Group Inc.
# Copyright notice at https://www.khronos.org/registry/speccopyright.html
#
# The 'normative' macros below (can: through shouldnot:) serve mostly
# to tag that those terms have been validated against their normative
# definitions. They ignore any arguments, and don't yet do anything
# but expand to their names.
#
# The remaining macros tag API terms:
# d*: C macro #defines
# elink: enumerated type names
# ename:/etext: enumerant names
# f*: functions/prototypes
# h*: handles
# p*: function parameters and structure members
# s*: structs
# t*: other types (function pointers)
# These macros expand in ways determined by the name following = in the
# macro definition:
#
# 'link' macros format as code and create an xref/link to the target
# 'code' macros format as code, but do not link
# 'strong' macros format as <strong>, and do not link
# 'param' macros format as <parameter>, and do not link
[attributes]
author="Khronos Group"
@ -9,7 +31,6 @@ max-width="1024px"
(?su)(?P<name>can):(?P<arg>\w*)=normative
(?su)(?P<name>cannot):(?P<arg>\w*)=normative
(?su)(?P<name>may):(?P<arg>\w*)=normative
(?su)(?P<name>maynot):(?P<arg>\w*)=maynot
(?su)(?P<name>must):(?P<arg>\w*)=normative
(?su)(?P<name>mustnot):(?P<arg>\w*)=mustnot
(?su)(?P<name>optional):(?P<arg>\w*)=normative
@ -18,18 +39,23 @@ max-width="1024px"
(?su)(?P<name>required):(?P<arg>\w*)=normative
(?su)(?P<name>should):(?P<arg>\w*)=normative
(?su)(?P<name>shouldnot):(?P<arg>\w*)=shouldnot
(?su)(?P<name>flink):(?P<target>\w+)=
(?su)(?P<name>fname):(?P<target>\w+)=
(?su)(?P<name>sname):(?P<target>\w+)=
(?su)(?P<name>slink):(?P<target>\w+)=
(?su)(?P<name>ename):(?P<target>\w+)=
(?su)(?P<name>pname):(?P<target>\w+)=
(?su)(?P<name>elink):(?P<target>\w+)=
(?su)(?P<name>etext):(?P<target>\w+)=
(?su)(?P<name>pname):(?P<target>(\w[\w.]*)*\w+)=
(?su)(?P<name>ptext):(?P<target>(\w[\w.]*)*\w+)=
(?su)(?P<name>basetype):(?P<target>\w+)=
(?su)(?P<name>code):(?P<target>\w+)=
(?su)(?P<name>flink):(?P<target>\w+)=link
(?su)(?P<name>fname):(?P<target>\w+)=strong
(?su)(?P<name>ftext):(?P<target>[\w*]+(\.[\w*]+)*)=strong
(?su)(?P<name>sname):(?P<target>\w+)=code
(?su)(?P<name>slink):(?P<target>\w+)=link
(?su)(?P<name>stext):(?P<target>[\w*]+(\.[\w*]+)*)=code
(?su)(?P<name>dname):(?P<target>\w+)=code
(?su)(?P<name>dlink):(?P<target>\w+)=link
(?su)(?P<name>ename):(?P<target>\w+)=code
(?su)(?P<name>elink):(?P<target>\w+)=link
(?su)(?P<name>etext):(?P<target>[\w*]+(\.[\w*]+)*)=code
(?su)(?P<name>pname):(?P<target>(\w[\w.]*)*\w+)=param
(?su)(?P<name>ptext):(?P<target>[\w*]+(\.[\w*]+)*)=param
(?su)(?P<name>tlink):(?P<target>\w+)=link
(?su)(?P<name>tname):(?P<target>\w+)=strong
(?su)(?P<name>basetype):(?P<target>\w+)=code
(?su)(?P<name>code):(?P<target>\w+)=strong
[normative-inlinemacro]
ifdef::basebackend-docbook[]
@ -39,14 +65,6 @@ ifdef::basebackend-html[]
<span role="normative">{name}</span>
endif::basebackend-html[]
[maynot-inlinemacro]
ifdef::basebackend-docbook[]
<phrase role="normative">may not</phrase>
endif::basebackend-docbook[]
ifdef::basebackend-html[]
<span role="normative">may not</span>
endif::basebackend-html[]
[mustnot-inlinemacro]
ifdef::basebackend-docbook[]
<phrase role="normative">must not</phrase>
@ -63,78 +81,34 @@ ifdef::basebackend-html[]
<span role="normative">should not</span>
endif::basebackend-html[]
[flink-inlinemacro]
[link-inlinemacro]
ifdef::basebackend-docbook[]
<code><ulink url="{target}.html">{target}</ulink></code>
endif::basebackend-docbook[]
[fname-inlinemacro]
ifdef::basebackend-docbook[]
<emphasis role="strong"><code>{target}</code></emphasis>
endif::basebackend-docbook[]
[sname-inlinemacro]
ifdef::basebackend-docbook[]
<type>{target}</type>
endif::basebackend-docbook[]
[slink-inlinemacro]
ifdef::basebackend-docbook[]
<type><ulink url="{target}.html">{target}</ulink></type>
endif::basebackend-docbook[]
[pname-inlinemacro]
ifdef::basebackend-docbook[]
<parameter>{target}</parameter>
endif::basebackend-docbook[]
[ename-inlinemacro]
ifdef::basebackend-docbook[]
<type>{target}</type>
endif::basebackend-docbook[]
[elink-inlinemacro]
ifdef::basebackend-docbook[]
<type><ulink url="{target}.html">{target}</ulink></type>
endif::basebackend-docbook[]
[ftext-inlinemacro]
ifdef::basebackend-docbook[]
<emphasis role="strong"><code>{target}</code></emphasis>
<code><link linkend="{target}.html">{target}</link></code>
endif::basebackend-docbook[]
ifdef::basebackend-html[]
<code>{target}</code>
<code><a href="{target}.html">{target}</a></code>
endif::basebackend-html[]
[stext-inlinemacro]
ifdef::basebackend-docbook[]
<type>{target}</type>
endif::basebackend-docbook[]
ifdef::basebackend-html[]
<code>{target}</code>
endif::basebackend-html[]
[etext-inlinemacro]
ifdef::basebackend-docbook[]
<type>{target}</type>
endif::basebackend-docbook[]
ifdef::basebackend-html[]
<code>{target}</code>
endif::basebackend-html[]
[ptext-inlinemacro]
ifdef::basebackend-docbook[]
<parameter>{target}</parameter>
endif::basebackend-docbook[]
ifdef::basebackend-html[]
<code>{target}</code>
endif::basebackend-html[]
[basetype-inlinemacro]
<code>{target}</code>
[code-inlinemacro]
ifdef::basebackend-docbook[]
<code>{target}</code>
endif::basebackend-docbook[]
ifdef::basebackend-html[]
<code>{target}</code>
endif::basebackend-html[]
[must-inlinemacro]
must {target}
[strong-inlinemacro]
ifdef::basebackend-docbook[]
<emphasis role="strong"><code>{target}</code></emphasis>
endif::basebackend-docbook[]
ifdef::basebackend-html[]
<code>{target}</code>
endif::basebackend-html[]
[param-inlinemacro]
ifdef::basebackend-docbook[]
<parameter>{target}</parameter>
endif::basebackend-docbook[]
ifdef::basebackend-html[]
<code>{target}</code>
endif::basebackend-html[]

29
doc/specs/vulkan/config/vkspec.conf
View File

@ -6,20 +6,31 @@
# definitions. They ignore any arguments, and don't yet do anything
# but expand to their names.
#
# The remaining macros tag API terms (f = function, s = struct, e = enum,
# p = parameter, t = other type) and expand in various ways determined by
# the name following the = in the macro definition:
# The remaining macros tag API terms:
# d*: C macro #defines
# elink: enumerated type names
# ename:/etext: enumerant names
# f*: functions/prototypes
# h*: handles
# p*: function parameters and structure members
# s*: structs
# t*: other types (function pointers)
# These macros expand in ways determined by the name following = in the
# macro definition:
#
# 'link' macros format as code and create an xref/link to the target
# 'code' macros format as code, but do not link
# 'strong' macros format as <strong>, and do not link
# 'param' macros format as <parameter>, and do not link
[macros]
(?su)(?P<name>can):(?P<arg>\w*)=normative
(?su)(?P<name>cannot):(?P<arg>\w*)=normative
(?su)(?P<name>may):(?P<arg>\w*)=normative
(?su)(?P<name>maynot):(?P<arg>\w*)=maynot
(?su)(?P<name>must):(?P<arg>\w*)=normative
(?su)(?P<name>mustnot):(?P<arg>\w*)=mustnot
(?su)(?P<name>optional):(?P<arg>\w*)=normative
@ -34,6 +45,8 @@
(?su)(?P<name>sname):(?P<target>\w+)=code
(?su)(?P<name>slink):(?P<target>\w+)=link
(?su)(?P<name>stext):(?P<target>[\w*]+(\.[\w*]+)*)=code
(?su)(?P<name>dname):(?P<target>\w+)=code
(?su)(?P<name>dlink):(?P<target>\w+)=link
(?su)(?P<name>ename):(?P<target>\w+)=code
(?su)(?P<name>elink):(?P<target>\w+)=link
(?su)(?P<name>etext):(?P<target>[\w*]+(\.[\w*]+)*)=code
@ -52,14 +65,6 @@ ifdef::basebackend-html[]
<span role="normative">{name}</span>
endif::basebackend-html[]
[maynot-inlinemacro]
ifdef::basebackend-docbook[]
<phrase role="normative">may not</phrase>
endif::basebackend-docbook[]
ifdef::basebackend-html[]
<span role="normative">may not</span>
endif::basebackend-html[]
[mustnot-inlinemacro]
ifdef::basebackend-docbook[]
<phrase role="normative">must not</phrase>

13
doc/specs/vulkan/defines/VK_API_VERSION.txt Normal file
View File

@ -0,0 +1,13 @@
// WARNING: DO NOT MODIFY! This file is automatically generated from the vk.xml registry
ifndef::doctype-manpage[]
[[VK_API_VERSION,VK_API_VERSION]]
["source","{basebackend@docbook:c++:cpp}",title=""]
endif::doctype-manpage[]
ifdef::doctype-manpage[]
["source","{basebackend@docbook:c++:cpp}"]
endif::doctype-manpage[]
------------------------------------------------------------------------------
// DEPRECATED: This define has been removed. Specific version defines (e.g. VK_API_VERSION_1_0), or the VK_MAKE_VERSION macro, should be used instead.
//#define VK_API_VERSION VK_MAKE_VERSION(1, 0, 0)
------------------------------------------------------------------------------

13
doc/specs/vulkan/defines/VK_API_VERSION_1_0.txt Normal file
View File

@ -0,0 +1,13 @@
// WARNING: DO NOT MODIFY! This file is automatically generated from the vk.xml registry
ifndef::doctype-manpage[]
[[VK_API_VERSION_1_0,VK_API_VERSION_1_0]]
["source","{basebackend@docbook:c++:cpp}",title=""]
endif::doctype-manpage[]
ifdef::doctype-manpage[]
["source","{basebackend@docbook:c++:cpp}"]
endif::doctype-manpage[]
------------------------------------------------------------------------------
// Vulkan 1.0 version number
#define VK_API_VERSION_1_0 VK_MAKE_VERSION(1, 0, 0)
------------------------------------------------------------------------------

13
doc/specs/vulkan/defines/VK_DEFINE_HANDLE.txt Normal file
View File

@ -0,0 +1,13 @@
// WARNING: DO NOT MODIFY! This file is automatically generated from the vk.xml registry
ifndef::doctype-manpage[]
[[VK_DEFINE_HANDLE,VK_DEFINE_HANDLE]]
["source","{basebackend@docbook:c++:cpp}",title=""]
endif::doctype-manpage[]
ifdef::doctype-manpage[]
["source","{basebackend@docbook:c++:cpp}"]
endif::doctype-manpage[]
------------------------------------------------------------------------------
#define VK_DEFINE_HANDLE(object) typedef struct object##_T* object;
------------------------------------------------------------------------------

18
doc/specs/vulkan/defines/VK_DEFINE_NON_DISPATCHABLE_HANDLE.txt Normal file
View File

@ -0,0 +1,18 @@
// WARNING: DO NOT MODIFY! This file is automatically generated from the vk.xml registry
ifndef::doctype-manpage[]
[[VK_DEFINE_NON_DISPATCHABLE_HANDLE,VK_DEFINE_NON_DISPATCHABLE_HANDLE]]
["source","{basebackend@docbook:c++:cpp}",title=""]
endif::doctype-manpage[]
ifdef::doctype-manpage[]
["source","{basebackend@docbook:c++:cpp}"]
endif::doctype-manpage[]
------------------------------------------------------------------------------
#if defined(__LP64__) || defined(_WIN64) || defined(__x86_64__) || defined(_M_X64) || defined(__ia64) || defined (_M_IA64) || defined(__aarch64__) || defined(__powerpc64__)
#define VK_DEFINE_NON_DISPATCHABLE_HANDLE(object) typedef struct object##_T *object;
#else
#define VK_DEFINE_NON_DISPATCHABLE_HANDLE(object) typedef uint64_t object;
#endif
------------------------------------------------------------------------------

13
doc/specs/vulkan/defines/VK_HEADER_VERSION.txt Normal file
View File

@ -0,0 +1,13 @@
// WARNING: DO NOT MODIFY! This file is automatically generated from the vk.xml registry
ifndef::doctype-manpage[]
[[VK_HEADER_VERSION,VK_HEADER_VERSION]]
["source","{basebackend@docbook:c++:cpp}",title=""]
endif::doctype-manpage[]
ifdef::doctype-manpage[]
["source","{basebackend@docbook:c++:cpp}"]
endif::doctype-manpage[]
------------------------------------------------------------------------------
// Version of this file
#define VK_HEADER_VERSION 20
------------------------------------------------------------------------------

13
doc/specs/vulkan/defines/VK_MAKE_VERSION.txt Normal file
View File

@ -0,0 +1,13 @@
// WARNING: DO NOT MODIFY! This file is automatically generated from the vk.xml registry
ifndef::doctype-manpage[]
[[VK_MAKE_VERSION,VK_MAKE_VERSION]]
["source","{basebackend@docbook:c++:cpp}",title=""]
endif::doctype-manpage[]
ifdef::doctype-manpage[]
["source","{basebackend@docbook:c++:cpp}"]
endif::doctype-manpage[]
------------------------------------------------------------------------------
#define VK_MAKE_VERSION(major, minor, patch) \
(((major) << 22) | ((minor) << 12) | (patch))
------------------------------------------------------------------------------

14
doc/specs/vulkan/defines/VK_NULL_HANDLE.txt Normal file
View File

@ -0,0 +1,14 @@
// WARNING: DO NOT MODIFY! This file is automatically generated from the vk.xml registry
ifndef::doctype-manpage[]
[[VK_NULL_HANDLE,VK_NULL_HANDLE]]
["source","{basebackend@docbook:c++:cpp}",title=""]
endif::doctype-manpage[]
ifdef::doctype-manpage[]
["source","{basebackend@docbook:c++:cpp}"]
endif::doctype-manpage[]
------------------------------------------------------------------------------
#define VK_NULL_HANDLE 0
------------------------------------------------------------------------------

12
doc/specs/vulkan/defines/VK_VERSION_MAJOR.txt Normal file
View File

@ -0,0 +1,12 @@
// WARNING: DO NOT MODIFY! This file is automatically generated from the vk.xml registry
ifndef::doctype-manpage[]
[[VK_VERSION_MAJOR,VK_VERSION_MAJOR]]
["source","{basebackend@docbook:c++:cpp}",title=""]
endif::doctype-manpage[]
ifdef::doctype-manpage[]
["source","{basebackend@docbook:c++:cpp}"]
endif::doctype-manpage[]
------------------------------------------------------------------------------
#define VK_VERSION_MAJOR(version) ((uint32_t)(version) >> 22)
------------------------------------------------------------------------------

12
doc/specs/vulkan/defines/VK_VERSION_MINOR.txt Normal file
View File

@ -0,0 +1,12 @@
// WARNING: DO NOT MODIFY! This file is automatically generated from the vk.xml registry
ifndef::doctype-manpage[]
[[VK_VERSION_MINOR,VK_VERSION_MINOR]]
["source","{basebackend@docbook:c++:cpp}",title=""]
endif::doctype-manpage[]
ifdef::doctype-manpage[]
["source","{basebackend@docbook:c++:cpp}"]
endif::doctype-manpage[]
------------------------------------------------------------------------------
#define VK_VERSION_MINOR(version) (((uint32_t)(version) >> 12) & 0x3ff)
------------------------------------------------------------------------------

12
doc/specs/vulkan/defines/VK_VERSION_PATCH.txt Normal file
View File

@ -0,0 +1,12 @@
// WARNING: DO NOT MODIFY! This file is automatically generated from the vk.xml registry
ifndef::doctype-manpage[]
[[VK_VERSION_PATCH,VK_VERSION_PATCH]]
["source","{basebackend@docbook:c++:cpp}",title=""]
endif::doctype-manpage[]
ifdef::doctype-manpage[]
["source","{basebackend@docbook:c++:cpp}"]
endif::doctype-manpage[]
------------------------------------------------------------------------------
#define VK_VERSION_PATCH(version) ((uint32_t)(version) & 0xfff)
------------------------------------------------------------------------------

20
doc/specs/vulkan/funcpointers/PFN_vkDebugReportCallbackEXT.txt
View File

@ -1,20 +0,0 @@
// WARNING: DO NOT MODIFY! This file is automatically generated from the vk.xml registry
ifndef::doctype-manpage[]
[[PFN_vkDebugReportCallbackEXT,PFN_vkDebugReportCallbackEXT]]
["source","{basebackend@docbook:c++:cpp}",title=""]
endif::doctype-manpage[]
ifdef::doctype-manpage[]
["source","{basebackend@docbook:c++:cpp}"]
endif::doctype-manpage[]
------------------------------------------------------------------------------
typedef VkBool32 (VKAPI_PTR *PFN_vkDebugReportCallbackEXT)(
VkDebugReportFlagsEXT flags,
VkDebugReportObjectTypeEXT objectType,
uint64_t object,
size_t location,
int32_t messageCode,
const char* pLayerPrefix,
const char* pMessage,
void* pUserData);
------------------------------------------------------------------------------

501
doc/specs/vulkan/genRef.py Executable file
View File

@ -0,0 +1,501 @@
#!/usr/bin/python3
#
# Copyright (c) 2016 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.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
# genRef.py - create Vulkan ref pages from spec source files
#
#
# Usage: genRef.py files
from reflib import *
from vkapi import *
import argparse, copy, os, pdb, re, string, sys
# Return True if name is a Vulkan extension name (ends with an upper-case
# author ID). This assumes that author IDs are at least two characters.
def isextension(name):
return name[-2:].isalpha() and name[-2:].isupper()
# Print Khronos CC-BY copyright notice on open file fp. If comment is
# True, print as an asciidoc comment block, which copyrights the source
# file. Otherwise print as an asciidoc include of the copyright in markup,
# which copyrights the outputs.
def printCopyrightBlock(fp, comment=True):
if (comment):
print('// Copyright (c) 2014-2016 Khronos Group. This work is licensed under a', file=fp)
print('// Creative Commons Attribution 4.0 International License; see', file=fp)
print('// http://creativecommons.org/licenses/by/4.0/', file=fp)
print('', file=fp)
else:
print('include::footer.txt[]', file=fp)
print('', file=fp)
# Add a spec asciidoc macro prefix to a Vulkan name, depending on its type
# (protos, structs, enums, etc.)
def macroPrefix(name):
if (name in basetypes.keys()):
return 'basetypes:' + name
elif (name in defines.keys()):
return 'slink:' + name
elif (name in enums.keys()):
return 'elink:' + name
elif (name in flags.keys()):
return 'elink:' + name
elif (name in funcpointers.keys()):
return 'tlink:' + name
elif (name in handles.keys()):
return 'slink:' + name
elif (name in protos.keys()):
return 'flink:' + name
elif (name in structs.keys()):
return 'slink:' + name
elif (name == 'TBD'):
return 'No cross-references are available'
else:
return 'UNKNOWN:' + name
# Return an asciidoc string with a list of 'See Also' references for the
# Vulkan entity 'name', based on the relationship mapping in vkapi.py and
# the additional references in explicitRefs. If no relationships are
# available, return None.
def seeAlsoList(apiName, explicitRefs = None):
refs = {}
# Add all the implicit references to refs
if (apiName in mapDict.keys()):
for name in sorted(mapDict[apiName].keys()):
refs[name] = None
# Add all the explicit references
if (explicitRefs != None):
for name in explicitRefs.split():
refs[name] = None
names = [macroPrefix(name) for name in sorted(refs.keys())]
if (len(names) > 0):
return ', '.join(names) + '\n'
else:
return None
# Generate header of a reference page
# pageName - string name of the page
# pageDesc - string short description of the page
# specText - string that goes in the "C Specification" section
# fieldName - string heading an additional section following specText, if not None
# fieldText - string that goes in the additional section
# descText - string that goes in the "Description" section
# fp - file to write to
def refPageHead(pageName, pageDesc, specText, fieldName, fieldText, descText, fp):
printCopyrightBlock(fp, comment=True)
s = pageName + '(3)'
print(s,
''.ljust(len(s), '='),
'',
sep='\n', file=fp)
print('Name',
'----',
pageName + ' - ' + pageDesc,
'',
sep='\n', file=fp)
print('C Specification',
'---------------',
'',
specText,
'',
sep='\n', file=fp)
if (fieldName != None):
print(fieldName,
''.ljust(len(fieldName), '-'),
'',
fieldText,
sep='\n', file=fp)
print('Description',
'-----------',
'',
descText,
'',
sep='\n', file=fp)
def refPageTail(pageName, seeAlso, fp, auto = False):
specURL = 'https://www.khronos.org/registry/vulkan/specs/1.0/xhtml/vkspec.html'
if (seeAlso == None):
seeAlso = 'No cross-references are available\n'
if (auto):
notes = [
'For more information, see the Vulkan Specification at URL',
'',
specURL + '#' + pageName,
'',
'This page is a generated document.',
'Fixes and changes should be made to the generator scripts,'
'not directly.',
]
else:
notes = [
'For more information, see the Vulkan Specification at URL',
'',
specURL + '#' + pageName,
'',
'This page is extracted from the Vulkan Specification.',
'Fixes and changes should be made to the Specification,'
'not directly.',
]
print('See Also',
'--------',
'',
seeAlso,
'',
sep='\n', file=fp)
print('Document Notes',
'--------------',
'',
'\n'.join(notes),
'',
sep='\n', file=fp)
printCopyrightBlock(fp, comment=False)
# Emit a single reference page in baseDir
# baseDir - base directory to emit page into
# pi - pageInfo for this page relative to file
# file - list of strings making up the file, indexed by pi
def emitPage(baseDir, pi, file):
pageName = baseDir + '/' + pi.name + '.txt'
fp = open(pageName, 'w')
# Add a dictionary entry for this page
global genDict
genDict[pi.name] = None
logDiag('emitPage:', pageName)
# Short description
if (pi.desc == None):
pi.desc = '(no short description available)'
# Specification text
specText = ''.join(file[pi.begin:pi.include+1])
# Member/parameter list, if there is one
field = None
fieldText = None
if (pi.param != None):
if (pi.type == 'structs'):
field = 'Members'
elif (pi.type in ['protos', 'funcpointers']):
field = 'Parameters'
else:
logWarn('PyOutputGenerator::emitPage: unknown field type:', pi.type,
'for', pi.name)
fieldText = ''.join(file[pi.param:pi.body])
# Description text
descText = ''.join(file[pi.body:pi.end+1])
refPageHead(pi.name,
pi.desc,
specText,
field, fieldText,
descText,
fp)
refPageTail(pi.name, seeAlsoList(pi.name, pi.refs), fp, auto = False)
fp.close()
# Autogenerate a single reference page in baseDir
# Script only knows how to do this for /enums/ pages, at present
# baseDir - base directory to emit page into
# pi - pageInfo for this page relative to file
# file - list of strings making up the file, indexed by pi
def autoGenEnumsPage(baseDir, pi, file):
pageName = baseDir + '/' + pi.name + '.txt'
fp = open(pageName, 'w')
# Add a dictionary entry for this page
global genDict
genDict[pi.name] = None
logDiag('autoGenEnumsPage:', pageName)
# Short description
if (pi.desc == None):
pi.desc = '(no short description available)'
# Description text
txt = ''.join([
'For more information, see:\n\n',
' * The reference page for ' + macroPrefix(pi.embed) +
', where this interface is defined.\n',
' * The See Also section for other reference pages using this type.\n',
' * The Vulkan Specification.\n' ])
refPageHead(pi.name,
pi.desc,
''.join(file[pi.begin:pi.include+1]),
None, None,
txt,
fp)
refPageTail(pi.name, seeAlsoList(pi.name, pi.refs), fp, auto = True)
fp.close()
# Pattern to break apart a Vk*Flags{authorID} name, used in autoGenFlagsPage.
flagNamePat = re.compile('(?P<name>\w+)Flags(?P<author>[A-Z]*)')
# Autogenerate a single reference page in baseDir for a Vk*Flags type
# baseDir - base directory to emit page into
# flagName - Vk*Flags name
def autoGenFlagsPage(baseDir, flagName):
pageName = baseDir + '/' + flagName + '.txt'
fp = open(pageName, 'w')
# Add a dictionary entry for this page
global genDict
genDict[flagName] = None
logDiag('autoGenFlagsPage:', pageName)
# Short description
matches = flagNamePat.search(flagName)
if (matches != None):
name = matches.group('name')
author = matches.group('author')
logDiag('autoGenFlagsPage: split name into', name, 'Flags', author)
flagBits = name + 'FlagBits' + author
desc = 'Bitmask of ' + flagBits
else:
logWarn('autoGenFlagsPage:', pageName, 'does not not end in "Flags{author ID}". Cannot infer FlagBits type.')
flagBits = None
desc = 'Unknown Vulkan flags type'
# Description text
if (flagBits != None):
txt = ''.join([
'etext:' + flagName,
' is a mask of zero or more elink:' + flagBits + '.\n',
'It is used as a member and/or parameter of the structures and commands\n',
'in the See Also section below.\n' ])
else:
txt = ''.join([
'etext:' + flagName,
' is an unknown Vulkan type, assumed to be a bitmask.\n' ])
refPageHead(flagName,
desc,
'include::../flags/' + flagName + '.txt[]\n',
None, None,
txt,
fp)
refPageTail(flagName, seeAlsoList(flagName), fp, auto = True)
fp.close()
# Autogenerate a single handle page in baseDir for a Vk* handle type
# baseDir - base directory to emit page into
# handleName - Vk* handle name
# @@ Need to determine creation function & add handles/ include for the
# @@ interface in generator.py.
def autoGenHandlePage(baseDir, handleName):
pageName = baseDir + '/' + handleName + '.txt'
fp = open(pageName, 'w')
# Add a dictionary entry for this page
global genDict
genDict[handleName] = None
logDiag('autoGenHandlePage:', pageName)
# Short description
desc = 'Vulkan object handle'
descText = ''.join([
'sname:' + handleName,
' is an object handle type, referring to an object used\n',
'by the Vulkan implementation. These handles are created or allocated\n',
'by the vk @@ TBD @@ function, and used by other Vulkan structures\n',
'and commands in the See Also section below.\n' ])
refPageHead(handleName,
desc,
'include::../handles/' + handleName + '.txt[]\n',
None, None,
descText,
fp)
refPageTail(handleName, seeAlsoList(handleName), fp, auto = True)
fp.close()
# Extract reference pages from a spec asciidoc source file
# specFile - filename to extract from
# baseDir - output directory to generate page in
#
def genRef(specFile, baseDir):
file = loadFile(specFile)
if (file == None):
return
pageMap = findRefs(file)
logDiag(specFile + ': found', len(pageMap.keys()), 'potential pages')
sys.stderr.flush()
# Fix up references in pageMap
fixupRefs(pageMap, specFile, file)
# Create each page, if possible
for name in sorted(pageMap.keys()):
pi = pageMap[name]
printPageInfo(pi, file)
if (pi.Warning):
logWarn('genRef:', pi.name + ':', pi.Warning)
if (pi.extractPage):
emitPage(baseDir, pi, file)
elif (pi.type == 'enums'):
autoGenEnumsPage(baseDir, pi, file)
elif (pi.type == 'flags'):
autoGenFlagsPage(baseDir, pi.name)
else:
# Don't extract this page
logWarn('genRef: Cannot extract or autogenerate:', pi.name)
# Generate baseDir/apispec.txt, the single-page version of the ref pages.
# This assumes there's a page for everything in the vkapi.py dictionaries.
# Extensions (KHR, EXT, etc.) are currently skipped
def genSinglePageRef(baseDir):
pageName = baseDir + '/apispec.txt'
fp = open(pageName, 'w')
printCopyrightBlock(fp, comment=True)
print('Vulkan API Reference Pages',
'==========================',
'include::../specversion.txt[]',
'',
':doctype: book',
':numbered!:',
':toc2:',
':max-width: 200',
':numbered:',
':doctype: book',
':data-uri:',
':asciimath:',
':toclevels: 4',
'',
sep='\n', file=fp)
print('include::khronoscopyright.txt[]', file=fp)
print('', file=fp)
# Inject the table of contents. Asciidoc really ought to be generating
# this for us.
sections = [
[ protos, 'protos', 'Vulkan Commands' ],
[ handles, 'handles', 'Object Handles' ],
[ structs, 'structs', 'Structures' ],
[ enums, 'enums', 'Enumerations' ],
[ flags, 'flags', 'Flags' ],
[ funcpointers, 'funcpointers', 'Function Pointer Types' ],
[ basetypes, 'basetypes', 'Vulkan Scalar types' ],
[ defines, 'defines', 'C Macro Definitions' ] ]
print('Table of Contents', file=fp)
print('-----------------', file=fp)
for (apiDict,label,title) in sections:
print(' * <<' + label + ',' + title + '>>', file=fp)
print('', file=fp)
for (apiDict,label,title) in sections:
print(title,
''.ljust(len(title), '-'),
'',
':leveloffset: 2',
'',
sep='\n', file=fp)
for refPage in sorted(apiDict.keys()):
if (apiDict == defines or not isextension(refPage)):
print('include::' + refPage + '.txt[]', file=fp)
else:
print('// not including ' + refPage, file=fp)
print('\n' + ':leveloffset: 0' + '\n', file=fp)
# An index of pages could be generated here
if __name__ == '__main__':
global genDict
genDict = {}
parser = argparse.ArgumentParser()
parser.add_argument('-diag', action='store', dest='diagFile',
help='Set the diagnostic file')
parser.add_argument('-warn', action='store', dest='warnFile',
help='Set the warning file')
parser.add_argument('-log', action='store', dest='logFile',
help='Set the log file for both diagnostics and warnings')
parser.add_argument('-basedir', action='store', dest='baseDir',
default='man',
help='Set the base directory in which pages are generated')
parser.add_argument('files', metavar='filename', nargs='*',
help='a filename to extract ref pages from')
parser.add_argument('--version', action='version', version='%(prog)s 1.0')
results = parser.parse_args()
setLogFile(True, True, results.logFile)
setLogFile(True, False, results.diagFile)
setLogFile(False, True, results.warnFile)
baseDir = results.baseDir
for file in results.files:
genRef(file, baseDir)
# Now figure out which pages *weren't* generated from the spec.
# This relies on the dictionaries of API constructs in vkapi.py.
# For Flags (e.g. Vk*Flags types), it's easy to autogenerate pages.
for page in flags.keys():
if not (page in genDict.keys()):
logWarn('Autogenerating flags page:', page, 'which should be included in the spec')
autoGenFlagsPage(baseDir, page)
# autoGenHandlePage is no longer needed because they are added to
# the spec sources now.
# for page in structs.keys():
# if (typeCategory[page] == 'handle'):
# autoGenHandlePage(baseDir, page)
sections = [
[ enums, 'Enumerated Types' ],
[ structs, 'Structures' ],
[ protos, 'Prototypes' ],
[ funcpointers, 'Function Pointers' ],
[ basetypes, 'Vulkan Scalar Types' ] ]
for (apiDict,title) in sections:
flagged = False
for page in apiDict.keys():
if not (page in genDict.keys()):
if (not flagged):
logWarn(title, 'with no ref page generated:')
flagged = True
logWarn(' ', page)
genSinglePageRef(baseDir)

6
doc/specs/vulkan/genRelease
View File

@ -3,11 +3,13 @@
from genspec import *
buildBranch('1.0',
coreTargets = True,
xmlTargets = 'clobber full_install pdf_install',
specTargets = 'xhtml styleguide manhtml manhtmlpages pdf manpdf',
repoDir = '/home/tree/git/vulkan',
outDir = '/home/tree/git/vulkan/out')
buildBranch('1.0-wsi_extensions',
coreTargets = False,
xmlTargets = 'clobber full_install',
specTargets = 'xhtml manhtml',
repoDir = '/home/tree/git/vulkan',
outDir = '/home/tree/git/vulkan/out')

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

@ -53,7 +53,9 @@ def buildRelease(branch, label, outdir,
outdir + '/chunked',
outdir + '/style',
outdir + '/vkspec.html',
'styleguide.html',
outdir + '/styleguide.html',
outdir + '/apispec.*',
outdir + '/readme.pdf',
'specversion.txt')
print('echo Info: Generating headers and spec include files')
@ -74,7 +76,7 @@ def buildRelease(branch, label, outdir,
# Build all target branches
# repoDir = path to the Vulkan git repo containing the specs
# outDir = path to the output base directory in which each branch is generated
def buildBranch(branch, coreTargets, repoDir, outDir):
def buildBranch(branch, xmlTargets, specTargets, repoDir, outDir):
# Directory with vk.xml and generation tools
xmlDir = repoDir + '/src/spec'
# Directory with spec sources
@ -83,14 +85,6 @@ def buildBranch(branch, coreTargets, repoDir, outDir):
miscSrc = repoDir + '/doc/specs/misc'
miscDst = outDir + '/misc'
# Generate specs
if (coreTargets):
xmlTargets = 'clobber full_install pdf_install'
specTargets = 'xhtml pdf styleguide manhtml manpdf manhtmlpages'
else:
xmlTargets = 'clobber full_install'
specTargets = 'xhtml pdf'
buildRelease(branch, branch, outDir + '/' + branch,
xmlDir, xmlTargets, specDir, specTargets,
miscSrc, miscDst)

12
doc/specs/vulkan/handles/VkBuffer.txt Normal file
View File

@ -0,0 +1,12 @@
// WARNING: DO NOT MODIFY! This file is automatically generated from the vk.xml registry
ifndef::doctype-manpage[]
[[VkBuffer,VkBuffer]]
["source","{basebackend@docbook:c++:cpp}",title=""]
endif::doctype-manpage[]
ifdef::doctype-manpage[]
["source","{basebackend@docbook:c++:cpp}"]
endif::doctype-manpage[]
------------------------------------------------------------------------------
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkBuffer)
------------------------------------------------------------------------------

12
doc/specs/vulkan/handles/VkBufferView.txt Normal file
View File

@ -0,0 +1,12 @@
// WARNING: DO NOT MODIFY! This file is automatically generated from the vk.xml registry
ifndef::doctype-manpage[]
[[VkBufferView,VkBufferView]]
["source","{basebackend@docbook:c++:cpp}",title=""]
endif::doctype-manpage[]
ifdef::doctype-manpage[]
["source","{basebackend@docbook:c++:cpp}"]
endif::doctype-manpage[]
------------------------------------------------------------------------------
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkBufferView)
------------------------------------------------------------------------------

12
doc/specs/vulkan/handles/VkCommandBuffer.txt Normal file
View File

@ -0,0 +1,12 @@
// WARNING: DO NOT MODIFY! This file is automatically generated from the vk.xml registry
ifndef::doctype-manpage[]
[[VkCommandBuffer,VkCommandBuffer]]
["source","{basebackend@docbook:c++:cpp}",title=""]
endif::doctype-manpage[]
ifdef::doctype-manpage[]
["source","{basebackend@docbook:c++:cpp}"]
endif::doctype-manpage[]
------------------------------------------------------------------------------
VK_DEFINE_HANDLE(VkCommandBuffer)
------------------------------------------------------------------------------

12
doc/specs/vulkan/handles/VkCommandPool.txt Normal file
View File

@ -0,0 +1,12 @@
// WARNING: DO NOT MODIFY! This file is automatically generated from the vk.xml registry
ifndef::doctype-manpage[]
[[VkCommandPool,VkCommandPool]]
["source","{basebackend@docbook:c++:cpp}",title=""]
endif::doctype-manpage[]
ifdef::doctype-manpage[]
["source","{basebackend@docbook:c++:cpp}"]
endif::doctype-manpage[]
------------------------------------------------------------------------------
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkCommandPool)
------------------------------------------------------------------------------

12
doc/specs/vulkan/handles/VkDescriptorPool.txt Normal file
View File

@ -0,0 +1,12 @@
// WARNING: DO NOT MODIFY! This file is automatically generated from the vk.xml registry
ifndef::doctype-manpage[]
[[VkDescriptorPool,VkDescriptorPool]]
["source","{basebackend@docbook:c++:cpp}",title=""]
endif::doctype-manpage[]
ifdef::doctype-manpage[]
["source","{basebackend@docbook:c++:cpp}"]
endif::doctype-manpage[]
------------------------------------------------------------------------------
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkDescriptorPool)
------------------------------------------------------------------------------

12
doc/specs/vulkan/handles/VkDescriptorSet.txt Normal file
View File

@ -0,0 +1,12 @@
// WARNING: DO NOT MODIFY! This file is automatically generated from the vk.xml registry
ifndef::doctype-manpage[]
[[VkDescriptorSet,VkDescriptorSet]]
["source","{basebackend@docbook:c++:cpp}",title=""]
endif::doctype-manpage[]
ifdef::doctype-manpage[]
["source","{basebackend@docbook:c++:cpp}"]
endif::doctype-manpage[]
------------------------------------------------------------------------------
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkDescriptorSet)
------------------------------------------------------------------------------

12
doc/specs/vulkan/handles/VkDescriptorSetLayout.txt Normal file
View File

@ -0,0 +1,12 @@
// WARNING: DO NOT MODIFY! This file is automatically generated from the vk.xml registry
ifndef::doctype-manpage[]
[[VkDescriptorSetLayout,VkDescriptorSetLayout]]
["source","{basebackend@docbook:c++:cpp}",title=""]
endif::doctype-manpage[]
ifdef::doctype-manpage[]
["source","{basebackend@docbook:c++:cpp}"]
endif::doctype-manpage[]
------------------------------------------------------------------------------
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkDescriptorSetLayout)
------------------------------------------------------------------------------

12
doc/specs/vulkan/handles/VkDevice.txt Normal file
View File

@ -0,0 +1,12 @@
// WARNING: DO NOT MODIFY! This file is automatically generated from the vk.xml registry
ifndef::doctype-manpage[]
[[VkDevice,VkDevice]]
["source","{basebackend@docbook:c++:cpp}",title=""]
endif::doctype-manpage[]
ifdef::doctype-manpage[]
["source","{basebackend@docbook:c++:cpp}"]
endif::doctype-manpage[]
------------------------------------------------------------------------------
VK_DEFINE_HANDLE(VkDevice)
------------------------------------------------------------------------------

12
doc/specs/vulkan/handles/VkDeviceMemory.txt Normal file
View File

@ -0,0 +1,12 @@
// WARNING: DO NOT MODIFY! This file is automatically generated from the vk.xml registry
ifndef::doctype-manpage[]
[[VkDeviceMemory,VkDeviceMemory]]
["source","{basebackend@docbook:c++:cpp}",title=""]
endif::doctype-manpage[]
ifdef::doctype-manpage[]
["source","{basebackend@docbook:c++:cpp}"]
endif::doctype-manpage[]
------------------------------------------------------------------------------
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkDeviceMemory)
------------------------------------------------------------------------------

12
doc/specs/vulkan/handles/VkDisplayKHR.txt Normal file
View File

@ -0,0 +1,12 @@
// WARNING: DO NOT MODIFY! This file is automatically generated from the vk.xml registry
ifndef::doctype-manpage[]
[[VkDisplayKHR,VkDisplayKHR]]
["source","{basebackend@docbook:c++:cpp}",title=""]
endif::doctype-manpage[]
ifdef::doctype-manpage[]
["source","{basebackend@docbook:c++:cpp}"]
endif::doctype-manpage[]
------------------------------------------------------------------------------
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkDisplayKHR)
------------------------------------------------------------------------------

12
doc/specs/vulkan/handles/VkDisplayModeKHR.txt Normal file
View File

@ -0,0 +1,12 @@
// WARNING: DO NOT MODIFY! This file is automatically generated from the vk.xml registry
ifndef::doctype-manpage[]
[[VkDisplayModeKHR,VkDisplayModeKHR]]
["source","{basebackend@docbook:c++:cpp}",title=""]
endif::doctype-manpage[]
ifdef::doctype-manpage[]
["source","{basebackend@docbook:c++:cpp}"]
endif::doctype-manpage[]
------------------------------------------------------------------------------
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkDisplayModeKHR)
------------------------------------------------------------------------------

12
doc/specs/vulkan/handles/VkEvent.txt Normal file
View File

@ -0,0 +1,12 @@
// WARNING: DO NOT MODIFY! This file is automatically generated from the vk.xml registry
ifndef::doctype-manpage[]
[[VkEvent,VkEvent]]
["source","{basebackend@docbook:c++:cpp}",title=""]
endif::doctype-manpage[]
ifdef::doctype-manpage[]
["source","{basebackend@docbook:c++:cpp}"]
endif::doctype-manpage[]
------------------------------------------------------------------------------
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkEvent)
------------------------------------------------------------------------------

12
doc/specs/vulkan/handles/VkFence.txt Normal file
View File

@ -0,0 +1,12 @@
// WARNING: DO NOT MODIFY! This file is automatically generated from the vk.xml registry
ifndef::doctype-manpage[]
[[VkFence,VkFence]]
["source","{basebackend@docbook:c++:cpp}",title=""]
endif::doctype-manpage[]
ifdef::doctype-manpage[]
["source","{basebackend@docbook:c++:cpp}"]
endif::doctype-manpage[]
------------------------------------------------------------------------------
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkFence)
------------------------------------------------------------------------------

12
doc/specs/vulkan/handles/VkFramebuffer.txt Normal file
View File

@ -0,0 +1,12 @@
// WARNING: DO NOT MODIFY! This file is automatically generated from the vk.xml registry
ifndef::doctype-manpage[]
[[VkFramebuffer,VkFramebuffer]]
["source","{basebackend@docbook:c++:cpp}",title=""]
endif::doctype-manpage[]
ifdef::doctype-manpage[]
["source","{basebackend@docbook:c++:cpp}"]
endif::doctype-manpage[]
------------------------------------------------------------------------------
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkFramebuffer)
------------------------------------------------------------------------------

12
doc/specs/vulkan/handles/VkImage.txt Normal file
View File

@ -0,0 +1,12 @@
// WARNING: DO NOT MODIFY! This file is automatically generated from the vk.xml registry
ifndef::doctype-manpage[]
[[VkImage,VkImage]]
["source","{basebackend@docbook:c++:cpp}",title=""]
endif::doctype-manpage[]
ifdef::doctype-manpage[]
["source","{basebackend@docbook:c++:cpp}"]
endif::doctype-manpage[]
------------------------------------------------------------------------------
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkImage)
------------------------------------------------------------------------------

12
doc/specs/vulkan/handles/VkImageView.txt Normal file
View File

@ -0,0 +1,12 @@
// WARNING: DO NOT MODIFY! This file is automatically generated from the vk.xml registry
ifndef::doctype-manpage[]
[[VkImageView,VkImageView]]
["source","{basebackend@docbook:c++:cpp}",title=""]
endif::doctype-manpage[]
ifdef::doctype-manpage[]
["source","{basebackend@docbook:c++:cpp}"]
endif::doctype-manpage[]
------------------------------------------------------------------------------
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkImageView)
------------------------------------------------------------------------------

12
doc/specs/vulkan/handles/VkInstance.txt Normal file
View File

@ -0,0 +1,12 @@
// WARNING: DO NOT MODIFY! This file is automatically generated from the vk.xml registry
ifndef::doctype-manpage[]
[[VkInstance,VkInstance]]
["source","{basebackend@docbook:c++:cpp}",title=""]
endif::doctype-manpage[]
ifdef::doctype-manpage[]
["source","{basebackend@docbook:c++:cpp}"]
endif::doctype-manpage[]
------------------------------------------------------------------------------
VK_DEFINE_HANDLE(VkInstance)
------------------------------------------------------------------------------

12
doc/specs/vulkan/handles/VkPhysicalDevice.txt Normal file
View File

@ -0,0 +1,12 @@
// WARNING: DO NOT MODIFY! This file is automatically generated from the vk.xml registry
ifndef::doctype-manpage[]
[[VkPhysicalDevice,VkPhysicalDevice]]
["source","{basebackend@docbook:c++:cpp}",title=""]
endif::doctype-manpage[]
ifdef::doctype-manpage[]
["source","{basebackend@docbook:c++:cpp}"]
endif::doctype-manpage[]
------------------------------------------------------------------------------
VK_DEFINE_HANDLE(VkPhysicalDevice)
------------------------------------------------------------------------------

12
doc/specs/vulkan/handles/VkPipeline.txt Normal file
View File

@ -0,0 +1,12 @@
// WARNING: DO NOT MODIFY! This file is automatically generated from the vk.xml registry
ifndef::doctype-manpage[]
[[VkPipeline,VkPipeline]]
["source","{basebackend@docbook:c++:cpp}",title=""]
endif::doctype-manpage[]
ifdef::doctype-manpage[]
["source","{basebackend@docbook:c++:cpp}"]
endif::doctype-manpage[]
------------------------------------------------------------------------------
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkPipeline)
------------------------------------------------------------------------------

12
doc/specs/vulkan/handles/VkPipelineCache.txt Normal file
View File

@ -0,0 +1,12 @@
// WARNING: DO NOT MODIFY! This file is automatically generated from the vk.xml registry
ifndef::doctype-manpage[]
[[VkPipelineCache,VkPipelineCache]]
["source","{basebackend@docbook:c++:cpp}",title=""]
endif::doctype-manpage[]
ifdef::doctype-manpage[]
["source","{basebackend@docbook:c++:cpp}"]
endif::doctype-manpage[]
------------------------------------------------------------------------------
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkPipelineCache)
------------------------------------------------------------------------------

12
doc/specs/vulkan/handles/VkPipelineLayout.txt Normal file
View File

@ -0,0 +1,12 @@
// WARNING: DO NOT MODIFY! This file is automatically generated from the vk.xml registry
ifndef::doctype-manpage[]
[[VkPipelineLayout,VkPipelineLayout]]
["source","{basebackend@docbook:c++:cpp}",title=""]
endif::doctype-manpage[]
ifdef::doctype-manpage[]
["source","{basebackend@docbook:c++:cpp}"]
endif::doctype-manpage[]
------------------------------------------------------------------------------
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkPipelineLayout)
------------------------------------------------------------------------------

12
doc/specs/vulkan/handles/VkQueryPool.txt Normal file
View File

@ -0,0 +1,12 @@
// WARNING: DO NOT MODIFY! This file is automatically generated from the vk.xml registry
ifndef::doctype-manpage[]
[[VkQueryPool,VkQueryPool]]
["source","{basebackend@docbook:c++:cpp}",title=""]
endif::doctype-manpage[]
ifdef::doctype-manpage[]
["source","{basebackend@docbook:c++:cpp}"]
endif::doctype-manpage[]
------------------------------------------------------------------------------
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkQueryPool)
------------------------------------------------------------------------------

12
doc/specs/vulkan/handles/VkQueue.txt Normal file
View File

@ -0,0 +1,12 @@
// WARNING: DO NOT MODIFY! This file is automatically generated from the vk.xml registry
ifndef::doctype-manpage[]
[[VkQueue,VkQueue]]
["source","{basebackend@docbook:c++:cpp}",title=""]
endif::doctype-manpage[]
ifdef::doctype-manpage[]
["source","{basebackend@docbook:c++:cpp}"]
endif::doctype-manpage[]
------------------------------------------------------------------------------
VK_DEFINE_HANDLE(VkQueue)
------------------------------------------------------------------------------

12
doc/specs/vulkan/handles/VkRenderPass.txt Normal file
View File

@ -0,0 +1,12 @@
// WARNING: DO NOT MODIFY! This file is automatically generated from the vk.xml registry
ifndef::doctype-manpage[]
[[VkRenderPass,VkRenderPass]]
["source","{basebackend@docbook:c++:cpp}",title=""]
endif::doctype-manpage[]
ifdef::doctype-manpage[]
["source","{basebackend@docbook:c++:cpp}"]
endif::doctype-manpage[]
------------------------------------------------------------------------------
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkRenderPass)
------------------------------------------------------------------------------

12
doc/specs/vulkan/handles/VkSampler.txt Normal file
View File

@ -0,0 +1,12 @@
// WARNING: DO NOT MODIFY! This file is automatically generated from the vk.xml registry
ifndef::doctype-manpage[]
[[VkSampler,VkSampler]]
["source","{basebackend@docbook:c++:cpp}",title=""]
endif::doctype-manpage[]
ifdef::doctype-manpage[]
["source","{basebackend@docbook:c++:cpp}"]
endif::doctype-manpage[]
------------------------------------------------------------------------------
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkSampler)
------------------------------------------------------------------------------

12
doc/specs/vulkan/handles/VkSemaphore.txt Normal file
View File

@ -0,0 +1,12 @@
// WARNING: DO NOT MODIFY! This file is automatically generated from the vk.xml registry
ifndef::doctype-manpage[]
[[VkSemaphore,VkSemaphore]]
["source","{basebackend@docbook:c++:cpp}",title=""]
endif::doctype-manpage[]
ifdef::doctype-manpage[]
["source","{basebackend@docbook:c++:cpp}"]
endif::doctype-manpage[]
------------------------------------------------------------------------------
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkSemaphore)
------------------------------------------------------------------------------

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