Vulkan 1.0 branch 1.0 for release
This commit is contained in:
Jon Leech
commit
d204ac2f69
|
|
@ -0,0 +1,56 @@
|
|||
# Compiled Object files
|
||||
*.slo
|
||||
*.lo
|
||||
*.o
|
||||
*.obj
|
||||
|
||||
# Precompiled Headers
|
||||
*.gch
|
||||
*.pch
|
||||
|
||||
# Compiled Dynamic libraries
|
||||
*.so
|
||||
*.dylib
|
||||
*.dll
|
||||
|
||||
# Fortran module files
|
||||
*.mod
|
||||
|
||||
# Compiled Static libraries
|
||||
*.lai
|
||||
*.la
|
||||
*.a
|
||||
*.lib
|
||||
|
||||
# Executables
|
||||
*.exe
|
||||
*.out
|
||||
*.app
|
||||
|
||||
# Vim temp files
|
||||
*.swp
|
||||
|
||||
# Python cache
|
||||
__pycache__
|
||||
|
||||
# Spec build temporary files and outputs
|
||||
out/checks
|
||||
out/html
|
||||
out/xhtml
|
||||
out/vkspec*
|
||||
out/apispec*
|
||||
out/man
|
||||
out/pdf
|
||||
out/core
|
||||
doc/specs/vulkan/specversion.txt
|
||||
|
||||
# Header build temporary files
|
||||
src/spec/diag.txt
|
||||
|
||||
# OS X folder attributes
|
||||
.DS_Store
|
||||
|
||||
# Auto-generated files
|
||||
src/spec/hostsynctable
|
||||
src/spec/validity
|
||||
src/spec/vulkan-docs
|
||||
|
|
@ -0,0 +1,106 @@
|
|||
Vulkan API Documentation Project
|
||||
================================
|
||||
|
||||
This repository contains formal documentation of the Vulkan API. This
|
||||
includes the main API Specification, the reference (man) pages, the XML API
|
||||
Registry, and related tools and scripts.
|
||||
|
||||
Repository Structure
|
||||
--------------------
|
||||
|
||||
```
|
||||
doc/specs/ Main documentation tree
|
||||
vulkan/ Vulkan specification
|
||||
appendices/ Appendices - one file each
|
||||
chapters/ Chapters - one file each
|
||||
config/ asciidoc configuration
|
||||
images/ Images (figures, diagrams, icons)
|
||||
man/ Reference (manual) pages for API
|
||||
enums/ Includeable snippets for enumerations from vk.xml
|
||||
flags/ Includeable snippets for flags from vk.xml
|
||||
protos/ Includeable snippets for prototypes from vk.xml
|
||||
structs/ Includeable snippets for structures from vk.xml
|
||||
validity/ Includeable validity language from vk.xml
|
||||
misc/ Related specifications (GL_KHR_vulkan_glsl)
|
||||
src/spec/ XML API Registry (vk.xml) and related scripts
|
||||
src/vulkan/ Vulkan headers, generated from the Registry
|
||||
```
|
||||
|
||||
Building the Specification and Reference Pages
|
||||
----------------------------------------------
|
||||
|
||||
To build the documents, you need to install, at a minimum:
|
||||
|
||||
* GNU-compatible make
|
||||
* asciidoc (http://www.methods.co.nz/asciidoc/)
|
||||
|
||||
On some systems/build targets you may also need:
|
||||
|
||||
* dblatex
|
||||
* source-highlight
|
||||
|
||||
These tools are known to work on several varieties of Linux, MacOS X, and
|
||||
Cygwin running under Microsoft Windows.
|
||||
|
||||
There are several make targets in doc/specs/vulkan :
|
||||
|
||||
* make xhtml - Build one large HTML specification document.
|
||||
* make pdf - Build one large PDF specification document.
|
||||
* make chunked - Build an HTML document broken into one file per chapter.
|
||||
* make manhtml - Make HTML API reference (all man pages as one big file).
|
||||
* make manpdf - Make a one-giant PDF API reference.
|
||||
* make manhtmlpages - Make man pages as one-file-per-API.
|
||||
* make manpages - Make man pages as nroff Unix-style (real) man pages.
|
||||
* make allchecks - Run the validation rules on the specification.
|
||||
|
||||
The outputs will be written to $(OUTDIR), which defaults to out/ at the root
|
||||
of the checked-out git repository.
|
||||
|
||||
To build PDF outputs (make pdf, make manpdf), you need a2x (part of the
|
||||
asciidoc) package, dblatex and a LaTeX processor. The PDF builds are
|
||||
currently configured to use a2x to go from asciidoc markdown to docbook, and
|
||||
then run the result through dblatex to go from there to LaTeX and then
|
||||
through your LaTeX processor to PDF.
|
||||
|
||||
Spec Validation
|
||||
---------------
|
||||
|
||||
There are a couple of validation tools which look for inconsistencies and
|
||||
missing material between the specification and ref pages, and the canonical
|
||||
description of the API in vk.xml :
|
||||
|
||||
* checkinc
|
||||
* checklinks
|
||||
* allchecks - both checkinc and checklinks
|
||||
|
||||
They are necessarily heuristic since they're dealing with lots of
|
||||
hand-written material. To use them you'll also need to install:
|
||||
|
||||
* python3
|
||||
|
||||
The '''checkinc''' target uses Unix filters to determine which autogenerated
|
||||
API include files are used (and not used) in the spec. It generates several
|
||||
output files, but the only one you're likely to care about is
|
||||
'''actual.only'''. This is a list of the include files which are *not*
|
||||
referenced anywhere in the spec, and probably correspond to undocumented
|
||||
material in the spec.
|
||||
|
||||
The '''checklinks''' target validates the various internal tagged links in
|
||||
the man pages and spec (e.g. the '''fname:vkFuncBlah''',
|
||||
'''sname:VkStructBlah''', etc.) against the canonical description of the API
|
||||
in vk.xml . It generates two output files, manErrs.txt and specErrs.txt,
|
||||
which report problematic tags and the filenames/lines on which those tags
|
||||
were found.
|
||||
|
||||
|
||||
Generating Headers and Related Files
|
||||
------------------------------------
|
||||
|
||||
The header file (src/vulkan/vulkan.h) and many parts of the specification
|
||||
and reference page documents are generated from descriptions in the XML API
|
||||
Registry (src/spec/vk.xml). All the generated files are checked into the
|
||||
repository, and should not be modified directly. If you change vk.xml,
|
||||
you can regenerated these files by going to src/spec and running:
|
||||
|
||||
* make clobber (get rid of all old generated files)
|
||||
* make full_install (regenerate all the files)
|
||||
File diff suppressed because it is too large
Load Diff
|
|
@ -0,0 +1,284 @@
|
|||
# Copyright (c) 2014-2016 The Khronos Group Inc.
|
||||
# Copyright notice at https://www.khronos.org/registry/speccopyright.html
|
||||
|
||||
# Vulkan Specification makefile
|
||||
#
|
||||
# Default targets:
|
||||
# - XHTML, XHTML chunked, and PDF specs ('allspecs')
|
||||
# - HTML single-document reference pages ('manhtml' and 'manpdf')
|
||||
# - HTML and nroff separate reference pages ('manpages' and 'manhtmlpages')
|
||||
# - Validator scripts ('allchecks')
|
||||
#
|
||||
# The 'html' target is deprecated but still supported, for now. It uses
|
||||
# a different toolchain than XHTML/PDF outputs, isn't quite compatible,
|
||||
# and will not be published, but is faster to generate for quick tests.
|
||||
|
||||
all: alldocs allchecks
|
||||
|
||||
alldocs: allspecs allman
|
||||
|
||||
allspecs: xhtml chunked pdf
|
||||
|
||||
allman: manhtml manpdf manpages manhtmlpages
|
||||
|
||||
allchecks: checkinc checklinks
|
||||
|
||||
# Note that the := assignments below are immediate, not deferred, and
|
||||
# are therefore order-dependent in the Makefile
|
||||
|
||||
APINAME=Vulkan
|
||||
QUIET?=@
|
||||
ASCIIDOC ?= asciidoc.py
|
||||
A2X ?= a2x.py
|
||||
DBLATEX ?= dblatex
|
||||
# DBLATEXPREFIX can be overriden by setting it as an environment variable if
|
||||
# the not installed in the standard location on your distribution
|
||||
DBLATEXPREFIX ?= /etc/asciidoc/dblatex
|
||||
RM=rm -f
|
||||
RMRF=rm -rf
|
||||
MKDIR=mkdir -p
|
||||
CP=cp
|
||||
ECHO:=echo
|
||||
# Target directories for output files
|
||||
# HTMLDIR - 'html' target
|
||||
# XHTMLDIR - 'xhtml' target
|
||||
# PDFDIR - 'pdf' target
|
||||
# CHECKDIR - 'allchecks' target
|
||||
OUTDIR :=../../../out/core
|
||||
HTMLDIR := $(OUTDIR)/html
|
||||
XHTMLDIR := $(OUTDIR)/xhtml
|
||||
PDFDIR := $(OUTDIR)/pdf
|
||||
CHECKDIR := $(OUTDIR)/checks
|
||||
# Images used in the API spec
|
||||
IMAGEPATH :=images
|
||||
ICONPATH :=$(IMAGEPATH)/icons
|
||||
PDFXSL :=config/vkspec-dblatex.xsl
|
||||
PDFSTY :=config/vkspec-dblatex.sty
|
||||
PYTHON ?= python3
|
||||
|
||||
# asciidoc / a2x attributes to set.
|
||||
# XMLLINT normally unset - to detect problems with intermediate files
|
||||
# NOTEOPTS sets options controlling which NOTEs are generated
|
||||
# ATTRIBOPTS sets {apiname} to "Vulkan" and enables MathJax generation
|
||||
# VKCONF contains Vulkan-specific Asciidoc macros
|
||||
# ADOCOPTS options for asciidoc->HTML output
|
||||
# ADOCPDFOPTS options for asciidoc->PDF output via dblatex (not using a2x)
|
||||
# A2XOPTS options for a2x->{HTML,PDF} output
|
||||
XMLLINT = --no-xmllint
|
||||
NOTEOPTS = -a editing-notes -a implementation-guide
|
||||
ATTRIBOPTS = -a apiname=$(APINAME)@ -a mathjax
|
||||
VKCONF = config/vkspec.conf
|
||||
ADOCOPTS = $(ATTRIBOPTS) $(NOTEOPTS) -f config/mathjax-asciidoc.conf \
|
||||
-f $(VKCONF) $(VERBOSE)
|
||||
ADOCPDFOPTS= $(ATTRIBOPTS) $(NOTEOPTS) -f config/mathjax-docbook.conf \
|
||||
-f $(VKCONF) $(VERBOSE)
|
||||
A2XOPTS = $(ATTRIBOPTS) $(NOTEOPTS) \
|
||||
--asciidoc-opts="-f config/mathjax-docbook.conf -f $(VKCONF)" \
|
||||
--xsltproc-opts="--param generate.consistent.ids 1" \
|
||||
$(XMLLINT) $(VERBOSE) --icons
|
||||
|
||||
# XSL customizing Asciibook XSL to pass through equations and add
|
||||
# MathJax. This varies depending on target type.
|
||||
XHTMLXSL = config/docbook-xsl/xhtml.xsl
|
||||
CHUNKEDXSL = config/docbook-xsl/chunked.xsl
|
||||
|
||||
# dblatex options passed two ways, directly to dblatex and via a2x.
|
||||
DBLATEXOPTS := $(KEEP) -V -T db2latex -I. -I images -I images/icons -s $(DBLATEXPREFIX)/asciidoc-dblatex.sty
|
||||
A2XDBLATEXOPTS := --dblatex-opts='$(DBLATEXOPTS)'
|
||||
|
||||
# Set VERBOSE to -v to see what asciidoc is doing.
|
||||
# Set KEEP to -d to retain intermediate dblatex files
|
||||
VERBOSE =
|
||||
KEEP =
|
||||
|
||||
# Misc. files to clean up (see 'checkinc' target below)
|
||||
DIRT :=
|
||||
|
||||
.PHONY: directories
|
||||
|
||||
ICONFILES := \
|
||||
$(ICONPATH)/caution.png \
|
||||
$(ICONPATH)/example.png \
|
||||
$(ICONPATH)/home.png \
|
||||
$(ICONPATH)/important.png \
|
||||
$(ICONPATH)/next.png \
|
||||
$(ICONPATH)/note.png \
|
||||
$(ICONPATH)/prev.png \
|
||||
$(ICONPATH)/tip.png \
|
||||
$(ICONPATH)/up.png \
|
||||
$(ICONPATH)/warning.png
|
||||
PNGFILES := $(ICONFILES) $(wildcard $(IMAGEPATH)/*.png)
|
||||
# This is a horrible hack to avoid pulling in vulkantexture0.svg
|
||||
SVGFILES := $(wildcard $(IMAGEPATH)/[A-Za-uw-z]*.svg)
|
||||
PDFFILES := $(SVGFILES:.svg=.pdf)
|
||||
# Some random directories and files that need to be copied into spec
|
||||
# output directory
|
||||
WEBIMAGES := $(SVGFILES:%=$(HTMLDIR)/%) $(PNGFILES:%=$(HTMLDIR)/%)
|
||||
# File suffix for image targets for HTML and PDF Builds - Asciidoc {svgtype} attribute
|
||||
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)
|
||||
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 generate included file with the spec version, date, and git commit
|
||||
SPECVERSION = specversion.txt
|
||||
SPECREVISION = 1.0
|
||||
SPECREMARK =
|
||||
|
||||
# Spec targets
|
||||
# There is some complexity to try and avoid short virtual targets like 'html'
|
||||
# causing specs to *always* be regenerated.
|
||||
|
||||
html: $(HTMLDIR)/vkspec.html $(TOPDOC) $(COMMONDOCS) $(WEBIMAGES)
|
||||
|
||||
$(HTMLDIR)/vkspec.html: $(VKCONF) $(SPECVERSION) $(TOPDOC) $(COMMONDOCS) $(WEBIMAGES)
|
||||
$(QUIET)if test ! -d $(HTMLDIR) ; then $(MKDIR) $(HTMLDIR) ; fi
|
||||
$(QUIET)$(ASCIIDOC) -b html5 $(ADOCOPTS) -o $(HTMLDIR)/vkspec.html -a svgpdf=$(SVGTYPEHTML) $(TOPDOC)
|
||||
|
||||
xhtml: $(XHTMLDIR)/vkspec.html $(TOPDOC) $(COMMONDOCS)
|
||||
|
||||
$(XHTMLDIR)/vkspec.html: $(VKCONF) $(SPECVERSION) $(TOPDOC) $(COMMONDOCS)
|
||||
$(QUIET)if test ! -d $(XHTMLDIR) ; then $(MKDIR) $(XHTMLDIR) ; fi
|
||||
$(QUIET)$(A2X) $(A2XOPTS) -f xhtml $(TOPDOC) \
|
||||
--xsl-file=$(XHTMLXSL) \
|
||||
-a toc2 -a toclevels=2 --destination-dir=$(XHTMLDIR) \
|
||||
-a svgpdf=$(SVGTYPEHTML)
|
||||
|
||||
chunked: $(OUTDIR)/vkspec.chunked/index.html $(TOPDOC) $(COMMONDOCS)
|
||||
|
||||
$(OUTDIR)/vkspec.chunked/index.html: $(VKCONF) $(SPECVERSION) $(TOPDOC) $(COMMONDOCS)
|
||||
$(QUIET)if test ! -d $(OUTDIR)/chunked ; then $(MKDIR) $(OUTDIR) ; fi
|
||||
$(QUIET)$(A2X) $(A2XOPTS) -f chunked $(TOPDOC) \
|
||||
--xsl-file=$(CHUNKEDXSL) \
|
||||
-a toc2 -a toclevels=2 --destination-dir=$(OUTDIR) \
|
||||
-a svgpdf=$(SVGTYPEHTML)
|
||||
|
||||
pdf: $(PDFDIR)/vkspec.pdf
|
||||
|
||||
$(PDFDIR)/vkspec.pdf: $(PDFXSL) $(PDFSTY) $(PDFDIR)/vkspec.xml
|
||||
$(QUIET)$(DBLATEX) -b pdftex $(DBLATEXOPTS) \
|
||||
-p "$(DBLATEXPREFIX)/asciidoc-dblatex.xsl" \
|
||||
-p $(PDFXSL) -s $(PDFSTY) \
|
||||
$(PDFDIR)/vkspec.xml -O $(PDFDIR)
|
||||
|
||||
$(PDFDIR)/vkspec.xml: $(VKCONF) $(SPECVERSION) $(TOPDOC) $(COMMONDOCS) $(PDFDIR) $(PDFFILES)
|
||||
$(QUIET)$(ASCIIDOC) --backend docbook $(ADOCPDFOPTS) \
|
||||
-a a2x-format=pdf -a svgpdf=pdf \
|
||||
--out-file $(PDFDIR)/vkspec.xml $(TOPDOC)
|
||||
|
||||
$(PDFDIR):
|
||||
$(QUIET)if test ! -d $(PDFDIR) ; then $(MKDIR) $(PDFDIR) ; fi
|
||||
|
||||
# Generate Asciidoc attributes for spec version / date
|
||||
# Could use `git log -1 --format="%cd"` to get branch commit date
|
||||
# This used to be a dependency in the spec html/chunked/pdf targets,
|
||||
# but that's likely to lead to merge conflicts. Just regenerate
|
||||
# when pushing a new spec for review to the sandbox.
|
||||
# The dependency on HEAD is per the suggestion in
|
||||
# http://neugierig.org/software/blog/2014/11/binary-revisions.html
|
||||
GITHEAD := ../../../.git/logs/HEAD
|
||||
$(SPECVERSION): $(GITHEAD)
|
||||
$(QUIET)echo ":revnumber: $(SPECREVISION)" > $@
|
||||
$(QUIET)echo ":revdate: " `date` >> $@
|
||||
$(QUIET)echo ":revremark: $(SPECREMARK) from git branch:" \
|
||||
`git symbolic-ref --short HEAD` \
|
||||
"commit:" `git log -1 --format="%H"` >> $@
|
||||
|
||||
styleguide: $(OUTDIR)/styleguide.html
|
||||
|
||||
STYLESRC = style/styleguide.txt
|
||||
$(OUTDIR)/styleguide.html: $(VKCONF) $(SPECVERSION) $(STYLESRC)
|
||||
$(QUIET)$(ASCIIDOC) -b html5 $(ADOCOPTS) \
|
||||
-o $(OUTDIR)/styleguide.html -a svgpdf=$(SVGTYPEHTML) \
|
||||
$(STYLESRC)
|
||||
|
||||
clean: clean_html clean_pdf clean_chunked clean_checks clean_dirt
|
||||
|
||||
clean_html:
|
||||
$(QUIET)$(RMRF) $(HTMLDIR) $(XHTMLDIR)
|
||||
$(QUIET)$(RM) $(OUTDIR)/apispec.html
|
||||
|
||||
clean_pdf:
|
||||
$(QUIET)$(RM) $(PDFDIR)/vkspec.pdf $(PDFDIR)/vkspec.xml $(OUTDIR)/apispec.pdf
|
||||
|
||||
clean_chunked:
|
||||
$(QUIET)$(RMRF) $(OUTDIR)/vkspec.chunked
|
||||
|
||||
clean_checks:
|
||||
$(QUIET)$(RMRF) $(CHECKDIR)
|
||||
|
||||
clean_dirt:
|
||||
$(QUIET)$(RM) $(DIRT)
|
||||
|
||||
# Man page targets for individual pages
|
||||
MANDIR:=man
|
||||
-include man/manpages.mak
|
||||
|
||||
# Man page targets for HTML and PDF single-file documents
|
||||
|
||||
manpdf: $(OUTDIR)/apispec.pdf
|
||||
|
||||
manhtml: $(OUTDIR)/apispec.html
|
||||
|
||||
$(OUTDIR)/apispec.pdf: $(CONFFILE) man/apispec.txt $(MANSOURCES) $(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)
|
||||
$(QUIET)if test ! -d $(OUTDIR) ; then $(MKDIR) $(OUTDIR) ; fi
|
||||
$(QUIET)$(ASCIIDOC) $(ADOCOPTS) -d book -b html --out-file=$(OUTDIR)/apispec.html man/apispec.txt
|
||||
|
||||
$(HTMLDIR)/images/%: images/%
|
||||
$(QUIET)$(MKDIR) $(@D)
|
||||
$(QUIET)$(CP) $< $@
|
||||
|
||||
# Automated (though heuristic) checks of consistency in the spec and
|
||||
# ref page sources
|
||||
|
||||
# Validate includes in spec source vs. includes actually in the tree
|
||||
# Generates file in $(CHECKDIR)
|
||||
# $(NOTINSPEC) notInSpec.txt - include files only found in XML, not in spec
|
||||
# Intermediate files removed after the run
|
||||
# $(ACTUAL) - include files generated from vk.xml
|
||||
# $(INSPEC) - include files referenced from the spec (not ref page) source
|
||||
# Other files which could be generated but are basically useless
|
||||
# include files only found in the spec source - comm -13 $(ACTUAL) $(INSPEC)
|
||||
# include files both existing and referenced by the spec - comm -12 $(ACTUAL) $(INSPEC)
|
||||
INCFILES = $(CHECKDIR)/incfiles
|
||||
ACTUAL = $(CHECKDIR)/actual
|
||||
INSPEC = $(CHECKDIR)/inspec
|
||||
NOTINSPEC = $(CHECKDIR)/notInSpec.txt
|
||||
checkinc:
|
||||
$(QUIET)if test ! -d $(CHECKDIR) ; then $(MKDIR) $(CHECKDIR) ; fi
|
||||
$(QUIET)ls $(INCLUDES) | sort > $(ACTUAL)
|
||||
$(QUIET)cat $(CHAPTERS) | \
|
||||
egrep '^include::\.\./' | tr -d '[]' | \
|
||||
sed -e 's#^include::\.\./##g' | sort > $(INCFILES)
|
||||
$(QUIET)echo "List of API include files repeatedly included in the API specification" > $(NOTINSPEC)
|
||||
$(QUIET)echo "----------------------------------------------------------------------" >> $(NOTINSPEC)
|
||||
$(QUIET)uniq -d $(INCFILES) >> $(NOTINSPEC)
|
||||
$(QUIET)(echo ; echo "List of API include files not referenced in the API specification") >> $(NOTINSPEC)
|
||||
$(QUIET)echo "-----------------------------------------------------------------" >> $(NOTINSPEC)
|
||||
$(QUIET)comm -23 $(ACTUAL) $(INCFILES) >> $(NOTINSPEC)
|
||||
$(QUIET)echo "Include files not found in the spec source are in $(CHECKDIR)/notInSpec.txt"
|
||||
$(QUIET)$(RM) $(INCFILES) $(ACTUAL) $(INSPEC)
|
||||
|
||||
# Validate link tags in spec and ref page sources against vk.xml
|
||||
# (represented in vkapi.py, which is autogenerated along with the
|
||||
# headers and ref page includes).
|
||||
# Generates files in $(CHECKDIR):
|
||||
# specErrs.txt - errors & warnings in API spec
|
||||
# manErrs.txt - errors & warnings in man pages
|
||||
checklinks:
|
||||
$(QUIET)if test ! -d $(CHECKDIR) ; then $(MKDIR) $(CHECKDIR) ; fi
|
||||
$(QUIET)echo "Generating link checks for spec (specErrs.txt) and man pages (manErrs.txt)"
|
||||
$(QUIET)$(PYTHON) checkLinks.py -follow man/[Vv][Kk]*.txt > $(CHECKDIR)/manErrs.txt
|
||||
$(QUIET)$(PYTHON) checkLinks.py -follow $(CHAPTERS) > $(CHECKDIR)/specErrs.txt
|
||||
|
||||
# README file with build instructions
|
||||
README.html: README.txt
|
||||
$(ASCIIDOC) -b html5 README.txt
|
||||
File diff suppressed because it is too large
Load Diff
|
|
@ -0,0 +1,3 @@
|
|||
See README.html (asciidoc source in README.txt) for instructions and
|
||||
notes about building the spec. Unfortunately gitlab won't render HTML or
|
||||
Asciidoc in its web view page, so this README.md is of limited utility.
|
||||
|
|
@ -0,0 +1,342 @@
|
|||
= Vulkan Specification Build Instructions and Notes =
|
||||
|
||||
* <<intro,Introduction>>
|
||||
* <<building,Building the spec>>
|
||||
* <<macros,Our asciidoc macros>>
|
||||
* <<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:
|
||||
|
||||
$ make all
|
||||
|
||||
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:
|
||||
|
||||
* 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
|
||||
* 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/*
|
||||
* 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
|
||||
** Validator script output for reference pages -
|
||||
$(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.
|
||||
|
||||
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).
|
||||
|
||||
[[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.
|
||||
|
||||
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
|
||||
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 .
|
||||
|
||||
=== Rebuilding The Generated Images ===
|
||||
|
||||
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.
|
||||
|
||||
[[macros]]
|
||||
== Our Asciidoc Macros ==
|
||||
|
||||
We use a bunch of custom macros in the reference pages and API spec asciidoc
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
Most of these macros deeply need more intuitive names.
|
||||
|
||||
[[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
|
||||
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.
|
||||
|
||||
Added, removed, and changed material is marked with the asciidoc *roles*
|
||||
named _added_, _removed_, and _changed_ respectively. They can be used to
|
||||
mark an entire paragraph, as follows:
|
||||
|
||||
[role="change"]
|
||||
This paragraph shows change markings.
|
||||
|
||||
Or a few words in a sentence, as follows:
|
||||
|
||||
This sentence contains [added]#some added words# and [removed]#some
|
||||
removed words#.
|
||||
|
||||
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').
|
||||
|
||||
Normative language is marked with the asciidoc *role* named _normative_.
|
||||
It can be used to mark entire paragraphs or spans of words, in the
|
||||
same fashion as change markings (described above). In addition, the
|
||||
normative terminology macros, such as must: and may: and cannot:,
|
||||
always use this role.
|
||||
|
||||
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
|
||||
|
||||
Equations should be written using the latexmath: inline and block macros.
|
||||
The contents of the latexmath: blocks should be LaTeX math notation,
|
||||
surrounded by appropriate delimiters - pass:[$$], +++\[\\]+++, pass:[\(\)],
|
||||
or pass:[\begin{env}/\end{env}] math environments such as pass:[{equation*}]
|
||||
or pass:[{align*}].
|
||||
|
||||
The asciidoc macros and configuration files, as well as the dblatex
|
||||
customization layers, have been modified significantly so that LaTeX math is
|
||||
passed through unmodified to all HTML output forms (using the MathJax engine
|
||||
for real-time rendering of equations) and to dblatex for PDF output.
|
||||
|
||||
The following caveats apply:
|
||||
|
||||
* The special characters < > & 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.
|
||||
* 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
|
||||
with +++\[\\]+++ brackets. That is not legal LaTeX math and will break the
|
||||
PDF build. It is good practice to make sure all spec targets build
|
||||
properly before proposing a merge to master.
|
||||
* Arbitrary LaTeX constructs cannot be used with MathJax. It is an equation
|
||||
renderer, not an full LaTeX engine. So imbedding stuff like \Large or
|
||||
pass:[\hbox{\tt\small VK\_FOO}] does not work in any of the HTML backends
|
||||
and should be avoided.
|
||||
|
||||
[[anchors]]
|
||||
== Asciidoc Anchors And Xrefs
|
||||
|
||||
In the API spec, sections can have anchors (labels) applied with the
|
||||
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':
|
||||
|
||||
++++
|
||||
[[synchronization-primitives]]
|
||||
Synchronization Primitives
|
||||
++++
|
||||
|
||||
Cross-references to those anchors can then be generated with, for example,
|
||||
|
||||
++++
|
||||
See the <<synchronization-primitives>> section for discussion
|
||||
of fences, semaphores, and events.
|
||||
++++
|
||||
|
||||
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:
|
||||
|
||||
Fences are used with the +++<<vkQueueSubmit>>+++ command...
|
||||
|
||||
[[depends]]
|
||||
== Software Dependencies ==
|
||||
|
||||
This section describes the software components used by the Vulkan spec
|
||||
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.
|
||||
|
||||
- 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).
|
||||
- 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 ===
|
||||
|
||||
The cygwin installer is at http://www.cygwin.org. Use the 64-bit version,
|
||||
because the 32-bit version does not include the latest version of asciidoc
|
||||
required for this project.
|
||||
|
||||
Required Cygwin packages (current version):
|
||||
|
||||
* Devel/make (4.1-1)
|
||||
* Python/python (2.7.10-1) - Needed for asciidoc toolchain
|
||||
* Python/python3 (3.4.3-1)
|
||||
* Python/python3-lxml (3.4.4-1) - Needed for generating vulkan.h
|
||||
* Text/asciidoc (8.6.8-1)
|
||||
* Text/dblatex (0.3.4-1)
|
||||
* Text/source-highlight (3.1.8-1)
|
||||
|
||||
Optional Cygwin packages (current version):
|
||||
|
||||
* Devel/gcc-core (4.9.3-1) - Needed for validating generated headers
|
||||
* 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
|
||||
|
||||
* 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.
|
||||
* 2015/09/21 - Add descriptions of LaTeX+MathJax math support for all
|
||||
output formats.
|
||||
* 2015/09/02 - Added Cygwin package info
|
||||
* 2015/09/02 - Initial version documenting macros, required toolchain
|
||||
components and versions, etc.
|
||||
|
||||
|
||||
|
|
@ -0,0 +1,118 @@
|
|||
// Copyright (c) 2015-2016 The Khronos Group Inc.
|
||||
// Copyright notice at https://www.khronos.org/registry/speccopyright.html
|
||||
|
||||
[appendix]
|
||||
= Compressed Image Formats
|
||||
|
||||
The compressed texture formats used by Vulkan are described in the
|
||||
specifically identified sections of the <<Khronos Data Format
|
||||
Specification>>, version 1.1.
|
||||
|
||||
Unless otherwise described, the quantities encoded in these compressed
|
||||
formats are treated as normalized, unsigned values.
|
||||
|
||||
<<<
|
||||
|
||||
[[appendix-compressedtex-bc]]
|
||||
== Block Compressed Image Formats
|
||||
|
||||
Those formats listed as ``sRGB-encoded'' have in-memory representations of
|
||||
_R_, _G_ and _B_ components which are nonlinearly-encoded as
|
||||
latexmath:[$R'$], latexmath:[$G'$], and latexmath:[$B'$]; any alpha
|
||||
component is unchanged. As part of filtering, the nonlinear
|
||||
latexmath:[$R'$], latexmath:[$G'$], and latexmath:[$B'$] values are
|
||||
converted to linear _R_, _G_, and _B_ components; any alpha component is
|
||||
unchanged. The conversion between linear and nonlinear encoding is performed
|
||||
as described in the ``KHR_DF_TRANSFER_SRGB'' section of the Khronos Data
|
||||
Format Specification.
|
||||
|
||||
.Mapping of {apiname} BC formats to descriptions
|
||||
[width="90%",options="header",cols="5,4"]
|
||||
|==============================
|
||||
| VkFormat | Data Format Specification description
|
||||
2+^| Formats described in the ``S3TC Compressed Texture Image Formats'' chapter
|
||||
| ename:VK_FORMAT_BC1_RGB_UNORM_BLOCK |BC1 with no alpha
|
||||
| ename:VK_FORMAT_BC1_RGB_SRGB_BLOCK |BC1 with no alpha, sRGB-encoded
|
||||
| ename:VK_FORMAT_BC1_RGBA_UNORM_BLOCK|BC1 with alpha
|
||||
| ename:VK_FORMAT_BC1_RGBA_SRGB_BLOCK |BC1 with alpha, sRGB-encoded
|
||||
| ename:VK_FORMAT_BC2_UNORM_BLOCK |BC2
|
||||
| ename:VK_FORMAT_BC2_SRGB_BLOCK |BC2, sRGB-encoded
|
||||
| ename:VK_FORMAT_BC3_UNORM_BLOCK |BC3
|
||||
| ename:VK_FORMAT_BC3_SRGB_BLOCK |BC3, sRGB-encoded
|
||||
2+^| Formats described in the ``RGTC Compressed Texture Image Formats'' chapter
|
||||
| ename:VK_FORMAT_BC4_UNORM_BLOCK |BC4 unsigned
|
||||
| ename:VK_FORMAT_BC4_SNORM_BLOCK |BC4 signed
|
||||
| ename:VK_FORMAT_BC5_UNORM_BLOCK |BC5 unsigned
|
||||
| ename:VK_FORMAT_BC5_SNORM_BLOCK |BC5 signed
|
||||
2+^| Formats described in the ``BPTC Compressed Texture Image Formats'' chapter
|
||||
| ename:VK_FORMAT_BC6H_UFLOAT_BLOCK |BC6H (unsigned version)
|
||||
| ename:VK_FORMAT_BC6H_SFLOAT_BLOCK |BC6H (signed version)
|
||||
| ename:VK_FORMAT_BC7_UNORM_BLOCK |BC7
|
||||
| ename:VK_FORMAT_BC7_SRGB_BLOCK |BC7, sRGB-encoded
|
||||
|=============================
|
||||
|
||||
<<<
|
||||
|
||||
[[appendix-compressedtex-etc2]]
|
||||
== ETC Compressed Image Formats
|
||||
|
||||
The following formats are described in the ``ETC2 Compressed Texture Image
|
||||
Formats'' chapter of the Khronos Data Format Specification.
|
||||
|
||||
.Mapping of {apiname} ETC formats to descriptions
|
||||
[options="header",cols="1,1"]
|
||||
|==============================
|
||||
| VkFormat | Data Format Specification description
|
||||
| ename:VK_FORMAT_ETC2_R8G8B8_UNORM_BLOCK |RGB ETC2
|
||||
| ename:VK_FORMAT_ETC2_R8G8B8_SRGB_BLOCK |RGB ETC2 with sRGB encoding
|
||||
| ename:VK_FORMAT_ETC2_R8G8B8A1_UNORM_BLOCK |RGB ETC2 with punchthrough alpha
|
||||
| ename:VK_FORMAT_ETC2_R8G8B8A1_SRGB_BLOCK |RGB ETC2 with punchthrough alpha and sRGB
|
||||
| ename:VK_FORMAT_ETC2_R8G8B8A8_UNORM_BLOCK |RGBA ETC2
|
||||
| ename:VK_FORMAT_ETC2_R8G8B8A8_SRGB_BLOCK |RGBA ETC2 with sRGB encoding
|
||||
| ename:VK_FORMAT_EAC_R11_UNORM_BLOCK |Unsigned R11 EAC
|
||||
| ename:VK_FORMAT_EAC_R11_SNORM_BLOCK |Signed R11 EAC
|
||||
| ename:VK_FORMAT_EAC_R11G11_UNORM_BLOCK |Unsigned RG11 EAC
|
||||
| ename:VK_FORMAT_EAC_R11G11_SNORM_BLOCK |Signed RG11 EAC
|
||||
|=============================
|
||||
|
||||
<<<
|
||||
|
||||
[[appendix-compressedtex-astc]]
|
||||
== ASTC Compressed Image Formats
|
||||
|
||||
ASTC formats are described in the ``ASTC Compressed Texture Image Formats''
|
||||
chapter of the Khronos Data Format Specification.
|
||||
|
||||
.Mapping of {apiname} ASTC formats to descriptions
|
||||
[width="80%",options="header",cols="6,1,1"]
|
||||
|==============================
|
||||
| VkFormat ^| Block size ^| sRGB output
|
||||
| ename:VK_FORMAT_ASTC_4x4_UNORM_BLOCK ^|latexmath:[$4\times 4$] ^|No
|
||||
| ename:VK_FORMAT_ASTC_4x4_SRGB_BLOCK ^|latexmath:[$4\times 4$] ^|Yes
|
||||
| ename:VK_FORMAT_ASTC_5x4_UNORM_BLOCK ^|latexmath:[$5\times 4$] ^|No
|
||||
| ename:VK_FORMAT_ASTC_5x4_SRGB_BLOCK ^|latexmath:[$5\times 4$] ^|Yes
|
||||
| ename:VK_FORMAT_ASTC_5x5_UNORM_BLOCK ^|latexmath:[$5\times 5$] ^|No
|
||||
| ename:VK_FORMAT_ASTC_5x5_SRGB_BLOCK ^|latexmath:[$5\times 5$] ^|Yes
|
||||
| ename:VK_FORMAT_ASTC_6x5_UNORM_BLOCK ^|latexmath:[$6\times 5$] ^|No
|
||||
| ename:VK_FORMAT_ASTC_6x5_SRGB_BLOCK ^|latexmath:[$6\times 5$] ^|Yes
|
||||
| ename:VK_FORMAT_ASTC_6x6_UNORM_BLOCK ^|latexmath:[$6\times 6$] ^|No
|
||||
| ename:VK_FORMAT_ASTC_6x6_SRGB_BLOCK ^|latexmath:[$6\times 6$] ^|Yes
|
||||
| ename:VK_FORMAT_ASTC_8x5_UNORM_BLOCK ^|latexmath:[$8\times 5$] ^|No
|
||||
| ename:VK_FORMAT_ASTC_8x5_SRGB_BLOCK ^|latexmath:[$8\times 5$] ^|Yes
|
||||
| ename:VK_FORMAT_ASTC_8x6_UNORM_BLOCK ^|latexmath:[$8\times 6$] ^|No
|
||||
| ename:VK_FORMAT_ASTC_8x6_SRGB_BLOCK ^|latexmath:[$8\times 6$] ^|Yes
|
||||
| ename:VK_FORMAT_ASTC_8x8_UNORM_BLOCK ^|latexmath:[$8\times 8$] ^|No
|
||||
| ename:VK_FORMAT_ASTC_8x8_SRGB_BLOCK ^|latexmath:[$8\times 8$] ^|Yes
|
||||
| ename:VK_FORMAT_ASTC_10x5_UNORM_BLOCK ^|latexmath:[$10\times 5$] ^|No
|
||||
| ename:VK_FORMAT_ASTC_10x5_SRGB_BLOCK ^|latexmath:[$10\times 5$] ^|Yes
|
||||
| ename:VK_FORMAT_ASTC_10x6_UNORM_BLOCK ^|latexmath:[$10\times 6$] ^|No
|
||||
| ename:VK_FORMAT_ASTC_10x6_SRGB_BLOCK ^|latexmath:[$10\times 6$] ^|Yes
|
||||
| ename:VK_FORMAT_ASTC_10x8_UNORM_BLOCK ^|latexmath:[$10\times 8$] ^|No
|
||||
| ename:VK_FORMAT_ASTC_10x8_SRGB_BLOCK ^|latexmath:[$10\times 8$] ^|Yes
|
||||
| ename:VK_FORMAT_ASTC_10x10_UNORM_BLOCK ^|latexmath:[$10\times 10$] ^|No
|
||||
| ename:VK_FORMAT_ASTC_10x10_SRGB_BLOCK ^|latexmath:[$10\times 10$] ^|Yes
|
||||
| ename:VK_FORMAT_ASTC_12x10_UNORM_BLOCK ^|latexmath:[$12\times 10$] ^|No
|
||||
| ename:VK_FORMAT_ASTC_12x10_SRGB_BLOCK ^|latexmath:[$12\times 10$] ^|Yes
|
||||
| ename:VK_FORMAT_ASTC_12x12_UNORM_BLOCK ^|latexmath:[$12\times 12$] ^|No
|
||||
| ename:VK_FORMAT_ASTC_12x12_SRGB_BLOCK ^|latexmath:[$12\times 12$] ^|Yes
|
||||
|==============================
|
||||
|
|
@ -0,0 +1,161 @@
|
|||
// Copyright (c) 2015-2016 The Khronos Group Inc.
|
||||
// Copyright notice at https://www.khronos.org/registry/speccopyright.html
|
||||
|
||||
[appendix]
|
||||
[[credits]]
|
||||
= Credits
|
||||
|
||||
Vulkan 1.0 is the result of contributions from many people and companies
|
||||
participating in the Khronos Vulkan Working Group, as well as input from the
|
||||
Vulkan Advisory Panel.
|
||||
|
||||
Members of the Working Group, including the company that they represented at
|
||||
the time of their contributions, are listed below. Some specific
|
||||
contributions made by individuals are listed together with their name.
|
||||
|
||||
* Adam Jackson, Red Hat
|
||||
* Adam Śmigielski, Mobica
|
||||
* Alex Bourd, Qualcomm Technologies, Inc.
|
||||
* Alexander Galazin, ARM
|
||||
* Allen Hux, Intel
|
||||
* Alon Or-bach, Samsung Electronics (WSI technical sub-group chair)
|
||||
* Andrew Cox, Samsung Electronics
|
||||
* Andrew Garrard, Samsung Electronics (format wrangler)
|
||||
* Andrew Poole, Samsung Electronics
|
||||
* Andrew Rafter, Samsung Electronics
|
||||
* Andrew Richards, Codeplay Software Ltd.
|
||||
* Andrew Woloszyn, Google
|
||||
* Antoine Labour, Google
|
||||
* Aras Pranckevičius, Unity
|
||||
* Ashwin Kolhe, NVIDIA
|
||||
* Ben Bowman, Imagination Technologies
|
||||
* Benj Lipchak
|
||||
* Bill Hollings, The Brenwill Workshop
|
||||
* Bill Licea-Kane, Qualcomm Technologies, Inc.
|
||||
* Brent E. Insko, Intel
|
||||
* Brian Ellis, Qualcomm Technologies, Inc.
|
||||
* Cass Everitt, Oculus VR
|
||||
* Cemil Azizoglu, Canonical
|
||||
* Chad Versace, Intel
|
||||
* Chang-Hyo Yu, Samsung Electronics
|
||||
* Chia-I Wu, LunarG
|
||||
* Chris Frascati, Qualcomm Technologies, Inc.
|
||||
* Christophe Riccio, Unity
|
||||
* Cody Northrop, LunarG
|
||||
* Courtney Goeltzenleuchter, LunarG
|
||||
* Damien Leone, NVIDIA
|
||||
* Dan Baker, Oxide Games
|
||||
* Dan Ginsburg, Valve
|
||||
* Daniel Johnston, Intel
|
||||
* Daniel Koch, NVIDIA (<<interfaces,Shader Interfaces>>;
|
||||
<<features,Features, Limits, and Formats>>)
|
||||
* Daniel Rakos, AMD
|
||||
* David Airlie, Red Hat
|
||||
* David Neto, Google
|
||||
* David Mao, AMD
|
||||
* David Yu, Pixar
|
||||
* Dominik Witczak, AMD
|
||||
* Frank (LingJun) Chen, Qualcomm Technologies, Inc.
|
||||
* Fred Liao, Mediatek
|
||||
* Gabe Dagani, Freescale
|
||||
* Graeme Leese, Broadcom
|
||||
* Graham Connor, Imagination Technologies
|
||||
* Graham Sellers, AMD
|
||||
* Hwanyong Lee, Kyungpook National University
|
||||
* Ian Elliott, LunarG
|
||||
* Ian Romanick, Intel
|
||||
* James Jones, NVIDIA
|
||||
* James Hughes, Oculus VR
|
||||
* Jan Hermes, Continental Corporation
|
||||
* Jan-Harald Fredriksen, ARM
|
||||
* Jason Ekstrand, Intel
|
||||
* Jeff Bolz, NVIDIA (extensive contributions, exhaustive review and
|
||||
rewrites for technical correctness)
|
||||
* Jeff Juliano, NVIDIA
|
||||
* Jeff Vigil, Qualcomm Technologies, Inc.
|
||||
* Jens Owen, LunarG
|
||||
* Jeremy Hayes, LunarG
|
||||
* Jesse Barker, ARM
|
||||
* Jesse Hall, Google
|
||||
* Johannes van Waveren, Oculus VR
|
||||
* John Kessenich, Independent (SPIR-V and GLSL for Vulkan spec author)
|
||||
* John McDonald, Valve
|
||||
* Jon Ashburn, LunarG
|
||||
* Jon Leech, Independent (XML toolchain, normative language, release
|
||||
wrangler)
|
||||
* Jonas Gustavsson, Sony Mobile
|
||||
* Jonathan Hamilton, Imagination Technologies
|
||||
* Jungwoo Kim, Samsung Electronics
|
||||
* Kenneth Benzie, Codeplay Software Ltd.
|
||||
* Kerch Holt, NVIDIA (SPIR-V technical sub-group chair)
|
||||
* Kristian Kristensen, Intel
|
||||
* Krzysztof Iwanicki, Samsung Electronics
|
||||
* Larry Seiler, Intel
|
||||
* Lutz Latta, Lucasfilm
|
||||
* Maria Rovatsou, Codeplay Software Ltd.
|
||||
* Mark Callow
|
||||
* Mark Lobodzinski, LunarG
|
||||
* Mateusz Przybylski, Intel
|
||||
* Mathias Heyer, NVIDIA
|
||||
* Mathias Schott, NVIDIA
|
||||
* Maxim Lukyanov, Samsung Electronics
|
||||
* Maurice Ribble, Qualcomm Technologies, Inc.
|
||||
* Michael Lentine, Google
|
||||
* Michael Worcester, Imagination Technologies
|
||||
* Michal Pietrasiuk, Intel
|
||||
* Mika Isojarvi, Google
|
||||
* Mike Stroyan, LunarG
|
||||
* Minyoung Son, Samsung Electronics
|
||||
* Mitch Singer, AMD
|
||||
* Mythri Venugopal, Samsung Electronics
|
||||
* Naveen Leekha, Google
|
||||
* Neil Henning, Codeplay Software Ltd.
|
||||
* Neil Trevett, NVIDIA
|
||||
* Nick Penwarden, Epic Games
|
||||
* Niklas Smedberg, Epic Games
|
||||
* Norbert Nopper, Freescale
|
||||
* Pat Brown, NVIDIA
|
||||
* Patrick Doane, Blizzard Entertainment
|
||||
* Peter Lohrmann, Valve
|
||||
* Pierre Boudier, NVIDIA
|
||||
* Pierre-Loup A. Griffais, Valve
|
||||
* Piers Daniell, NVIDIA (dynamic state, copy commands, memory types)
|
||||
* Piotr Bialecki, Intel
|
||||
* Prabindh Sundareson, Samsung Electronics
|
||||
* Pyry Haulos, Google (Vulkan conformance test subcommittee chair)
|
||||
* Ray Smith, ARM
|
||||
* Rob Stepinski, Transgaming
|
||||
* Robert J. Simpson, Qualcomm Technologies, Inc.
|
||||
* Rolando Caloca Olivares, Epic Games
|
||||
* Roy Ju, Mediatek
|
||||
* Rufus Hamede, Imagination Technologies
|
||||
* Sean Ellis, ARM
|
||||
* Sean Harmer, KDAB
|
||||
* Shannon Woods, Google
|
||||
* Slawomir Cygan, Intel
|
||||
* Slawomir Grajewski, Intel
|
||||
* Stefanus Du Toit, Google
|
||||
* Steve Hill, Broadcom
|
||||
* Steve Viggers, Core Avionics & Industrial Inc.
|
||||
* Stuart Smith, Imagination Technologies
|
||||
* Tim Foley, Intel
|
||||
* Timo Suoranta, AMD
|
||||
* Timothy Lottes, AMD
|
||||
* Tobias Hector, Imagination Technologies (validity language and
|
||||
toolchain)
|
||||
* Tobin Ehlis, LunarG
|
||||
* Tom Olson, ARM (working group chair)
|
||||
* Tomasz Kubale, Intel
|
||||
* Tony Barbour, LunarG
|
||||
* Wayne Lister, Imagination Technologies
|
||||
* Yanjun Zhang, Vivante
|
||||
* Zhenghong Wang, Mediatek
|
||||
|
||||
In addition to the Working Group, the Vulkan Advisory Panel members provided
|
||||
important real-world usage information and advice that helped guide design
|
||||
decisions.
|
||||
|
||||
Administrative support to the Working Group was provided by members of Gold
|
||||
Standard Group, including Andrew Riegel, Elizabeth Riegel, Glenn Fredericks,
|
||||
Kathleen Mattson and Michelle Clark. Technical support was provided by James
|
||||
Riordon, webmaster of Khronos.org and OpenGL.org.
|
||||
|
|
@ -0,0 +1,565 @@
|
|||
// Copyright (c) 2015-2016 The Khronos Group Inc.
|
||||
// Copyright notice at https://www.khronos.org/registry/speccopyright.html
|
||||
|
||||
[appendix]
|
||||
= Layers & Extensions
|
||||
|
||||
Extensions to the {apiname} API can: be defined by authors, groups of
|
||||
authors, and the Khronos {apiname} Working Group. In order not to compromise
|
||||
the readability of the {apiname} Specification, the core Specification does
|
||||
not incorporate most extensions. The online registry of extensions is
|
||||
available at URL
|
||||
|
||||
http://www.khronos.org/registry/vulkan/
|
||||
|
||||
and allows generating versions of the Specification incorporating different
|
||||
extensions.
|
||||
|
||||
[NOTE]
|
||||
.Note
|
||||
====
|
||||
The mechanism and process of specifying extensions is subject to change, as
|
||||
we receive feedback from authors and further requirements of documentation
|
||||
tooling. This appendix will be updated as this evolves.
|
||||
====
|
||||
|
||||
|
||||
== Introduction
|
||||
|
||||
The Khronos extension registries and extension naming conventions serve
|
||||
several purposes:
|
||||
|
||||
* Avoiding naming collisions between extensions developed by mutually
|
||||
unaware parties, both in the extension names themselves, as well as
|
||||
their token, command, and type names.
|
||||
* Allocating enumerant values for tokens added by extensions
|
||||
* Creating a defined order between extensions. Extensions with higher
|
||||
numbers may: have dependencies upon extensions with lower numbers, and
|
||||
must: define any relevant interactions with lower-numbered extensions.
|
||||
* Provides a central repository for documentation and header changes
|
||||
associated with extensions
|
||||
|
||||
{apiname}'s design and general software development trends introduces two
|
||||
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
|
||||
single global set of token values.
|
||||
|
||||
|
||||
== General Rules/Guidelines
|
||||
|
||||
Some general rules to simplify the specific rules below:
|
||||
|
||||
* Extensions and layers must: each have a globally unique name.
|
||||
* All commands and tokens must: have a globally unique name.
|
||||
* Extensions can: expose new commands, types, and/or tokens, but layers
|
||||
mustnot:.
|
||||
** However, layers can: expose their own extensions, which in turn are
|
||||
allowed to expose new commands and tokens.
|
||||
* All extensions must: be registered with Khronos.
|
||||
* Extensions must: be strictly additive and backwards-compatible. That is,
|
||||
extensions mustnot: remove existing functionality, or change existing
|
||||
default behaviors. A {apiname} implementation may: support any
|
||||
combination of extensions, but applications written using only the core
|
||||
API, or a subset of the supported extensions, must: continue to work in
|
||||
such an implementation without changes in behavior.
|
||||
|
||||
== Extension and Layer Naming Conventions
|
||||
|
||||
* Extensions are named with the syntax: +VK_AUTHOR_<name>+.
|
||||
* Layers are named with the syntax: +VK_LAYER_{AUTHOR|FQDN}_<name>+.
|
||||
|
||||
Both extensions and layer names include a +VK_+ prefix. In addition, layers
|
||||
add a +LAYER_+ prefix. Extension and layer names also contain an _author
|
||||
prefix_ identifying the author of the extension/layer. This prefix is a
|
||||
short, capitalized, registered string identifying an author, such as a
|
||||
Khronos member developing {apiname} implementations for their devices, or a
|
||||
non-Khronos developer creating {apiname} layers.
|
||||
|
||||
Some authors have platform communities they wish to distinguish between, and
|
||||
can: register additional author prefixes for that purpose. For example,
|
||||
Google has separate Android and Chrome communities.
|
||||
|
||||
Details on how to register an author prefix are provided below. Layer
|
||||
authors not wishing to register an author prefix with Khronos can: instead
|
||||
use a fully-qualified domain name (FQDN) as the prefix. The FQDN should: be
|
||||
a domain name owned by the author. FQDNs cannot: be used for extensions,
|
||||
only for layers.
|
||||
|
||||
* The following are examples of extension and layer names, demonstrating
|
||||
the above syntax:
|
||||
** Extension names all use the base prefix +VK_+.
|
||||
** Khronos-ratified extensions add the special author prefix +KHR+, and
|
||||
will use the prefix +VK_KHR_+.
|
||||
** The following author prefixes are reserved and mustnot: be used:
|
||||
*** +VK+ - To avoid confusion with the top-level +VK_+ prefix.
|
||||
*** +VULKAN+ - To avoid confusion with the name of the {apiname} API.
|
||||
*** +LAYER+ - To avoid confusion with the higher-level ``LAYER'' prefix.
|
||||
*** +KHRONOS+ - To avoid confusion with the Khronos organization.
|
||||
** Multi-author extensions that have not been ratified by Khronos (those
|
||||
developed via cooperation between, and intended to be supported by two
|
||||
or more registered authors) add the special author prefix +EXT+ to the
|
||||
base prefix, and will use the prefix +VK_EXT_+.
|
||||
** Traditional author-specific extensions developed by one author (or one
|
||||
author in cooperation with non-authors) add the author prefix to the
|
||||
base prefix. For example, NVIDIA will use the prefix +VK_NV_+, and
|
||||
Valve will use the prefix +VK_VALVE_+. Some authors can: have
|
||||
additional registered author prefixes for special purposes. For
|
||||
example, an Android extension developed by Google - but part of an
|
||||
Android open-source community project, and so not a proprietary Google
|
||||
extension - will use the prefix +VK_ANDROID_+.
|
||||
** Layer names follow the same conventions as extensions, but use the base
|
||||
prefix +VK_LAYER_+.
|
||||
** Because layers need not be registered with Khronos, an alternative
|
||||
prefix mechanism is needed to allow creating unique layer names without
|
||||
registering an author prefix. Layer authors that prefer not to register
|
||||
an author prefix can: instead use a fully-qualified domain name (FQDN)
|
||||
in reverse-order as an author prefix, using all lower-case characters,
|
||||
and replacing +.+ (period) with `_` (underscore) characters. For
|
||||
example, a layer written by the owner of www.3dxcl.com would use the
|
||||
prefix `VK_LAYER_com_3dxcl_www_`. FQDNs must: be encoded in UTF-8.
|
||||
|
||||
|
||||
== Extension Command, Token, and Type Naming Conventions
|
||||
|
||||
Extensions may: add new commands, tokens, and types, or collectively
|
||||
``objects'' to the {apiname} API. These objects also require globally unique
|
||||
names. These names shall conform to the following template:
|
||||
|
||||
["source","{basebackend@docbook:c++:cpp}",title=""]
|
||||
------------------------------------------------------------------------------
|
||||
vk<CommandName><ExtensionAuthorPrefix>
|
||||
------------------------------------------------------------------------------
|
||||
|
||||
Where +ExtensionAuthorPrefix+ is equal to that of the prefixes defined above
|
||||
for extension names with the exception that a leading `_` (underscore) is
|
||||
added for non-Khronos extensions. For example, a Khronos-blessed extension
|
||||
could expose the following command:
|
||||
|
||||
["source","{basebackend@docbook:c++:cpp}",title=""]
|
||||
------------------------------------------------------------------------------
|
||||
void vkDoSomethingKHR(void);
|
||||
------------------------------------------------------------------------------
|
||||
|
||||
A Google extension could expose the following command:
|
||||
|
||||
["source","{basebackend@docbook:c++:cpp}",title=""]
|
||||
------------------------------------------------------------------------------
|
||||
void vkDoSomethingGOOGLE(void);
|
||||
------------------------------------------------------------------------------
|
||||
|
||||
A multi-author extension could expose the following type:
|
||||
|
||||
["source","{basebackend@docbook:c++:cpp}",title=""]
|
||||
------------------------------------------------------------------------------
|
||||
typedef struct VkSomeDataEXT;
|
||||
------------------------------------------------------------------------------
|
||||
|
||||
And a non-Khronos extension could expose this enumerant:
|
||||
|
||||
["source","{basebackend@docbook:c++:cpp}",title=""]
|
||||
------------------------------------------------------------------------------
|
||||
enum VkSomeValuesGRPHX {
|
||||
VK_SOME_VALUE_0_GRPHX = 0,
|
||||
VK_SOME_VALUE_1_GRPHX = 1,
|
||||
VK_SOME_VALUE_2_GRPHX = 2,
|
||||
};
|
||||
------------------------------------------------------------------------------
|
||||
|
||||
|
||||
[[extensions-api-registry]]
|
||||
== The {apiname} Registry
|
||||
|
||||
The canonical definition of the {apiname} APIs is kept in an XML file known
|
||||
as the *{apiname} registry*. The registry is kept in +src/spec/vk.xml+ in
|
||||
the branch of the vulkan project containing the most recently released core
|
||||
API specification. The registry contains reserved author prefixes, core and
|
||||
extension interface definitions, definitions of individual commands and
|
||||
structures, and other information which must be agreed on by all
|
||||
implementations. The registry is used to maintain a single, consistent
|
||||
global namespace for the registered entities, to generate the
|
||||
Khronos-supplied +vulkan.h+, and to create a variety of related
|
||||
documentation used in generating the API specification and reference pages.
|
||||
|
||||
|
||||
[[extensions-author-prefix]]
|
||||
== Registering an Author Prefix with Khronos
|
||||
|
||||
Previous Khronos APIs could only officially be modified by Khronos members.
|
||||
In an effort to build a more flexible platform, {apiname} allows non-Khronos
|
||||
developers to extend and modify the API via layers and extensions in the
|
||||
same manner as Khronos members. However, extensions must: still be
|
||||
registered with Khronos. A mechanism for non-members to register layers and
|
||||
extensions is provided.
|
||||
|
||||
Extension authors will be able to create an account on the Khronos github
|
||||
project and, using this account, register an author prefix with
|
||||
Khronos. This string must: be used as the author prefix in any extensions
|
||||
the author registers. The same account will be used to request registration
|
||||
of extensions or layers with Khronos, as described below.
|
||||
|
||||
To reserve an author prefix, propose a merge request against
|
||||
<<extensions-api-registry,+vk.xml+>>. The merge must: add a +<tag>+ XML tag
|
||||
and fill in the +name+, +author+ and +contact+ attributes with the requested
|
||||
author prefix, the author's formal name (e.g. company or project name), and
|
||||
contact email address, respectively. The author prefix will be reserved only
|
||||
once this merge request is accepted.
|
||||
|
||||
Please do not try to reserve author names which clearly belong to another
|
||||
existing company or software project which may: wish to develop {apiname}
|
||||
extensions or layers in the future, as a matter of courtesy and respect.
|
||||
Khronos may: decline to register author names that are not requested in good
|
||||
faith.
|
||||
|
||||
|
||||
[[extensions-vendor-id]]
|
||||
== Registering a Vendor ID with Khronos
|
||||
|
||||
{apiname} implementers must report a valid vendor ID for their
|
||||
implementation, as reported by
|
||||
<<devsandqueues-physical-device-enumeration,physical device queries>>. If
|
||||
there is no valid PCI vendor ID defined for the physical device,
|
||||
implementations must: obtain a Khronos vendor ID.
|
||||
|
||||
Khronos vendor IDs are reserved in a similar fashion to
|
||||
<<extensions-author-prefix,author prefixes>>. While vendor IDs are not
|
||||
directly related to API extensions, the reservation process is very similar
|
||||
and so is described in this section.
|
||||
|
||||
To reserve an Khronos vendor ID, you must first have a Khronos author
|
||||
prefix. Propose a merge request against
|
||||
<<extensions-api-registry,+vk.xml+>>. The merge must: add a +<vendorid>+ tag
|
||||
and fill in the +name+ and +id+ attributes. The +name+ attribute must: be
|
||||
set to the author prefix. The +id+ attribute must: be the first sequentially
|
||||
available ID in the list of +<vendorid>+ tags. The vendor ID will be
|
||||
reserved only once this merge request has been accepted.
|
||||
|
||||
Please do not try to reserve vendor IDs unless you are making a good faith
|
||||
effort to develop a {apiname} implementation and require one for that
|
||||
purpose.
|
||||
|
||||
|
||||
== Registering Extensions and Layers
|
||||
|
||||
Extensions must: be registered with Khronos. Layers may: be registered, and
|
||||
registration is strongly recommended. Registration means:
|
||||
|
||||
* Receiving an extension number.
|
||||
* Adding the extension or layer name to the list in +vk.xml+ and appearing
|
||||
on the Khronos registry website, which will link to associated
|
||||
documentation hosted on Khronos.
|
||||
* For extensions which add to the {apiname} API, including definitions of
|
||||
those additions to +vk.xml+.
|
||||
|
||||
Registration for Khronos members is handled by filing a merge request in the
|
||||
internal gitlab repository against the branch containing the core
|
||||
specification against which the extension or layer will be written. The
|
||||
merge must: modify +vk.xml+ to define extension names, API interfaces, and
|
||||
related information. Registration is not complete until the registry
|
||||
maintainer has validated and accepted the merge.
|
||||
|
||||
Since this process could in principle be completely automated, this
|
||||
suggests a scalable mechanism for accepting registration of non-Khronos
|
||||
extensions. Non-Khronos members who want to create extensions must: register
|
||||
with Khronos by creating a github account, and registering their author
|
||||
prefix and/or FQDNs to that account. They can: then submit new extension
|
||||
registration requests by proposing merges to +vk.xml+. On acceptance of the
|
||||
merge, the extension will be registered, though its specification need not
|
||||
be checked into the Khronos github repository at that point.
|
||||
|
||||
The registration process can: be split into several steps to accommodate
|
||||
extension number assignment prior to extension publication:
|
||||
|
||||
* Acquire an extension number. This is done by proposing a merge request
|
||||
against +vk.xml+ similarly to how <<extensions-author-prefix,author
|
||||
prefixes are reserved>>. The merge should: add a new +<extension>+ tag
|
||||
at the end of the file with attributes specifying the proposed extension
|
||||
+name+, the next unused sequential extension +number+, the +author+ and
|
||||
+contact+ information (if different than that already specified for the
|
||||
author prefix used in the extension name), and finally, specifying
|
||||
+supported="disabled"+. The extension number will be reserved only once
|
||||
this merge request is accepted into the master branch.
|
||||
* Develop and test the extension using the registered extension number.
|
||||
* Publish the extension to Khronos using the previously registered
|
||||
extension number, by creating a branch of the repository with
|
||||
appropriate changes relative to the core {apiname} API branch.
|
||||
* Mark the extension as enabled, by proposing a merge to master changing
|
||||
the +supported+ attribute value of the +<extension>+ to
|
||||
+supported="vulkan"+. This should: be completely automated and under the
|
||||
control of the publishers, to allow them to align publication on Khronos
|
||||
with product releases. However, complete automation might be difficult,
|
||||
since steps such as regenerating and validating +vulkan.h+ are involved.
|
||||
Once the merge is accepted and the corresponding updated header with the
|
||||
new extension interface is committed to the master branch, publication
|
||||
is complete.
|
||||
|
||||
The automated process does not exist yet, and would require significant
|
||||
investment in infrastructure to support the process on the Khronos servers.
|
||||
|
||||
ifdef::editing-notes[]
|
||||
[NOTE]
|
||||
.editing-note
|
||||
====
|
||||
TODO: This section is subject to change and not complete yet, but in broad
|
||||
is how we expect extension registration and specifications to work. The
|
||||
process will be refined as members and outside authors define further
|
||||
extensions.
|
||||
====
|
||||
endif::editing-notes[]
|
||||
|
||||
|
||||
== Documenting Extensions
|
||||
|
||||
Extensions are documented as modifications to the {apiname} specification.
|
||||
These modifications will be on Git branches that are named with the
|
||||
following syntax: +<major.minor core spec version>-<extension_name>+
|
||||
|
||||
For example, the VK_KHR_surface extension will be documented relative
|
||||
to version 1.0 of the {apiname} specification. As such, the branch name will
|
||||
be: +1.0-VK_KHR_surface+
|
||||
|
||||
If the extension modifies an existing section of the {apiname}
|
||||
specification, those modifications are made in-place. Since the changes are
|
||||
on a branch, the core-only specification can: be easily produced. A
|
||||
specification with an extension is created by merging in the extension's
|
||||
branch contents.
|
||||
|
||||
Extensions should: be merged according to their registered extension number.
|
||||
If two extensions both modify the same portion of the specification, the
|
||||
higher-numbered extension should: take care to deal with any conflicts.
|
||||
|
||||
The WSI extensions were used to help pioneer what should: be done for
|
||||
extensions. This includes the following:
|
||||
|
||||
* All extensions should: add to the appendix of the {apiname}
|
||||
specification. This should: be modeled after what was done for the
|
||||
+VK_KHR_surface+ extension, which contains some high-level information
|
||||
about the extension (as well as code examples, and revision history) in
|
||||
the +appendices/vk_khr_surface.txt+ file.
|
||||
* 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
|
||||
exist on the master branch. This will avoid merge conflicts when
|
||||
multiple extensions' branches are merged in order to create the ``full''
|
||||
branch specification.
|
||||
* If there are any other places where 2 or more extensions will extend the
|
||||
{apiname} specification, it is best to put that content in a file, and
|
||||
use an +include+ statement to put that content into the spec. Again,
|
||||
this +include+ line should: be put on the master branch in order to
|
||||
avoid merge conflicts.
|
||||
* If an extension is more of an addition to the {apiname} specification,
|
||||
the extension should: add a chapter to the {apiname} specification.
|
||||
|
||||
|
||||
== Assigning Extension Token Values
|
||||
|
||||
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 object 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.
|
||||
|
||||
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
|
||||
positive numbers are also reserved. The ability to create both positive and
|
||||
negative extension values is necessary to enable extending enumerations such
|
||||
as stext:VkResult that assign special meaning to negative and positive
|
||||
values. Therefore, 1000 positive and 1000 negative values are reserved for
|
||||
each extension. Extensions must: not define enum values outside their
|
||||
reserved range without explicit permission from the owner of those values
|
||||
(e.g. from the author of another extension whose range is infringed on, or
|
||||
from the Khronos Registrar if the values do not belong to any extension's
|
||||
range).
|
||||
|
||||
[NOTE]
|
||||
.Note
|
||||
====
|
||||
Typically, extensions use a unique offset for each enumeration constant they
|
||||
add, yielding 1000 distinct token values per extension. Since each
|
||||
enumeration object has its own namespace, if an extension needs to add many
|
||||
enumeration constant values, it can: reuse offsets on a per-type basis.
|
||||
====
|
||||
|
||||
The information needed to add new values to the XML are as follows:
|
||||
|
||||
* The **extension name** (e.g. +VK_KHR_swapchain+) that is adding the new
|
||||
enumeration constant.
|
||||
* The existing enumeration **type** being extended (e.g.
|
||||
stext:VkStructureType).
|
||||
* The name of the new enumeration **token** being added (e.g.
|
||||
etext:VK_STRUCTURE_TYPE_SWAPCHAIN_CREATE_INFO_KHR).
|
||||
* 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
|
||||
errors, like etext:VK_ERROR_SURFACE_LOST_KHR. The default direction is
|
||||
positive, if not specified.
|
||||
|
||||
Implicit is the registered number of an extension, which is used to create a
|
||||
block of unused values offset against a global extension base value.
|
||||
Individual enumerant values are calculated as offsets in that block. Values
|
||||
are calculated as follows:
|
||||
|
||||
* base_value = 1000000000
|
||||
* block_size = 1000
|
||||
* enum_offset(extension_number,offset) = base_value +
|
||||
(extension_number - 1) × block_size + offset
|
||||
* Positive values: enum_offset(extension_number,offset)
|
||||
* Negative values: -enum_offset(extension_number,offset)
|
||||
|
||||
The exact syntax for specifying extension enumerant values is defined in the
|
||||
+readme.pdf+ specifying the format of +vk.xml+, and extension authors can:
|
||||
also refer to existing extensions for examples.
|
||||
|
||||
|
||||
== Required Extension Tokens
|
||||
|
||||
In addition to any tokens specific to the functionality of an extension,
|
||||
all extensions must: define two additional tokens.
|
||||
|
||||
* VK_EXTNAME_SPEC_VERSION is an integer constant which is the revision of
|
||||
the extension named +VK_extname+ (EXTNAME is all upper-case, while
|
||||
extname is the capitalization of the actual extension name) in
|
||||
+vulkan.h+. This value begins at 1 with the initial version of an
|
||||
extension specification, and is incremented when significant changes
|
||||
(bugfixes or added functionality) are made. Note that the revision of an
|
||||
extension defined in +vulkan.h+ and the revision supported by the
|
||||
{apiname} implementation (the pname:specVersion field of the
|
||||
slink:VkExtensionProperties structure corresponding to the extension and
|
||||
returned by one of the <<debug-extensions,Extension Queries>>) may:
|
||||
differ. In such cases, only the functionality and behavior of the
|
||||
lowest-numbered revision can: be used.
|
||||
* VK_EXTNAME_EXTENSION_NAME is a string constant which is the name of the
|
||||
extension.
|
||||
|
||||
For example, for the WSI extension +VK_KHR_surface+, at the time of writing
|
||||
the following definitions were in effect:
|
||||
|
||||
[source,c]
|
||||
---------------------------------------------------
|
||||
#define VK_KHR_SURFACE_SPEC_VERSION 24
|
||||
#define VK_KHR_SURFACE_EXTENSION_NAME "VK_KHR_surface"
|
||||
---------------------------------------------------
|
||||
|
||||
|
||||
== Extension Objects, Enums, and Typedefs
|
||||
|
||||
Expanding on previous discussion, extensions can: add values to existing
|
||||
enums; and can: add their own objects, enums, typedefs, etc. This is done by
|
||||
adding to <<extensions-api-registry,+vk.xml+>>. All such additions will be
|
||||
included in the +vulkan.h+ header supplied by Khronos.
|
||||
|
||||
[NOTE]
|
||||
.Note
|
||||
====
|
||||
Application developers are encouraged to be careful when using +switch+
|
||||
statements with {apiname} API enums. This is because extensions can: add new
|
||||
values to existing enums. The use of a +default:+ statement, within a
|
||||
+switch+, may: avoid future compilation issues.
|
||||
====
|
||||
|
||||
|
||||
[[extension-function_prototypes]]
|
||||
== Extension Function Prototypes
|
||||
|
||||
Function pointer declarations and function prototypes for all core {apiname}
|
||||
API functions are included in the +vulkan.h+ file. These come from the
|
||||
official XML specification of the {apiname} API hosted by Khronos.
|
||||
|
||||
Function pointer declarations are also included in the +vulkan.h+ file for
|
||||
all extension functions. Function prototypes for extensions may: be included
|
||||
in +vulkan.h+. Extension functions that are part of the {apiname} ABI must:
|
||||
be flagged in the XML. Prototypes will be included in +vulkan.h+ for all
|
||||
extension functions that are part of the {apiname} ABI.
|
||||
|
||||
An extension can: be considered platform specific, in which case, its
|
||||
objects, functions, etc. are protected by #ifdefs. This is orthogonal to
|
||||
whether a function is considered to be part of the {apiname} ABI.
|
||||
|
||||
The initial set of WSI extension functions are considered to be part of the
|
||||
{apiname} ABI. Prototypes for these WSI functions are included in the
|
||||
+vulkan.h+ provided by Khronos, though the platform-specific portions of
|
||||
+vulkan.h+ are protected by #ifdefs.
|
||||
|
||||
[NOTE]
|
||||
.Note
|
||||
====
|
||||
Based on feedback from implementers, Khronos expects that the Android,
|
||||
Linux, and Windows {apiname} SDKs will include our +vulkan.h+ and export
|
||||
the supported WSI functions for those platforms from their loader
|
||||
libraries. Other implementations can: make different choices for their
|
||||
headers and loader libraries, but are encouraged to be consistent with
|
||||
these implementations.
|
||||
====
|
||||
|
||||
|
||||
== Accessing Extension Function from Programs
|
||||
|
||||
The {apiname} API flink:vkGetInstanceProcAddr and flink:vkGetDeviceProcAddr
|
||||
functions (i.e. GPA functions) can: be used in order to obtain addresses for
|
||||
core and extension functions (per the description in
|
||||
<<initialization-functionpointers,Command Function Pointers>>). Various
|
||||
{apiname} API loaders can: be created on different platforms, which can:
|
||||
statically export some or all of the core {apiname} API functions, and which
|
||||
can: statically export some or all extension functions. If a loader
|
||||
statically exports a function, an application can: link against that
|
||||
function without needing to call a GPA function.
|
||||
|
||||
[NOTE]
|
||||
.Note
|
||||
====
|
||||
As mentioned above, the {apiname} API loader on Android, Linux, and Windows
|
||||
will export all core {apiname} API and WSI extension functions. The WSI
|
||||
functions are considered special, because they are required for many
|
||||
applications.
|
||||
====
|
||||
|
||||
[[extensions-reserving-bitfield-values]]
|
||||
=== Reserving Bitfield Values
|
||||
|
||||
Enumerants which define bitfield 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
|
||||
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
|
||||
<<extensions-api-registry,+vk.xml+>> by the registry maintainer.
|
||||
|
||||
[NOTE]
|
||||
.Note
|
||||
====
|
||||
In reality the approving authority for EXT and vendor extension bitfield
|
||||
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.
|
||||
====
|
||||
|
||||
|
||||
== Extension Interactions
|
||||
|
||||
Extensions modifying the behavior of existing commands should: provide
|
||||
additional parameters by using the param:pNext field of an existing
|
||||
structure, pointing to a new structure defined by the extension, as
|
||||
described in the <<fundamentals-validusage,Valid Usage>> section. Extension
|
||||
structures defined by multiple extensions affecting the same structure can
|
||||
be chained together in this fashion.
|
||||
|
||||
It is in principle possible for extensions to provide additional parameters
|
||||
through alternate means, such as passing a handle parameter to a structure
|
||||
with a pname:sType defined by the extension, but this approach is
|
||||
discouraged and shouldnot: be used.
|
||||
|
||||
When chaining multiple extensions to a structure, the implementation will
|
||||
process the chain starting with the base parameter and proceeding through
|
||||
each successive chained structure in turn. Extensions should: be defined to
|
||||
accept any order of chaining, and must: define their interactions with other
|
||||
extensions such that the results are deterministic. If an extension needs a
|
||||
specific ordering of its extension structure with respect to other
|
||||
extensions in a chain to provide deterministic results, it must: define the
|
||||
required ordering and expected behavior as part of its specification.
|
||||
|
|
@ -0,0 +1,779 @@
|
|||
// Copyright (c) 2015-2016 The Khronos Group Inc.
|
||||
// Copyright notice at https://www.khronos.org/registry/speccopyright.html
|
||||
|
||||
// The asciidoc [glossary] template cannot contain subsections.
|
||||
// The abbreviations and prefixes probably belong in the upcoming
|
||||
// API/extension-writing-guidelines appendix, anyway.
|
||||
|
||||
[glossary]
|
||||
= Glossary
|
||||
|
||||
The terms defined in this section are used consistently throughout this
|
||||
Specification and may be used with or without capitalization.
|
||||
|
||||
Accessible (Descriptor Binding)::
|
||||
A descriptor binding is accessible to a shader stage if that stage is
|
||||
included in the pname:stageFlags of the descriptor binding. Descriptors
|
||||
using that binding can: only be used by stages in which they are
|
||||
accessible.
|
||||
|
||||
Adjacent Vertex::
|
||||
A vertex in an adjacency primitive topology that is not part of a given
|
||||
primitive, but is accessible in geometry shaders.
|
||||
|
||||
Aliased Range (Memory)::
|
||||
A range of a device memory allocation that is bound to multiple
|
||||
resources simultaneously.
|
||||
|
||||
API Order::
|
||||
A set of ordering rules that govern how primitives in draw commands
|
||||
affect the framebuffer.
|
||||
|
||||
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
|
||||
index also refers to an attachment description which includes
|
||||
information about the properties of the image view that will later be
|
||||
attached.
|
||||
|
||||
Available::
|
||||
See Memory Dependency.
|
||||
|
||||
Back-Facing::
|
||||
See Facingness.
|
||||
|
||||
Batch::
|
||||
A collection of command buffers that are submitted to a queue, and
|
||||
corresponding semaphores to wait and signal. Corresponds to an instance
|
||||
of the slink:VkSubmitInfo structure.
|
||||
|
||||
Backwards Compatibility::
|
||||
A given version of the API is backwards compatible with an earlier
|
||||
version if an application, relying only on valid behavior and
|
||||
functionality defined by the earlier specification, is able to correctly
|
||||
run against each version without any modification. This assumes no
|
||||
active attempt by that application to not run when it detects a
|
||||
different version.
|
||||
|
||||
Full Compatibility::
|
||||
A given version of the API is fully compatible with another version if
|
||||
an application, relying only on valid behavior and functionality defined
|
||||
by either of those specifications, is able to correctly run against each
|
||||
version without any modification. This assumes no active attempt by that
|
||||
application to not run when it detects a different version.
|
||||
|
||||
Binding (Memory)::
|
||||
An association established between a range of a resource object and a
|
||||
range of a memory object. These associations determine the memory
|
||||
locations affected by operations performed on elements of a resource
|
||||
object. Memory bindings are established using the
|
||||
flink:vkBindBufferMemory command for non-sparse buffer objects, using
|
||||
the flink:vkBindImageMemory command for non-sparse image objects, and
|
||||
using the flink:vkQueueBindSparse command for sparse resources.
|
||||
|
||||
Blend Constant::
|
||||
Four floating point (RGBA) values used as an input to blending.
|
||||
|
||||
Blending::
|
||||
Arithmetic operations between a fragment color value and a value in a
|
||||
color attachment that produce a final color value to be written to the
|
||||
attachment.
|
||||
|
||||
Buffer::
|
||||
A resource that represents a linear array of data in device memory.
|
||||
Represented by a sname:VkBuffer object.
|
||||
|
||||
Buffer View::
|
||||
An object that represents a range of a specific buffer, and state that
|
||||
controls how the contents are interpreted. Represented by a
|
||||
sname:VkBufferView object.
|
||||
|
||||
Built-In Variable::
|
||||
A variable decorated in a shader, where the decoration makes the
|
||||
variable take values provided by the execution environment or values
|
||||
that are generated by fixed-function pipeline stages.
|
||||
|
||||
Built-In Interface Block::
|
||||
A block defined in a shader that contains only variables decorated with
|
||||
built-in decorations, and is used to match against other shader
|
||||
stages.
|
||||
|
||||
Clip Coordinates::
|
||||
The homogeneous coordinate space that vertex positions
|
||||
(code:Position decoration) are written in by vertex processing stages.
|
||||
|
||||
Clip Distance::
|
||||
A built-in output from vertex processing stages that defines a clip
|
||||
half-space against which the primitive is clipped.
|
||||
|
||||
Clip Volume::
|
||||
The intersection of the view volume with all clip half-spaces.
|
||||
|
||||
Color Attachment::
|
||||
A subpass attachment point, or image view, that is the target of
|
||||
fragment color outputs and blending.
|
||||
|
||||
Combined Image Sampler::
|
||||
A descriptor type that includes both a sampled image and a sampler.
|
||||
|
||||
Command Buffer::
|
||||
An object that records commands to be submitted to a queue. Represented
|
||||
by a sname:VkCommandBuffer object.
|
||||
|
||||
Command Pool::
|
||||
An object that command buffer memory is allocated from, and that owns
|
||||
that memory. Command pools aid multithreaded performance by enabling
|
||||
different threads to use different allocators, without internal
|
||||
synchronization on each use. Represented by a sname:VkCommandPool
|
||||
object.
|
||||
|
||||
Compatible Allocator::
|
||||
When allocators are compatible, allocations from each allocator can: be
|
||||
freed by the other allocator.
|
||||
|
||||
Compatible Image Formats::
|
||||
When formats are compatible, images created with one of the formats can:
|
||||
have image views created from it using any of the compatible formats.
|
||||
|
||||
Compatible Queues::
|
||||
Queues within a queue family. Compatible queues have identical
|
||||
properties.
|
||||
|
||||
Cull Distance::
|
||||
A built-in output from vertex processing stages that defines a cull
|
||||
half-space where the primitive is rejected if all vertices have a
|
||||
negative value for the same cull distance.
|
||||
|
||||
Cull Volume::
|
||||
The intersection of the view volume with all cull half-spaces.
|
||||
|
||||
Decoration (SPIR-V)::
|
||||
Auxiliary information such as built-in variables, stream numbers,
|
||||
invariance, interpolation type, relaxed precision, etc., added to
|
||||
variables or structure-type members through decorations.
|
||||
|
||||
Depth/Stencil Attachment::
|
||||
A subpass attachment point, or image view, that is the target of depth
|
||||
and/or stencil test operations and writes.
|
||||
|
||||
Depth/Stencil Format::
|
||||
A elink:VkFormat that includes depth and/or stencil components.
|
||||
|
||||
Depth/Stencil Image (or ImageView)::
|
||||
A sname:VkImage (or sname:VkImageView) with a depth/stencil format.
|
||||
|
||||
Descriptor::
|
||||
Information about a resource or resource view written into a descriptor
|
||||
set that is used to access the resource or view from a shader.
|
||||
|
||||
Descriptor Binding::
|
||||
An entry in a descriptor set layout corresponding to zero or more
|
||||
descriptors of a single descriptor type in a set. Defined by a
|
||||
slink:VkDescriptorSetLayoutBinding structure.
|
||||
|
||||
Descriptor Pool::
|
||||
An object that descriptor sets are allocated from, and that owns the
|
||||
storage of those descriptor sets. Descriptor pools aid multithreaded
|
||||
performance by enabling different threads to use different allocators,
|
||||
without internal synchronization on each use. Represented by a
|
||||
sname:VkDescriptorPool object.
|
||||
|
||||
Descriptor Set::
|
||||
An object that resource descriptors are written into via the API, and
|
||||
that can: be bound to a command buffer such that the descriptors
|
||||
contained within it can: be accessed from shaders. Represented by a
|
||||
sname:VkDescriptorSet object.
|
||||
|
||||
Descriptor Set Layout::
|
||||
An object that defines the set of resources (types and counts) and their
|
||||
relative arrangement (in the binding namespace) within a descriptor set.
|
||||
Used when allocating descriptor sets and when creating pipeline layouts.
|
||||
Represented by a sname:VkDescriptorSetLayout object.
|
||||
|
||||
Device::
|
||||
The processor(s) and execution environment that perform tasks requested
|
||||
by the application via the Vulkan API.
|
||||
|
||||
Device Memory::
|
||||
Memory accessible to the device. Represented by a sname:VkDeviceMemory
|
||||
object.
|
||||
|
||||
Device-Local Memory::
|
||||
Memory that is connected to the device, and may: be more performant for
|
||||
device access than host-local memory.
|
||||
|
||||
Dispatchable Handle::
|
||||
A handle of a pointer handle type which may: be used by layers as part
|
||||
of intercepting API commands. The first argument to each {apiname}
|
||||
command is a dispatchable handle type.
|
||||
|
||||
Dispatching Commands::
|
||||
Commands that provoke work using a compute pipeline. Includes
|
||||
flink:vkCmdDispatch and flink:vkCmdDispatchIndirect.
|
||||
|
||||
Drawing Commands::
|
||||
Commands that provoke work using a graphics pipeline. Includes
|
||||
flink:vkCmdDraw, flink:vkCmdDrawIndexed, flink:vkCmdDrawIndirect, and
|
||||
flink:vkCmdDrawIndexedIndirect.
|
||||
|
||||
Dynamic Storage Buffer::
|
||||
A storage buffer whose offset is specified each time the storage buffer
|
||||
is bound to a command buffer via a descriptor set.
|
||||
|
||||
Dynamic Uniform Buffer::
|
||||
A uniform buffer whose offset is specified each time the uniform buffer
|
||||
is bound to a command buffer via a descriptor set.
|
||||
|
||||
Explicitly-Enabled Layer::
|
||||
A layer enabled by the application by adding it to the enabled layer
|
||||
list in flink:vkCmdCreateInstance or flink:vkCmdCreateDevice.
|
||||
|
||||
Event::
|
||||
A synchronization primitive that is signalled when execution of previous
|
||||
commands complete through a specified set of pipeline stages. Events can
|
||||
be waited on by the device and polled by the host. Represented by a
|
||||
sname:VkEvent object.
|
||||
|
||||
Executable State (Command Buffer)::
|
||||
A command buffer that has ended recording commands and can: be executed.
|
||||
See also Initial State and Recording State.
|
||||
|
||||
Execution Dependency::
|
||||
A dependency that guarantees that certain pipeline stages' work for a
|
||||
first set of commands has completed execution before certain pipeline
|
||||
stages' work for a second set of commands begins execution. This is
|
||||
accomplished via pipeline barriers, subpass dependencies, events, or
|
||||
implicit ordering operations.
|
||||
|
||||
Execution Dependency Chain::
|
||||
A sequence of execution dependencies that transitively act as an
|
||||
execution dependency.
|
||||
|
||||
External synchronization::
|
||||
A type of synchronization required of the application, where parameters
|
||||
defined to be externally synchronized mustnot: be used simultaneously in
|
||||
multiple threads.
|
||||
|
||||
Facingness (Polygon)::
|
||||
A classification of a polygon as either front-facing or back-facing,
|
||||
depending on the orientation (winding order) of its vertices.
|
||||
|
||||
Fence::
|
||||
A synchronization primitive that is signaled when a set of batches or
|
||||
sparse binding operations complete execution on a queue. Fences can: be
|
||||
waited on by the host. Represented by a sname:VkFence object.
|
||||
|
||||
Flatshading::
|
||||
A property of a vertex attribute that causes the value from a single
|
||||
vertex (the provoking vertex) to be used for all vertices in a
|
||||
primitive, and for interpolation of that attribute to return that single
|
||||
value unaltered.
|
||||
|
||||
Fragment Input Attachment Interface::
|
||||
A fragment shader entry point's variables with code:Input storage class
|
||||
and a decoration of code:InputAttachmentIndex, which receive values from
|
||||
input attachments.
|
||||
|
||||
Fragment Output Interface::
|
||||
A fragment shader entry point's variables with code:Output storage
|
||||
class, which output to color and/or depth/stencil attachments.
|
||||
|
||||
Framebuffer::
|
||||
A collection of image views and a set of dimensions that, in conjunction
|
||||
with a render pass, define the inputs and outputs used by drawing
|
||||
commands. Represented by a sname:VkFramebuffer object.
|
||||
|
||||
Framebuffer Attachment::
|
||||
One of the image views used in a framebuffer.
|
||||
|
||||
Framebuffer Coordinates::
|
||||
A coordinate system in which adjacent pixels' coordinates differ by 1 in
|
||||
x and/or y, with latexmath:[$(0,0)$] in the upper left corner and pixel
|
||||
centers at half-integers.
|
||||
|
||||
Front-Facing::
|
||||
See Facingness.
|
||||
|
||||
Handle::
|
||||
An opaque integer or pointer value used to refer to a {apiname} object.
|
||||
Each object type has a unique handle type.
|
||||
|
||||
Helper Invocation::
|
||||
A fragment shader invocation that is created solely for the purposes of
|
||||
evaluating derivatives for use in non-helper fragment shader
|
||||
invocations, and which does not have side effects.
|
||||
|
||||
Host::
|
||||
The processor(s) and execution environment that the application runs on,
|
||||
and that the Vulkan API is exposed on.
|
||||
|
||||
Host Memory::
|
||||
Memory not accessible to the device, used to store implementation data
|
||||
structures.
|
||||
|
||||
Host-Accessible Subresource::
|
||||
A buffer, or a linear image subresource in either the
|
||||
ename:VK_IMAGE_LAYOUT_PREINITIALIZED or ename:VK_IMAGE_LAYOUT_GENERAL
|
||||
layout. Host-accessible subresources have a well-defined addressing
|
||||
scheme which can be used by the host.
|
||||
|
||||
Host-Local Memory::
|
||||
Memory that is not local to the device, and may: be less performant for
|
||||
device access than device-local memory.
|
||||
|
||||
Host-Visible Memory::
|
||||
Device memory that can: be mapped on the host and can: be read and
|
||||
written by the host.
|
||||
|
||||
Image::
|
||||
A resource that represents a multi-dimensional formatted interpretation
|
||||
of device memory. Represented by a sname:VkImage object.
|
||||
|
||||
Image Subresource::
|
||||
A specific mipmap level and layer of an image.
|
||||
|
||||
Image Subresource Range::
|
||||
A set of image subresources that are contiguous mipmap levels and
|
||||
layers.
|
||||
|
||||
Image View::
|
||||
An object that represents a subresource range of a specific image, and
|
||||
state that controls how the contents are interpreted. Represented by a
|
||||
sname:VkImageView object.
|
||||
|
||||
Immutable Sampler::
|
||||
A sampler descriptor provided at descriptor set layout creation time,
|
||||
and that is used for that binding in all descriptor sets created from
|
||||
the layout, and cannot be changed.
|
||||
|
||||
Implicitly-Enabled Layer::
|
||||
A layer enabled by a loader-defined mechanism outside the {apiname} API,
|
||||
rather than explicitly by the application during instance or device
|
||||
creation.
|
||||
|
||||
Index Buffer::
|
||||
A buffer bound via flink:vkCmdBindIndexBuffer which is the source of
|
||||
index values used to fetch vertex attributes for a
|
||||
flink:vkCmdDrawIndexed or flink:vkCmdDrawIndexedIndirect command.
|
||||
|
||||
Indirect Commands::
|
||||
Drawing or dispatching commands that source some of their parameters
|
||||
from structures in buffer memory. Includes flink:vkCmdDrawIndirect,
|
||||
flink:vkCmdDrawIndexedIndirect, and flink:vkCmdDispatchIndirect.
|
||||
|
||||
Initial State (Command Buffer)::
|
||||
A command buffer that has not begun recording commands. See also
|
||||
Recorded State and Executable State.
|
||||
|
||||
Input Attachment::
|
||||
A descriptor type that represents an image view, and supports unfiltered
|
||||
read-only access in a shader, only at the fragment's location in the
|
||||
view.
|
||||
|
||||
Instance::
|
||||
The top-level {apiname} object, which represents the application's
|
||||
connection to the implementation. Represented by a sname:VkInstance
|
||||
object.
|
||||
|
||||
Internal Synchronization::
|
||||
A type of synchronization required of the implementation, where
|
||||
parameters not defined to be externally synchronized may: require
|
||||
internal mutexing to avoid multithreaded race conditions.
|
||||
|
||||
Invocation (Shader)::
|
||||
A single execution of an entry point in a SPIR-V module. For example, a
|
||||
single vertex's execution of a vertex shader or a single fragment's
|
||||
execution of a fragment shader.
|
||||
|
||||
Logical Device::
|
||||
An object that represents the application's interface to the physical
|
||||
device. The logical device is the parent of most {apiname} objects.
|
||||
Represented by a sname:VkDevice object.
|
||||
|
||||
Logical Operation::
|
||||
Bitwise operations between a fragment color value and a value in a color
|
||||
attachment, that produce a final color value to be written to the
|
||||
attachment.
|
||||
|
||||
Lost Device::
|
||||
A state that a logical device may: be in as a result of hardware errors
|
||||
or other exceptional conditions.
|
||||
|
||||
Mappable::
|
||||
See Host-Visible Memory.
|
||||
|
||||
Memory Dependency::
|
||||
A sequence of operations that makes writes available, performs an
|
||||
execution dependency between the writes and subsequent accesses, and
|
||||
makes available writes visible to later accesses. In order for the
|
||||
effects of a write to be coherent with later accesses, it must be made
|
||||
available from the old access type and then made visible to the new
|
||||
access type.
|
||||
|
||||
Memory Heap::
|
||||
A region of memory from which device memory allocations can: be made.
|
||||
|
||||
Memory Type::
|
||||
An index used to select a set of memory properties (e.g. mappable,
|
||||
cached) for a device memory allocation.
|
||||
|
||||
Mip Tail Region::
|
||||
The set of mipmap levels of a sparse residency texture that are too
|
||||
small to fill a block, and that must all be bound to memory collectively
|
||||
and opaquely.
|
||||
|
||||
Non-Dispatchable Handle::
|
||||
A handle of an integer handle type. Handle values maynot: be unique,
|
||||
even for two objects of the same type.
|
||||
|
||||
Normalized::
|
||||
A value that is interpreted as being in the range latexmath:[$[0,1\]$]
|
||||
as a result of being implicitly divided by some other value.
|
||||
|
||||
Normalized Device Coordinates::
|
||||
A coordinate space after perspective division is applied to clip
|
||||
coordinates, and before the viewport transformation converts to
|
||||
framebuffer coordinates.
|
||||
|
||||
Overlapped Range (Aliased Range)::
|
||||
The aliased range of a device memory allocation that intersects a given
|
||||
subresource of an image or range of a buffer.
|
||||
|
||||
Packed Format::
|
||||
A format whose components are stored as a single data element in memory,
|
||||
with their relative locations defined within that element.
|
||||
|
||||
Physical Device::
|
||||
An object that represents a single device in the system. Represented by
|
||||
a sname:VkPhysicalDevice object.
|
||||
|
||||
Pipeline::
|
||||
An object that controls how graphics or compute work is executed on the
|
||||
device. A pipeline includes one or more shaders, as well as state
|
||||
controlling any non-programmable stages of the pipeline. Represented by
|
||||
a sname:VkPipeline object.
|
||||
|
||||
Pipeline Barrier::
|
||||
An execution and/or memory dependency recorded as an explicit command in
|
||||
a command buffer, that forms a dependency between the previous and
|
||||
subsequent commands.
|
||||
|
||||
Pipeline Cache::
|
||||
An object that can: be used to collect and retrieve information from
|
||||
pipelines as they are created, and can: be populated with previously
|
||||
retrieved information in order to accelerate pipeline creation.
|
||||
Represented by a sname:VkPipelineCache object.
|
||||
|
||||
Pipeline Layout::
|
||||
An object that defines the set of resources (via a collection of
|
||||
descriptor set layouts) and push constants used by pipelines that are
|
||||
created using the layout. Used when creating a pipeline and when binding
|
||||
descriptor sets and setting push constant values. Represented by a
|
||||
sname:VkPipelineLayout object.
|
||||
|
||||
Point Sampling (Rasterization)::
|
||||
A rule that determines whether a fragment sample location is covered by
|
||||
a polygon primitive by testing whether the sample location is in the
|
||||
interior of the polygon in framebuffer-space, or on the boundary of the
|
||||
polygon according to the tie-breaking rules.
|
||||
|
||||
Preserve Attachment::
|
||||
One of a list of attachments in a subpass description that is not read
|
||||
or written by the subpass, but that is read or written on earlier and
|
||||
later subpasses and whose contents must be preserved through this
|
||||
subpass.
|
||||
|
||||
Primary Command Buffer::
|
||||
A command buffer that can: execute secondary command buffers, and can:
|
||||
be submitted directly to a queue.
|
||||
|
||||
Primitive Topology::
|
||||
State that controls how vertices are assembled into primitives, e.g. as
|
||||
lists of triangles, strips of lines, etc..
|
||||
|
||||
Provoking Vertex::
|
||||
The vertex in a primitive from which flatshaded attribute values are
|
||||
taken. This is generally the ``first'' vertex in the primitive, and
|
||||
depends on the primitive topology.
|
||||
|
||||
Push Constants::
|
||||
A small bank of values writable via the API and accessible in shaders.
|
||||
Push constants allow the application to set values used in shaders
|
||||
without creating buffers or modifying and binding descriptor sets for
|
||||
each update.
|
||||
|
||||
Push Constant Interface::
|
||||
The set of variables with code:PushConstant storage class that are
|
||||
statically used by a shader entry point, and which receive values
|
||||
from push constant commands.
|
||||
|
||||
Query Pool::
|
||||
An object that contains a number of query entries and their associated
|
||||
state and results. Represented by a sname:VkQueryPool object.
|
||||
|
||||
Queue::
|
||||
An object that executes command buffers and sparse binding operations on
|
||||
a device. Represented by a sname:VkQueue object.
|
||||
|
||||
Queue Family::
|
||||
A set of queues that have common properties and support the same
|
||||
functionality, as advertised in slink:VkQueueFamilyProperties.
|
||||
|
||||
Queue Submission::
|
||||
An operation that is enqueued for execution on a queue typically as a
|
||||
result of the issue of commands of the form ftext:vkQueue*.
|
||||
|
||||
Recording State (Command Buffer)::
|
||||
A command buffer that is ready to record commands. See also Initial
|
||||
State and Executable State.
|
||||
|
||||
Render Pass::
|
||||
An object that represents a set of framebuffer attachments and phases of
|
||||
rendering using those attachments. Represented by a sname:VkRenderPass
|
||||
object.
|
||||
|
||||
Render Pass Instance::
|
||||
A use of a render pass in a command buffer.
|
||||
|
||||
Reset (Command Buffer)::
|
||||
Resetting a command buffer discards any previously recorded commands
|
||||
and puts a command buffer in the initial state.
|
||||
|
||||
Residency Code::
|
||||
An integer value returned by sparse image instructions, indicating
|
||||
whether any sparse unbound texels were accessed.
|
||||
|
||||
Resolve Attachment::
|
||||
A subpass attachment point, or image view, that is the target of a
|
||||
multisample resolve operation from the corresponding color attachment at
|
||||
the end of the subpass.
|
||||
|
||||
Sampled Image::
|
||||
A descriptor type that represents an image view, and supports filtered
|
||||
(sampled) and unfiltered read-only acccess in a shader.
|
||||
|
||||
Sampler::
|
||||
An object that contains state that controls how sampled image data is
|
||||
sampled (or filtered) when accessed in a shader. Also a descriptor type
|
||||
describing the object. Represented by a sname:VkSampler object.
|
||||
|
||||
Secondary Command Buffer::
|
||||
A command buffer that can: be executed by a primary command buffer, and
|
||||
mustnot: be submitted directly to a queue.
|
||||
|
||||
Self-Dependency::
|
||||
A subpass dependency from a subpass to itself, i.e. with
|
||||
pname:srcSubpass equal to pname:dstSubpass. A self-dependency is not
|
||||
automatically performed during a render pass instance, rather a subset
|
||||
of it can: be performed via flink:vkCmdPipelineBarrier during the
|
||||
subpass.
|
||||
|
||||
Semaphore::
|
||||
A synchronization primitive that supports signal and wait operations,
|
||||
and can: be used to synchronize operations within a queue or across
|
||||
queues. Represented by a sname:VkSemaphore object.
|
||||
|
||||
Shader::
|
||||
Instructions selected (via an entry point) from a shader module, which
|
||||
are executed in a shader stage.
|
||||
|
||||
Shader Code::
|
||||
A stream of instructions used to describe the operation of a shader.
|
||||
|
||||
Shader Module::
|
||||
A collection of shader code, potentially including several functions and
|
||||
entry points, that is used to create shaders in pipelines. Represented
|
||||
by a sname:VkShaderModule object.
|
||||
|
||||
Shader Stage::
|
||||
A stage of the graphics or compute pipeline that executes shader code.
|
||||
|
||||
Side Effect::
|
||||
A store to memory or atomic operation on memory from a shader invocation.
|
||||
|
||||
Sparse Unbound Texel::
|
||||
A texel read from a region of a sparse texture that does not have
|
||||
memory bound to it.
|
||||
|
||||
Static Use::
|
||||
An object in a shader is statically used by a shader entry point if any
|
||||
function in the entry point's call tree contains an instruction using
|
||||
the object. Static use is used to constrain the set of descriptors used
|
||||
by a shader entry point.
|
||||
|
||||
Storage Buffer::
|
||||
A descriptor type that represents a buffer, and supports reads, writes,
|
||||
and atomics in a shader.
|
||||
|
||||
Storage Image::
|
||||
A descriptor type that represents an image view, and supports unfiltered
|
||||
loads, stores, and atomics in a shader.
|
||||
|
||||
Storage Texel Buffer::
|
||||
A descriptor type that represents a buffer view, and supports
|
||||
unfiltered, formatted reads, writes, and atomics in a shader.
|
||||
|
||||
Subpass::
|
||||
A phase of rendering within a render pass, that reads and writes a
|
||||
subset of the attachments.
|
||||
|
||||
Subpass Dependency::
|
||||
An execution and/or memory dependency between two subpasses described as
|
||||
part of render pass creation, and automatically performed between
|
||||
subpasses in a render pass instance. A subpass dependency limits the
|
||||
overlap of execution of the pair of subpasses, and can: provide
|
||||
guarantees of memory coherence between accesses in the subpasses.
|
||||
|
||||
Subpass Description::
|
||||
Lists of attachment indices for input attachments, color attachments,
|
||||
depth/stencil attachment, resolve attachments, and preserve attachments
|
||||
used by the subpass in a render pass.
|
||||
|
||||
Subset (Self-Dependency)::
|
||||
A subset of a self-dependency is a pipeline barrier performed during the
|
||||
subpass of the self-dependency, and whose stage masks and access masks
|
||||
each contain a subset of the bits set in the identically named mask in
|
||||
the self-dependency.
|
||||
|
||||
Texel Coordinate System::
|
||||
One of three coordinate systems (normalized, unnormalized, integer) that
|
||||
define how texel coordinates are interpreted in an image or a specific
|
||||
mipmap level of an image.
|
||||
|
||||
Uniform Texel Buffer::
|
||||
A descriptor type that represents a buffer view, and supports
|
||||
unfiltered, formatted, read-only access in a shader.
|
||||
|
||||
Uniform Buffer::
|
||||
A descriptor type that represents a buffer, and supports read-only
|
||||
access in a shader.
|
||||
|
||||
Unnormalized::
|
||||
A value that is interpreted according to its conventional
|
||||
interpretation, and is not normalized.
|
||||
|
||||
User-Defined Variable Interface::
|
||||
A shader entry point's variables with code:Input or code:Output storage
|
||||
class that are not built-in variables.
|
||||
|
||||
Vertex Input Attribute::
|
||||
A graphics pipeline resource that produces input values for the vertex
|
||||
shader by reading data from a vertex input binding and converting it to
|
||||
the attribute's format.
|
||||
|
||||
Vertex Input Binding::
|
||||
A graphics pipeline resource that is bound to a buffer and includes
|
||||
state that affects addressing calculations within that buffer.
|
||||
|
||||
Vertex Input Interface::
|
||||
A vertex shader entry point's variables with code:Input storage class,
|
||||
which receive values from vertex input attributes.
|
||||
|
||||
Vertex Processing Stages::
|
||||
A set of shader stages that comprises the vertex shader, tessellation
|
||||
control shader, tessellation evaluation shader, and geometry shader
|
||||
stages.
|
||||
|
||||
View Volume::
|
||||
A subspace in homogeneous coordinates, corresponding to post-projection
|
||||
x and y values between -1 and +1, and z values between 0 and +1.
|
||||
|
||||
Viewport Transformation::
|
||||
A transformation from normalized device coordinates to framebuffer
|
||||
coordinates, based on a viewport rectangle and depth range.
|
||||
|
||||
Visible::
|
||||
See Memory Dependency.
|
||||
|
||||
// To be added per issue 18:
|
||||
// Current State <<fundamentals-queueoperation>>
|
||||
// Barycentric Coordinates <<primsrast-polygons-basic>>
|
||||
// Internal Allocations <<memory-host-allocation-scope>>
|
||||
// Unavailable, Available <<queries-operation>>
|
||||
// Signaled, Unsignaled <<synchronization-semaphores>> <<synchronization-fences>>
|
||||
// Interior Vertices <<tessellation-tessellator-spacing>>
|
||||
// Inner Vertices <<tessellation-triangle-tessellation>> <<tessellation-quad-tessellation>>
|
||||
// Isolines <<tessellation-isoline-tessellation>>
|
||||
// Binding Range <<sparsemem-memory-binding>>
|
||||
|
||||
|
||||
[glossary]
|
||||
= Common Abbreviations
|
||||
|
||||
Abbreviations and acronyms are sometimes used in the Specification and the
|
||||
API where they are considered clear and commonplace, and are defined here:
|
||||
|
||||
Src::
|
||||
Source
|
||||
|
||||
Dst::
|
||||
Destination
|
||||
|
||||
Min::
|
||||
Minimum
|
||||
|
||||
Max::
|
||||
Maximum
|
||||
|
||||
Rect::
|
||||
Rectangle
|
||||
|
||||
Info::
|
||||
Information
|
||||
|
||||
LOD::
|
||||
Level of Detail
|
||||
|
||||
ID::
|
||||
Identifier
|
||||
|
||||
UUID::
|
||||
Universally Unique Identifier
|
||||
|
||||
Op::
|
||||
Operation
|
||||
|
||||
R::
|
||||
Red color component
|
||||
|
||||
G::
|
||||
Green color component
|
||||
|
||||
B::
|
||||
Blue color component
|
||||
|
||||
A::
|
||||
Alpha color component
|
||||
|
||||
|
||||
[glossary]
|
||||
= Prefixes
|
||||
|
||||
Prefixes are used in the API to denote specific semantic meaning of
|
||||
{apiname} names, or as a label to avoid name clashes, and are explained
|
||||
here:
|
||||
|
||||
VK/Vk/vk::
|
||||
Vulkan namespace +
|
||||
All types, commands, enumerants and defines in this specification are
|
||||
prefixed with these two characters.
|
||||
|
||||
PFN/pfn::
|
||||
Function Pointer +
|
||||
Denotes that a type is a function pointer, or that a variable is of a
|
||||
pointer type.
|
||||
|
||||
p::
|
||||
Pointer +
|
||||
Variable is a pointer.
|
||||
|
||||
vkCmd::
|
||||
Commands that record commands in command buffers +
|
||||
These API commands do not result in immediate processing on the device.
|
||||
Instead, they record the requested action in a command buffer for
|
||||
execution when the command buffer is submitted to a queue.
|
||||
|
||||
s::
|
||||
Structure +
|
||||
Used to denote the etext:VK_STRUCTURE_TYPE* member of each structure in
|
||||
pname:sType
|
||||
|
|
@ -0,0 +1,208 @@
|
|||
// Copyright (c) 2015-2016 The Khronos Group Inc.
|
||||
// Copyright notice at https://www.khronos.org/registry/speccopyright.html
|
||||
|
||||
[appendix]
|
||||
= Invariance
|
||||
|
||||
The {apiname} specification is not pixel exact. It therefore does not
|
||||
guarantee an exact match between images produced by different {apiname}
|
||||
implementations. However, the specification does specify exact matches, in
|
||||
some cases, for images produced by the same implementation. The purpose of
|
||||
this appendix is to identify and provide justification for those cases that
|
||||
require exact matches.
|
||||
|
||||
== Repeatability
|
||||
|
||||
The obvious and most fundamental case is repeated issuance of a series of
|
||||
{apiname} commands. For any given {apiname} and framebuffer state vector,
|
||||
and for any {apiname} command, the resulting {apiname} and framebuffer state
|
||||
must: be identical whenever the command is executed on that initial
|
||||
{apiname} and framebuffer state. This repeatability requirement doesn't
|
||||
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.
|
||||
|
||||
One purpose of repeatability is avoidance of visual artifacts when a
|
||||
doublebuffered scene is redrawn. If rendering is not repeatable, swapping
|
||||
between two buffers rendered with the same command sequence may: result in
|
||||
visible changes in the image. Such false motion is distracting to the
|
||||
viewer. Another reason for repeatability is testability.
|
||||
|
||||
Repeatability, while important, is a weak requirement. Given only
|
||||
repeatability as a requirement, two scenes rendered with one (small) polygon
|
||||
changed in position might differ at every pixel. Such a difference, while
|
||||
within the law of repeatability, is certainly not within its spirit.
|
||||
Additional invariance rules are desirable to ensure useful operation.
|
||||
|
||||
|
||||
== Multi-pass Algorithms
|
||||
|
||||
Invariance is necessary for a whole set of useful multi-pass algorithms.
|
||||
Such algorithms render multiple times, each time with a different {apiname}
|
||||
mode vector, to eventually produce a result in the framebuffer. Examples of
|
||||
these algorithms include:
|
||||
|
||||
* ``Erasing'' a primitive from the framebuffer by redrawing it, either in
|
||||
a different color or using the XOR logical operation.
|
||||
* Using stencil operations to compute capping planes.
|
||||
|
||||
|
||||
== Invariance Rules
|
||||
|
||||
For a given instantiation of an {apiname} rendering context:
|
||||
|
||||
*Rule 1* _For any given {apiname} and framebuffer state vector, and for any
|
||||
given {apiname} command, the resulting {apiname} and framebuffer state must:
|
||||
be identical each time the command is executed on that initial {apiname} and
|
||||
framebuffer state._
|
||||
|
||||
*Rule 2* _Changes to the following state values have no side effects (the
|
||||
use of any other state value is not affected by the change):_
|
||||
|
||||
*Required:*
|
||||
|
||||
* _Framebuffer contents (all bitplanes)_
|
||||
* _The color buffers enabled for writing_
|
||||
* _Scissor parameters (other than enable)_
|
||||
* _Writemasks (color, depth, stencil)_
|
||||
* _Clear values (color, depth, stencil)_
|
||||
|
||||
*Strongly suggested:*
|
||||
|
||||
* _Stencil Parameters (other than enable)_
|
||||
* _Depth test parameters (other than enable)_
|
||||
* _Blend parameters (other than enable)_
|
||||
* _Logical operation parameters (other than enable)_
|
||||
* _Pixel storage state_
|
||||
|
||||
*Corollary 1* _Fragment generation is invariant with respect to the state
|
||||
values marked with * in Rule 2._
|
||||
|
||||
*Rule 3* _The arithmetic of each per-fragment operation is invariant except
|
||||
with respect to parameters that directly control it._
|
||||
|
||||
*Corollary 2* _Images rendered into different color buffers sharing the same
|
||||
framebuffer, either simultaneously or separately using the same command
|
||||
sequence, are pixel identical._
|
||||
|
||||
*Rule 4* _The same vertex or fragment shader will produce the same result
|
||||
when run multiple times with the same input. The wording ``the same shader''
|
||||
means a program object that is populated with the same SPIR-V binary, which
|
||||
is used to create pipelines, possibly multiple times, and which program
|
||||
object is then executed using the same {apiname} state vector. Invariance is
|
||||
relaxed for shaders with side effects, such as performing stores or
|
||||
atomics._
|
||||
|
||||
*Rule 5* _All fragment shaders that either conditionally or unconditionally
|
||||
assign_ code:FragCoord.z _to_ code:FragDepth _are depth-invariant with
|
||||
respect to each other, for those fragments where the assignment to_
|
||||
code:FragDepth _actually is done._
|
||||
|
||||
If a sequence of {apiname} commands specifies primitives to be rendered with
|
||||
shaders containing side effects (image and buffer variable stores and atomic
|
||||
operations), invariance rules are relaxed. In particular, rule 1, corollary
|
||||
2, and rule 4 do not apply in the presence of shader side effects.
|
||||
|
||||
The following weaker versions of rules 1 and 4 apply to {apiname} commands
|
||||
involving shader side effects:
|
||||
|
||||
*Rule 6* _For any given {apiname} and framebuffer state vector, and for any
|
||||
given {apiname} command, the contents of any framebuffer state not directly
|
||||
or indirectly affected by results of shader image or buffer variable stores
|
||||
or atomic operations must: be identical each time the command is executed on
|
||||
that initial {apiname} and framebuffer state._
|
||||
|
||||
*Rule 7* _The same vertex or fragment shader will produce the same result
|
||||
when run multiple times with the same input as long as:_
|
||||
|
||||
* _shader invocations do not use image atomic operations;_
|
||||
* _no framebuffer memory is written to more than once by image stores,
|
||||
unless all such stores write the same value; and_
|
||||
* _no shader invocation, or other operation performed to process the
|
||||
sequence of commands, reads memory written to by an image store._
|
||||
|
||||
When any sequence of {apiname} commands triggers shader invocations that
|
||||
perform image stores or atomic operations, and subsequent {apiname} commands
|
||||
read the memory written by those shader invocations, these operations must:
|
||||
be explicitly synchronized.
|
||||
|
||||
|
||||
== Tessellation Invariance
|
||||
|
||||
When using a program containing tessellation evaluation shaders, the
|
||||
fixed-function tessellation primitive generator consumes the input patch
|
||||
specified by an application and emits a new set of primitives. The following
|
||||
invariance rules are intended to provide repeatability guarantees.
|
||||
Additionally, they are intended to allow an application with a carefully
|
||||
crafted tessellation evaluation shader to ensure that the sets of triangles
|
||||
generated for two adjacent patches have identical vertices along shared
|
||||
patch edges, avoiding ``cracks'' caused by minor differences in the
|
||||
positions of vertices along shared edges.
|
||||
|
||||
*Rule 1* _When processing two patches with identical outer and inner
|
||||
tessellation levels, the tessellation primitive generator will emit an
|
||||
identical set of point, line, or triangle primitives as long as the active
|
||||
program used to process the patch primitives has tessellation evaluation
|
||||
shaders specifying the same tessellation mode, spacing, vertex order, and
|
||||
point mode decorations. Two sets of primitives are considered identical if
|
||||
and only if they contain the same number and type of primitives and the
|
||||
generated tessellation coordinates for the vertex numbered m of the
|
||||
primitive numbered n are identical for all values of m and n._
|
||||
|
||||
*Rule 2* _The set of vertices generated along the outer edge of the
|
||||
subdivided primitive in triangle and quad tessellation, and the tessellation
|
||||
coordinates of each, depends only on the corresponding outer tessellation
|
||||
level and the spacing decorations in the tessellation shaders of the
|
||||
pipeline._
|
||||
|
||||
*Rule 3* _The set of vertices generated when subdividing any outer primitive
|
||||
edge is always symmetric. For triangle tessellation, if the subdivision
|
||||
generates a vertex with tessellation coordinates of the form (0, x, 1-x),
|
||||
(x, 0, 1-x), or (x, 1-x, 0), it will also generate a vertex with coordinates
|
||||
of exactly (0, 1-x, x), (1-x, 0, x), or (1-x, x, 0), respectively. For quad
|
||||
tessellation, if the subdivision generates a vertex with coordinates of (x,
|
||||
0) or (0, x), it will also generate a vertex with coordinates of exactly
|
||||
(1-x, 0) or (0, 1-x), respectively. For isoline tessellation, if it
|
||||
generates vertices at (0, x) and (1, x) where x is not zero, it will also
|
||||
generate vertices at exactly (0, 1-x) and (1, 1-x), respectively._
|
||||
|
||||
*Rule 4* _The set of vertices generated when subdividing outer edges in
|
||||
triangular and quad tessellation must: be independent of the specific edge
|
||||
subdivided, given identical outer tessellation levels and spacing. For
|
||||
example, if vertices at (x, 1 - x, 0) and (1-x, x, 0) are generated when
|
||||
subdividing the w = 0 edge in triangular tessellation, vertices must: be
|
||||
generated at (x, 0, 1-x) and (1-x, 0, x) when subdividing an otherwise
|
||||
identical v = 0 edge. For quad tessellation, if vertices at (x, 0) and
|
||||
(1-x, 0) are generated when subdividing the v = 0 edge, vertices must: be
|
||||
generated at (0, x) and (0, 1-x) when subdividing an otherwise identical
|
||||
u = 0 edge._
|
||||
|
||||
*Rule 5* _When processing two patches that are identical in all respects
|
||||
enumerated in rule 1 except for vertex order, the set of triangles generated
|
||||
for triangle and quad tessellation must: be identical except for vertex and
|
||||
triangle order. For each triangle n1 produced by processing the first patch,
|
||||
there must: be a triangle n2 produced when processing the second patch each
|
||||
of whose vertices has the same tessellation coordinates as one of the
|
||||
vertices in n1._
|
||||
|
||||
*Rule 6* _When processing two patches that are identical in all respects
|
||||
enumerated in rule 1 other than matching outer tessellation levels and/or
|
||||
vertex order, the set of interior triangles generated for triangle and quad
|
||||
tessellation must: be identical in all respects except for vertex and
|
||||
triangle order. For each interior triangle n1 produced by processing the
|
||||
first patch, there must: be a triangle n2 produced when processing the
|
||||
second patch each of whose vertices has the same tessellation coordinates as
|
||||
one of the vertices in n1. A triangle produced by the tessellator is
|
||||
considered an interior triangle if none of its vertices lie on an outer edge
|
||||
of the subdivided primitive._
|
||||
|
||||
*Rule 7* _For quad and triangle tessellation, the set of triangles
|
||||
connecting an inner and outer edge depends only on the inner and outer
|
||||
tessellation levels corresponding to that edge and the spacing decorations._
|
||||
|
||||
*Rule 8* _The value of all defined components of_ code:TessellationCoord
|
||||
_will be in the range [0, 1]. Additionally, for any defined component x of_
|
||||
code:TessellationCoord, _the results of computing 1.0-x in a tessellation
|
||||
evaluation shader will be exact. If any floating-point values in the range
|
||||
[0, 1] fail to satisfy this property, such values mustnot: be used as
|
||||
tessellation coordinate components._
|
||||
|
|
@ -0,0 +1,248 @@
|
|||
// Copyright (c) 2015-2016 The Khronos Group Inc.
|
||||
// Copyright notice at https://www.khronos.org/registry/speccopyright.html
|
||||
|
||||
[appendix]
|
||||
[[spirvenv]]
|
||||
= {apiname} Environment for SPIR-V
|
||||
|
||||
Shaders for {apiname} are defined by the <<Khronos SPIR-V Specification>> as
|
||||
well as the <<Khronos SPIR-V Extended Instructions for GLSL Specification>>.
|
||||
This appendix defines additional SPIR-V requirements applying to {apiname}
|
||||
shaders.
|
||||
|
||||
== Required Versions and Formats
|
||||
|
||||
A {apiname} 1.0 implementation must: support the 1.0 version of SPIR-V and
|
||||
the 1.0 version of the SPIR-V Extended Instructions for GLSL.
|
||||
|
||||
A SPIR-V module passed into flink:vkCreateShaderModule is interpreted as
|
||||
a series of 32-bit words in host endianness, with literal strings packed
|
||||
as described in section 2.2 of the SPIR-V Specification. The first few words
|
||||
of the SPIR-V module must: be a magic number and a SPIR-V version number, as
|
||||
described in section 2.3 of the SPIR-V Specification.
|
||||
|
||||
|
||||
[[spirvenv-capabilities]]
|
||||
== Capabilities
|
||||
|
||||
Implementations must: support the following capability operands declared by
|
||||
*OpCapability*:
|
||||
|
||||
- Matrix
|
||||
- Shader
|
||||
- InputAttachment
|
||||
- Sampled1D
|
||||
- Image1D
|
||||
- SampledBuffer
|
||||
- ImageBuffer
|
||||
- ImageQuery
|
||||
- DerivativeControl
|
||||
|
||||
Implementations may: support features that are not required: by the
|
||||
Specification, as described in the <<features-features,Features>> chapter.
|
||||
If such a feature is supported, then any capability operand(s) corresponding
|
||||
to that feature must: also be supported.
|
||||
|
||||
[[spirvenv-capabilities-table]]
|
||||
.SPIR-V Capabilities which are not required:, and corresponding feature names
|
||||
[options="header"]
|
||||
|====
|
||||
| SPIR-V OpCapability | {apiname} feature name
|
||||
| *Geometry* | <<features-features-geometryShader,geometryShader>>
|
||||
| *Tessellation* | <<features-features-tessellationShader,tessellationShader>>
|
||||
| *Float64* | <<features-features-shaderFloat64,shaderFloat64>>
|
||||
| *Int64* | <<features-features-shaderInt64,shaderInt64>>
|
||||
| *Int16* | <<features-features-shaderInt16,shaderInt16>>
|
||||
| *TessellationPointSize* | <<features-features-shaderTessellationAndGeometryPointSize,shaderTessellationAndGeometryPointSize>>
|
||||
| *GeometryPointSize* | <<features-features-shaderTessellationAndGeometryPointSize,shaderTessellationAndGeometryPointSize>>
|
||||
| *ImageGatherExtended* | <<features-features-shaderImageGatherExtended,shaderImageGatherExtended>>
|
||||
| *StorageImageMultisample* | <<features-features-shaderStorageImageMultisample,shaderStorageImageMultisample>>
|
||||
| *UniformBufferArrayDynamicIndexing* | <<features-features-shaderUniformBufferArrayDynamicIndexing,shaderUniformBufferArrayDynamicIndexing>>
|
||||
| *SampledImageArrayDynamicIndexing* | <<features-features-shaderSampledImageArrayDynamicIndexing,shaderSampledImageArrayDynamicIndexing>>
|
||||
| *StorageBufferArrayDynamicIndexing* | <<features-features-shaderStorageBufferArrayDynamicIndexing,shaderStorageBufferArrayDynamicIndexing>>
|
||||
| *StorageImageArrayDynamicIndexing* | <<features-features-shaderStorageImageArrayDynamicIndexing,shaderStorageImageArrayDynamicIndexing>>
|
||||
| *ClipDistance* | <<features-features-shaderClipDistance,shaderClipDistance>>
|
||||
| *CullDistance* | <<features-features-shaderCullDistance,shaderCullDistance>>
|
||||
| *ImageCubeArray* | <<features-features-imageCubeArray,imageCubeArray>>
|
||||
| *SampleRateShading* | <<features-features-sampleRateShading,sampleRateShading>>
|
||||
| *SparseResidency* | <<features-features-shaderResourceResidency,shaderResourceResidency>>
|
||||
| *MinLod* | <<features-features-shaderResourceMinLod,shaderResourceMinLod>>
|
||||
| *SampledCubeArray* | <<features-features-imageCubeArray,imageCubeArray>>
|
||||
| *ImageMSArray* | <<features-features-shaderStorageImageMultisample,shaderStorageImageMultisample>>
|
||||
| *StorageImageExtendedFormats* | <<features-features-shaderStorageImageExtendedFormats,shaderStorageImageExtendedFormats>>
|
||||
| *InterpolationFunction* | <<features-features-sampleRateShading,sampleRateShading>>
|
||||
| *StorageImageReadWithoutFormat* | <<features-features-shaderStorageImageReadWithoutFormat,shaderStorageImageReadWithoutFormat>>
|
||||
| *StorageImageWriteWithoutFormat* | <<features-features-shaderStorageImageWriteWithoutFormat,shaderStorageImageWriteWithoutFormat>>
|
||||
| *MultiViewport* | <<features-features-multiViewport,multiViewport>>
|
||||
|====
|
||||
|
||||
The application mustnot: pass a SPIR-V module containing any of the
|
||||
following to flink:vkCreateShaderModule:
|
||||
|
||||
- any OpCapability not listed above,
|
||||
- an unsupported capability, or
|
||||
- a capability which corresponds to a {apiname} feature which has not been
|
||||
enabled.
|
||||
|
||||
|
||||
[[spirvenv-module-validation]]
|
||||
== Validation Rules within a Module
|
||||
|
||||
A SPIR-V module passed to flink:vkCreateShaderModule must: conform to the
|
||||
following rules:
|
||||
|
||||
* Every entry point must: have no return value and accept no arguments.
|
||||
* The *Logical* addressing model must: be selected.
|
||||
* *Scope* for execution must: be limited to:
|
||||
** *Workgroup*
|
||||
** *Subgroup*
|
||||
* *Scope* for memory must: be limited to:
|
||||
** *Device*
|
||||
** *Workgroup*
|
||||
** *Invocation*
|
||||
* The *OriginLowerLeft* execution mode mustnot: be used; fragment entry
|
||||
points must: declare *OriginUpperLeft*.
|
||||
* The *PixelCenterInteger* execution mode mustnot: be used. Pixels are
|
||||
always centered at half-integer coordinates.
|
||||
* Images
|
||||
** *OpTypeImage* must: declare a scalar 32-bit float or 32-bit integer
|
||||
type for the ``Sampled Type''. (RelaxedPrecision can: be applied to a
|
||||
sampling instruction and to the variable holding the result of a
|
||||
sampling instruction.)
|
||||
** *OpSampledImage* must: only consume an ``Image'' operand whose type has
|
||||
its ``Sampled'' operand set to 1.
|
||||
** The ``(u, v)'' coordinates used for a *SubpassData* must: be the <id>
|
||||
of a constant vector (0, 0), or if a layer coordinate is used, must: be
|
||||
a vector that was formed with constant 0 for the ``u'' and ``v''
|
||||
components.
|
||||
** The ``Depth'' operand of *OpTypeImage* is ignored.
|
||||
* Decorations
|
||||
** The *GLSLShared* and *GLSLPacked* decorations mustnot: be used.
|
||||
** The code:Flat, code:NoPerspective, code:Sample, and code:Centroid
|
||||
decorations mustnot: be used on variables with storage class other than
|
||||
code:Input or on variables used in the interface of non-fragment shader
|
||||
entry points.
|
||||
** The code:Patch decoration mustnot: be used on variables in the
|
||||
interface of a vertex, geometry, or fragment shader stage's entry
|
||||
point.
|
||||
- *OpTypeRuntimeArray* must: only be used for the last member of an
|
||||
*OpTypeStruct* in the *Uniform* storage class.
|
||||
- Linkage: See <<interfaces,Shader Interfaces>> for additional linking and
|
||||
validation rules.
|
||||
|
||||
|
||||
[[spirvenv-precision-operation]]
|
||||
== Precision and Operation of SPIR-V Instructions
|
||||
|
||||
The following rules apply to both single and double-precision floating point
|
||||
instructions:
|
||||
|
||||
- Positive and negative infinities and positive and negative zeros are
|
||||
generated as dictated by <<IEEE 754>>, but subject to the precisions
|
||||
allowed in the following table.
|
||||
- Dividing a non-zero by a zero results in the appropriately signed <<IEEE
|
||||
754>> infinity.
|
||||
- Any denormalized value input into a shader or potentially generated by
|
||||
any instruction in a shader may: be flushed to 0.
|
||||
- The rounding mode cannot: be set and is undefined.
|
||||
- NaNs maynot: be generated. Instructions that operate on a NaN maynot:
|
||||
result in a NaN.
|
||||
- Support for signaling NaNs is optional: and exceptions are never raised.
|
||||
|
||||
The precision of double-precision instructions is at least that of single
|
||||
precision. For single precision (32 bit) instructions, precisions are
|
||||
required: to be at least as follows, unless decorated with RelaxedPrecision:
|
||||
|
||||
.Precision of core SPIRV Instructions
|
||||
[options="header"]
|
||||
|====
|
||||
|Instruction | Precision
|
||||
|*OpFAdd* | Correctly rounded.
|
||||
|*OpFSub* | Correctly rounded.
|
||||
|*OpFMul* | Correctly rounded.
|
||||
|*OpFOrdEqual*, *OpFUnordEqual* | Correct result.
|
||||
|*OpFOrdLessThan*, *OpFUnordLessThan* | Correct result.
|
||||
|*OpFOrdGreaterThan*, *OpFUnordGreaterThan* | Correct result.
|
||||
|*OpFOrdLessThanEqual*, *OpFUnordLessThanEqual* | Correct result.
|
||||
|*OpFOrdGreaterThanEqual*, *OpFUnordGreaterThanEqual*| Correct result.
|
||||
|*OpFDiv* | 2.5 ULP for b in the range [2^-126^, 2^126^].
|
||||
|conversions between types | Correctly rounded.
|
||||
|====
|
||||
|
||||
Precision of GLSL.std.450 Instructions
|
||||
[options="header"]
|
||||
|====
|
||||
|Instruction | Precision
|
||||
|*fma*() | Inherited from *OpFMul* followed by *OpFAdd*.
|
||||
|*exp*(x), *exp2*(x) | latexmath:[$(3 + 2 \times \|x\|)$] ULP.
|
||||
|*log*(), *log2*() | 3 ULP outside the range [0.5, 2.0]. Absolute error < 2^-21^ inside the range [0.5, 2.0].
|
||||
|*pow*(x, y) | Inherited from *exp2* (y × *log2* (x)).
|
||||
|*sqrt*() | Inherited from 1.0 / *inversesqrt*().
|
||||
|*inversesqrt*() | 2 ULP.
|
||||
|====
|
||||
|
||||
GLSL.std.450 extended instructions specifically defined in terms of the
|
||||
above instructions inherit the above errors. GLSL.std.450 extended
|
||||
instructions not listed above and not defined in terms of the above have
|
||||
undefined precision. These include, for example, the trigonometric functions
|
||||
and determinant.
|
||||
|
||||
For the code:OpSRem and code:OpSMod instructions, if either operand is
|
||||
negative the result is undefined.
|
||||
|
||||
[NOTE]
|
||||
.Note
|
||||
====
|
||||
While the code:OpSRem and code:OpSMod instructions are supported by the
|
||||
{apiname} environment, they require non-negative values and thus do not
|
||||
enable additional functionality beyond what code:OpUMod provides.
|
||||
====
|
||||
|
||||
|
||||
[[spirvenv-image-formats]]
|
||||
Compatibility Between SPIR-V Image Formats And {apiname} Formats
|
||||
----------------------------------------------------------------
|
||||
|
||||
[cols="2*", options="header"]
|
||||
|===
|
||||
|SPIR-V Image Format |{apiname} Format
|
||||
|code:Rgba32f |ename:VK_FORMAT_R32G32B32A32_SFLOAT
|
||||
|code:Rgba16f |ename:VK_FORMAT_R16G16B16A16_SFLOAT
|
||||
|code:R32f |ename:VK_FORMAT_R32_SFLOAT
|
||||
|code:Rgba8 |ename:VK_FORMAT_R8G8B8A8_UNORM
|
||||
|code:Rgba8Snorm |ename:VK_FORMAT_R8G8B8A8_SNORM
|
||||
|code:Rg32f |ename:VK_FORMAT_R32G32_SFLOAT
|
||||
|code:Rg16f |ename:VK_FORMAT_R16G16_SFLOAT
|
||||
|code:R11fG11fB10f |ename:VK_FORMAT_B10G11R11_UFLOAT_PACK32
|
||||
|code:R16f |ename:VK_FORMAT_R16_SFLOAT
|
||||
|code:Rgba16 |ename:VK_FORMAT_R16G16B16A16_UNORM
|
||||
|code:Rgb10A2 |ename:VK_FORMAT_A2B10G10R10_UNORM_PACK32
|
||||
|code:Rg16 |ename:VK_FORMAT_R16G16_UNORM
|
||||
|code:Rg8 |ename:VK_FORMAT_R8G8_UNORM
|
||||
|code:R16 |ename:VK_FORMAT_R16_UNORM
|
||||
|code:R8 |ename:VK_FORMAT_R8_UNORM
|
||||
|code:Rgba16Snorm |ename:VK_FORMAT_R16G16B16A16_SNORM
|
||||
|code:Rg16Snorm |ename:VK_FORMAT_R16G16_SNORM
|
||||
|code:Rg8Snorm |ename:VK_FORMAT_R8G8_SNORM
|
||||
|code:R16Snorm |ename:VK_FORMAT_R16_SNORM
|
||||
|code:R8Snorm |ename:VK_FORMAT_R8_SNORM
|
||||
|code:Rgba32i |ename:VK_FORMAT_R32G32B32A32_SINT
|
||||
|code:Rgba16i |ename:VK_FORMAT_R16G16B16A16_SINT
|
||||
|code:Rgba8i |ename:VK_FORMAT_R8G8B8A8_SINT
|
||||
|code:R32i |ename:VK_FORMAT_R32_SINT
|
||||
|code:Rg32i |ename:VK_FORMAT_R32G32_SINT
|
||||
|code:Rg16i |ename:VK_FORMAT_R16G16_SINT
|
||||
|code:Rg8i |ename:VK_FORMAT_R8G8_SINT
|
||||
|code:R16i |ename:VK_FORMAT_R16_SINT
|
||||
|code:R8i |ename:VK_FORMAT_R8_SINT
|
||||
|code:Rgba32ui |ename:VK_FORMAT_R32G32B32A32_UINT
|
||||
|code:Rgba16ui |ename:VK_FORMAT_R16G16B16A16_UINT
|
||||
|code:Rgba8ui |ename:VK_FORMAT_R8G8B8A8_UINT
|
||||
|code:R32ui |ename:VK_FORMAT_R32_UINT
|
||||
|code:Rgb10a2ui |ename:VK_FORMAT_A2B10G10R10_UINT_PACK32
|
||||
|code:Rg32ui |ename:VK_FORMAT_R32G32_UINT
|
||||
|code:Rg16ui |ename:VK_FORMAT_R16G16_UINT
|
||||
|code:Rg8ui |ename:VK_FORMAT_R8G8_UINT
|
||||
|code:R16ui |ename:VK_FORMAT_R16_UINT
|
||||
|code:R8ui |ename:VK_FORMAT_R8_UINT
|
||||
|===
|
||||
|
|
@ -0,0 +1,84 @@
|
|||
#!/bin/sh
|
||||
# This script builds a full release package including XHTML and PDF
|
||||
# versions of both master and wsi_extensions branches. Other files
|
||||
# in the release directory are removed, including man pages,
|
||||
# XHTML chunked, HTML, validity output, etc.
|
||||
#
|
||||
# Both branches must be fully committed and up to date when the
|
||||
# script is run, with no outstanding un-added / un-committed
|
||||
# files. Both branches must have fully regenerated all
|
||||
# automatically-regeneratable files.
|
||||
#
|
||||
# After completing the build, the current branch is set to 'master'
|
||||
# and suggestions for creating tags are printed out.
|
||||
#
|
||||
# Essentially replaced by genRelease
|
||||
|
||||
# Root of the Vulkan git repo
|
||||
root=/home/tree/git/vulkan
|
||||
|
||||
# Directory with vk.xml and generation tools
|
||||
xml=$root/src/spec
|
||||
|
||||
# Directory with spec sources
|
||||
spec=$root/doc/specs/vulkan
|
||||
|
||||
# Branch name for WSI
|
||||
wsibranch=wsi_extensions
|
||||
|
||||
##################### master Branch #####################
|
||||
|
||||
echo "**** GENERATING MASTER BRANCH ****"
|
||||
git checkout master
|
||||
|
||||
echo "**** AUTOGENERATING HEADERS AND SPEC INCLUDE FILES ****"
|
||||
cd $xml
|
||||
make clobber
|
||||
make full_install
|
||||
|
||||
echo "**** CLEANING SPEC ****"
|
||||
cd $spec
|
||||
outdir=$root/out
|
||||
rm -rf $outdir/man $outdir/xhtml $outdir/pdf $outdir/chunked $outdir/vkspec.html
|
||||
rm specversion.txt
|
||||
|
||||
echo "**** GENERATING SPEC ****"
|
||||
make specversion.txt
|
||||
make OUTDIR=$outdir xhtml pdf
|
||||
rm $outdir/pdf/vkspec.xml
|
||||
git checkout -- specversion.txt
|
||||
|
||||
##################### wsi_extensions Branch #####################
|
||||
|
||||
echo "**** GENERATING WSI BRANCH ****"
|
||||
git checkout $wsibranch
|
||||
|
||||
echo "**** AUTOGENERATING WSI HEADERS AND SPEC INCLUDE FILES ****"
|
||||
cd $xml
|
||||
make clobber
|
||||
make full_install
|
||||
|
||||
echo "**** CLEANING WSI SPEC ****"
|
||||
cd $spec
|
||||
outdir=$root/out/wsi
|
||||
rm -rf $outdir/man $outdir/xhtml $outdir/pdf $outdir/chunked $outdir/vkspec.html
|
||||
rm specversion.txt
|
||||
|
||||
echo "**** GENERATING WSI SPEC ****"
|
||||
make specversion.txt
|
||||
make OUTDIR=$outdir xhtml pdf
|
||||
rm $outdir/pdf/vkspec.xml
|
||||
git checkout -- specversion.txt
|
||||
|
||||
##################### Post-generation cleanup #####################
|
||||
|
||||
git checkout master
|
||||
echo "*** Spec generaion complete, on master branch"
|
||||
echo "To tag the spec branches, do the following:"
|
||||
|
||||
date=`date +%Y%m%d`
|
||||
echo git checkout master
|
||||
echo git tag -a -m '"Tag core API specification for' $date 'release"' v1.0-core-$date
|
||||
|
||||
echo git checkout $wsibranch
|
||||
echo git tag -a -m '"Tag core+WSI API specification for' $date 'release"' v1.0-core+wsi-$date
|
||||
|
|
@ -0,0 +1,268 @@
|
|||
// Copyright (c) 2015-2016 The Khronos Group Inc.
|
||||
// Copyright notice at https://www.khronos.org/registry/speccopyright.html
|
||||
|
||||
[[clears]]
|
||||
= Clear Commands
|
||||
|
||||
|
||||
[[clears-outside]]
|
||||
== Clearing Images Outside A Render Pass Instance
|
||||
|
||||
Color and depth/stencil images can: be cleared outside a render pass
|
||||
instance using flink:vkCmdClearColorImage or
|
||||
flink:vkCmdClearDepthStencilImage, respectively. These commands are only
|
||||
allowed outside of a render pass instance.
|
||||
|
||||
To clear one or more subranges of a color image, call:
|
||||
|
||||
include::../protos/vkCmdClearColorImage.txt[]
|
||||
|
||||
* pname:commandBuffer is the command buffer into which the command will be
|
||||
recorded.
|
||||
* pname:image is the image to be cleared.
|
||||
* pname:imageLayout specifies the current layout of the image subresource
|
||||
ranges to be cleared, and must: be ename:VK_IMAGE_LAYOUT_GENERAL or
|
||||
ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL.
|
||||
* pname:pColor is a pointer to a slink:VkClearColorValue structure that
|
||||
contains the values the image subresource ranges will be cleared to (see
|
||||
<<clears-values>> below).
|
||||
* pname:rangeCount is the number of subresource range structures in
|
||||
pname:pRanges.
|
||||
* pname:pRanges points to an array of slink:VkImageSubresourceRange
|
||||
structures that describe a range of mipmap levels, array layers, and
|
||||
aspects to be cleared, as described in <<resources-image-views,Image
|
||||
Views>>. The pname:aspectMask of all subresource ranges must: only
|
||||
include ename:VK_IMAGE_ASPECT_COLOR_BIT.
|
||||
|
||||
Each specified range in pname:pRanges is cleared to the value specified by
|
||||
pname:pColor.
|
||||
|
||||
include::../validity/protos/vkCmdClearColorImage.txt[]
|
||||
|
||||
To clear one or more subranges of a depth/stencil image, call:
|
||||
|
||||
include::../protos/vkCmdClearDepthStencilImage.txt[]
|
||||
|
||||
* pname:commandBuffer is the command buffer into which the command will be
|
||||
recorded.
|
||||
* pname:image is the image to be cleared.
|
||||
* pname:imageLayout specifies the current layout of the image subresource
|
||||
ranges to be cleared, and must: be ename:VK_IMAGE_LAYOUT_GENERAL or
|
||||
ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL.
|
||||
* pname:pDepthStencil is a pointer to a slink:VkClearDepthStencilValue
|
||||
structure that contains the values the depth and stencil image
|
||||
subresource ranges will be cleared to (see <<clears-values>> below).
|
||||
* pname:rangeCount is the number of subresource range structures in
|
||||
pname:pRanges.
|
||||
* pname:pRanges points to an array of slink:VkImageSubresourceRange
|
||||
structures that describe a range of mipmap levels, array layers, and
|
||||
aspects to be cleared, as described in <<resources-image-views,Image
|
||||
Views>>. The pname:aspectMask of each subresource range in pname:pRanges
|
||||
can: include ename:VK_IMAGE_ASPECT_DEPTH_BIT if the image format has a
|
||||
depth component, and ename:VK_IMAGE_ASPECT_STENCIL_BIT if the image
|
||||
format has a stencil component. pname:pDepthStencil is a pointer to a
|
||||
sname:VkClearDepthStencilValue structure that contains the values the
|
||||
image subresource ranges will be cleared to (see <<clears-values>>
|
||||
below).
|
||||
|
||||
include::../validity/protos/vkCmdClearDepthStencilImage.txt[]
|
||||
|
||||
Clears outside render pass instances are treated as transfer operations for
|
||||
the purposes of memory barriers.
|
||||
|
||||
|
||||
[[clears-inside]]
|
||||
== Clearing Images Inside A Render Pass Instance
|
||||
|
||||
To clear one or more regions of color and depth/stencil attachments inside a
|
||||
render pass instance, call:
|
||||
|
||||
include::../protos/vkCmdClearAttachments.txt[]
|
||||
|
||||
* pname:commandBuffer is the command buffer into which the command will be
|
||||
recorded.
|
||||
* pname:attachmentCount is the number of entries in the pname:pAttachments
|
||||
array.
|
||||
* pname:pAttachments is a pointer to an array of slink:VkClearAttachment
|
||||
structures defining the attachments to clear and the clear values to
|
||||
use.
|
||||
* pname:rectCount is the number of entries in the pname:pRects array.
|
||||
* pname:pRects points to an array of slink:VkClearRect structures defining
|
||||
regions within each selected attachment to clear. describe these
|
||||
regions.
|
||||
|
||||
fname:vkCmdClearAttachments can: clear multiple regions of each attachment
|
||||
used in the current subpass of a render pass instance. This command must: be
|
||||
called only inside a render pass instance, and implicitly selects the images
|
||||
to clear based on the current framebuffer attachments and the command
|
||||
parameters.
|
||||
|
||||
include::../validity/protos/vkCmdClearAttachments.txt[]
|
||||
|
||||
The sname:VkClearRect struct is defined as follows:
|
||||
|
||||
include::../structs/VkClearRect.txt[]
|
||||
|
||||
* pname:rect is the two-dimensional region to be cleared.
|
||||
* pname:baseArrayLayer is the first layer to be cleared.
|
||||
* pname:layerCount is the number of layers to clear.
|
||||
|
||||
The layers latexmath:[$[baseArrayLayer, baseArrayLayer+layerCount)$]
|
||||
counting from the base layer of the attachment image view are cleared.
|
||||
|
||||
include::../validity/structs/VkClearRect.txt[]
|
||||
|
||||
The sname:VkClearAttachment struct is defined as follows:
|
||||
|
||||
include::../structs/VkClearAttachment.txt[]
|
||||
|
||||
* pname:aspectMask is a mask selecting the color, depth and/or stencil
|
||||
aspects of the attachment to be cleared. pname:aspectMask can: include
|
||||
ename:VK_IMAGE_ASPECT_COLOR_BIT for color attachments,
|
||||
ename:VK_IMAGE_ASPECT_DEPTH_BIT for depth/stencil attachments with a
|
||||
depth component, and ename:VK_IMAGE_ASPECT_STENCIL_BIT for depth/stencil
|
||||
attachments with a stencil component.
|
||||
* pname:colorAttachment is only meaningful if
|
||||
ename:VK_IMAGE_ASPECT_COLOR_BIT is set in pname:aspectMask, in which
|
||||
case it is an index to the pname:pColorAttachments array in the
|
||||
slink:VkSubpassDescription structure of the current subpass which
|
||||
selects the color attachment to clear.
|
||||
* pname:clearValue is the color or depth/stencil value to clear the
|
||||
attachment to, as described in <<clears-values,Clear Values>> below.
|
||||
|
||||
No memory barriers are needed between fname:vkCmdClearAttachments and
|
||||
preceding or subsequent draw or attachment clear commands in the same
|
||||
subpass.
|
||||
|
||||
The fname:vkCmdClearAttachments commands is not affected by the bound
|
||||
pipeline state.
|
||||
|
||||
Attachments can: also be cleared at the beginning of a render pass instance
|
||||
by setting pname:loadOp (or pname:stencilLoadOp) of
|
||||
slink:VkAttachmentDescription to ename:VK_ATTACHMENT_LOAD_OP_CLEAR, as
|
||||
described for flink:vkCreateRenderPass.
|
||||
|
||||
include::../validity/structs/VkClearAttachment.txt[]
|
||||
|
||||
|
||||
[[clears-values]]
|
||||
== Clear Values
|
||||
|
||||
The definition of sname:VkClearColorValue is as follows:
|
||||
|
||||
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.
|
||||
|
||||
The four array elements of the clear color map to R, G, B, and A components
|
||||
of image formats, in order.
|
||||
|
||||
If the image has more than one sample, the same value is written to all
|
||||
samples for any pixels being cleared. The ftext:vkClear*Image commands do
|
||||
not support compressed image formats.
|
||||
|
||||
include::../validity/structs/VkClearColorValue.txt[]
|
||||
|
||||
The definition of sname:VkClearDepthStencilValue is as follows:
|
||||
|
||||
include::../structs/VkClearDepthStencilValue.txt[]
|
||||
|
||||
* pname:depth is the clear value for the depth aspect of the depth/stencil
|
||||
attachment. It is a floating-point value which is automatically
|
||||
converted to the attachment's format.
|
||||
* pname:stencil is the clear value for the stencil aspect of the
|
||||
depth/stencil attachment. It is a 32-bit integer value which is
|
||||
converted to the attachment's format by taking the appropriate number of
|
||||
LSBs.
|
||||
|
||||
include::../validity/structs/VkClearDepthStencilValue.txt[]
|
||||
|
||||
Some parts of the API require either color or depth/stencil clear values,
|
||||
depending on the attachment. For this the sname:VkClearValue union is
|
||||
defined as follows:
|
||||
|
||||
include::../structs/VkClearValue.txt[]
|
||||
|
||||
* pname:color specifies the color image clear values to use when
|
||||
clearing a color image or attachment.
|
||||
* 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.
|
||||
|
||||
include::../validity/structs/VkClearValue.txt[]
|
||||
|
||||
|
||||
[[clears-filling-buffers]]
|
||||
== Filling Buffers
|
||||
|
||||
To clear buffer data, call:
|
||||
|
||||
include::../protos/vkCmdFillBuffer.txt[]
|
||||
|
||||
* pname:commandBuffer is the command buffer into which the command will be
|
||||
recorded.
|
||||
* pname:dstBuffer is the buffer to be filled.
|
||||
* pname:dstOffset is the byte offset into the buffer at which to start
|
||||
filling, and must: be a multiple of 4.
|
||||
* pname:size is the number of bytes to fill, and must: be either a
|
||||
multiple of 4, or ename:VK_WHOLE_SIZE to fill the range from
|
||||
pname:offset to the end of the buffer.
|
||||
* pname:data is the 4-byte word written repeatedly to the buffer to fill
|
||||
pname:size bytes of data. The data word is written to memory according
|
||||
to the host endianness.
|
||||
|
||||
fname:vkCmdFillBuffer 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 buffer to be compatible with fname:vkCmdFillBuffer.
|
||||
|
||||
include::../validity/protos/vkCmdFillBuffer.txt[]
|
||||
|
||||
|
||||
[[clears-updating-buffers]]
|
||||
== Updating Buffers
|
||||
|
||||
To update buffer data inline in a command buffer, call:
|
||||
|
||||
include::../protos/vkCmdUpdateBuffer.txt[]
|
||||
|
||||
* pname:commandBuffer is the command buffer into which the command will be
|
||||
recorded.
|
||||
* pname:dstBuffer is a handle to the buffer to be updated.
|
||||
* pname:dstOffset is the byte offset into the buffer to start updating,
|
||||
and must: be a multiple of 4.
|
||||
* pname:dataSize is the number of bytes to update, and must: be a multiple
|
||||
of 4.
|
||||
* pname:pData is a pointer to the source data for the buffer update, and
|
||||
must: be at least pname:dataSize bytes in size.
|
||||
|
||||
pname:dataSize must: be less than or equal to 65536 bytes. For larger
|
||||
updates, applications can: use buffer to buffer <<copies-buffers,copies>>.
|
||||
|
||||
The source data is copied from the user pointer to the command buffer when
|
||||
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
|
||||
buffer to be compatible with fname:vkCmdUpdateBuffer.
|
||||
|
||||
include::../validity/protos/vkCmdUpdateBuffer.txt[]
|
||||
|
||||
[[clears-end]]
|
||||
|
|
@ -0,0 +1,521 @@
|
|||
// Copyright (c) 2015-2016 The Khronos Group Inc.
|
||||
// Copyright notice at https://www.khronos.org/registry/speccopyright.html
|
||||
|
||||
[[commandbuffers]]
|
||||
= Command Buffers
|
||||
|
||||
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
|
||||
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.
|
||||
|
||||
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
|
||||
secondary command buffers (for primary command buffers only), commands to
|
||||
copy buffers and images, and other commands.
|
||||
|
||||
[[commandbuffers-statereset]]
|
||||
Each command buffer manages state independently of other command buffers.
|
||||
There is no inheritance of state across primary and secondary command
|
||||
buffers, or between secondary command buffers. When a command buffer begins
|
||||
recording, all state in that command buffer is undefined. When secondary
|
||||
command buffer(s) are recorded to execute on a primary command buffer, the
|
||||
secondary command buffer inherits no state from the primary command buffer,
|
||||
and all state of the primary command buffer is undefined after an execute
|
||||
secondary command buffer command is recorded. There is one exception to this
|
||||
rule - if the primary command buffer is inside a render pass instance, then
|
||||
the render pass and subpass state is not disturbed by executing secondary
|
||||
command buffers. Whenever the state of a command buffer is undefined, the
|
||||
application must: set all relevant state on the command buffer before any
|
||||
state dependent commands such as draws and dispatches are recorded,
|
||||
otherwise the behavior of executing that command buffer is undefined.
|
||||
|
||||
Unless otherwise specified, and without explicit synchronization, the
|
||||
various commands submitted to a queue via command buffers may: execute in
|
||||
arbitrary order relative to each other, and/or concurrently. Also, the
|
||||
memory side-effects of those commands maynot: be directly visible to other
|
||||
commands without memory barriers. This is true within a command buffer, and
|
||||
across command buffers submitted to a given queue. See
|
||||
<<synchronization-events>>, <<synchronization-pipeline-barriers>> and
|
||||
<<synchronization-memory-barriers>> about synchronization primitives
|
||||
suitable to guarantee execution order and side-effect visibility between
|
||||
commands on a given queue.
|
||||
|
||||
Each command buffer is always in one of three states:
|
||||
|
||||
* _Initial state_: Before flink:vkBeginCommandBuffer. Either
|
||||
flink:vkBeginCommandBuffer has never been called, or the command buffer
|
||||
has been reset since it last recorded commands.
|
||||
* _Recording state_: Between flink:vkBeginCommandBuffer and
|
||||
flink:vkEndCommandBuffer. The command buffer is in a state where it can:
|
||||
record commands.
|
||||
* _Executable state_: After flink:vkEndCommandBuffer. The command buffer
|
||||
is in a state where it has finished recording commands and can: be
|
||||
executed.
|
||||
|
||||
_Resetting_ a command buffer is an operation that discards any previously
|
||||
recorded commands and puts a command buffer in the initial state. Resetting
|
||||
occurs as a result of flink:vkResetCommandBuffer or
|
||||
flink:vkResetCommandPool, or as part of flink:vkBeginCommandBuffer (which
|
||||
additionally puts the command buffer in the recording state).
|
||||
|
||||
|
||||
[[commandbuffers-pools]]
|
||||
== Command Pools
|
||||
|
||||
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
|
||||
application-synchronized, meaning that a command pool mustnot: be used
|
||||
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.
|
||||
|
||||
To create a command pool, call:
|
||||
|
||||
include::../protos/vkCreateCommandPool.txt[]
|
||||
|
||||
* pname:device is the logical device that creates the command pool.
|
||||
* pname:pCreateInfo contains information used to create the command pool.
|
||||
* pname:pAllocator controls host memory allocation as described in the
|
||||
<<memory-allocation, Memory Allocation>> chapter.
|
||||
* pname:pCommandPool points to an sname:VkCommandPool handle in which the
|
||||
created pool is returned.
|
||||
|
||||
include::../validity/protos/vkCreateCommandPool.txt[]
|
||||
|
||||
The sname:VkCommandPoolCreateInfo structure is defined as follows:
|
||||
|
||||
include::../structs/VkCommandPoolCreateInfo.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 combination of bitfield flags indicating usage behavior
|
||||
for the pool and command buffers allocated from it. Possible values
|
||||
include:
|
||||
+
|
||||
--
|
||||
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.
|
||||
--
|
||||
* 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
|
||||
from the same queue family.
|
||||
|
||||
include::../validity/structs/VkCommandPoolCreateInfo.txt[]
|
||||
|
||||
Reset a command pool by calling:
|
||||
|
||||
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[]
|
||||
|
||||
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 of type elink:VkCommandPoolResetFlags, which is defined as:
|
||||
|
||||
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.
|
||||
|
||||
To destroy a command pool, call:
|
||||
|
||||
include::../protos/vkDestroyCommandPool.txt[]
|
||||
|
||||
* pname:device is the logical device that destroys the command pool.
|
||||
* pname:commandPool is the handle of the command pool to destroy.
|
||||
* 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.
|
||||
|
||||
|
||||
[[commandbuffers-lifetime]]
|
||||
== Command Buffer Lifetime
|
||||
|
||||
Command buffers are allocated by calling:
|
||||
|
||||
include::../protos/vkAllocateCommandBuffers.txt[]
|
||||
|
||||
* pname:device is the logical device that owns the command pool.
|
||||
* pname:pAllocateInfo is an instance of the
|
||||
sname:VkCommandBufferAllocateInfo structure which defines additional
|
||||
information about creating the pool.
|
||||
* pname:pCommandBuffers points to an array in which the allocated command
|
||||
buffers are returned. Each allocated command buffer begins in the
|
||||
initial state.
|
||||
|
||||
include::../validity/protos/vkAllocateCommandBuffers.txt[]
|
||||
|
||||
The sname:VkCommandBufferAllocateInfo structure is defined as:
|
||||
|
||||
include::../structs/VkCommandBufferAllocateInfo.txt[]
|
||||
|
||||
* pname:sType is the type of this structure.
|
||||
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
|
||||
* pname:commandPool is the name of the command pool that the command
|
||||
buffers allocate their memory from.
|
||||
* pname:level determines whether the command buffers are primary or
|
||||
secondary command buffers. Possible values include:
|
||||
+
|
||||
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:
|
||||
|
||||
include::../protos/vkResetCommandBuffer.txt[]
|
||||
|
||||
* pname:commandBuffer is the command buffer to reset. The command buffer
|
||||
can: be in any state, and is put in the initial state.
|
||||
* pname:flags is of type elink:VkCommandBufferResetFlags:
|
||||
+
|
||||
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:
|
||||
|
||||
include::../protos/vkFreeCommandBuffers.txt[]
|
||||
|
||||
* pname:device is the logical device that owns the command pool.
|
||||
* pname:commandPool is the handle of the command pool that the command
|
||||
buffers were allocated from.
|
||||
* pname:commandBufferCount is the length of the pname:pCommandBuffers
|
||||
array.
|
||||
* pname:pCommandBuffers is an array of handles of command buffers to free.
|
||||
|
||||
include::../validity/protos/vkFreeCommandBuffers.txt[]
|
||||
|
||||
|
||||
[[commandbuffers-recording]]
|
||||
== Command Buffer Recording
|
||||
|
||||
To begin recording a command buffer, call:
|
||||
|
||||
include::../protos/vkBeginCommandBuffer.txt[]
|
||||
|
||||
* pname:commandBuffer is the handle of the command buffer which is to be
|
||||
put in the recording state.
|
||||
* pname:pBeginInfo is an instance of the sname:VkCommandBufferBeginInfo
|
||||
structure, which defines additional information about how the command
|
||||
buffer begins recording.
|
||||
|
||||
include::../validity/protos/vkBeginCommandBuffer.txt[]
|
||||
|
||||
The sname:VkCommandBufferBeginInfo structure is defined as:
|
||||
|
||||
include::../structs/VkCommandBufferBeginInfo.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 combination of bitfield flags indicating usage behavior
|
||||
for the command buffer. Possible values include:
|
||||
+
|
||||
--
|
||||
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.
|
||||
--
|
||||
* 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
|
||||
command buffer, then this value is ignored.
|
||||
|
||||
include::../validity/structs/VkCommandBufferBeginInfo.txt[]
|
||||
|
||||
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:
|
||||
|
||||
include::../structs/VkCommandBufferInheritanceInfo.txt[]
|
||||
|
||||
* pname:renderPass is a sname:VkRenderPass object that must: be
|
||||
<<renderpass-compatibility, compatible>> with the one that is bound when
|
||||
the sname:VkCommandBuffer is executed if the command buffer was
|
||||
allocated with the
|
||||
ename:VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT set.
|
||||
* pname:subpass is the index of the subpass within pname:renderPass that
|
||||
the sname:VkCommandBuffer will be rendering against if it was allocated
|
||||
with the ename:VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT set.
|
||||
* 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 sname:VK_NULL_HANDLE if the framebuffer is not known.
|
||||
+
|
||||
[NOTE]
|
||||
.Note
|
||||
====
|
||||
Specifying the exact framebuffer that the secondary command buffer will be
|
||||
executed with may: result in better performance at command buffer execution
|
||||
time.
|
||||
====
|
||||
* pname:occlusionQueryEnable indicates whether the command buffer can: be
|
||||
executed while an occlusion query is active in the primary command
|
||||
buffer. If this is ename:VK_TRUE, then this command buffer can: be
|
||||
executed whether the primary command buffer has an occlusion query
|
||||
active or not. If this is ename:VK_FALSE, then the primary command
|
||||
buffer mustnot: have an occlusion query active.
|
||||
* pname:queryFlags indicates the query flags that can: be used by an
|
||||
active occlusion query in the primary command buffer when this secondary
|
||||
command buffer is executed. If this value includes the
|
||||
ename:VK_QUERY_CONTROL_PRECISE_BIT bit, then the active query can:
|
||||
return boolean results or actual sample counts. If this bit is not set,
|
||||
then the active query mustnot: use the
|
||||
ename:VK_QUERY_CONTROL_PRECISE_BIT bit. If this is a primary command
|
||||
buffer, then this value is ignored.
|
||||
* pname:pipelineStatistics indicates the set of pipeline statistics that
|
||||
can: be counted by an active query in the primary command buffer when
|
||||
this secondary command buffer is executed. If this value includes a
|
||||
given bit, then this command buffer can: be executed whether the primary
|
||||
command buffer has a pipeline statistics query active that includes this
|
||||
bit or not. If this value excludes a given bit, then the active pipeline
|
||||
statistics query mustnot: be from a query pool that counts that
|
||||
statistic.
|
||||
|
||||
include::../validity/structs/VkCommandBufferInheritanceInfo.txt[]
|
||||
|
||||
A primary command buffer is considered to be pending execution from the time
|
||||
it is submitted via fname:vkQueueSubmit until that submission completes.
|
||||
|
||||
A secondary command buffer is considered to be pending execution from the
|
||||
time its execution is recorded into a primary buffer (via
|
||||
fname:vkCmdExecuteCommands) until the final time that primary buffer's
|
||||
submission to a queue completes. If, after the primary buffer completes, the
|
||||
secondary command buffer is recorded to execute on a different primary
|
||||
buffer, the first primary buffer mustnot: be resubmitted until after it is
|
||||
reset with flink:vkResetCommandBuffer.
|
||||
|
||||
If ename:VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT is not set on a
|
||||
secondary command buffer, that command buffer mustnot: be used more than
|
||||
once in a given primary command buffer. Furthermore, if a secondary command
|
||||
buffer without ename:VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT set is
|
||||
recorded to execute in a primary command buffer with
|
||||
ename:VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT set, the primary command
|
||||
buffer mustnot: be pending execution more than once at a time.
|
||||
|
||||
[NOTE]
|
||||
.Note
|
||||
====
|
||||
On some implementations, not using the
|
||||
ename:VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT bit enables command
|
||||
buffers to be patched in-place if needed, rather than creating a copy of the
|
||||
command buffer.
|
||||
====
|
||||
|
||||
If a command buffer is in the executable state and the command buffer was
|
||||
allocated from a command pool with the
|
||||
ename:VK_COMMAND_POOL_CREATE_RESET_COMMAND_BUFFER_BIT flag set, then
|
||||
fname:vkBeginCommandBuffer implicitly resets the command buffer, behaving as
|
||||
if fname:vkResetCommandBuffer had been called with
|
||||
ename:VK_COMMAND_BUFFER_RESET_RELEASE_RESOURCES_BIT not set. It then puts
|
||||
the command buffer in the recording state.
|
||||
|
||||
Once recording starts, an application records a sequence of commands
|
||||
(ftext:vkCmd*) to set state in the command buffer, draw, dispatch, and other
|
||||
commands.
|
||||
|
||||
To complete recording of a command buffer, call:
|
||||
|
||||
include::../protos/vkEndCommandBuffer.txt[]
|
||||
|
||||
* pname:commandBuffer is the command buffer to complete recording. The
|
||||
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.
|
||||
|
||||
When a command buffer is in the executable state, it can: be submitted to a
|
||||
queue for execution.
|
||||
|
||||
|
||||
[[commandbuffers-submission]]
|
||||
== Command Buffer Submission
|
||||
|
||||
Command buffers are submitted to a queue by calling:
|
||||
|
||||
include::../protos/vkQueueSubmit.txt[]
|
||||
|
||||
* pname:queue is the handle of the queue that the command buffers will be
|
||||
submitted to.
|
||||
* pname:submitCount is the number of elements in the pname:pSubmits array.
|
||||
* pname:pSubmits is a pointer to an array of slink:VkSubmitInfo structures
|
||||
which describe the work to submit. All work described by pname:pSubmits
|
||||
must: be submitted to the queue before the command returns.
|
||||
* pname:fence is an optional handle to a fence. If pname:fence is not
|
||||
sname:VK_NULL_HANDLE, the fence is signaled when execution of all
|
||||
sname:VkSubmitInfo::pname:pCommandBuffers members of pname:pSubmits is
|
||||
completed. If pname:submitCount is zero but pname:fence is not
|
||||
sname:VK_NULL_HANDLE, the fence will still be submitted to the queue and
|
||||
will become signaled when all work previously submitted to the queue has
|
||||
completed.
|
||||
|
||||
ifdef::editing-notes[]
|
||||
[NOTE]
|
||||
.editing-note
|
||||
====
|
||||
(Jon) The description of pname:fence here was added from the ref page
|
||||
because it was missing from the starting point of MR #1048, which is just
|
||||
about cleaning up the markup of command parameters. It needs to be resolved
|
||||
with the description far below of pname:fence, as noted by @jbolz, because
|
||||
they're not very similar and because most of the second description belongs
|
||||
in validity XML language.
|
||||
====
|
||||
endif::editing-notes[]
|
||||
|
||||
include::../validity/protos/vkQueueSubmit.txt[]
|
||||
|
||||
Each submission of work is represented by a sequence of command buffers,
|
||||
each preceded by a list of semaphores upon which to wait before beginning
|
||||
execution of specific stages of commands in the command buffers, and
|
||||
followed by a second list of semaphores to signal upon completion of the
|
||||
work contained in the command buffers.
|
||||
|
||||
[NOTE]
|
||||
.Note
|
||||
====
|
||||
The exact definition of a submission is platform-specific, but is considered
|
||||
a relatively expensive operation. In general, applications should: attempt
|
||||
to batch work together into as few calls to fname:vkQueueSubmit as possible.
|
||||
====
|
||||
|
||||
Each call to fname:vkQueueSubmit submits zero or more _batches_ of work to
|
||||
the queue for execution. pname:submitCount is used to specify the number of
|
||||
batches to submit. Each batch includes zero or more semaphores to wait upon,
|
||||
and a corresponding set of stages that will wait for the semaphore to be
|
||||
signalled before executing any work, followed by a number of command buffers
|
||||
that will be executed, and finally, zero or more semaphores that will be
|
||||
signaled after command buffer execution completes. Each batch is represented
|
||||
as an instance of the slink:VkSubmitInfo structure stored in an array, the
|
||||
address of which is passed in pname:pSubmitInfo. The definition of
|
||||
sname:VkSubmitInfo is:
|
||||
|
||||
include::../structs/VkSubmitInfo.txt[]
|
||||
|
||||
* pname:sType is the type of this structure.
|
||||
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
|
||||
* pname:waitSemaphoreCount is the number of semaphores upon which
|
||||
to wait before executing the command buffers for the batch.
|
||||
* pname:pWaitSemaphores is a pointer to an array of semaphores upon which
|
||||
to wait before executing the command buffers in the batch.
|
||||
* pname:pWaitDstStageMask is a pointer to an array of pipeline stages at
|
||||
which each corresponding semaphore wait will occur.
|
||||
* pname:commandBufferCount contains the number of command buffers to
|
||||
execute in the batch.
|
||||
* pname:pCommandBuffers is a pointer to an array of command buffers to
|
||||
execute in the batch. The command buffers submitted in a batch begin
|
||||
execution in the order they appear in pname:pCommandBuffers, but may:
|
||||
complete out of order.
|
||||
* pname:signalSemaphoreCount is the number of semaphores to be
|
||||
signaled once the commands specified in pname:pCommandBuffers have
|
||||
completed execution.
|
||||
* pname:pSignalSemaphores is a pointer to an array of semaphores which
|
||||
will be signaled when the command buffers for this batch have completed
|
||||
execution.
|
||||
|
||||
include::../validity/structs/VkSubmitInfo.txt[]
|
||||
|
||||
If pname:fence is provided, it must: be in the unsignaled state (see
|
||||
<<synchronization-fences,Fences>>) and a fence must: only be associated with
|
||||
a single submission until that submission completes, and the fence is
|
||||
subsequently reset. When all command buffers in pname:pCommandBuffers have
|
||||
completed execution, the status of pname:fence is set to signaled, providing
|
||||
certain <<synchronization-implicit-ordering,implicit ordering guarantees>>.
|
||||
|
||||
|
||||
[[commandbuffers-submission-progress]]
|
||||
== Queue Forward Progress
|
||||
|
||||
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
|
||||
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
|
||||
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
|
||||
these limits, results are undefined and may: include device loss.
|
||||
|
||||
|
||||
[[commandbuffers-secondary]]
|
||||
== Secondary Command Buffer Execution
|
||||
|
||||
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:
|
||||
|
||||
include::../protos/vkCmdExecuteCommands.txt[]
|
||||
|
||||
* pname:commandBuffer is a handle to a primary command buffer that the
|
||||
secondary command buffers are submitted to, and must: be in the
|
||||
recording state.
|
||||
* pname:commandBufferCount is the length of the pname:pCommandBuffers
|
||||
array.
|
||||
* pname:pCommandBuffers is an array of secondary command buffer handles,
|
||||
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.
|
||||
|
|
@ -0,0 +1,519 @@
|
|||
// Copyright (c) 2015-2016 The Khronos Group Inc.
|
||||
// Copyright notice at https://www.khronos.org/registry/speccopyright.html
|
||||
|
||||
[[copies]]
|
||||
= Copy Commands
|
||||
|
||||
An application can: copy buffer and image data using several methods
|
||||
depending on the type of data transfer. Data can: be copied between buffer
|
||||
objects with fname:vkCmdCopyBuffer and a portion of an image can: be copied
|
||||
to another image with fname:vkCmdCopyImage. Image data can: also be
|
||||
copied to and from buffer memory using fname:vkCmdCopyImageToBuffer and
|
||||
fname:vkCmdCopyBufferToImage. Image data can: be blitted (with or without
|
||||
scaling and filtering) with fname:vkCmdBlitImage. Multisampled images can:
|
||||
be resolved to a non-multisampled image with fname:vkCmdResolveImage.
|
||||
|
||||
|
||||
== Common Operation
|
||||
|
||||
Some rules for valid operation are common to all copy commands:
|
||||
|
||||
* Copy commands must: be recorded outside of a render pass instance.
|
||||
* For non-sparse resources, the union of the source regions in a given
|
||||
buffer or image must: not overlap the union of the destination regions
|
||||
in the same buffer or image.
|
||||
* For sparse resources, the set of bytes used by all the source regions
|
||||
must: not intersect the set of bytes used by all the destination
|
||||
regions.
|
||||
* Copy regions must: be non-empty.
|
||||
* Regions must: not extend outside the bounds of the buffer or image
|
||||
level, except that regions of compressed images can: extend as far as
|
||||
the dimension of the image level rounded up to a complete block.
|
||||
* Source image subresources must: be in either the
|
||||
ename:VK_IMAGE_LAYOUT_GENERAL or
|
||||
ename:VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL layout. Destination image
|
||||
subresources must: be in either the ename:VK_IMAGE_LAYOUT_GENERAL or
|
||||
ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL layout. As a consequence, if
|
||||
an image subresource is used as both source and destination of a copy,
|
||||
it must: be in the ename:VK_IMAGE_LAYOUT_GENERAL layout.
|
||||
* Source images must: have been created with the
|
||||
ename:VK_IMAGE_USAGE_TRANSFER_SRC_BIT usage bit enabled and destination
|
||||
images must: have been created with the
|
||||
ename:VK_IMAGE_USAGE_TRANSFER_DST_BIT usage bit enabled.
|
||||
* Source buffers must: have been created with the
|
||||
ename:VK_BUFFER_USAGE_TRANSFER_SRC_BIT usage bit enabled and destination
|
||||
buffers must: have been created with the
|
||||
ename:VK_BUFFER_USAGE_TRANSFER_DST_BIT usage bit enabled.
|
||||
|
||||
All copy commands are treated as ``transfer'' operations for the purposes of
|
||||
synchronization barriers.
|
||||
|
||||
|
||||
[[copies-buffers]]
|
||||
== Copying Data Between Buffers
|
||||
|
||||
To copy data between buffer objects, call:
|
||||
|
||||
include::../protos/vkCmdCopyBuffer.txt[]
|
||||
|
||||
* pname:commandBuffer is the command buffer into which the command will be
|
||||
recorded.
|
||||
* pname:srcBuffer is the source buffer.
|
||||
* pname:dstBuffer is the destination buffer.
|
||||
* pname:regionCount is the number of regions to copy.
|
||||
* pname:pRegions is a pointer to an array of slink:VkBufferCopy structures
|
||||
specifying the regions to copy.
|
||||
|
||||
Each region in pname:pRegions is copied from the source buffer to the same
|
||||
region of the destination buffer. pname:srcBuffer and pname:dstBuffer can:
|
||||
be the same buffer or alias the same memory, but the result is undefined if
|
||||
the copy regions overlap in memory.
|
||||
|
||||
include::../validity/protos/vkCmdCopyBuffer.txt[]
|
||||
|
||||
Each element of pname:pRegions is a structure defined as:
|
||||
|
||||
include::../structs/VkBufferCopy.txt[]
|
||||
|
||||
* pname:srcOffset is the starting offset in bytes from the start of
|
||||
pname:srcBuffer.
|
||||
* pname:dstOffset is the starting offset in bytes from the start of
|
||||
pname:dstBuffer.
|
||||
* pname:size is the number of bytes to copy.
|
||||
|
||||
include::../validity/structs/VkBufferCopy.txt[]
|
||||
|
||||
|
||||
[[copies-images]]
|
||||
== Copying Data Between Images
|
||||
|
||||
fname:vkCmdCopyImage performs image copies in a similar manner to a host
|
||||
memcpy. It does not perform general-purpose conversions such as scaling,
|
||||
resizing, blending, color-space conversion, or format conversions.
|
||||
Rather, it simply copies raw image data. fname:vkCmdCopyImage can: copy
|
||||
between images with different formats, provided the formats are compatible
|
||||
as defined below.
|
||||
|
||||
To copy data between image objects, call:
|
||||
|
||||
include::../protos/vkCmdCopyImage.txt[]
|
||||
|
||||
* pname:commandBuffer is the command buffer into which the command will be
|
||||
recorded.
|
||||
* pname:srcImage is the source image.
|
||||
* pname:srcImageLayout is the current layout of the source image
|
||||
subresource.
|
||||
* pname:dstImage is the destination image.
|
||||
* pname:dstImageLayout is the current layout of the destination image
|
||||
subresource.
|
||||
* pname:regionCount is the number of regions to copy.
|
||||
* pname:pRegions is a pointer to an array of slink:VkImageCopy structures
|
||||
specifying the regions to copy.
|
||||
|
||||
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[]
|
||||
|
||||
Each element of pname:pRegions is a structure defined as:
|
||||
|
||||
include::../structs/VkImageCopy.txt[]
|
||||
|
||||
* pname:srcSubresource and pname:dstSubresource are
|
||||
slink:VkImageSubresourceLayers structures specifying the 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.
|
||||
|
||||
[[copies-images-format-compatibility]]
|
||||
The formats of pname:srcImage and pname:dstImage must: be compatible.
|
||||
Formats are considered compatible if their texel size in bytes is the same
|
||||
between both formats. For example, ename:VK_FORMAT_R8G8B8A8_UNORM is
|
||||
compatible with ename:VK_FORMAT_R32_UINT because because both texels are 4
|
||||
bytes in size. Depth/stencil formats must: match exactly.
|
||||
|
||||
fname:vkCmdCopyImage allows copying between size-compatible compressed
|
||||
and uncompressed internal formats. Formats are size-compatible if the texel
|
||||
size of the uncompressed format is equal to the block size in bytes of the
|
||||
compressed format. Such a copy does not perform on-the-fly compression or
|
||||
decompression. When copying from an uncompressed format to a compressed
|
||||
format, each texel of uncompressed data becomes a single block of compressed
|
||||
data. When copying from a compressed format to an uncompressed format, a
|
||||
block of compressed data becomes a single texel of uncompressed data. Thus,
|
||||
for example, it is legal to copy between a 128-bit uncompressed format and a
|
||||
compressed format which uses 8-bit/texel 4x4 blocks, or between a 64-bit
|
||||
uncompressed format and a compressed format which uses 4-bit/texel 4x4
|
||||
blocks.
|
||||
|
||||
When copying between compressed and uncompressed formats the pname:extent
|
||||
members represent the texel dimensions of the source image and not the
|
||||
destination. When copying from a compressed image to an uncompressed image
|
||||
the image texel dimensions written to the uncompressed image will be source
|
||||
extent divided by the block size. When copying from an uncompressed image to
|
||||
a compressed image the image texel dimensions written to the compressed
|
||||
image will be the source extent multiplied by the block size. In both cases
|
||||
the number of bytes read and the number of bytes written will be identical.
|
||||
|
||||
Copying to or from block-compressed images is typically done in multiples of
|
||||
the block. For this reason the pname:extent must: be a multiple of the
|
||||
block dimension. There is one exception to this rule which is required: to
|
||||
handle compressed images created with dimensions that are not a multiple
|
||||
of the block dimensions. If the pname:srcImage is compressed and if
|
||||
pname:extent.width is not a multiple of the block width then
|
||||
(pname:extent.width + pname:srcOffset.x) must: equal the subresource width,
|
||||
if pname:extent.height is not a multiple of the block height then
|
||||
(pname:extent.height + pname:srcOffset.y) must: equal
|
||||
the subresource height and if pname:extent.depth is not a multiple of the
|
||||
block depth then (pname:extent.depth + pname:srcOffset.z) must: equal
|
||||
the subresource depth. Similarily if the pname:dstImage is compressed and
|
||||
if pname:extent.width is not a multiple of the block width then
|
||||
(pname:extent.width + pname:dstOffset.x) must: equal the subresource width,
|
||||
if pname:extent.height is not a multiple of the block height then
|
||||
(pname:extent.height + pname:dstOffset.y) must: equal
|
||||
the subresource height and if pname:extent.depth is not a multiple of the
|
||||
block depth then (pname:extent.depth + pname:dstOffset.z) must: equal
|
||||
the subresource depth. This allows the last block of the image in each
|
||||
non-multiple dimension to be included as a source or target 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.
|
||||
|
||||
|
||||
[[copies-buffers-images]]
|
||||
== Copying Data Between Buffers and Images
|
||||
|
||||
To copy data from a buffer object to an image object, call:
|
||||
|
||||
include::../protos/vkCmdCopyBufferToImage.txt[]
|
||||
|
||||
* pname:commandBuffer is the command buffer into which the command will be
|
||||
recorded.
|
||||
* pname:srcBuffer is the source buffer.
|
||||
* pname:dstImage is the destination image.
|
||||
* pname:dstImageLayout is the layout of the destination image subresources
|
||||
for the copy.
|
||||
* pname:regionCount is the number of regions to copy.
|
||||
* pname:pRegions is a pointer to an array of slink:VkBufferImageCopy
|
||||
structures specifying the regions to copy.
|
||||
|
||||
Each region in pname:pRegions is copied from the specified region of the
|
||||
source buffer to the specified region of the destination image.
|
||||
|
||||
include::../validity/protos/vkCmdCopyBufferToImage.txt[]
|
||||
|
||||
To copy data from an image object to a buffer object, call:
|
||||
|
||||
include::../protos/vkCmdCopyImageToBuffer.txt[]
|
||||
|
||||
* pname:commandBuffer is the command buffer into which the command will be
|
||||
recorded.
|
||||
* pname:srcImage is the source image.
|
||||
* pname:srcImageLayout is the layout of the source image subresources for
|
||||
the copy.
|
||||
* pname:dstBuffer is the destination buffer.
|
||||
* pname:regionCount is the number of regions to copy.
|
||||
* pname:pRegions is a pointer to an array of slink:VkBufferImageCopy
|
||||
structures specifying the regions to copy.
|
||||
|
||||
Each region in pname:pRegions is copied from the specified region of the
|
||||
source buffer to the specified region of the destination image.
|
||||
|
||||
include::../validity/protos/vkCmdCopyImageToBuffer.txt[]
|
||||
|
||||
For both flink:vkCmdCopyBufferToImage and flink:vkCmdCopyImageToBuffer, each
|
||||
element of pname:pRegions is a structure defined as:
|
||||
|
||||
include::../structs/VkBufferImageCopy.txt[]
|
||||
|
||||
* pname:bufferOffset is the offset in bytes from the start of the
|
||||
buffer object where the image data is copied from or to.
|
||||
* pname:bufferRowLength and pname:bufferImageHeight specify the
|
||||
data in buffer memory as a subregion of a larger two- or
|
||||
three-dimensional image, and control the addressing calculations of data
|
||||
in buffer memory. If either of these values is zero, that aspect of the
|
||||
buffer memory is considered to be tightly packed according to the
|
||||
pname:imageExtent.
|
||||
* pname:imageSubresource is an slink:VkImageSubresourceLayers used to
|
||||
specify the specific subresources of the image used for the source or
|
||||
destination image data.
|
||||
* pname:imageOffset selects the initial x, y, z offsets in texels of the
|
||||
sub-region of the source or destination image data.
|
||||
* pname:imageExtent is the size in texels of the 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.
|
||||
|
||||
When copying to or from a depth or stencil aspect, the data in buffer
|
||||
memory uses a layout that is a (mostly) tightly packed representation of
|
||||
the depth or stencil data. Specifically:
|
||||
|
||||
* data copied to or from the stencil aspect of any depth/stencil format
|
||||
is tightly packed with one ename:VK_FORMAT_S8_UINT value per texel.
|
||||
* data copied to or from the depth aspect of a ename:VK_FORMAT_D16_UNORM
|
||||
or ename:VK_FORMAT_D16_UNORM_S8_UINT format is tightly packed with one
|
||||
ename:VK_FORMAT_D16_UNORM value per texel.
|
||||
* data copied to or from the depth aspect of a ename:VK_FORMAT_D32_SFLOAT
|
||||
or ename:VK_FORMAT_D32_SFLOAT_S8_UINT format is tightly packed with
|
||||
one ename:VK_FORMAT_D32_SFLOAT value per texel.
|
||||
* data copied to or from the depth aspect of a
|
||||
ename:VK_FORMAT_X8_D24_UNORM_PACK32 or
|
||||
ename:VK_FORMAT_D24_UNORM_S8_UINT format is packed with one 32-bit word
|
||||
per texel with the D24 value in the LSBs of the word, and undefined
|
||||
values in the eight MSBs.
|
||||
|
||||
[NOTE]
|
||||
.Note
|
||||
====
|
||||
To copy both the depth and stencil aspects of a depth/stencil format, two
|
||||
entries in pname:pRegions can: be used, where one specifies the depth
|
||||
aspect in pname:imageSubresource, and the other specifies the stencil
|
||||
aspect.
|
||||
====
|
||||
|
||||
Because depth or stencil aspect buffer to image copies may: require format
|
||||
conversions on some implementations, they are not supported on queues
|
||||
that do not support graphics.
|
||||
|
||||
Copies are done layer by layer starting with image layer
|
||||
pname:baseArrayLayer member of pname:imageSubresource. pname:layerCount
|
||||
layers are copied from the source image or to the destination image.
|
||||
|
||||
include::../validity/structs/VkBufferImageCopy.txt[]
|
||||
|
||||
Pseudocode for image/buffer addressing is:
|
||||
|
||||
[source,c]
|
||||
---------------------------------------------------
|
||||
rowLength = region->bufferRowLength;
|
||||
if (rowLength == 0)
|
||||
rowLength = region->imageExtent.width;
|
||||
|
||||
imageHeight = region->bufferImageHeight;
|
||||
if (imageHeight == 0)
|
||||
imageHeight = region->imageExtent.height;
|
||||
|
||||
texelSize = <texel size taken from the src/dstImage>;
|
||||
|
||||
address of (x,y,z) = region->bufferOffset + (((z * imageHeight) + y) * rowLength + x) * texelSize;
|
||||
|
||||
where x,y,z range from (0,0,0) to region->imageExtent.{width,height,depth}.
|
||||
---------------------------------------------------
|
||||
|
||||
Note that pname:imageOffset does not affect addressing calculations for
|
||||
buffer memory. Instead, pname:bufferOffset can: be used to
|
||||
select the starting address in buffer memory.
|
||||
|
||||
For block-compression formats, all parameters are still specified in texels
|
||||
rather than blocks, but the addressing math operates on whole blocks.
|
||||
Pseudocode for compressed copy addressing is:
|
||||
|
||||
[source,c]
|
||||
---------------------------------------------------
|
||||
rowLength = region->bufferRowLength;
|
||||
if (rowLength == 0)
|
||||
rowLength = region->imageExtent.width;
|
||||
|
||||
imageHeight = region->bufferImageHeight;
|
||||
if (imageHeight == 0)
|
||||
imageHeight = region->imageExtent.height;
|
||||
|
||||
blockSizeInBytes = <block size taken from the src/dstImage>;
|
||||
rowLength /= blockWidth;
|
||||
imageHeight /= blockHeight;
|
||||
|
||||
address of (x,y,z) = region->bufferOffset + (((z * imageHeight) + y) * rowLength + x) * blockSizeInBytes;
|
||||
|
||||
where x,y,z range from (0,0,0) to region->imageExtent.{width/blockWidth,height/blockHeight,depth/blockDepth}.
|
||||
---------------------------------------------------
|
||||
|
||||
Copying to or from block-compressed images is typically done in multiples of
|
||||
the block. For this reason the pname:imageExtent must: be a multiple of the
|
||||
block dimension. There is one exception to this rule which is required: to
|
||||
handle compressed images created with dimensions that are not a multiple of
|
||||
the block dimensions. If pname:imageExtent.width is not a multiple of the
|
||||
block width then (pname:imageExtent.width + pname:imageOffset.x) must: equal
|
||||
the subresource width, if pname:imageExtent.height is not a multiple of the
|
||||
block height then (pname:imageExtent.height + pname:imageOffset.y) must:
|
||||
equal the subresource height and if pname:imageExtent.depth is not a
|
||||
multiple of the block depth then (pname:imageExtent.depth +
|
||||
pname:imageOffset.z) must: equal the subresource depth. This allows the last
|
||||
block of the image in each non-multiple dimension to be included as a source
|
||||
or target of the copy.
|
||||
|
||||
|
||||
[[copies-imagescaling]]
|
||||
== Image Copies with Scaling
|
||||
|
||||
To copy regions of a source image into a destination image, potentially
|
||||
performing format conversion, arbitrary scaling, and filtering, call:
|
||||
|
||||
include::../protos/vkCmdBlitImage.txt[]
|
||||
|
||||
* pname:commandBuffer is the command buffer into which the command will be
|
||||
recorded.
|
||||
* pname:srcImage is the source image.
|
||||
* pname:srcImageLayout is the layout of the source image subresources for
|
||||
the blit.
|
||||
* pname:dstImage is the destination image.
|
||||
* pname:dstImageLayout is the layout of the destination image subresources
|
||||
for the blit.
|
||||
* pname:regionCount is the number of regions to blit.
|
||||
* pname:pRegions is a pointer to an array of slink:VkImageBlit structures
|
||||
specifying the regions to blit.
|
||||
* 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.
|
||||
|
||||
Each element of pname:pRegions is a structure 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
|
||||
ename:VK_FILTER_NEAREST uses point sampling. When using
|
||||
ename:VK_FILTER_LINEAR, magnifying blits may: generate texel coordinates
|
||||
outside of the source region. If those coordinates are outside the bounds of
|
||||
the image level, the coordinates are clamped as in
|
||||
ename:VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_EDGE address mode. However, if the
|
||||
coordinates are outside the source region but inside the image level, the
|
||||
implementation may: clamp coordinates to the source region.
|
||||
|
||||
If source and destination extents are identical, no filtering is performed.
|
||||
Pixels in the axis-aligned region bounded by srcOffsets[0] and srcOffsets[1]
|
||||
will be copied to the destination region bound by dstOffsets[0] and
|
||||
dstOffsets[1]. In the case where dstOffsets[0].x > dstOffsets[1].x the
|
||||
copied pixels are reversed in that direction. Likewise for y and z.
|
||||
|
||||
Blits are done layer by layer starting with the pname:baseArrayLayer member
|
||||
of pname:srcSubresource for the source and pname:dstSubresource for the
|
||||
destination. pname:layerCount layers are blitted to the destination image.
|
||||
|
||||
3D textures are blitted slice by slice. Slices in the source region bounded
|
||||
by pname:srcOffsets[0].z and pname:srcOffsets[1].z are copied to slices in
|
||||
the destination region bounded by pname:dstOffsets[0].z and
|
||||
pname:dstOffsets[1].z. For each destination slice, a source z coordinate is
|
||||
linearly interpolated between pname:srcOffsets[0].z and
|
||||
pname:srcOffsets[1].z. If the pname:filter parameter is
|
||||
ename:VK_FILTER_LINEAR then the value sampled from the source image is taken
|
||||
by doing linear filtering using the interpolated z coordinate. If
|
||||
pname:filter parameter is ename:VK_FILTER_NEAREST then value sampled from
|
||||
the source image is taken from the single nearest slice (with undefined
|
||||
rounding mode).
|
||||
|
||||
If fname:vkCmdBlitImage is used on images of different formats, the
|
||||
following conversion rules apply:
|
||||
|
||||
* Integer formats can: only be converted to other integer formats with the
|
||||
same signedness.
|
||||
* No format conversion is supported between depth/stencil images - the
|
||||
formats must: match.
|
||||
* Format conversions on unorm, snorm, unscaled and packed float formats of
|
||||
the copied aspect of the image are performed by first converting the
|
||||
pixels to float values.
|
||||
* In case of sRGB source format, values are converted to linear color
|
||||
space prior to filtering.
|
||||
* After filtering, the float values are first clamped and then cast to the
|
||||
destination image format. In case of sRGB destination format, values are
|
||||
converted to sRGB color space before writing the pixel to the image.
|
||||
|
||||
Signed and unsigned integers are converted by first clamping to the
|
||||
representable range of destination format, then casting the value.
|
||||
|
||||
|
||||
[[copies-resolve]]
|
||||
== Resolving Multisample Images
|
||||
|
||||
To resolve a multisample image to a non-multisample image, call:
|
||||
|
||||
include::../protos/vkCmdResolveImage.txt[]
|
||||
|
||||
* pname:commandBuffer is the command buffer into which the command will be
|
||||
recorded.
|
||||
* pname:srcImage is the source image.
|
||||
* pname:srcImageLayout is the layout of the source image subresources for
|
||||
the blit.
|
||||
* pname:dstImage is the destination image.
|
||||
* pname:dstImageLayout is the layout of the destination image subresources
|
||||
for the blit.
|
||||
* pname:regionCount is the number of regions to blit.
|
||||
* pname:pRegions is a pointer to an array of slink:VkImageResolve
|
||||
structures specifying the regions to resolve.
|
||||
|
||||
include::../validity/protos/vkCmdResolveImage.txt[]
|
||||
|
||||
Each element of pname:pRegions is a structure defined as:
|
||||
|
||||
include::../structs/VkImageResolve.txt[]
|
||||
|
||||
* pname:srcSubresource and pname:dstSubresource are
|
||||
slink:VkImageSubresourceLayers structures specifying the subresources of
|
||||
the images used for the source and destination image data, respectively.
|
||||
Resolve of depth/stencil images is not supported.
|
||||
* 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.
|
||||
|
||||
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 blitted to the destination image.
|
||||
File diff suppressed because it is too large
Load Diff
|
|
@ -0,0 +1,661 @@
|
|||
// Copyright (c) 2015-2016 The Khronos Group Inc.
|
||||
// Copyright notice at https://www.khronos.org/registry/speccopyright.html
|
||||
|
||||
[[devsandqueues]]
|
||||
= Devices and Queues
|
||||
|
||||
Once {apiname} is initialized, devices and queues are the primary objects
|
||||
used to interact with a {apiname} implementation.
|
||||
|
||||
{apiname} 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.
|
||||
|
||||
[[devsandqueues-physical-device-enumeration]]
|
||||
== Physical Devices
|
||||
|
||||
To retrieve a list of physical device objects representing the
|
||||
physical devices installed in the system, call:
|
||||
|
||||
include::../protos/vkEnumeratePhysicalDevices.txt[]
|
||||
|
||||
* pname:instance is a handle to a {apiname} instance previously created
|
||||
with fname:vkCreateInstance.
|
||||
* If pname:pPhysicalDevices is `NULL`, the number of physical devices
|
||||
available is returned in pname:pPhysicalDeviceCount. If
|
||||
pname:pPhysicalDevices is not `NULL`,
|
||||
* pname:pPhysicalDeviceCount must: point to a variable set by the user to
|
||||
the size of the array pointed to by pname:pPhysicalDevices, and is
|
||||
overwritten with the number of physical devices actually written to
|
||||
pname:pPhysicalDevices.
|
||||
|
||||
include::../validity/protos/vkEnumeratePhysicalDevices.txt[]
|
||||
|
||||
Once enumerated, general properties of the physical devices are queried by
|
||||
calling:
|
||||
|
||||
include::../protos/vkGetPhysicalDeviceProperties.txt[]
|
||||
|
||||
* pname:physicalDevice is the handle to the physical device whose
|
||||
properties will be queried.
|
||||
* pname:pProperties points to an instance of the
|
||||
sname:VkPhysicalDeviceProperties structure, that will be filled with
|
||||
returned information.
|
||||
|
||||
include::../validity/protos/vkGetPhysicalDeviceProperties.txt[]
|
||||
|
||||
The definition of sname:VkPhysicalDeviceProperties is:
|
||||
|
||||
include::../structs/VkPhysicalDeviceProperties.txt[]
|
||||
|
||||
The members of sname:VkPhysicalDeviceProperties have the following meanings:
|
||||
|
||||
* pname:apiVersion is the version of {apiname} supported by the device,
|
||||
encoded as described in the <<fundamentals-versionnum,API Version
|
||||
Numbers and Semantics>> section.
|
||||
* pname:driverVersion is the vendor-specified version of the driver.
|
||||
* pname:vendorID is a unique identifier for the _vendor_ (see below) of
|
||||
the physical device.
|
||||
* pname:deviceID is a unique identifier for the physical device among
|
||||
devices available from the vendor.
|
||||
* pname:deviceType is a elink:VkPhysicalDeviceType specifying the type of
|
||||
device.
|
||||
* pname:deviceName is a pointer to a null-terminated UTF-8 string
|
||||
containing the name of the device.
|
||||
* pname:pipelineCacheUUID is an array of size ename:VK_UUID_SIZE,
|
||||
containing 8-bit values that represent a universally unique identifier
|
||||
for the device.
|
||||
* pname:limits is the sname:VkPhysicalDeviceLimits structure which
|
||||
specifies device-specific limits of the physical device. See
|
||||
<<features-limits,Limits>> for details.
|
||||
* pname:sparseProperties is the sname:VkPhysicalDeviceSparseProperties
|
||||
structure which specifies various sparse related properties of the
|
||||
physical device. See <<features-sparseproperties,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
|
||||
performance profiles, hardware errata, or other characteristics.
|
||||
In PCI-based implementations, the low sixteen bits of pname:vendorID
|
||||
and pname:deviceID must: contain (respectively) the PCI vendor and
|
||||
device IDs associated with the hardware device, and the remaining bits
|
||||
must: be set to zero. In non-PCI implementations, the choice of what values
|
||||
to return may: be dictated by operating system or platform policies. It is
|
||||
otherwise at the discretion of the implementer, subject to the following
|
||||
constraints and guidelines:
|
||||
|
||||
* For purposes of physical device identification, the _vendor_ of a
|
||||
physical device is the entity responsible for the most salient
|
||||
characteristics of the hardware represented by the physical device
|
||||
handle. In the case of a discrete GPU, this should: be the GPU
|
||||
chipset vendor. In the case of a GPU or other accelerator integrated
|
||||
into a system-on-chip (SoC), this should: be the supplier of the
|
||||
silicon IP used to create the GPU or other accelerator.
|
||||
* If the vendor of the physical device has a valid PCI vendor ID issued by
|
||||
https://pcisig.com/[PCI-SIG], that ID should: be used to construct the
|
||||
value of pname:vendorID as described above for PCI-based
|
||||
implementations. Implementations that do not return a PCI vendor ID in
|
||||
pname:vendorID must: return a valid Khronos vendor ID, obtained as
|
||||
defined in the <<extensions-vendor-id,Registering a Vendor ID with
|
||||
Khronos>> section. Khronos vendor IDs are allocated starting at 0x10000,
|
||||
to distinguish them from the PCI vendor ID namespace.
|
||||
* The vendor of the physical device is responsible for selecting the
|
||||
value of pname:deviceID. The value selected should: uniquely
|
||||
identify both the device version and any major configuration options
|
||||
(for example, core count in the case of multicore devices). The same
|
||||
device ID should: be used for all physical implementations of that
|
||||
device version and configuration. For example, all uses of a
|
||||
specific silicon IP GPU version and configuration should use the
|
||||
same device ID, even if those uses occur in different SoCs.
|
||||
|
||||
The physical devices types are:
|
||||
|
||||
include::../enums/VkPhysicalDeviceType.txt[]
|
||||
|
||||
* ename:VK_PHYSICAL_DEVICE_TYPE_OTHER The device does not match any
|
||||
other available types.
|
||||
* ename:VK_PHYSICAL_DEVICE_TYPE_INTEGRATED_GPU The device is typically
|
||||
one embedded in or tightly coupled with the host.
|
||||
* ename:VK_PHYSICAL_DEVICE_TYPE_DISCRETE_GPU The device is typically
|
||||
a separate processor connected to the host via an interlink.
|
||||
* ename:VK_PHYSICAL_DEVICE_TYPE_VIRTUAL_GPU The device is typically
|
||||
a virtual node in a virtualization environment.
|
||||
* ename:VK_PHYSICAL_DEVICE_TYPE_CPU The device is typically running on the
|
||||
same processors as the host.
|
||||
|
||||
The physical device type is advertised for informational purposes only, and
|
||||
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:
|
||||
|
||||
include::../protos/vkGetPhysicalDeviceQueueFamilyProperties.txt[]
|
||||
|
||||
* pname:physicalDevice is the handle to the physical device whose
|
||||
properties will be queried.
|
||||
* pname:pQueueFamilyPropertyCount is a pointer to an integer related to
|
||||
the number of queue families available or queried, as described below.
|
||||
* pname:pQueueFamilyProperties is either `NULL` or a pointer to an array
|
||||
of sname:VkQueueFamilyProperties structures.
|
||||
|
||||
If pname:pQueueFamilyProperties is `NULL`, then the number of queue families
|
||||
available is returned in pname:pQueueFamilyPropertyCount. Otherwise,
|
||||
pname:pQueueFamilyPropertyCount must: point to a variable set by the user to
|
||||
the number of elements in the pname:pQueueFamilyProperties array, and on
|
||||
return the variable is overwritten with the number of structures actually
|
||||
written to pname:pQueueFamilyProperties. If the value of
|
||||
pname:pQueueFamilyPropertyCount is less than the number of queue families
|
||||
available, at most pname:pQueueFamilyPropertyCount structures will be
|
||||
written.
|
||||
|
||||
include::../validity/protos/vkGetPhysicalDeviceQueueFamilyProperties.txt[]
|
||||
|
||||
The definition of sname:VkQueueFamilyProperties is:
|
||||
|
||||
include::../structs/VkQueueFamilyProperties.txt[]
|
||||
|
||||
The members of sname:VkQueueFamilyProperties have the following meanings:
|
||||
|
||||
* pname:queueFlags contains flags indicating the capabilities of the
|
||||
queues in this queue family.
|
||||
* pname:queueCount is the unsigned integer count of queues in this
|
||||
queue family.
|
||||
* pname:timestampValidBits is the unsigned integer count of meaningful
|
||||
bits in the timestamps written via fname:vkCmdWriteTimestamp. The valid
|
||||
range for the count is 36..64 bits, or a value of 0, indicating no
|
||||
support for timestamps. Bits outside the valid range are guaranteed to
|
||||
be zeros.
|
||||
* pname:minImageTransferGranularity is the minimum granularity
|
||||
supported for image transfer operations on the queues in this queue
|
||||
family.
|
||||
|
||||
The bits specified in pname:queueFlags are:
|
||||
include::../enums/VkQueueFlagBits.txt[]
|
||||
|
||||
* if ename:VK_QUEUE_GRAPHICS_BIT is set, then the queues in this queue
|
||||
family support graphics operations.
|
||||
* if ename:VK_QUEUE_COMPUTE_BIT is set, then the queues in this queue
|
||||
family support compute operations.
|
||||
* if ename:VK_QUEUE_TRANSFER_BIT is set, then the queues in this queue
|
||||
family support transfer operations.
|
||||
* if ename:VK_QUEUE_SPARSE_BINDING_BIT is set, then the queues in this
|
||||
queue family support sparse memory management operations (see
|
||||
<<sparsememory,Sparse Resources>>). If any of the sparse resource
|
||||
features are enabled, then at least one queue family must: support this
|
||||
bit.
|
||||
|
||||
If an implementation exposes any queue family that supports graphics
|
||||
operations, at least one queue family of at least one physical device
|
||||
exposed by the implementation must: support both graphics and compute
|
||||
operations.
|
||||
|
||||
include::../validity/structs/VkQueueFamilyProperties.txt[]
|
||||
|
||||
For further details see <<devsandqueues-queues,Queues>>.
|
||||
|
||||
The value returned in pname:minImageTransferGranularity has a unit of blocks
|
||||
for images having a block compressed format, and a unit of texels otherwise.
|
||||
|
||||
Possible values of pname:minImageTransferGranularity are:
|
||||
|
||||
* latexmath:[$(0,0,0)$] which indicates that only whole mip levels must:
|
||||
be transferred using the image transfer operations on the corresponding
|
||||
queues. In this case, the following restrictions apply to all offset and
|
||||
extent parameters of image transfer operations:
|
||||
|
||||
** The pname:x, pname:y, and pname:z members of a sname:VkOffset3D
|
||||
parameter must: always be zero.
|
||||
** The pname:width, pname:height, and pname:depth members of a
|
||||
sname:VkExtent3D parameter must: always match the width, height, and
|
||||
depth of the image subresource corresponding to the parameter,
|
||||
respectively.
|
||||
|
||||
* latexmath:[$(Ax, Ay, Az)$] where latexmath:[$Ax$], latexmath:[$Ay$],
|
||||
and latexmath:[$Az$] are all integer powers of two. In this case the
|
||||
following restrictions apply to all image transfer operations:
|
||||
|
||||
** pname:x, pname:y, and pname:z of a sname:VkOffset3D parameter must: be
|
||||
integer multiples of latexmath:[$Ax$], latexmath:[$Ay$], and
|
||||
latexmath:[$Az$], respectively.
|
||||
** pname:width of a sname:VkExtent3D parameter must: be an integer
|
||||
multiple of latexmath:[$Ax$], or else latexmath:[$(x + width)$] must:
|
||||
equal the width of the image subresource corresponding to the
|
||||
parameter.
|
||||
** pname:height of a sname:VkExtent3D parameter must: be an integer
|
||||
multiple of latexmath:[$Ay$], or else latexmath:[$(y + height)$] must:
|
||||
equal the height of the image subresource corresponding to the
|
||||
parameter.
|
||||
** pname:depth of a sname:VkExtent3D parameter must: be an integer
|
||||
multiple of latexmath:[$Az$], or else latexmath:[$(z + depth)$] must:
|
||||
equal the depth of the image subresource corresponding to the
|
||||
parameter.
|
||||
** If the format of the image corresponding to the parameters is one of
|
||||
the block compressed formats then for the purposes of the above
|
||||
calculations the granularity must: be scaled up by the block size.
|
||||
|
||||
Queues supporting graphics and/or compute operations must: report
|
||||
latexmath:[$(1,1,1)$] in pname:minImageTransferGranularity, meaning that
|
||||
there are no additional restrictions on the granularity of image
|
||||
transfer operations for these queues. Other queues supporting image
|
||||
transfer operations are only required: to support whole mip level
|
||||
transfers, thus the value of pname:minImageTransferGranularity for
|
||||
queues belonging to such queue families may: be latexmath:[$(0,0,0)$].
|
||||
|
||||
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
|
||||
|
||||
Device objects represent logical connections to physical devices. Each
|
||||
device exposes a number of _queue families_ each having one or more
|
||||
_queues_. All queues in a queue family support the same operations.
|
||||
|
||||
As described in <<devsandqueues-physical-device-enumeration,Physical
|
||||
Devices>>, a {apiname} application will first query for all physical devices
|
||||
in a system. Each physical device can: then be queried for its capabilities,
|
||||
including its queue and queue family properties. Once an acceptable physical
|
||||
device is identified, an application will create a corresponding logical
|
||||
device. An application must: create a separate logical device for each
|
||||
physical device it will use. The created logical device is then the primary
|
||||
interface to the physical device.
|
||||
|
||||
How to enumerate the physical devices in a system and query those physical
|
||||
devices for their queue family properties is described in the
|
||||
<<devsandqueues-physical-device-enumeration, Physical Device Enumeration>>
|
||||
section above.
|
||||
|
||||
|
||||
[[devsandqueues-device-creation]]
|
||||
=== Device Creation
|
||||
|
||||
A logical device is created as a _connection_ to a physical device. To
|
||||
create a logical device, call:
|
||||
|
||||
include::../protos/vkCreateDevice.txt[]
|
||||
|
||||
* pname:physicalDevice must: be one of the device handles returned from a
|
||||
call to fname:vkEnumeratePhysicalDevices (see
|
||||
<<devsandqueues-physical-device-enumeration, Physical Device
|
||||
Enumeration>>).
|
||||
* pname:pCreateInfo is a pointer to a sname:VkDeviceCreateInfo structure
|
||||
containing information about how to create the device.
|
||||
* pname:pAllocator controls host memory allocation as described in the
|
||||
<<memory-allocation, Memory Allocation>> chapter.
|
||||
* pname:pDevice points to a handle in which the created sname:VkDevice is
|
||||
returned.
|
||||
|
||||
include::../validity/protos/vkCreateDevice.txt[]
|
||||
|
||||
The definition of sname:VkDeviceCreateInfo is:
|
||||
|
||||
include::../structs/VkDeviceCreateInfo.txt[]
|
||||
|
||||
The members of sname:VkDeviceCreateInfo have the following meanings:
|
||||
|
||||
* 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:queueCreateInfoCount is the unsigned integer size of the
|
||||
pname:pQueueCreateInfos array. Refer to the
|
||||
<<devsandqueues-queue-creation,Queue Creation>> section below for
|
||||
further details.
|
||||
* pname:pQueueCreateInfos is a pointer to an array of
|
||||
sname:VkDeviceQueueCreateInfo structures describing the queues that are
|
||||
requested to be created along with the logical device. Refer to the
|
||||
<<devsandqueues-queue-creation,Queue Creation>> section below for
|
||||
further details.
|
||||
* pname:enabledLayerCount is the number of device layers to enable.
|
||||
* pname:ppEnabledLayerNames is a pointer to an array of
|
||||
pname:enabledLayerCount null-terminated UTF-8 strings containing the
|
||||
names of layers to enable for the created device. See the
|
||||
<<querying-layers-and-extensions,Querying Layers and Extensions>>
|
||||
chapter for further details.
|
||||
* pname:enabledExtensionCount is the number of device extensions to
|
||||
enable.
|
||||
* pname:ppEnabledExtensionNames is a pointer to an array of
|
||||
pname:enabledExtensionCount null-terminated UTF-8 strings containing the
|
||||
names of extensions to enable for the created device. See the
|
||||
<<querying-layers-and-extensions,Querying Layers and Extensions>>
|
||||
chapter for further details.
|
||||
* pname:pEnabledFeatures is a pointer to a sname:VkPhysicalDeviceFeatures
|
||||
structure that contains boolean indicators of all the features to be
|
||||
enabled. Refer to the <<features-features,Features>> section for further
|
||||
details.
|
||||
|
||||
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
|
||||
|
||||
The following is a high-level list of sname:VkDevice uses along with
|
||||
references on where to find more information:
|
||||
|
||||
* Creation of queues. See the <<devsandqueues-queues,Queues>> section
|
||||
below for further details.
|
||||
* Creation and tracking of various synchronization constructs. See
|
||||
<<synchronization,Synchronization and Cache Control>> for further
|
||||
details.
|
||||
* Allocating, freeing, and managing memory. See <<memory,Memory
|
||||
Allocation>> and <<resources,Resource Creation>> for further details.
|
||||
* Creation and destruction of command buffers and command buffer pools.
|
||||
See <<commandbuffers,Command Buffers>> for further details.
|
||||
* Creation, destruction, and management of graphics state. See
|
||||
<<pipelines,Pipelines>> and <<descriptorsets,Resource Descriptors>>,
|
||||
among others, for further details.
|
||||
|
||||
|
||||
[[devsandqueues-idle]]
|
||||
=== Device Idle
|
||||
|
||||
A device is active while any of its queues have work to process. Once all
|
||||
device queues are idle, the device is idle. To wait for this condition,
|
||||
call:
|
||||
|
||||
include::../protos/vkDeviceWaitIdle.txt[]
|
||||
|
||||
* pname:device is the logical device to idle.
|
||||
|
||||
include::../validity/protos/vkDeviceWaitIdle.txt[]
|
||||
|
||||
|
||||
[[devsandqueues-lost-device]]
|
||||
=== Lost Device
|
||||
|
||||
A logical device may: become _lost_ because of hardware errors, execution
|
||||
timeouts, power management events and/or platform-specific events. This may:
|
||||
cause pending and future command execution to fail and cause hardware
|
||||
resources to be corrupted. When this happens, certain commands will return
|
||||
ename:VK_ERROR_DEVICE_LOST (see <<fundamentals-errorcodes,Error Codes>> for
|
||||
a list of such commands). After any such event, the logical device is
|
||||
considered _lost_. It is not possible to reset the logical device to a
|
||||
non-lost state, however the lost state is specific to a logical device
|
||||
(sname:VkDevice), and the corresponding physical device
|
||||
(sname:VkPhysicalDevice) may: be otherwise unaffected. In some cases, the
|
||||
physical device may: also be lost, and attempting to create a new logical
|
||||
device will fail, returning ename:VK_ERROR_DEVICE_LOST. This is usually
|
||||
indicative of a problem with the underlying hardware, or its connection to
|
||||
the host. If the physical device has not been lost, and a new logical device
|
||||
is successfully created from that physical device, it must: be in the
|
||||
non-lost state.
|
||||
|
||||
[NOTE]
|
||||
.Note
|
||||
====
|
||||
Whilst logical device loss may: be recoverable, in the case of physical
|
||||
device loss, it is unlikely that an application will be able to recover
|
||||
unless additional, unaffected physical devices exist on the system. The
|
||||
error is largely informational and intended only to inform the user that
|
||||
their hardware has probably developed a fault or become physically
|
||||
disconnected, and should: be investigated further. In many cases, physical
|
||||
device loss may: cause other more serious issues such as the operating
|
||||
system crashing; in which case it maynot: be reported via the {apiname} API.
|
||||
====
|
||||
|
||||
[NOTE]
|
||||
.Note
|
||||
====
|
||||
Undefined behavior caused by an application error may: cause a device to
|
||||
become lost. However, such undefined behavior may: also cause unrecoverable
|
||||
damage to the process, and it is then not guaranteed that the API objects,
|
||||
including the sname:VkPhysicalDevice or the sname:VkInstance are still valid
|
||||
or that the error is recoverable.
|
||||
====
|
||||
|
||||
When a device is lost, its child objects are not implicitly destroyed and
|
||||
their handles are still valid. Those objects must: still be destroyed before
|
||||
their parents or the device can: be destroyed (see
|
||||
<<objectmodel-lifetime,Lifetime>>). The host address space corresponding to
|
||||
device memory mapped using flink:vkMapMemory is still valid, and host memory
|
||||
accesses to these mapped regions are still valid, but the contents are
|
||||
undefined. It is still legal to call any API command on the device and child
|
||||
objects.
|
||||
|
||||
Once a device is lost, command execution may: fail, and commands that return
|
||||
a basetype:VkResult may: return ename:VK_ERROR_DEVICE_LOST. Commands that do
|
||||
not allow run-time errors must: still operate correctly for valid usage and,
|
||||
if applicable, return valid data.
|
||||
|
||||
Commands that wait indefinitely for device execution (namely
|
||||
flink:vkDeviceWaitIdle, flink:vkQueueWaitIdle, flink:vkWaitForFences with a
|
||||
maximum pname:timeout, and flink:vkGetQueryPoolResults with the
|
||||
ename:VK_QUERY_RESULT_WAIT_BIT bit set in pname:flags) must: return in
|
||||
finite time even in the case of a lost device, and return either
|
||||
ename:VK_SUCCESS or ename:VK_ERROR_DEVICE_LOST. For any command that may:
|
||||
return ename:VK_ERROR_DEVICE_LOST, for the purpose of determining whether a
|
||||
command buffer is pending execution, or whether resources are considered
|
||||
in-use by the device, a return value of ename:VK_ERROR_DEVICE_LOST is
|
||||
equivalent to ename:VK_SUCCESS.
|
||||
|
||||
ifdef::editing-notes[]
|
||||
[NOTE]
|
||||
.editing-note
|
||||
====
|
||||
TODO (piman) - I don't think we're very clear about what ``in-use by the
|
||||
device'' means.
|
||||
====
|
||||
endif::editing-notes[]
|
||||
|
||||
|
||||
[[devsandqueues-destruction]]
|
||||
=== Device Destruction
|
||||
|
||||
To destroy a device, call:
|
||||
|
||||
include::../protos/vkDestroyDevice.txt[]
|
||||
|
||||
* pname:device is the logical device to destroy.
|
||||
* 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 {apiname}
|
||||
objects that were created using that device as the first parameter of the
|
||||
corresponding ftext:vkCreate* or ftext:vkAllocate* command.
|
||||
|
||||
[NOTE]
|
||||
.Note
|
||||
====
|
||||
The lifetime of each of these objects is bound by the lifetime of the
|
||||
sname:VkDevice object. Therefore, to avoid resource leaks, it is critical
|
||||
that an application explicitly free all of these resources prior to calling
|
||||
fname:vkDestroyDevice.
|
||||
====
|
||||
|
||||
|
||||
[[devsandqueues-queues]]
|
||||
== Queues
|
||||
|
||||
|
||||
[[devsandqueues-queueprops]]
|
||||
=== Queue Family Properties
|
||||
|
||||
As discussed in the <<devsandqueues-physical-device-enumeration,Physical
|
||||
Device Enumeration>> section above, the
|
||||
flink:vkGetPhysicalDeviceQueueFamilyProperties command is used to retrieve
|
||||
details about the queue families and queues supported by a device.
|
||||
|
||||
Each index in the pname:pQueueFamilyProperties array returned by
|
||||
flink:vkGetPhysicalDeviceQueueFamilyProperties describes a unique queue
|
||||
family on that physical device. These indices are used when creating queues,
|
||||
and they correspond directly with the pname:queueFamilyIndex that is passed
|
||||
to the flink:vkCreateDevice command via the slink:VkDeviceQueueCreateInfo
|
||||
structure as described in the <<devsandqueues-queue-creation,Queue
|
||||
Creation>> section below.
|
||||
|
||||
Grouping of queue families within a physical device is
|
||||
implementation-dependent.
|
||||
|
||||
[NOTE]
|
||||
.Note
|
||||
====
|
||||
The general expectation is that a physical device groups all queues of
|
||||
matching capabilities into a single family. However, this is a
|
||||
recommendation to implementations and it is possible that a physical device
|
||||
may: return two separate queue families with the same capabilities.
|
||||
====
|
||||
|
||||
Once an application has identified a physical device with the queue(s) that
|
||||
it desires to use, it will create those queues in conjunction with a logical
|
||||
device. This is described in the following section.
|
||||
|
||||
|
||||
[[devsandqueues-queue-creation]]
|
||||
=== Queue Creation
|
||||
|
||||
Creating a logical device also creates the queues associated with that
|
||||
device. The queues to create are described by a set of
|
||||
sname:VkDeviceQueueCreateInfo structures that are passed to
|
||||
flink:vkCreateDevice in pname:pQueueCreateInfos. The definition of
|
||||
sname:VkDeviceQueueCreateInfo is:
|
||||
|
||||
include::../structs/VkDeviceQueueCreateInfo.txt[]
|
||||
|
||||
The members of sname:VkDeviceQueueCreateInfo have the following meanings:
|
||||
|
||||
* 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:queueFamilyIndex is an unsigned integer indicating the index of
|
||||
the queue family to create on this device. The value of this index
|
||||
corresponds to the index of an element of the
|
||||
pname:pQueueFamilyProperties array that was returned by
|
||||
fname:vkGetPhysicalDeviceQueueFamilyProperties.
|
||||
* pname:queueCount is an unsigned integer specifying the number of
|
||||
queues to create in the queue family indicated by
|
||||
pname:queueFamilyIndex.
|
||||
* pname:pQueuePriorities is an array of pname:queueCount
|
||||
normalized floating point values, specifying priorities of work that
|
||||
will be submitted to each created queue. See
|
||||
<<devsandqueues-priority,Queue Priority>> for more information.
|
||||
|
||||
include::../validity/structs/VkDeviceQueueCreateInfo.txt[]
|
||||
|
||||
To retrieve a handle to a VkQueue object, call:
|
||||
|
||||
include::../protos/vkGetDeviceQueue.txt[]
|
||||
|
||||
* pname:device is the logical device that owns the queue.
|
||||
* pname:queueFamilyIndex is the index of the queue family to which the
|
||||
queue belongs.
|
||||
* pname:queueIndex is the index within this queue family of the queue to
|
||||
retrieve.
|
||||
* pname:pQueue is a pointer to a sname:VkQueue object that will be filled
|
||||
with the handle for the requested queue.
|
||||
|
||||
include::../validity/protos/vkGetDeviceQueue.txt[]
|
||||
|
||||
|
||||
[[devsandqueues-index]]
|
||||
=== Queue Family Index
|
||||
|
||||
The queue family index is used in multiple places in {apiname} in order to
|
||||
tie operations to a specific family of queues.
|
||||
|
||||
When retrieving a handle to the queue via fname:vkGetDeviceQueue, the queue
|
||||
family index is used to select which queue family to retrieve the
|
||||
sname:VkQueue handle from as described in the previous section.
|
||||
|
||||
When creating a sname:VkCommandPool object (see
|
||||
<<commandbuffers-pools,Command Pools>>), a queue family index is specified
|
||||
in the sname:VkCommandPoolCreateInfo structure. Command buffers from this
|
||||
pool can: only be submitted on queues corresponding to this queue family.
|
||||
|
||||
When creating sname:VkImage (see <<resources-images,Images>>) and
|
||||
sname:VkBuffer (see <<resources-buffers,Buffers>>) resources, a set of queue
|
||||
families is included in the slink:VkImageCreateInfo and
|
||||
slink:VkBufferCreateInfo structures to specify the queue families that can:
|
||||
access the resource.
|
||||
|
||||
When inserting a slink:VkBufferMemoryBarrier or slink:VkImageMemoryBarrier
|
||||
(see <<synchronization-events>>) a source and destination queue family index
|
||||
is specified to allow the ownership of a buffer or image to be transferred
|
||||
from one queue family to another. See the <<resources-sharing,Resource
|
||||
Sharing>> section for details.
|
||||
|
||||
|
||||
[[devsandqueues-priority]]
|
||||
=== Queue Priority
|
||||
|
||||
Each queue is assigned a priority, as set in the
|
||||
sname:VkDeviceQueueCreateInfo structures when creating the device. The
|
||||
priority of each queue is a normalized floating point value between 0.0 and
|
||||
1.0, which is then translated to a discrete priority level by the
|
||||
implementation. Higher values indicate a higher priority, with 0.0 being the
|
||||
lowest priority and 1.0 being the highest.
|
||||
|
||||
Within the same device, queues with higher priority may: be allotted more
|
||||
processing time than queues with lower priority. The implementation makes no
|
||||
guarantees with regards to ordering or scheduling among queues with the same
|
||||
priority, other than the constraints defined by explicit scheduling
|
||||
primitives. The implementation make no guarantees with regards to queues
|
||||
across different devices.
|
||||
|
||||
An implementation may: allow a higher-priority queue to starve a
|
||||
lower-priority queue on the same sname:VkDevice until the higher-priority
|
||||
queue has no further commands to execute. The relationship of queue
|
||||
priorities mustnot: cause queues on one VkDevice to starve queues on another
|
||||
sname:VkDevice.
|
||||
|
||||
No specific guarantees are made about higher priority queues receiving more
|
||||
processing time or better quality of service than lower priority queues.
|
||||
|
||||
|
||||
[[devsandqueues-queuesynchronization]]
|
||||
=== Queue Synchronization
|
||||
|
||||
To wait on the completion of all work within a single queue, call:
|
||||
|
||||
include::../protos/vkQueueWaitIdle.txt[]
|
||||
|
||||
* pname:queue is the queue on which to wait.
|
||||
|
||||
fname:vkQueueWaitIdle will block until all command buffers and sparse
|
||||
binding operations in the queue have completed.
|
||||
|
||||
include::../validity/protos/vkQueueWaitIdle.txt[]
|
||||
|
||||
Synchronization between queues is done using {apiname} semaphores as
|
||||
described in the <<synchronization,Synchronization and Cache Control>>
|
||||
chapter.
|
||||
|
||||
|
||||
[[devsandqueues-sparsebinding]]
|
||||
=== Sparse Memory Binding
|
||||
|
||||
In {apiname} it is possible to sparsely bind memory to buffers and
|
||||
images as described in the <<sparsemem,Sparse Resource>> chapter. Sparse
|
||||
memory binding is a queue operation. A queue whose flags include the
|
||||
ename:VK_QUEUE_SPARSE_BINDING_BIT must: be able to support the
|
||||
mapping of a virtual address to a physical address on the device. This
|
||||
causes an update to the page table mappings on the device. This update must:
|
||||
be synchronized on a queue to avoid corrupting page table mappings during
|
||||
execution of graphics commands. By binding the sparse memory resources on
|
||||
queues, all commands that are dependent on the updated bindings are
|
||||
synchronized to only execute after the binding is updated. See the
|
||||
<<synchronization,Synchronization and Cache Control>> chapter for how this
|
||||
synchronization is accomplished.
|
||||
|
||||
|
||||
[[devsandqueues-queuedestruction]]
|
||||
=== Queue Destruction
|
||||
|
||||
Queues are created along with a logical device during
|
||||
fname:vkCreateDevice. All queues associated with a logical device
|
||||
are destroyed when fname:vkDestroyDevice is called on that device.
|
||||
|
|
@ -0,0 +1,54 @@
|
|||
// Copyright (c) 2015-2016 The Khronos Group Inc.
|
||||
// Copyright notice at https://www.khronos.org/registry/speccopyright.html
|
||||
|
||||
[[dispatch]]
|
||||
= Dispatching Commands
|
||||
|
||||
_Dispatching commands_ (commands with ``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.
|
||||
|
||||
To record a dispatch, call:
|
||||
|
||||
include::../protos/vkCmdDispatch.txt[]
|
||||
|
||||
* pname:commandBuffer is the command buffer into which the command will be
|
||||
recorded.
|
||||
* pname:x is the number of workgroups to dispatch in the X dimension.
|
||||
* pname:y is the number of workgroups to dispatch in the Y dimension.
|
||||
* pname:z is the number of workgroups to dispatch in the Z dimension.
|
||||
|
||||
When the command is executed, workgroups are assembled using pname:x,
|
||||
pname:y, and pname:z.
|
||||
|
||||
include::../validity/protos/vkCmdDispatch.txt[]
|
||||
|
||||
An indirect dispatch is recorded by calling:
|
||||
|
||||
include::../protos/vkCmdDispatchIndirect.txt[]
|
||||
|
||||
* pname:commandBuffer is the command buffer into which the command will be
|
||||
recorded.
|
||||
* pname:buffer is the buffer containing dispatch parameters.
|
||||
* pname:offset is the byte offset into pname:buffer where parameters
|
||||
begin.
|
||||
|
||||
fname:vkCmdDispatchIndirect behaves similarly to flink:vkCmdDispatch except
|
||||
that the parameters are read by the device from a buffer during execution.
|
||||
The parameters of the dispatch are encoded in a
|
||||
slink:VkDispatchIndirectCommand structure taken from pname:buffer starting
|
||||
at pname:offset.
|
||||
|
||||
include::../validity/protos/vkCmdDispatchIndirect.txt[]
|
||||
|
||||
The definition of sname:VkDispatchIndirectCommand is:
|
||||
|
||||
include::../structs/VkDispatchIndirectCommand.txt[]
|
||||
|
||||
The members of sname:VkDispatchIndirectCommand structure have the same
|
||||
meaning as the similarly named parameters of flink:vkCmdDispatch.
|
||||
|
||||
include::../validity/structs/VkDispatchIndirectCommand.txt[]
|
||||
|
|
@ -0,0 +1,519 @@
|
|||
// Copyright (c) 2015-2016 The Khronos Group Inc.
|
||||
// Copyright notice at https://www.khronos.org/registry/speccopyright.html
|
||||
|
||||
[[drawing]]
|
||||
= Drawing Commands
|
||||
|
||||
_Drawing commands_ (command with ftext:Draw in the name) provoke work in a
|
||||
graphics pipeline. Drawing commands are recorded into a command buffer and
|
||||
when executed by a queue, will produce work which executes according to the
|
||||
currently bound graphics pipeline. A graphics pipeline must: be bound to a
|
||||
command buffer before any drawing commands are recorded in that command
|
||||
buffer.
|
||||
|
||||
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
|
||||
pname:pInputAssemblyState member of the sname:VkGraphicsPipelineCreateInfo
|
||||
structure, which is of type sname:VkPipelineInputAssemblyStateCreateInfo:
|
||||
|
||||
include::../structs/VkPipelineInputAssemblyStateCreateInfo.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:primitiveRestartEnable controls whether a special vertex index
|
||||
value is treated as restarting the assembly of primitives. This enable
|
||||
only applies to indexed draws (flink:vkCmdDrawIndexed and
|
||||
flink:vkCmdDrawIndexedIndirect), and the special index value is either
|
||||
0xFFFFFFFF when the pname:indexType parameter of
|
||||
fname:vkCmdBindIndexBuffer is equal to ename:VK_INDEX_TYPE_UINT32, or
|
||||
0xFFFF when pname:indexType is equal to ename:VK_INDEX_TYPE_UINT16.
|
||||
Primitive restart is not allowed for ``list'' topologies.
|
||||
* 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
|
||||
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.
|
||||
|
||||
|
||||
[[drawing-primitive-topologies]]
|
||||
== 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
|
||||
of the pipeline is altered by tessellation or geometry shading (if either is
|
||||
in use) and depends on the execution modes of those shaders. Supported
|
||||
topologies are defined by elink:VkPrimitiveTopology and include:
|
||||
|
||||
include::../enums/VkPrimitiveTopology.txt[]
|
||||
|
||||
Each primitive topology, and its construction from a list of vertices, is
|
||||
summarized below.
|
||||
|
||||
|
||||
=== Points
|
||||
|
||||
A series of individual points are specified with pname:topology
|
||||
ename:VK_PRIMITIVE_TOPOLOGY_POINT_LIST. Each vertex defines a separate
|
||||
point.
|
||||
|
||||
|
||||
=== Separate Lines
|
||||
|
||||
Individual line segments, each defined by a pair of vertices, are specified
|
||||
with pname:topology ename:VK_PRIMITIVE_TOPOLOGY_LINE_LIST. The first two
|
||||
vertices define the first segment, with subsequent pairs of vertices each
|
||||
defining one more segment. If the number of vertices is odd, then the last
|
||||
vertex is ignored.
|
||||
|
||||
|
||||
=== Line Strips
|
||||
|
||||
A series of one or more connected line segments are specified with
|
||||
pname:topology ename:VK_PRIMITIVE_TOPOLOGY_LINE_STRIP. In this case, the
|
||||
first vertex specifies the first segment's start point while the second
|
||||
vertex specifies the first segment's endpoint and the second segment's start
|
||||
point. In general, the latexmath:[$i$]th vertex (for latexmath:[$i > 0$])
|
||||
specifies the beginning of the latexmath:[$i$]th segment and the end of the
|
||||
latexmath:[$i-1$]st. The last vertex specifies the end of the last segment.
|
||||
If only one vertex is specified, then no primitive is generated.
|
||||
|
||||
|
||||
=== Triangle Strips
|
||||
|
||||
A triangle strip is a series of triangles connected along shared edges, and
|
||||
is specified with pname:topology ename:VK_PRIMITIVE_TOPOLOGY_TRIANGLE_STRIP.
|
||||
In this case, the first three vertices define the first triangle, and their
|
||||
order is significant. Each subsequent vertex defines a new triangle using
|
||||
that point along with the last two vertices from the previous triangle, as
|
||||
shown in figure <<fig-triangles>>. If fewer than three vertices are
|
||||
specified, no primitive is produced. The order of vertices in successive
|
||||
triangles changes as shown in the figure, so that all triangle faces have
|
||||
the same orientation.
|
||||
|
||||
[[fig-triangles]]
|
||||
.Triangle strips, fans, and lists
|
||||
image:images/triangles.{svgpdf}["Triangle strips, fans, and lists",{fullimagewidth}]
|
||||
|
||||
ifdef::editing-notes[]
|
||||
[NOTE]
|
||||
.editing-note
|
||||
====
|
||||
TODO: Add full caption:
|
||||
|
||||
* (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
|
||||
first triangle, while in (c) the order of each triangle's edges is
|
||||
independent of the other triangles.
|
||||
====
|
||||
endif::editing-notes[]
|
||||
|
||||
|
||||
=== Triangle Fans
|
||||
|
||||
A triangle fan is specified with pname:topology
|
||||
ename:VK_PRIMITIVE_TOPOLOGY_TRIANGLE_FAN. It is similar to a triangle strip,
|
||||
but changes the vertex replaced from the previous triangle as shown in
|
||||
figure <<fig-triangles>>, so that all triangles in the fan share a common
|
||||
vertex.
|
||||
|
||||
|
||||
=== Separate Triangles
|
||||
|
||||
Separate triangles are specified with pname:topology
|
||||
ename:VK_PRIMITIVE_TOPOLOGY_TRIANGLE_LIST, as shown in figure
|
||||
<<fig-triangles>>. In this case, vertices latexmath:[$3i$],
|
||||
latexmath:[$3i+1$], and latexmath:[$3i+2$] vertices (in that order)
|
||||
determine a triangle for each latexmath:[$i=0,1,\ldots,n-1$], where there
|
||||
are latexmath:[$3n+k$] vertices drawn. latexmath:[$k$] is either 0, 1, or 2;
|
||||
if latexmath:[$k$] is not zero, the final latexmath:[$k$] vertices are
|
||||
ignored.
|
||||
|
||||
|
||||
=== Lines With Adjacency
|
||||
|
||||
Lines with adjacency are specified with pname:topology
|
||||
ename:VK_PRIMITIVE_TOPOLOGY_LINE_LIST_WITH_ADJACENCY, and are independent
|
||||
line segments where each endpoint has a corresponding _adjacent_ vertex that
|
||||
is accessible in a <<geometry,geometry shader>>.
|
||||
If a geometry shader is not active, the adjacent vertices are ignored.
|
||||
|
||||
A line segment is drawn from the latexmath:[$4 i+1$]st vertex to the
|
||||
latexmath:[$4 i+2$]nd vertex for each latexmath:[$i=0,1,\ldots, n-1$], where
|
||||
there are latexmath:[$4 n+k$] vertices. latexmath:[$k$] is either 0,
|
||||
1, 2, or 3; if latexmath:[$k$] is not zero, the final latexmath:[$k$]
|
||||
vertices are ignored. For line segment latexmath:[$i$], the latexmath:[$4
|
||||
i$]th and latexmath:[$4 i+3$]rd vertices are considered adjacent to the
|
||||
latexmath:[$4 i+1$]st and latexmath:[$4 i+2$]nd vertices, respectively, as
|
||||
shown in figure <<fig-lineadj>>.
|
||||
|
||||
[[fig-lineadj]]
|
||||
.Lines with adjacency
|
||||
image:images/lineadj.{svgpdf}["Lines with adjacency",{fullimagewidth}]
|
||||
|
||||
ifdef::editing-notes[]
|
||||
[NOTE]
|
||||
.editing-note
|
||||
====
|
||||
TODO: Add full caption:
|
||||
|
||||
Lines with adjacency (a) and line strips with adjacency (b). The vertices
|
||||
connected with solid lines belong to the main primitives; the vertices
|
||||
connected by dashed lines are the adjacent vertices that are accessible in a
|
||||
geometry shader.
|
||||
====
|
||||
endif::editing-notes[]
|
||||
|
||||
|
||||
=== Line Strips With Adjacency
|
||||
|
||||
Line strips with adjacency are specified with pname:topology
|
||||
ename:VK_PRIMITIVE_TOPOLOGY_LINE_STRIP_WITH_ADJACENCY and are similar to
|
||||
line strips, except that each line segment has a pair of adjacent vertices
|
||||
that are accessible in a geometry shader. If a geometry shader is not
|
||||
active, the adjacent vertices are ignored.
|
||||
|
||||
A line segment is drawn from the latexmath:[$i+1$]st vertex to the
|
||||
latexmath:[$i+2$]nd vertex for each latexmath:[$i=0,1,\ldots, n-1$], where
|
||||
there are latexmath:[$n+3$] vertices. If there are fewer than four
|
||||
vertices, all vertices are ignored. For line segment latexmath:[$i$], the
|
||||
latexmath:[$i$]th and latexmath:[$i+3$]rd vertex are considered adjacent
|
||||
to the latexmath:[$i+1$]st and latexmath:[$i+2$]nd vertices, respectively,
|
||||
as shown in figure <<fig-lineadj>>.
|
||||
|
||||
|
||||
=== Triangle List With Adjacency
|
||||
|
||||
Triangles with adjacency are specified with pname:topology
|
||||
ename:VK_PRIMITIVE_TOPOLOGY_TRIANGLE_LIST_WITH_ADJACENCY, and are similar to
|
||||
separate triangles except that each triangle edge has an adjacent vertex
|
||||
that is accessible in a geometry shader. If a geometry shader is not
|
||||
active, the adjacent vertices are ignored.
|
||||
|
||||
The latexmath:[$6i$]th, latexmath:[$6i+2$]nd, and latexmath:[$6i+4$]th
|
||||
vertices (in that order) determine a triangle for each
|
||||
latexmath:[$i=0,1, \ldots, n-1$], where there are latexmath:[$6 n+k$]
|
||||
vertices. latexmath:[$k$] is either 0, 1, 2, 3, 4, or 5; if
|
||||
latexmath:[$k$] is non-zero, the final latexmath:[$k$] vertices are ignored.
|
||||
For triangle latexmath:[$i$], the latexmath:[$6 i+1$]st, latexmath:[$6
|
||||
i+3$]rd, and latexmath:[$6 i+5$]th vertices are considered adjacent to edges
|
||||
from the latexmath:[$6 i$]th to the latexmath:[$6 i+2$]nd, from the
|
||||
latexmath:[$6 i+2$]nd to the latexmath:[$6 i+4$]th, and from the
|
||||
latexmath:[$6 i+4$]th to the latexmath:[$6 i$]th vertices, respectively, as
|
||||
shown in figure <<fig-triadj>>.
|
||||
|
||||
[[fig-triadj]]
|
||||
.Triangles with adjacency
|
||||
image:images/triadj.{svgpdf}["Triangles with adjacency",{fullimagewidth}]
|
||||
|
||||
ifdef::editing-notes[]
|
||||
[NOTE]
|
||||
.editing-note
|
||||
====
|
||||
TODO: Add full caption:
|
||||
|
||||
Triangles with adjacency. The vertices connected with solid lines belong
|
||||
to the main primitive; the vertices connected by dashed lines are the
|
||||
adjacent vertices that are accessible in a geometry shader.}
|
||||
====
|
||||
endif::editing-notes[]
|
||||
|
||||
|
||||
=== Triangle Strips With Adjacency
|
||||
|
||||
Triangle strips with adjacency are specified with pname:topology
|
||||
ename:VK_PRIMITIVE_TOPOLOGY_TRIANGLE_STRIP_WITH_ADJACENCY, and are similar
|
||||
to triangle strips except that each triangle edge has an adjacent vertex
|
||||
that is accessible in a geometry shader. If a geometry shader is not
|
||||
active, the adjacent vertices are ignored.
|
||||
|
||||
In triangle strips with adjacency, latexmath:[$n$] triangles are drawn where
|
||||
there are latexmath:[$2(n+2)+k$] vertices. latexmath:[$k$] is
|
||||
either 0 or 1; if latexmath:[$k$] is 1, the final vertex is ignored. If
|
||||
there are fewer than 6 vertices, the entire primitive is ignored. Table
|
||||
<<trigenadj>> describes the vertices and order used to draw each triangle,
|
||||
and which vertices are considered adjacent to each edge of the triangle, as
|
||||
shown in figure <<fig-tstripadj>>.
|
||||
|
||||
|
||||
[[trigenadj]]
|
||||
.Triangles generated by triangle strips with adjacency.
|
||||
[options="header", cols="2,1,1,1,1,1,1"]
|
||||
|====
|
||||
| 3+| Primitive Vertices 3+| Adjacent Vertices
|
||||
| Primitive | 1st | 2nd | 3rd | 1/2 | 2/3 | 3/1
|
||||
| only (latexmath:[$i=0$], latexmath:[$n=1$]) | 0 | 2 | 4 | 1 | 5 | 3
|
||||
| first (latexmath:[$i=0$]) | 0 | 2 | 4 | 1 | 6 | 3
|
||||
| middle (latexmath:[$i$] odd) | latexmath:[$2 i+2$] | latexmath:[$2 i $] | latexmath:[$2 i+4$] | latexmath:[$2 i-2$] | latexmath:[$2 i+3$] | latexmath:[$2 i+6$]
|
||||
| middle (latexmath:[$i$] even) | latexmath:[$2 i $] | latexmath:[$2 i+2$] | latexmath:[$2 i+4$] | latexmath:[$2 i-2$] | latexmath:[$2 i+6$] | latexmath:[$2 i+3$]
|
||||
| last (latexmath:[$i=n-1$], latexmath:[$i$] odd) | latexmath:[$2 i+2$] | latexmath:[$2 i $] | latexmath:[$2 i+4$] | latexmath:[$2 i-2$] | latexmath:[$2 i+3$] | latexmath:[$2 i+5$]
|
||||
| last (latexmath:[$i=n-1$], latexmath:[$i$] even)| latexmath:[$2 i $] | latexmath:[$2 i+2$] | latexmath:[$2 i+4$] | latexmath:[$2 i-2$] | latexmath:[$2 i+5$] | latexmath:[$2 i+3$]
|
||||
|====
|
||||
|
||||
ifdef::editing-notes[]
|
||||
[NOTE]
|
||||
.editing-note
|
||||
====
|
||||
TODO: Add full caption:
|
||||
|
||||
Triangles generated by triangle strips with adjacency. Each triangle is
|
||||
drawn using the vertices whose numbers are in the *1st*, *2nd*, and *3rd*
|
||||
columns under *primitive vertices*, in that order. The vertices in the 1/2,
|
||||
2/3, and 3/1 columns under *adjacent vertices* are considered adjacent to
|
||||
the edges from the first to the second, from the second to the third, and
|
||||
from the third to the first vertex of the triangle, respectively. The six
|
||||
rows correspond to six cases: the first and only triangle latexmath:[$(i=0,
|
||||
n=1)$], the first triangle of several latexmath:[$(i=0, n>0)$], ``odd''
|
||||
middle triangles latexmath:[$(i=1,3,5 \ldots)$], ``even'' middle triangles
|
||||
latexmath:[$(i=2,4,6,\ldots)$], and special cases for the last triangle,
|
||||
when latexmath:[$i$] is either even or odd. For the purposes of this table,
|
||||
both the first vertex and first triangle are numbered latexmath:[$0$].
|
||||
====
|
||||
endif::editing-notes[]
|
||||
|
||||
[[fig-tstripadj]]
|
||||
.Triangle strips with adjacency
|
||||
image:images/tstripadj.{svgpdf}["Triangle strips with adjacency",width="{svgpdf@pdf:400:800}"]
|
||||
|
||||
ifdef::editing-notes[]
|
||||
[NOTE]
|
||||
.editing-note
|
||||
====
|
||||
TODO: Add full caption:
|
||||
|
||||
Triangle strips with adjacency. The vertices connected with solid lines
|
||||
belong to the main primitives; the vertices connected by dashed lines are
|
||||
the adjacent vertices that are accessible in a geometry shader.
|
||||
====
|
||||
endif::editing-notes[]
|
||||
|
||||
|
||||
[[drawing-primitive-topologies-patches]]
|
||||
=== Separate Patches
|
||||
|
||||
Separate patches are specified with pname:topology
|
||||
ename:VK_PRIMITIVE_TOPOLOGY_PATCH_LIST. A patch is an ordered collection of
|
||||
vertices used for <<tessellation,primitive tessellation>>. The
|
||||
vertices comprising a patch have no implied geometric ordering, and are used
|
||||
by tessellation shaders and the fixed-function tessellator to generate new
|
||||
point, line, or triangle primitives.
|
||||
|
||||
Each patch in the series has a fixed number of vertices, specified by the
|
||||
pname:patchControlPoints member of the
|
||||
slink:VkPipelineTessellationStateCreateInfo structure passed to
|
||||
flink:vkCreateGraphicsPipelines. Once assembled and vertex shaded, these
|
||||
patches are provided as input to the tessellation control shader stage.
|
||||
|
||||
If the number of vertices in a patch is given by latexmath:[$v$], the
|
||||
latexmath:[$v i$]th through latexmath:[$v i+v-1$]st vertices (in that
|
||||
order) determine a patch for each
|
||||
latexmath:[$i=0,1,\dots n-1$],
|
||||
where there are latexmath:[$v n+k$] vertices. latexmath:[$k$] is in the
|
||||
range latexmath:[$[0,v-1\]$]; if latexmath:[$k$] is not zero, the final
|
||||
latexmath:[$k$] vertices are ignored.
|
||||
|
||||
|
||||
=== General Considerations For Polygon Primitives
|
||||
|
||||
Depending on the <<primsrast-polygonmode,polygon mode>>, a _polygon
|
||||
primitive_ generated from a drawing command with pname:topology
|
||||
ename:VK_PRIMITIVE_TOPOLOGY_TRIANGLE_FAN,
|
||||
ename:VK_PRIMITIVE_TOPOLOGY_TRIANGLE_STRIP,
|
||||
ename:VK_PRIMITIVE_TOPOLOGY_TRIANGLE_LIST,
|
||||
ename:VK_PRIMITIVE_TOPOLOGY_TRIANGLE_LIST_WITH_ADJACENCY, or
|
||||
ename:VK_PRIMITIVE_TOPOLOGY_TRIANGLE_STRIP_WITH_ADJACENCY is rendered in
|
||||
one of several ways, such as outlining its border or filling its interior.
|
||||
The order of vertices in such a primitive is significant during
|
||||
<<primsrast-polygons-basic,polygon rasterization>> and <<ref-tbd,fragment
|
||||
shading>>.
|
||||
|
||||
|
||||
=== Programmable Primitive Shading
|
||||
|
||||
Once primitives are assembled, they proceed to the vertex shading stage of
|
||||
the pipeline. If the draw includes multiple instances, then the set of
|
||||
primitives is sent to the vertex shading stage multiple times, once for each
|
||||
instance.
|
||||
|
||||
It is undefined whether vertex shading occurs on vertices that are discarded
|
||||
as part of incomplete primitives, but if it does occur then it operates as
|
||||
if they were vertices in complete primitives and such invocations can: have
|
||||
side effects.
|
||||
|
||||
Vertex shading receives two per-vertex inputs from the primitive assembly
|
||||
stage - the code:vertexIndex and the code:instanceIndex. How these values
|
||||
are generated is defined below, with each command.
|
||||
|
||||
Drawing commands fall roughly into two categories:
|
||||
|
||||
* Non-indexed drawing (fname:vkCmdDraw and fname:vkCmdDrawIndirect)
|
||||
commands present a sequential code:vertexIndex to the vertex shader. The
|
||||
sequential index is generated automatically by the device.
|
||||
* Indexed drawing commands (fname:vkCmdDrawIndexed and
|
||||
fname:vkCmdDrawIndexed) 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:
|
||||
|
||||
include::../protos/vkCmdBindIndexBuffer.txt[]
|
||||
|
||||
* pname:commandBuffer is the command buffer into which the command is
|
||||
recorded.
|
||||
* pname:buffer is the buffer being bound.
|
||||
* pname:offset is the starting offset in bytes within pname:buffer used in
|
||||
index buffer address calculations.
|
||||
* pname:indexType selects whether indices are treated as 16 bits or 32
|
||||
bits. Possible values include:
|
||||
+
|
||||
include::../enums/VkIndexType.txt[]
|
||||
|
||||
include::../validity/protos/vkCmdBindIndexBuffer.txt[]
|
||||
|
||||
The parameters for each drawing command are specified directly in the
|
||||
command or read from buffer memory, depending on the command. Drawing
|
||||
commands that source their parameters from buffer memory are known as
|
||||
_indirect_ drawing commands.
|
||||
|
||||
All drawing commands interact with the
|
||||
<<features-features-robustBufferAccess, Robust Buffer Access>> feature.
|
||||
|
||||
[[drawing-primitive-assembly-apiorder]]
|
||||
Primitives assembled by draw commands are considered to have an
|
||||
<<fundamentals-queueoperation-apiorder,API order>>, which defines the order
|
||||
their fragments affect the framebuffer. When a draw command includes
|
||||
multiple instances, the lower numbered instances are earlier in API order.
|
||||
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.
|
||||
|
||||
To record a non-indexed draw, call:
|
||||
|
||||
include::../protos/vkCmdDraw.txt[]
|
||||
|
||||
* pname:commandBuffer is the command buffer into which the command is
|
||||
recorded.
|
||||
* 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.
|
||||
|
||||
When the command is executed, primitives are assembled using the current
|
||||
primitive topology and pname:vertexCount consecutive vertex indices with the
|
||||
first code:vertexIndex value equal to pname:firstVertex. The primitives are
|
||||
drawn pname:instanceCount times with code:instanceIndex starting with
|
||||
pname:firstInstance and increasing sequentially for each instance. The
|
||||
assembled primitives execute the currently bound graphics pipeline.
|
||||
|
||||
include::../validity/protos/vkCmdDraw.txt[]
|
||||
|
||||
To record an indexed draw, call:
|
||||
|
||||
include::../protos/vkCmdDrawIndexed.txt[]
|
||||
|
||||
* pname:commandBuffer is the command buffer into which the command is
|
||||
recorded.
|
||||
* 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 base offset within the index buffer.
|
||||
* pname:firstInstance is the instance ID of the first instance to draw.
|
||||
|
||||
When the command is executed, primitives are assembled using the current
|
||||
primitive topology and pname:indexCount vertices whose indices are retrieved
|
||||
from the index buffer. The index buffer is treated as an array of tightly
|
||||
packed unsigned integers of size defined by the
|
||||
flink:vkCmdBindIndexBuffer::pname:indexType parameter with which the buffer
|
||||
was bound.
|
||||
|
||||
The first vertex index is at an offset of pname:firstIndex * code:indexSize
|
||||
+ pname:offset within the currently bound index buffer, where pname:offset
|
||||
is the offset specified by fname:vkCmdBindIndexBuffer and code:indexSize is
|
||||
the byte size of the type specified by pname:indexType. Subsequent index
|
||||
values are retrieved from consecutive locations in the index buffer. Indices
|
||||
are first compared to the primitive restart value, then zero extended to 32
|
||||
bits (if the code:indexType is ename:VK_INDEX_TYPE_UINT16) and have
|
||||
pname:vertexOffset added to them, before being supplied as the
|
||||
code:vertexIndex value.
|
||||
|
||||
The primitives are drawn pname:instanceCount times with code:instanceIndex
|
||||
starting with pname:firstInstance and increasing sequentially for each
|
||||
instance. The assembled primitives execute the currently bound graphics
|
||||
pipeline.
|
||||
|
||||
include::../validity/protos/vkCmdDrawIndexed.txt[]
|
||||
|
||||
A non-indexed indirect draw is recorded by calling:
|
||||
|
||||
include::../protos/vkCmdDrawIndirect.txt[]
|
||||
|
||||
* pname:commandBuffer is the command buffer into which the command is
|
||||
recorded.
|
||||
* pname:buffer is the buffer containing draw parameters.
|
||||
* pname:offset is the byte offset into pname:buffer where parameters
|
||||
begin.
|
||||
* pname:drawCount is the number of draws to execute, and can: be zero.
|
||||
* pname:stride is the byte stride between successive sets of draw
|
||||
parameters.
|
||||
|
||||
fname:vkCmdDrawIndirect behaves similarly to flink:vkCmdDraw except that the
|
||||
parameters are read by the device from a buffer during execution.
|
||||
pname:drawCount draws are executed by the command, with parameters taken
|
||||
from pname:buffer starting at pname:offset and increasing by pname:stride
|
||||
bytes for each successive draw. The parameters of each draw are encoded in
|
||||
an array of slink:VkDrawIndirectCommand structures. If pname:drawCount is
|
||||
less than or equal to one, pname:stride is ignored.
|
||||
|
||||
include::../validity/protos/vkCmdDrawIndirect.txt[]
|
||||
|
||||
The definition of sname:VkDrawIndirectCommand is:
|
||||
|
||||
include::../structs/VkDrawIndirectCommand.txt[]
|
||||
|
||||
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:
|
||||
|
||||
include::../protos/vkCmdDrawIndexedIndirect.txt[]
|
||||
|
||||
* pname:commandBuffer is the command buffer into which the command is
|
||||
recorded.
|
||||
* pname:buffer is the buffer containing draw parameters.
|
||||
* pname:offset is the byte offset into pname:buffer where parameters
|
||||
begin.
|
||||
* pname:drawCount is the number of draws to execute, and can: be zero.
|
||||
* pname:stride is the byte stride between successive sets of draw
|
||||
parameters.
|
||||
|
||||
fname:vkCmdDrawIndexedIndirect behaves similarly to flink:vkCmdDrawIndirect
|
||||
except that the parameters are read by the device from a buffer during
|
||||
execution. pname:drawCount draws are executed by the command, with
|
||||
parameters taken from pname:buffer starting at pname:offset and increasing
|
||||
by pname:stride bytes for each successive draw. The parameters of each draw
|
||||
are encoded in an array of slink:VkDrawIndexedIndirectCommand structures. If
|
||||
pname:drawCount is less than or equal to one, pname:stride is ignored.
|
||||
|
||||
include::../validity/protos/vkCmdDrawIndexedIndirect.txt[]
|
||||
|
||||
The definition of sname:VkDrawIndexedIndirectCommand is
|
||||
|
||||
include::../structs/VkDrawIndexedIndirectCommand.txt[]
|
||||
|
||||
The members of sname:VkDrawIndexedIndirectCommand have the same meaning as
|
||||
the similarly named parameters of flink:vkCmdDrawIndexed.
|
||||
|
||||
include::../validity/structs/VkDrawIndexedIndirectCommand.txt[]
|
||||
|
|
@ -0,0 +1,193 @@
|
|||
// Copyright (c) 2015-2016 The Khronos Group Inc.
|
||||
// Copyright notice at https://www.khronos.org/registry/speccopyright.html
|
||||
|
||||
[[extended-functionality]]
|
||||
= Extended Functionality
|
||||
|
||||
Additional functionality may: be provided by layers or extensions. A layer
|
||||
cannot: add or modify {apiname} commands, while an extension may: do so.
|
||||
|
||||
There are two kinds of layers and extensions, instance and device. Instance
|
||||
layers and extensions are general purpose and do not depend on a specific
|
||||
device. Device layers and extensions operate on specific devices, and
|
||||
require a valid sname:VkDevice to be used. Instance extensions usually
|
||||
affect the operation of the API as a whole, whereas device layers and
|
||||
extensions tend to be hardware-specific. Examples of these might be:
|
||||
|
||||
* Whole API validation is an example of a good instance layer.
|
||||
* Debug capabilities might make a good instance extension.
|
||||
* A layer that provides hardware-specific performance telemetry and
|
||||
analysis could be a device layer.
|
||||
* Functions to allow an application to use additional hardware features
|
||||
beyond the core would be a good candidate for a device extension.
|
||||
|
||||
[[extended-functionality-layers]]
|
||||
== Layers
|
||||
|
||||
When a layer is enabled, it inserts itself into the call chain for {apiname}
|
||||
commands the layer is interested in. A common use of layers is to validate
|
||||
application behavior during development. For example, the implementation
|
||||
will not check that {apiname} enums used by the application fall within
|
||||
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.
|
||||
|
||||
To query the available instance layers, call:
|
||||
|
||||
include::../protos/vkEnumerateInstanceLayerProperties.txt[]
|
||||
|
||||
* pname:pPropertyCount is the number of layer properties that can be
|
||||
returned in pname:pProperties.
|
||||
* pname:pProperties is an array of slink:VkLayerProperties structures in
|
||||
which properties of instance layers available on this implementation are
|
||||
returned.
|
||||
|
||||
include::../validity/protos/vkEnumerateInstanceLayerProperties.txt[]
|
||||
|
||||
To enable a instance layer, the name of the layer should be added to the
|
||||
pname:ppEnabledLayerNames member of slink:VkInstanceCreateInfo when creating
|
||||
a slink:VkInstance.
|
||||
|
||||
To query the layers available to a given physical device, call:
|
||||
|
||||
include::../protos/vkEnumerateDeviceLayerProperties.txt[]
|
||||
|
||||
* pname:physicalDevice is the physical device that will be queried.
|
||||
* pname:pPropertyCount is the number of layer properties that can be
|
||||
returned in pname:pProperties.
|
||||
* pname:pProperties is an array of slink:VkLayerProperties structures in
|
||||
which properties of layers available on pname:physicalDevice are
|
||||
returned.
|
||||
|
||||
include::../validity/protos/vkEnumerateDeviceLayerProperties.txt[]
|
||||
|
||||
To enable a device layer, the name of the layer should be added to the
|
||||
pname:ppEnabledLayerNames member of slink:VkDeviceCreateInfo when creating
|
||||
a slink:VkDevice.
|
||||
|
||||
Both commands will return an array of sname:VkLayerProperties of the
|
||||
respective instance or device layers present. Calling
|
||||
fname:vkEnumerateInstanceLayerProperties or
|
||||
fname:vkEnumerateDeviceLayerProperties with pname:pProperties set to `NULL`
|
||||
will return the number of supported layers in the basetype:uint32_t variable
|
||||
pointed to by pname:pPropertyCount. If pname:pProperties is not set to
|
||||
`NULL`, the query will fill the array and update pname:pPropertyCount to
|
||||
indicate the number of sname:VkLayerProperties filled in. If
|
||||
pname:pPropertyCount 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 properties were returned.
|
||||
|
||||
The definition of sname:VkLayerProperties is:
|
||||
|
||||
include::../structs/VkLayerProperties.txt[]
|
||||
|
||||
* pname:layerName is a null-terminated string specifying the name of the
|
||||
layer. Use this name in the pname:ppEnabledLayerNames array in the
|
||||
sname:VkInstanceCreateInfo given to fname:vkCreateInstance to enable
|
||||
this layer in the instance.
|
||||
* pname:apiVersion is the {apiname} version the layer was written to,
|
||||
encoded as described in the <<fundamentals-versionnum,API Version
|
||||
Numbers and Semantics>> section.
|
||||
* pname:implementationVersion is the version of this layer. It is an
|
||||
integer, increasing with backward compatible changes.
|
||||
* pname:description is a null-terminated string providing additional
|
||||
details that can: be used by the application to identify the layer.
|
||||
|
||||
include::../validity/structs/VkLayerProperties.txt[]
|
||||
|
||||
Loader implementations may: provide mechanisms outside the {apiname} API for
|
||||
enabling specific layers. Layers enabled through such a mechanism are
|
||||
_implicitly enabled_, while layers enabled by including the layer name in
|
||||
the pname:ppEnabledLayerNames member of slink:VkDeviceCreateInfo are
|
||||
_explicitly enabled_. Except where otherwise specified, implicitly enabled
|
||||
and explicitly enabled layers differ only in the way they are enabled.
|
||||
Explicitly enabling a layer that is implicitly enabled has no additional
|
||||
effect.
|
||||
|
||||
[[extended-functionality-extensions]]
|
||||
== Extensions
|
||||
|
||||
Extensions may: define new {apiname} commands, structures, and enumerants.
|
||||
For compilation purposes, the interfaces defined by registered extensions,
|
||||
including new structures and enumerants as well as function pointer types
|
||||
for new commands, are defined in the Khronos-supplied +vulkan.h+ together
|
||||
with the core API. However, commands defined by extensions maynot: be
|
||||
available for static linking - in which case function pointers to these
|
||||
commands should: be queried at runtime as described in
|
||||
<<initialization-functionpointers>>. Extensions may: be provided by layers
|
||||
as well as by a {apiname} implementation.
|
||||
|
||||
To query the available instance extensions, call:
|
||||
|
||||
include::../protos/vkEnumerateInstanceExtensionProperties.txt[]
|
||||
|
||||
* pname:pLayerName is either `NULL` or the name of a instance layer to
|
||||
retrieve extensions from.
|
||||
* pname:pPropertyCount is the number of extension properties that can be
|
||||
returned in pname:pProperties.
|
||||
* pname:pProperties is an array of slink:VkExtensionProperties structures
|
||||
in which properties of instance extensions available on this
|
||||
implementation are returned.
|
||||
|
||||
include::../validity/protos/vkEnumerateInstanceExtensionProperties.txt[] Any
|
||||
instance extensions provided by the {apiname} implementation or by
|
||||
implicitly enabled layers, but not by explicitly enabled layers, are
|
||||
returned when pname:pLayerName parameter is `NULL`. When pname:pLayerName is
|
||||
the name of a layer, the instance extensions provided by that layer are
|
||||
returned.
|
||||
|
||||
To enable a instance extension, the name of the extension should be added to
|
||||
the pname:ppEnabledExtensionNames member of slink:VkInstanceCreateInfo when
|
||||
creating a slink:VkInstance.
|
||||
|
||||
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 the name of a device layer to
|
||||
retrieve extensions from.
|
||||
* pname:pPropertyCount is the number of extension properties that can be
|
||||
returned in pname:pProperties.
|
||||
* pname:pProperties is an array of slink:VkExtensionProperties structures
|
||||
in which properties of extensions available on pname:physicalDevice are
|
||||
returned.
|
||||
|
||||
include::../validity/protos/vkEnumerateDeviceExtensionProperties.txt[]
|
||||
|
||||
Any device extensions provided by the {apiname} implementation or by
|
||||
implicitly enabled layers, but not by explicitly enabled layers, are
|
||||
returned when pname:pLayerName parameter is `NULL`. When pname:pLayerName is
|
||||
the name of a layer, the device extensions provided by that layer are
|
||||
returned.
|
||||
|
||||
To enable a device layer, the name of the layer should be added to the
|
||||
pname:ppEnabledExtensionNames member of slink:VkDeviceCreateInfo when
|
||||
creating a slink:VkDevice.
|
||||
|
||||
Both commands return an array of sname:VkExtensionProperties
|
||||
for any extensions implemented by the given pname:pLayerName.
|
||||
Set pname:pLayerName to `NULL` to query for extensions not part of any
|
||||
layer. Calling fname:vkEnumerateInstanceExtensionProperties or
|
||||
fname:vkEnumerateDeviceExtensionProperties with pname:pProperties set to
|
||||
`NULL` will return the count of extensions for the given layer in the
|
||||
basetype:uint32_t variable pointed to by pname:pPropertyCount. With
|
||||
pname:pProperties pointing to an array of sname:VkExtensionProperties,
|
||||
fname:vkEnumerateInstanceExtensionProperties
|
||||
and fname:vkEnumerateDeviceExtensionProperties will fill the array and
|
||||
update the count to indicate the number of sname:VkExtensionProperties
|
||||
filled in. If the provided count 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.
|
||||
|
||||
The definition of sname:VkExtensionProperties is:
|
||||
|
||||
include::../structs/VkExtensionProperties.txt[]
|
||||
|
||||
* pname:extensionName is a null-terminated string specifying the name of
|
||||
the extension.
|
||||
* pname:specVersion is the version of this extension. It is an integer,
|
||||
incremented with backward compatible changes.
|
||||
|
||||
include::../validity/structs/VkExtensionProperties.txt[]
|
||||
File diff suppressed because it is too large
Load Diff
|
|
@ -0,0 +1,544 @@
|
|||
// Copyright (c) 2015-2016 The Khronos Group Inc.
|
||||
// Copyright notice at https://www.khronos.org/registry/speccopyright.html
|
||||
|
||||
[[fragops]]
|
||||
= Fragment Operations
|
||||
|
||||
|
||||
[[fragops-early]]
|
||||
== Early Per-Fragment Tests
|
||||
|
||||
Once fragments are produced by rasterization, a number of per-fragment
|
||||
operations are performed prior to fragment shader execution.
|
||||
If a fragment is discarded during any of these
|
||||
operations, it will not be processed by any subsequent stage, including
|
||||
fragment shader execution.
|
||||
|
||||
Two fragment operations are performed in the following order:
|
||||
|
||||
* the scissor test (see <<fragops-scissor,Scissor Test>>)
|
||||
* multisample fragment operations (see <<fragops-samplemask,Sample Mask>>)
|
||||
|
||||
If early per-fragment operations are <<shaders-fragment-earlytest,enabled by
|
||||
the fragment shader>>, these tests are also performed in the following
|
||||
order:
|
||||
|
||||
* the depth bounds tests (see <<fragops-dbt,Depth Bounds Tests>>)
|
||||
* the stencil test (see <<fragops-stencil,Stencil Test>>)
|
||||
* the depth test (see <<fragops-depth,Depth Test>>)
|
||||
* sample counting (see <<fragops-samplecount,Sample Counting>>)
|
||||
|
||||
|
||||
[[fragops-scissor]]
|
||||
== Scissor Test
|
||||
|
||||
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
|
||||
Viewport>>) used by the primitive that generated the fragment. If the
|
||||
pipeline state object is created without ename:VK_DYNAMIC_STATE_SCISSOR
|
||||
enabled then the scissor rectangles are set by the
|
||||
slink:VkPipelineViewportStateCreateInfo state of the pipeline state object.
|
||||
Otherwise, to dynamically set the scissor rectangles call:
|
||||
|
||||
include::../protos/vkCmdSetScissor.txt[]
|
||||
|
||||
* pname:commandBuffer is the command buffer into which the command will be
|
||||
recorded.
|
||||
* pname:firstScissor is the index of the first scissor whose state is
|
||||
updated by the command.
|
||||
* pname:scissorCount is the number of scissors whose rectangles are
|
||||
updated by the command.
|
||||
* pname:pScissors is a pointer to an array of slink:VkRect2D structures
|
||||
defining scissor rectangles.
|
||||
|
||||
The scissor rectangles taken from element latexmath:[$i$] of pname:pScissors
|
||||
replace the current state for the scissor index
|
||||
latexmath:[$\mathit{firstScissor}+i$], for latexmath:[$i$] in
|
||||
latexmath:[$[0, scissorCount)$].
|
||||
|
||||
Each scissor rectangle is described by a slink:VkRect2D structure, with the
|
||||
pname:offset.x and pname:offset.y values determining the upper left corner
|
||||
of the scissor rectangle, and the pname:extent.width and pname:extent.height
|
||||
values determining the size in pixels.
|
||||
|
||||
include::../validity/protos/vkCmdSetScissor.txt[]
|
||||
|
||||
If latexmath:[$\mathit{offset.x} \le x_f \lt \mathit{offset.x} +
|
||||
\mathit{extent.width}$] and latexmath:[$\mathit{offset.y} \le y_f \lt
|
||||
\mathit{offset.y} + \mathit{extent.height}$] for the selected scissor
|
||||
rectangle, then the scissor test passes. Otherwise, the test fails and the
|
||||
fragment is discarded. For points, lines, and polygons, the scissor
|
||||
rectangle for a primitive is selected in the same manner as the viewport
|
||||
(see <<vertexpostproc-viewport,Controlling the Viewport>>). The scissor
|
||||
rectangles only apply to drawing commands, not to other commands like clears
|
||||
or copies.
|
||||
|
||||
It is legal for latexmath:[$\mathit{offset.x} + \mathit{extent.width}$] or
|
||||
latexmath:[$\mathit{offset.y} + \mathit{extent.height}$] to exceed the
|
||||
dimensions of the framebuffer - the scissor test still applies as defined
|
||||
above. Rasterization does not produce fragments outside of the framebuffer,
|
||||
so such fragments never have the scissor test performed on them.
|
||||
|
||||
The scissor test is always performed. Applications can: effectively disable
|
||||
the scissor test by specifying a scissor rectangle that encompasses the
|
||||
entire framebuffer.
|
||||
|
||||
|
||||
[[fragops-samplemask]]
|
||||
== Sample Mask
|
||||
|
||||
This step modifies fragment coverage values based on the values in the
|
||||
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
|
||||
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
|
||||
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.
|
||||
|
||||
|
||||
[[fragops-early-mode]]
|
||||
== Early Fragment Test Mode
|
||||
|
||||
The depth bounds test, stencil test, depth test, and occlusion query sample
|
||||
counting are performed before fragment shading if and only if early fragment
|
||||
tests are enabled by the fragment shader (see
|
||||
<<shaders-fragment-earlytest,Early Fragment Tests>>). When early
|
||||
per-fragment operations are enabled, these operations are performed prior to
|
||||
fragment shader execution, and the stencil buffer, depth buffer, and
|
||||
occlusion query sample counts will be updated accordingly; these operations
|
||||
will not be performed again after fragment shader execution.
|
||||
|
||||
If a pipeline's fragment shader has early fragment tests disabled, these
|
||||
operations are performed only after fragment program execution, in the order
|
||||
described below. If a pipeline does not contain a fragment shader, these
|
||||
operations are performed only once.
|
||||
|
||||
If early fragment tests are enabled, any depth value computed by the
|
||||
fragment shader has no effect. Additionally, the depth test (including depth
|
||||
writes), stencil test (including stencil writes) and sample counting
|
||||
operations are performed even for fragments or samples that would be
|
||||
discarded after fragment shader execution due to per-fragment operations
|
||||
such as alpha-to-coverage tests, or due to the fragment being discarded by
|
||||
the shader itself.
|
||||
|
||||
|
||||
[[fragops-late]]
|
||||
== Late Per-Fragment Tests
|
||||
|
||||
After programmable fragment processing, per-fragment operations are
|
||||
performed before blending and color output to the framebuffer.
|
||||
|
||||
A fragment is produced by rasterization with framebuffer coordinates of
|
||||
latexmath:[$(x_f,y_f)$] and depth latexmath:[$z$], as described in
|
||||
<<primsrast,Rasterization>>. The fragment is then modified by programmable
|
||||
fragment processing, which adds associated data as described in
|
||||
<<shaders,Shaders>>. The fragment is then further modified, and possibly
|
||||
discarded by the late per-fragment operations described in this chapter.
|
||||
These operations are diagrammed in figure <<fig-fragops,Fragment
|
||||
Operations>>, in the order in which they are performed. Finally, if the
|
||||
fragment was not discarded, it is used to update the framebuffer at the
|
||||
fragment's framebuffer coordinates for any samples that remain covered.
|
||||
|
||||
The depth bounds test, stencil test, and depth test are performed for each
|
||||
pixel sample, rather than just once for each fragment. Stencil and depth
|
||||
operations are performed for a pixel sample only if that sample's fragment
|
||||
coverage bit is a value of 1 when the fragment executes the corresponding
|
||||
stage of the graphics pipeline. If the corresponding coverage bit is 0, no
|
||||
operations are performed for that sample. Failure of the depth bounds,
|
||||
stencil, or depth test results in termination of the processing of that
|
||||
sample by means of disabling coverage for that sample, rather than
|
||||
discarding of the fragment. If, at any point, a fragment's coverage becomes
|
||||
zero for all samples, then the fragment is discarded. All operations are
|
||||
performed on the depth and stencil values stored in the depth/stencil
|
||||
attachment of the framebuffer. The contents of the color attachments are not
|
||||
modified at this point.
|
||||
|
||||
The depth bounds test, stencil test, depth test, and occlusion query
|
||||
operations described in <<fragops-dbt,Depth Bounds Test>>,
|
||||
<<fragops-stencil,Stencil Test>>, <<fragops-depth,Depth Test>>,
|
||||
<<fragops-samplecount,Sample Counting>> are instead performed prior to
|
||||
fragment processing, as described in <<fragops-early-mode,Early Fragment
|
||||
Test Mode>>, if requested by the fragment shader.
|
||||
|
||||
|
||||
[[fragops-covg]]
|
||||
== Multisample Coverage
|
||||
|
||||
If a fragment shader is active and its entry point's interface includes a
|
||||
built-in output variable decorated with code:SampleMask, the fragment
|
||||
coverage is code:ANDed with the bits
|
||||
of the sample mask to generate a new fragment coverage value. If such a
|
||||
fragment shader did not assign a value to code:SampleMask due to flow of
|
||||
control, the value code:ANDed with the fragment coverage is undefined. If no
|
||||
fragment shader is active, or if the active fragment shader does not
|
||||
include code:SampleMask in its interface, the fragment coverage is not
|
||||
modified.
|
||||
|
||||
Next, the fragment alpha and coverage values are modified based on the
|
||||
values of the pname:alphaToCoverageEnable and pname:alphaToOneEnable members
|
||||
of the slink:VkPipelineMultisampleStateCreateInfo structure.
|
||||
|
||||
All alpha values in this section refer only to the alpha component of the
|
||||
fragment shader output that has a code:Location and code:Index decoration of
|
||||
zero (see <<pipelines-linking-fragmentoutput,Fragment Output Interface>>).
|
||||
If that shader output has an integer or unsigned integer type, then these
|
||||
operations are skipped.
|
||||
|
||||
If pname:alphaToCoverageEnable is enabled, a temporary coverage value is
|
||||
generated where each bit is determined by the fragment's alpha value. The
|
||||
temporary coverage value is then ANDed with the fragment coverage value to
|
||||
generate a new fragment coverage value.
|
||||
|
||||
No specific algorithm is specified for converting the alpha value to a
|
||||
temporary coverage mask. It is intended that the number of 1's in this value
|
||||
be proportional to the alpha value (clamped to
|
||||
latexmath:[$[0,1\]$]), with all 1's corresponding to a value of 1.0 and all
|
||||
0's corresponding to 0.0. The algorithm may: be different at different pixel
|
||||
locations.
|
||||
|
||||
[NOTE]
|
||||
.Note
|
||||
====
|
||||
Using different algorithms at different pixel location may: help to
|
||||
avoid artifacts caused by regular coverage sample locations.
|
||||
====
|
||||
|
||||
Next, if pname:alphaToOneEnable is enabled, each alpha value is replaced by
|
||||
the maximum representable alpha value for fixed-point color buffers, or by
|
||||
1.0 for floating-point buffers. Otherwise, the alpha values are not changed.
|
||||
|
||||
[[fragops-ds-state]]
|
||||
== Depth and Stencil Operations
|
||||
|
||||
Pipeline state controlling the <<fragops-dbt,depth bounds tests>>,
|
||||
<<fragops-stencil,stencil test>>, and <<fragops-depth,depth test>> is
|
||||
specified through the members of
|
||||
sname:VkPipelineDepthStencilStateCreateInfo:
|
||||
|
||||
include::../structs/VkPipelineDepthStencilStateCreateInfo.txt[]
|
||||
|
||||
The members of sname:VkPipelineDepthStencilStateCreateInfo structure are as
|
||||
follows:
|
||||
|
||||
* 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:depthTestEnable controls whether <<fragops-depth,depth testing>>
|
||||
is enabled.
|
||||
* pname:depthWriteEnable controls whether
|
||||
<<fragops-depth-write,depth writes>> are enabled.
|
||||
* pname:depthCompareOp is the comparison operator used in the
|
||||
<<fragops-depth,depth test>>.
|
||||
* pname:depthBoundsTestEnable controls whether <<fragops-dbt,depth bounds
|
||||
testing>> is enabled.
|
||||
* pname:stencilTestEnable controls whether <<fragops-stencil,stencil
|
||||
testing>> is enabled.
|
||||
* pname:front and pname:back control the parameters of the
|
||||
<<fragops-stencil,stencil test>>.
|
||||
* pname:minDepthBounds and pname:maxDepthBounds define the range of values
|
||||
used in the <<fragops-dbt,depth bounds test>>.
|
||||
|
||||
include::../validity/structs/VkPipelineDepthStencilStateCreateInfo.txt[]
|
||||
|
||||
[[fragops-dbt]]
|
||||
== Depth Bounds Test
|
||||
|
||||
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)
|
||||
and a range of values. The test is enabled or disabled by the
|
||||
pname:depthBoundsTestEnable member of
|
||||
slink:VkPipelineDepthStencilStateCreateInfo: If the pipeline state object
|
||||
is created without the ename:VK_DYNAMIC_STATE_DEPTH_BOUNDS dynamic state
|
||||
enabled then the range of values used in the depth bounds test are defined
|
||||
by the pname:minDepthBounds and pname:maxDepthBounds members of the
|
||||
slink:VkPipelineDepthStencilStateCreateInfo structure. Otherwise, to
|
||||
dynamically set the depth bounds range values call:
|
||||
|
||||
include::../protos/vkCmdSetDepthBounds.txt[]
|
||||
|
||||
* pname:commandBuffer is the command buffer into which the command will be
|
||||
recorded.
|
||||
* pname:minDepthBounds is the lower bound of the range of depth values
|
||||
used in the depth bounds test.
|
||||
* pname:maxDepthBounds is the upper bound of the range.
|
||||
|
||||
include::../validity/protos/vkCmdSetDepthBounds.txt[]
|
||||
|
||||
If latexmath:[$\mathit{minDepthBounds} \leq z_a \leq
|
||||
\mathit{maxDepthBounds}$], then the depth bounds test passes. Otherwise, the
|
||||
test fails and the sample's coverage bit is cleared in the fragment. If
|
||||
there is no depth framebuffer attachment or if the depth bounds test is
|
||||
disabled, it is as if the depth bounds test always passes.
|
||||
|
||||
|
||||
[[fragops-stencil]]
|
||||
== Stencil Test
|
||||
|
||||
The stencil test conditionally disables coverage of a sample based on the
|
||||
outcome of a comparison between the stencil value in the depth/stencil
|
||||
attachment at location latexmath:[$(x_f,y_f)$] (for the appropriate sample)
|
||||
and a reference value. The stencil test also updates the value in the
|
||||
stencil attachment, depending on the test state, the stencil value and the
|
||||
stencil write masks. The test is enabled or disabled by the
|
||||
pname:stencilTestEnable member of
|
||||
slink:VkPipelineDepthStencilStateCreateInfo.
|
||||
|
||||
When disabled, the stencil test and associated modifications are not made,
|
||||
and the sample's coverage is not modified.
|
||||
|
||||
The stencil test is controlled with the pname:front and pname:back members
|
||||
of sname:VkPipelineDepthStencilStateCreateInfo which are of type
|
||||
sname:VkStencilOpState.
|
||||
|
||||
The definition of sname:VkStencilOpState is:
|
||||
|
||||
include::../structs/VkStencilOpState.txt[]
|
||||
|
||||
The members of sname:VkStencilOpState structure are as follows:
|
||||
|
||||
* pname:failOp is the action performed on samples that fail the stencil
|
||||
test.
|
||||
* pname:passOp is the action performed on samples that pass both the depth
|
||||
and stencil tests.
|
||||
* pname:depthFailOp is the action performed on samples that pass the
|
||||
stencil test and fail the depth test.
|
||||
* pname:compareOp is the comparison operator used in the stencil test.
|
||||
* pname:compareMask selects the bits of the unsigned integer stencil
|
||||
values participating in the stencil test.
|
||||
* pname:writeMask selects the bits of the unsigned integer stencil values
|
||||
updated by the stencil test in the stencil framebuffer attachment.
|
||||
* pname:reference is an integer reference value that is used in the
|
||||
unsigned stencil comparison.
|
||||
|
||||
include::../validity/structs/VkStencilOpState.txt[]
|
||||
|
||||
There are two sets of stencil-related state, the front stencil state set and
|
||||
the back stencil state set. Stencil tests and writes use the front set of
|
||||
stencil state when processing fragments rasterized from non-polygon
|
||||
primitives (points and lines) and front-facing polygon primitives while the
|
||||
back set of stencil state is used when processing fragments rasterized from
|
||||
back-facing polygon primitives. For the purposes of stencil testing, a
|
||||
primitive is still considered a polygon even if the polygon is to be
|
||||
rasterized as points or lines due to the current elink:VkPolygonMode.
|
||||
Whether a polygon is front- or back-facing is determined in the same manner
|
||||
used for face culling (see <<primsrast-triangles-basic,Basic Triangle
|
||||
Rasterization>>).
|
||||
|
||||
The operation of the stencil test is also affected by the
|
||||
pname:compareMask, pname:writeMask, and pname:reference
|
||||
members of sname:VkStencilOpState set in the pipeline state object if the
|
||||
pipeline state object is created without the
|
||||
ename:VK_DYNAMIC_STATE_STENCIL_COMPARE_MASK,
|
||||
ename:VK_DYNAMIC_STATE_STENCIL_WRITE_MASK, and
|
||||
ename:VK_DYNAMIC_STATE_STENCIL_REFERENCE dynamic states enabled,
|
||||
respectively.
|
||||
|
||||
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:
|
||||
|
||||
include::../protos/vkCmdSetStencilCompareMask.txt[]
|
||||
|
||||
* pname:commandBuffer is the command buffer into which the command will be
|
||||
recorded.
|
||||
* pname:faceMask is a bitmask specifying the set of stencil state for
|
||||
which to update the compare mask, and may include the bits:
|
||||
+
|
||||
--
|
||||
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
|
||||
stencil state is updated.
|
||||
** 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[]
|
||||
|
||||
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:
|
||||
|
||||
include::../protos/vkCmdSetStencilWriteMask.txt[]
|
||||
|
||||
* pname:commandBuffer is the command buffer into which the command will be
|
||||
recorded.
|
||||
* pname:faceMask is a bitmask of elink:VkStencilFaceFlagBits specifying
|
||||
the set of stencil state for which to update the compare mask, as
|
||||
described above for flink:vkCmdSetStencilCompareMask.
|
||||
* pname:writeMask is the new value to use as the stencil write mask.
|
||||
|
||||
include::../validity/protos/vkCmdSetStencilWriteMask.txt[]
|
||||
|
||||
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:
|
||||
|
||||
include::../protos/vkCmdSetStencilReference.txt[]
|
||||
|
||||
* pname:commandBuffer is the command buffer into which the command will be
|
||||
recorded.
|
||||
* pname:faceMask is a bitmask of elink:VkStencilFaceFlagBits specifying
|
||||
the set of stencil state for which to update the compare mask, as
|
||||
described above for flink:vkCmdSetStencilCompareMask.
|
||||
* pname:reference is the new value to use as the stencil reference value.
|
||||
|
||||
include::../validity/protos/vkCmdSetStencilReference.txt[]
|
||||
|
||||
pname:reference is an integer reference value that is used in the
|
||||
unsigned stencil comparison. Stencil comparison clamps the reference value
|
||||
to latexmath:[$[0,2^s-1\]$], where latexmath:[$s$] is the number
|
||||
of bits in the stencil framebuffer attachment. The latexmath:[$s$] least
|
||||
significant bits of pname:compareMask are bitwise code:ANDed with
|
||||
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.
|
||||
pname:compareOp is a symbolic constant that determines the stencil
|
||||
comparison function:
|
||||
|
||||
include::../enums/VkCompareOp.txt[]
|
||||
|
||||
* ename:VK_COMPARE_OP_NEVER: the test never passes.
|
||||
* ename:VK_COMPARE_OP_LESS: the test passes when latexmath:[$R \lt S$].
|
||||
* ename:VK_COMPARE_OP_EQUAL: the test passes when latexmath:[$R = S$].
|
||||
* ename:VK_COMPARE_OP_LESS_OR_EQUAL: the test passes when latexmath:[$R
|
||||
\leq S$].
|
||||
* ename:VK_COMPARE_OP_GREATER: the test passes when latexmath:[$R \gt S$].
|
||||
* ename:VK_COMPARE_OP_NOT_EQUAL: the test passes when latexmath:[$R \neq
|
||||
S$].
|
||||
* ename:VK_COMPARE_OP_GREATER_OR_EQUAL: the test passes when latexmath:[$R
|
||||
\geq S$].
|
||||
* ename:VK_COMPARE_OP_ALWAYS: the test always passes.
|
||||
|
||||
As described earlier, the pname:failOp, pname:passOp, and pname:depthFailOp
|
||||
members of pname:VkStencilOpState indicate what happens to the stored
|
||||
stencil value if this or certain subsequent tests fail or pass. Each enum is
|
||||
of type ename:VkStencilOp, which is defined as:
|
||||
|
||||
include::../enums/VkStencilOp.txt[]
|
||||
|
||||
The possible values are:
|
||||
|
||||
* ename:VK_STENCIL_OP_KEEP keeps the current value.
|
||||
* ename:VK_STENCIL_OP_ZERO sets the value to 0.
|
||||
* ename:VK_STENCIL_OP_REPLACE sets the value to pname:reference.
|
||||
* ename:VK_STENCIL_OP_INCREMENT_AND_CLAMP increments the current value and
|
||||
clamps to the maximum representable unsigned value.
|
||||
* ename:VK_STENCIL_OP_DECREMENT_AND_CLAMP decrements the current value and
|
||||
clamps to 0.
|
||||
* ename:VK_STENCIL_OP_INVERT bitwise-inverts the current value.
|
||||
* ename:VK_STENCIL_OP_INCREMENT_AND_WRAP increments the current value and
|
||||
wraps to 0 when the maximum value would have been exceeded.
|
||||
* ename:VK_STENCIL_OP_DECREMENT_AND_WRAP decrements the current value and
|
||||
wraps to the maximum possible value when the value would go below 0.
|
||||
|
||||
For purposes of increment and decrement, the stencil bits are considered as
|
||||
an unsigned integer.
|
||||
|
||||
If the stencil test fails, the sample's coverage bit is cleared in the
|
||||
fragment. If there is no stencil framebuffer attachment, stencil
|
||||
modification cannot: occur, and it is as if the stencil tests always pass.
|
||||
|
||||
If the stencil test passes, the pname:writeMask member of the
|
||||
slink:VkStencilOpState structures controls how the updated stencil value is
|
||||
written to the stencil framebuffer attachment.
|
||||
|
||||
The least significant latexmath:[$s$] bits of pname:writeMask, where
|
||||
latexmath:[$s$] is the number of bits in the stencil framebuffer attachment,
|
||||
specify an integer mask. Where a latexmath:[$1$] appears in this mask, the
|
||||
corresponding bit in the stencil value in the depth/stencil attachment is
|
||||
written; where a latexmath:[$0$] appears, the bit is not written. The
|
||||
pname:writeMask value uses either the front-facing or back-facing state
|
||||
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.
|
||||
|
||||
|
||||
[[fragops-depth]]
|
||||
== Depth Test
|
||||
|
||||
The depth test conditionally disables coverage of a sample based on the
|
||||
outcome of a comparison between the fragment's depth value at the sample
|
||||
location and the sample's depth value in the depth/stencil attachment at
|
||||
location latexmath:[$(x_f,y_f)$]. The comparison is enabled or disabled with
|
||||
the pname:depthTestEnable member of the
|
||||
slink:VkPipelineDepthStencilStateCreateInfo structure. When disabled, the
|
||||
depth comparison and subsequent possible updates to the depth/stencil
|
||||
attachment value are bypassed and the fragment is passed to the next
|
||||
operation. The stencil value, however, can: be modified as indicated above
|
||||
if the depth test passed. If enabled, the comparison takes place and the
|
||||
depth/stencil attachment value can: subsequently be modified.
|
||||
|
||||
The comparison is specified with the pname:depthCompareOp member of
|
||||
slink:VkPipelineDepthStencilStateCreateInfo. Let latexmath:[$z_f$] be the
|
||||
incoming fragment's depth value for a sample, and let latexmath:[$z_a$] be
|
||||
the depth/stencil attachment value in memory for that sample. The depth test
|
||||
passes under the following conditions:
|
||||
|
||||
* ename:VK_COMPARE_OP_NEVER: the test never passes.
|
||||
* ename:VK_COMPARE_OP_LESS: the test passes when
|
||||
latexmath:[$z_f \lt z_a$].
|
||||
* ename:VK_COMPARE_OP_EQUAL: the test passes when
|
||||
latexmath:[$z_f = z_a$].
|
||||
* ename:VK_COMPARE_OP_LESS_OR_EQUAL: the test passes when
|
||||
latexmath:[$z_f \leq z_a$].
|
||||
* ename:VK_COMPARE_OP_GREATER: the test passes when
|
||||
latexmath:[$z_f \gt z_a$].
|
||||
* ename:VK_COMPARE_OP_NOT_EQUAL: the test passes when
|
||||
latexmath:[$z_f \neq z_a$].
|
||||
* ename:VK_COMPARE_OP_GREATER_OR_EQUAL: the test passes when
|
||||
latexmath:[$z_f \geq z_a$].
|
||||
* ename:VK_COMPARE_OP_ALWAYS: the test always passes.
|
||||
|
||||
If depth clamping (see <<vertexpostproc-clipping,Primitive Clipping>>) is
|
||||
enabled, before the incoming fragment's latexmath:[$z_f$] is compared to
|
||||
latexmath:[$z_a$], latexmath:[$z_f$] is clamped to
|
||||
latexmath:[$[\min(n,f), \max(n,f)\]$], where latexmath:[$n$] and
|
||||
latexmath:[$f$] are the pname:minDepth and pname:maxDepth depth range values
|
||||
of the viewport used by this fragment, respectively.
|
||||
|
||||
If the depth test fails, the sample's coverage bit is cleared in the
|
||||
fragment. The stencil value at the sample's location is updated according to
|
||||
the function currently in effect for depth test failure. Otherwise, the
|
||||
fragment continues to the next operation and the value of the depth
|
||||
framebuffer attachment at the sample's location is conditionally written to
|
||||
the sample's latexmath:[$z_f$] value. In this case the stencil value is
|
||||
updated according to the function currently in effect for depth test
|
||||
success.
|
||||
|
||||
[[fragops-depth-write]]
|
||||
Upon passing the depth test, a sample's (possibly clamped) latexmath:[$z_f$]
|
||||
value is conditionally written to the depth framebuffer attachment based on
|
||||
the value of the pname:depthWriteEnable member of
|
||||
slink:VkPipelineDepthStencilStateCreateInfo. If pname:depthWriteEnable is
|
||||
ename:VK_TRUE the value is written, and if it is ename:VK_FALSE the value is
|
||||
not written.
|
||||
|
||||
If there is no depth framebuffer attachment, it is as if the depth test
|
||||
always passes.
|
||||
|
||||
|
||||
[[fragops-samplecount]]
|
||||
== Sample Counting
|
||||
|
||||
Occlusion queries use query pool entries to track the number of samples that
|
||||
pass all the per-fragment tests. The mechanism of collecting an occlusion
|
||||
query value is described in <<queries-occlusion,Occlusion Queries>>.
|
||||
|
||||
The occlusion query sample counter increments by one for each sample with a
|
||||
coverage value of 1 in each fragment that survives all the per-fragment
|
||||
tests, including scissor, sample mask, alpha to coverage, stencil, and depth
|
||||
tests.
|
||||
|
|
@ -0,0 +1,365 @@
|
|||
// Copyright (c) 2015-2016 The Khronos Group Inc.
|
||||
// Copyright notice at https://www.khronos.org/registry/speccopyright.html
|
||||
|
||||
[[framebuffer]]
|
||||
= The Framebuffer
|
||||
|
||||
|
||||
[[framebuffer-blending]]
|
||||
== Blending
|
||||
|
||||
Blending combines the incoming ``source'' fragment's R, G, B, and A values
|
||||
with the ``destination'' R, G, B, and A values of each sample stored in the
|
||||
framebuffer at the fragment's latexmath:[$(x_f,y_f)$] location. Blending is
|
||||
performed for each pixel sample, rather than just once for each fragment.
|
||||
|
||||
Source and destination values are combined according to the
|
||||
<<framebuffer-blendoperations,blend operation>>, quadruplets of source and
|
||||
destination weighting factors determined by the <<framebuffer-blendfactors,
|
||||
blend factors>>, and a <<framebuffer-blendconstants,blend constant>>,
|
||||
to obtain a new set of R, G, B, and A values, as described below.
|
||||
|
||||
Blending is computed and applied separately to each color attachment used by
|
||||
the subpass, with separate controls for each attachment.
|
||||
|
||||
Prior to performing the blend operation, signed and unsigned normalized
|
||||
fixed-point color components undergo an implied conversion to floating-point
|
||||
as specified by <<fundamentals-fixedfpconv,Conversion
|
||||
from Normalized Fixed-Point to Floating-Point>>. Blending
|
||||
computations are treated as if carried out in floating-point, and will be
|
||||
performed with a precision and dynamic range no lower than that used to
|
||||
represent destination components.
|
||||
|
||||
Blending applies only to fixed-point and floating-point color attachments.
|
||||
If the color attachment has an integer format, blending is not applied.
|
||||
|
||||
The pipeline blend state is included in the
|
||||
sname:VkPipelineColorBlendStateCreateInfo struct during graphics pipeline
|
||||
creation:
|
||||
|
||||
include::../structs/VkPipelineColorBlendStateCreateInfo.txt[]
|
||||
|
||||
The members of the sname:VkPipelineColorBlendStateCreateInfo structure are
|
||||
as follows:
|
||||
|
||||
* 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:logicOpEnable controls whether to apply <<framebuffer-logicop,
|
||||
Logical Operations>>.
|
||||
* pname:logicOp selects which logical operation to apply.
|
||||
* pname:attachmentCount is the number of
|
||||
sname:VkPipelineColorBlendAttachmentState elements in
|
||||
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: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[]
|
||||
|
||||
The elements of the pname:pAttachments array specify per-target blending
|
||||
state, and are of type:
|
||||
|
||||
include::../structs/VkPipelineColorBlendAttachmentState.txt[]
|
||||
|
||||
Blending of each individual color attachment is controlled by the
|
||||
corresponding element of the pname:pAttachments array. If the
|
||||
<<features-features-independent-blending,independent blending>> feature is
|
||||
not enabled on the device, all sname:VkPipelineColorBlendAttachmentState
|
||||
elements in the pname:pAttachments array must: be identical. The members of
|
||||
the sname:VkPipelineColorBlendAttachmentState struct have the following
|
||||
meanings:
|
||||
|
||||
* pname:blendEnable controls whether blending is enabled for the
|
||||
corresponding color attachment. If blending is not enabled, the source
|
||||
fragment's color for that attachment is passed through unmodified.
|
||||
* pname:srcColorBlendFactor selects which blend factor is used to
|
||||
determine the source factors latexmath:[$S_r,S_g,S_b$].
|
||||
* pname:dstColorBlendFactor selects which blend factor is used to
|
||||
determine the destination factors latexmath:[$D_r,D_g,D_b$].
|
||||
* pname:colorBlendOp selects which blend operation is used to calculate
|
||||
the RGB values to write to the color attachment.
|
||||
* pname:srcAlphaBlendFactor selects which blend factor is used to
|
||||
determine the source factor latexmath:[$S_a$].
|
||||
* pname:dstAlphaBlendFactor selects which blend factor is used to
|
||||
determine the destination factor latexmath:[$D_a$].
|
||||
* pname:alphaBlendOp selects which blend operation is use to calculate the
|
||||
alpha values to write to the color attachment.
|
||||
* pname:colorWriteMask is a bitmask selecting which of the R, G, B,
|
||||
and/or A components are enabled for writing, as described later in this
|
||||
chapter.
|
||||
|
||||
include::../validity/structs/VkPipelineColorBlendAttachmentState.txt[]
|
||||
|
||||
|
||||
[[framebuffer-blendfactors]]
|
||||
=== Blend Factors
|
||||
|
||||
The source and destination color and alpha blending factors are selected
|
||||
from the enum:
|
||||
|
||||
include::../enums/VkBlendFactor.txt[]
|
||||
|
||||
The semantics of each enum value is described in the table below:
|
||||
|
||||
.Blend Factors
|
||||
[width="100%",options="header",align="center",cols="59%,28%,13%"]
|
||||
|========================================
|
||||
|VkBlendFactor | RGB Blend Factors (latexmath:[$S_r,S_g,S_b$]) or (latexmath:[$D_r,D_g,D_b$]) | Alpha Blend Factor (latexmath:[$S_a$] or latexmath:[$D_a$])
|
||||
|ename:VK_BLEND_FACTOR_ZERO | latexmath:[$(0,0,0)$] | latexmath:[$0$]
|
||||
|ename:VK_BLEND_FACTOR_ONE | latexmath:[$(1,1,1)$] | latexmath:[$1$]
|
||||
|ename:VK_BLEND_FACTOR_SRC_COLOR | latexmath:[$(R_{s0},G_{s0},B_{s0})$] | latexmath:[$A_{s0}$]
|
||||
|ename:VK_BLEND_FACTOR_ONE_MINUS_SRC_COLOR | latexmath:[$(1-R_{s0},1-G_{s0},1-B_{s0})$] | latexmath:[$1-A_{s0}$]
|
||||
|ename:VK_BLEND_FACTOR_DST_COLOR | latexmath:[$(R_d,G_d,B_d)$] | latexmath:[$A_d$]
|
||||
|ename:VK_BLEND_FACTOR_ONE_MINUS_DST_COLOR | latexmath:[$(1-R_d,1-G_d,1-B_d)$] | latexmath:[$1-A_d$]
|
||||
|ename:VK_BLEND_FACTOR_SRC_ALPHA | latexmath:[$(A_{s0},A_{s0},A_{s0})$] | latexmath:[$A_{s0}$]
|
||||
|ename:VK_BLEND_FACTOR_ONE_MINUS_SRC_ALPHA | latexmath:[$(1-A_{s0},1-A_{s0},1-A_{s0})$] | latexmath:[$1-A_{s0}$]
|
||||
|ename:VK_BLEND_FACTOR_DST_ALPHA | latexmath:[$(A_d,A_d,A_d)$] | latexmath:[$A_d$]
|
||||
|ename:VK_BLEND_FACTOR_ONE_MINUS_DST_ALPHA | latexmath:[$(1-A_d,1-A_d,1-A_d)$] | latexmath:[$1-A_d$]
|
||||
|ename:VK_BLEND_FACTOR_CONSTANT_COLOR | latexmath:[$(R_c,G_c,B_c)$] | latexmath:[$A_c$]
|
||||
|ename:VK_BLEND_FACTOR_ONE_MINUS_CONSTANT_COLOR | latexmath:[$(1-R_c,1-G_c,1-B_c)$] | latexmath:[$1-A_c$]
|
||||
|ename:VK_BLEND_FACTOR_CONSTANT_ALPHA | latexmath:[$(A_c,A_c,A_c)$] | latexmath:[$A_c$]
|
||||
|ename:VK_BLEND_FACTOR_ONE_MINUS_CONSTANT_ALPHA | latexmath:[$(1-A_c,1-A_c,1-A_c)$] | latexmath:[$1-A_c$]
|
||||
|ename:VK_BLEND_FACTOR_SRC_ALPHA_SATURATE | latexmath:[$(f,f,f); f=\min(A_{s0},1-A_d)$] | latexmath:[$1$]
|
||||
|ename:VK_BLEND_FACTOR_SRC1_COLOR | latexmath:[$(R_{s1},G_{s1},B_{s1})$] | latexmath:[$A_{s1}$]
|
||||
|ename:VK_BLEND_FACTOR_ONE_MINUS_SRC1_COLOR | latexmath:[$(1-R_{s1},1-G_{s1},1-B_{s1})$] | latexmath:[$1-A_{s1}$]
|
||||
|ename:VK_BLEND_FACTOR_SRC1_ALPHA | latexmath:[$(A_{s1},A_{s1},A_{s1})$] | latexmath:[$A_{s1}$]
|
||||
|ename:VK_BLEND_FACTOR_ONE_MINUS_SRC1_ALPHA | latexmath:[$(1-A_{s1},1-A_{s1},1-A_{s1})$] | latexmath:[$1-A_{s1}$]
|
||||
|========================================
|
||||
|
||||
In this table, the following conventions are used:
|
||||
|
||||
- latexmath:[$R_{s0},G_{s0},B_{s0}$] and latexmath:[$A_{s0}$] represent
|
||||
the first source color R, G, B, and A components, respectively, for the
|
||||
fragment output location corresponding to the color attachment being
|
||||
blended.
|
||||
- latexmath:[$R_{s1},G_{s1},B_{s1}$] and latexmath:[$A_{s1}$] represent
|
||||
the second source color R, G, B, and A components, respectively, used in
|
||||
dual source blending modes, for the fragment output location
|
||||
corresponding to the color attachment being blended.
|
||||
- latexmath:[$R_d,G_d,B_d$] and latexmath:[$A_d$] represent the R, G, B,
|
||||
and A components of the destination color. That is, the color currently
|
||||
in the corresponding color attachment for this fragment/sample.
|
||||
- latexmath:[$R_c,G_c,B_c$] and latexmath:[$A_c$] represent the blend
|
||||
constant R, G, B, and A components, respectively.
|
||||
|
||||
[[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:
|
||||
|
||||
include::../protos/vkCmdSetBlendConstants.txt[]
|
||||
|
||||
* pname:commandBuffer is the command buffer into which the command will be
|
||||
recorded.
|
||||
* pname:blendConstants is an array of four values specifying the R, G, B,
|
||||
and A components of the blend constant color used in blending, depending
|
||||
on the <<framebuffer-blendfactors,blend factor>>.
|
||||
|
||||
include::../validity/protos/vkCmdSetBlendConstants.txt[]
|
||||
|
||||
|
||||
[[framebuffer-dsb]]
|
||||
=== Dual-Source Blending
|
||||
|
||||
Blend factors that use the secondary color input
|
||||
latexmath:[$(R_{s1},G_{s1},B_{s1},A_{s1})$]
|
||||
(ename:VK_BLEND_FACTOR_SRC1_COLOR,
|
||||
ename:VK_BLEND_FACTOR_ONE_MINUS_SRC1_COLOR,
|
||||
ename:VK_BLEND_FACTOR_SRC1_ALPHA, and
|
||||
ename:VK_BLEND_FACTOR_ONE_MINUS_SRC1_ALPHA) may: consume hardware resources
|
||||
that could otherwise be used for rendering to multiple color attachments.
|
||||
Therefore, the number of color attachments that can: be used in a
|
||||
framebuffer may: be lower when using dual-source blending.
|
||||
|
||||
Dual-source blending is only supported if the
|
||||
<<features-features-dualSrcBlend,pname:dualSrcBlend>> feature is enabled.
|
||||
|
||||
The maximum number of color attachments that can: be used in a subpass when
|
||||
using dual-source blending functions is implementation-dependent and is
|
||||
reported as the pname:maxFragmentDualSrcAttachments member of
|
||||
sname:VkPhysicalDeviceLimits.
|
||||
|
||||
When using a fragment shader with dual-source blending functions, the color
|
||||
outputs are bound to the first and second inputs of the blender using the
|
||||
code:Index decoration, as described in <<interfaces-fragmentoutput,Fragment
|
||||
Output Interface>>. If the second color input to the blender is not
|
||||
written in the shader, or if no output is bound to the second input of a
|
||||
blender, the result of the blending operation is not defined.
|
||||
|
||||
|
||||
[[framebuffer-blendoperations]]
|
||||
=== Blend 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,
|
||||
with RGB and alpha components potentially using different blend operations:
|
||||
|
||||
include::../enums/VkBlendOp.txt[]
|
||||
|
||||
The semantics of each enum value is described in the table below:
|
||||
|
||||
.Blend Operations
|
||||
[width="100%",cols="45%,30%,25%",options="header",style="verse",align="center"]
|
||||
|==========================================
|
||||
|VkBlendOp | RGB Components | Alpha Component
|
||||
|
||||
|ename:VK_BLEND_OP_ADD
|
||||
| latexmath:[$R=R_{s0}\times S_r+R_d\times D_r$] +
|
||||
latexmath:[$G=G_{s0}\times S_g+G_d\times D_g$] +
|
||||
latexmath:[$B=B_{s0}\times S_b+B_d\times D_b$]
|
||||
| latexmath:[$A=A_{s0}\times S_a+A_d\times D_a$]
|
||||
|
||||
|ename:VK_BLEND_OP_SUBTRACT
|
||||
| latexmath:[$R=R_{s0}\times S_r-R_d\times D_r$] +
|
||||
latexmath:[$G=G_{s0}\times S_g-G_d\times D_g$] +
|
||||
latexmath:[$B=B_{s0}\times S_b-B_d\times D_b$] +
|
||||
| latexmath:[$A=A_{s0}\times S_a-A_d\times D_a$]
|
||||
|
||||
|ename:VK_BLEND_OP_REVERSE_SUBTRACT
|
||||
| latexmath:[$R=R_d\times D_r-R_{s0}\times S_r$] +
|
||||
latexmath:[$G=G_d\times D_g-G_{s0}\times S_g$] +
|
||||
latexmath:[$B=B_d\times D_b-B_{s0}\times S_b$] +
|
||||
| latexmath:[$A=A_d\times D_a-A_{s0}\times S_a$]
|
||||
|
||||
|ename:VK_BLEND_OP_MIN
|
||||
| latexmath:[$R=\min(R_{s0},R_d)$] +
|
||||
latexmath:[$G=\min(G_{s0},G_d)$] +
|
||||
latexmath:[$B=\min(B_{s0},B_d)$]
|
||||
| latexmath:[$A=\min(A_{s0},A_d)$]
|
||||
|
||||
|ename:VK_BLEND_OP_MAX
|
||||
| latexmath:[$R=\max(R_{s0},R_d)$] +
|
||||
latexmath:[$G=\max(G_{s0},G_d)$] +
|
||||
latexmath:[$B=\max(B_{s0},B_d)$] +
|
||||
| latexmath:[$A=\max(A_{s0},A_d)$]
|
||||
|==========================================
|
||||
|
||||
In this table, the following conventions are used:
|
||||
|
||||
- latexmath:[$R_{s0},G_{s0},B_{s0}$] and latexmath:[$A_{s0}$] represent
|
||||
the first source color R, G, B, and A components, respectively.
|
||||
- latexmath:[$R_d,G_d,B_d$] and latexmath:[$A_d$] represent the R, G, B,
|
||||
and A components of the destination color. That is, the color currently
|
||||
in the corresponding color attachment for this fragment/sample.
|
||||
- latexmath:[$S_r,S_g,S_b$] and latexmath:[$S_a$] represent the source
|
||||
blend factor R, G, B, and A components, respectively.
|
||||
- latexmath:[$D_r,D_g,D_b$] and latexmath:[$D_a$] represent the
|
||||
destination blend factor R, G, B, and A components, respectively.
|
||||
|
||||
The blending operation produces a new set of values latexmath:[$R, G,
|
||||
B$] and latexmath:[$A$], which are written to the framebuffer attachment. If
|
||||
blending is not enabled for this attachment, then latexmath:[$R, G, B$] and
|
||||
latexmath:[$A$] are assigned the values of
|
||||
latexmath:[$R_{s0},G_{s0},B_{s0}$] and latexmath:[$A_{s0}$].
|
||||
|
||||
If the color attachment is fixed-point, the components of the source and
|
||||
destination values and blend factors are each clamped to
|
||||
latexmath:[$[0,1\]$] or latexmath:[$[-1,1\]$] respectively for an unsigned
|
||||
normalized or signed normalized color attachment prior to evaluating the
|
||||
blend operations. If the color attachment is floating-point, no clamping
|
||||
occurs.
|
||||
|
||||
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.
|
||||
pname:colorWriteMask is any combination of the following bits:
|
||||
|
||||
include::../enums/VkColorComponentFlagBits.txt[]
|
||||
|
||||
If ename:VK_COLOR_COMPONENT_R_BIT is set, then the latexmath:[$R$] value is
|
||||
written to color attachment for the appropriate sample, otherwise the value
|
||||
in memory is unmodified. The ename:VK_COLOR_COMPONENT_G_BIT,
|
||||
ename:VK_COLOR_COMPONENT_B_BIT, and ename:VK_COLOR_COMPONENT_A_BIT bits
|
||||
similarly control writing of the latexmath:[$G, B,$] and latexmath:[$A$]
|
||||
values. The pname:colorWriteMask is applied regardless of whether blending
|
||||
is enabled.
|
||||
|
||||
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
|
||||
hence are linearized prior to their use in blending. Each R, G, and B
|
||||
component is converted from nonlinear to linear as described in the
|
||||
``KHR_DF_TRANSFER_SRGB`` section of the Khronos Data Format Specification.
|
||||
If the format is not sRGB, no linearization is performed.
|
||||
|
||||
If the numeric format of a framebuffer attachment uses sRGB encoding, then
|
||||
the final R, G and B values are converted into the nonlinear sRGB color
|
||||
space before being written to the framebuffer attachment as described in the
|
||||
``KHR_DF_TRANSFER_SRGB`` section of the Khronos Data Format Specification.
|
||||
|
||||
If the framebuffer color attachment numeric format is not sRGB encoded then
|
||||
the resulting latexmath:[$c_s$] values for R, G and B are unmodified. The
|
||||
value of A is never sRGB encoded. That is, the alpha component is always
|
||||
stored in memory as linear.
|
||||
|
||||
|
||||
[[framebuffer-logicop]]
|
||||
== Logical Operations
|
||||
|
||||
The application can: enable a _logical operation_ between the fragment's
|
||||
color values and the existing value in the framebuffer attachment. This
|
||||
logical operation is applied prior to updating the framebuffer attachment.
|
||||
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.
|
||||
|
||||
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
|
||||
pname:logicOp is applied between each color attachment and the fragment's
|
||||
corresponding output value, and blending of all attachments is treated as if
|
||||
it were disabled. Any attachments using color formats for which logical
|
||||
operations are not supported simply pass through the color values
|
||||
unmodified. The logical operation is applied independently for each of the
|
||||
red, green, blue, and alpha components. The pname:logicOp is selected from
|
||||
the following operations:
|
||||
|
||||
include::../enums/VkLogicOp.txt[]
|
||||
|
||||
The logical operations supported by {apiname} are summarized in the
|
||||
following table in which
|
||||
|
||||
* latexmath:[$\lnot$] is bitwise invert,
|
||||
* latexmath:[$\land$] is bitwise and,
|
||||
* latexmath:[$\lor$] is bitwise or,
|
||||
* latexmath:[$\oplus$] is bitwise exclusive or,
|
||||
* latexmath:[$s$] is the fragment's latexmath:[$R_{s0}, G_{s0}, B_{s0}$]
|
||||
or latexmath:[$A_{s0}$] component value for the fragment output
|
||||
corresponding to the color attachment being updated, and
|
||||
* latexmath:[$d$] is the color attachment's latexmath:[$R, G, B$] or
|
||||
latexmath:[$A$] component value:
|
||||
|
||||
.Logical Operations
|
||||
[width="75%",options="header",style="verse",align="center"]
|
||||
|==========================================
|
||||
|Mode | Operation
|
||||
|ename:VK_LOGIC_OP_CLEAR | latexmath:[$0$]
|
||||
|ename:VK_LOGIC_OP_AND | latexmath:[$s \land d$]
|
||||
|ename:VK_LOGIC_OP_AND_REVERSE | latexmath:[$s \land \lnot d$]
|
||||
|ename:VK_LOGIC_OP_COPY | latexmath:[$s$]
|
||||
|ename:VK_LOGIC_OP_AND_INVERTED | latexmath:[$\lnot s \land d$]
|
||||
|ename:VK_LOGIC_OP_NO_OP | latexmath:[$d$]
|
||||
|ename:VK_LOGIC_OP_XOR | latexmath:[$s \oplus d$]
|
||||
|ename:VK_LOGIC_OP_OR | latexmath:[$s \lor d$]
|
||||
|ename:VK_LOGIC_OP_NOR | latexmath:[$\lnot (s \lor d)$]
|
||||
|ename:VK_LOGIC_OP_EQUIVALENT | latexmath:[$\lnot (s \oplus d)$]
|
||||
|ename:VK_LOGIC_OP_INVERT | latexmath:[$\lnot d$]
|
||||
|ename:VK_LOGIC_OP_OR_REVERSE | latexmath:[$s \lor \lnot d$]
|
||||
|ename:VK_LOGIC_OP_COPY_INVERTED | latexmath:[$\lnot s$]
|
||||
|ename:VK_LOGIC_OP_OR_INVERTED | latexmath:[$\lnot s \lor d$]
|
||||
|ename:VK_LOGIC_OP_NAND | latexmath:[$\lnot (s \land d)$]
|
||||
|ename:VK_LOGIC_OP_SET | all 1s
|
||||
|==========================================
|
||||
|
||||
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>>.
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
|
|
@ -0,0 +1,455 @@
|
|||
// Copyright (c) 2015-2016 The Khronos Group Inc.
|
||||
// Copyright notice at https://www.khronos.org/registry/speccopyright.html
|
||||
|
||||
[[fxvertex]]
|
||||
= Fixed-Function Vertex Processing
|
||||
|
||||
Some implementations have specialized fixed-function hardware for fetching
|
||||
and format-converting vertex input data from buffers, rather than performing
|
||||
the fetch as part of the vertex shader. {apiname} includes a vertex
|
||||
attribute fetch stage in the graphics pipeline in order to take advantage of
|
||||
this.
|
||||
|
||||
|
||||
[[fxvertex-attrib]]
|
||||
== Vertex Attributes
|
||||
|
||||
Vertex shaders can: define input variables, which receive _vertex attribute_
|
||||
data transferred from one or more sname:VkBuffer(s) by drawing commands.
|
||||
Vertex shader input variables are bound to buffers via an indirect binding
|
||||
where the vertex shader associates a _vertex input attribute_ number with
|
||||
each variable, vertex input attributes are associated to _vertex input
|
||||
bindings_ on a per-pipeline basis, and vertex input bindings are associated
|
||||
with specific buffers on a per-draw basis via the
|
||||
fname:vkCmdBindVertexBuffers command. Vertex input attribute and vertex
|
||||
input binding descriptions also contain format information controlling how
|
||||
data is extracted from buffer memory and converted to the format expected by
|
||||
the vertex shader.
|
||||
|
||||
There are sname:VkPhysicalDeviceLimits::pname:maxVertexInputAttributes
|
||||
number of vertex input attributes and
|
||||
sname:VkPhysicalDeviceLimits::pname:maxVertexInputBindings number of
|
||||
vertex input bindings (each referred to
|
||||
by zero-based indices), where there are at least as many vertex input
|
||||
attributes as there are vertex input bindings. Applications can: store
|
||||
multiple vertex input attributes interleaved in a single buffer, and use a
|
||||
single vertex input binding to access those attributes.
|
||||
|
||||
In GLSL, vertex shaders associate input variables with a vertex input
|
||||
attribute number using the code:location layout qualifier. The
|
||||
code:component layout qualifier associates components of a vertex shader
|
||||
input variable with components of a vertex input attribute.
|
||||
|
||||
.GLSL example
|
||||
[source,{basebackend@docbook:c:glsl}]
|
||||
---------------------------------------------------
|
||||
// Assign location M to variableName
|
||||
layout (location=M, component=2) in vec2 variableName;
|
||||
|
||||
// Assign locations [N,N+L) to the array elements of variableNameArray
|
||||
layout (location=N) in vec4 variableNameArray[L];
|
||||
---------------------------------------------------
|
||||
|
||||
In SPIR-V, vertex shaders associate input variables with a vertex input
|
||||
attribute number using the code:Location decoration. The code:Component
|
||||
decoration associates components of a vertex shader input variable with
|
||||
components of a vertex input attribute. The code:Location and code:Component
|
||||
decorations are specified via the code:OpDecorate instruction.
|
||||
|
||||
.SPIR-V example
|
||||
---------------------------------------------------
|
||||
...
|
||||
%1 = OpExtInstImport "GLSL.std.450"
|
||||
...
|
||||
OpName %9 "variableName"
|
||||
OpName %15 "variableNameArray"
|
||||
OpName %18 "gl_VertexID"
|
||||
OpName %19 "gl_InstanceID"
|
||||
OpDecorate %9 Location M
|
||||
OpDecorate %9 Component 2
|
||||
OpDecorate %15 Location N
|
||||
...
|
||||
%2 = OpTypeVoid
|
||||
%3 = OpTypeFunction %2
|
||||
%6 = OpTypeFloat 32
|
||||
%7 = OpTypeVector %6 2
|
||||
%8 = OpTypePointer Input %7
|
||||
%9 = OpVariable %8 Input
|
||||
%10 = OpTypeVector %6 4
|
||||
%11 = OpTypeInt 32 0
|
||||
%12 = OpConstant %11 L
|
||||
%13 = OpTypeArray %10 %12
|
||||
%14 = OpTypePointer Input %13
|
||||
%15 = OpVariable %14 Input
|
||||
...
|
||||
---------------------------------------------------
|
||||
|
||||
|
||||
[[fxvertex-attrib-location]]
|
||||
=== Attribute Location and Component Assignment
|
||||
|
||||
Vertex shaders allow code:Location and code:Component decorations on
|
||||
input variable declarations. The code:Location decoration specifies which
|
||||
vertex input attribute is used to read and interpret the data that
|
||||
a variable will consume. The code:Component decoration allows the location
|
||||
to be more finely specified for scalars and vectors, down to the
|
||||
individual components within a location that are consumed. The
|
||||
components within a location are 0, 1, 2, and 3. A variable starting
|
||||
at component N will consume components N, N+1, N+2, ... up through
|
||||
its size. For single precision types, it is invalid if the sequence
|
||||
of components gets larger than 3.
|
||||
|
||||
When a vertex shader input variable declared using a scalar or vector
|
||||
32-bit data type is assigned a location, its value(s) are taken from
|
||||
the components of the input attribute specified with the corresponding
|
||||
sname:VkVertexInputAttributeDescription::pname:location.
|
||||
The components used depend on the type of variable and the value of the
|
||||
code:Component decoration specified in the variable declaration,
|
||||
as identified in <<fxvertex-attrib-components>>. Any 32-bit scalar
|
||||
or vector input will consume a single location. For 32-bit data types,
|
||||
missing components are filled in with default values as described
|
||||
<<fxvertex-input-extraction,below>>.
|
||||
|
||||
|
||||
[[fxvertex-attrib-components]]
|
||||
.Input attribute components accessed by 32-bit input variables
|
||||
[width="65%",cols="<5,<3,<3",options="header"]
|
||||
|=============================================
|
||||
| 32-bit data type | code:Component decoration | Components consumed
|
||||
| scalar | 0 or unspecified | (x, o, o, o)
|
||||
| scalar | 1 | (o, y, o, o)
|
||||
| scalar | 2 | (o, o, z, o)
|
||||
| scalar | 3 | (o, o, o, w)
|
||||
| two-component vector | 0 or unspecified | (x, y, o, o)
|
||||
| two-component vector | 1 | (o, y, z, o)
|
||||
| two-component vector | 2 | (o, o, z, w)
|
||||
| three-component vector| 0 or unspecified | (x, y, z, o)
|
||||
| three-component vector| 1 | (o, y, z, w)
|
||||
| four-component vector | 0 or unspecified | (x, y, z, w)
|
||||
|=============================================
|
||||
|
||||
Components indicated by `o' are available for use by other input variables
|
||||
which are sourced from the same attribute, and if used, are either filled
|
||||
with the corresponding component from the input format (if present), or
|
||||
the default value.
|
||||
|
||||
When a vertex shader input variable declared using a 32-bit floating point
|
||||
matrix type is assigned a location _i_, its values are taken from
|
||||
consecutive input attributes starting with the corresponding
|
||||
sname:VkVertexInputAttributeDescription::pname:location. Such matrices are
|
||||
treated as an array of column vectors with values taken from the input
|
||||
attributes identified in <<fxvertex-attrib-matrix>>. The
|
||||
sname:VkVertexInputAttributeDescription::pname:format must: be specified
|
||||
with a elink:VkFormat that corresponds to the appropriate type of column
|
||||
vector. The code:Component decoration mustnot: be used with matrix types.
|
||||
|
||||
[[fxvertex-attrib-matrix]]
|
||||
.Input attributes accessed by 32-bit input matrix variables
|
||||
[width="100%",cols="<10%,<24%,<21%,<45%",options="header"]
|
||||
|=============================================
|
||||
| Data type | Column vector type | Locations consumed | Components consumed
|
||||
| mat2 | two-component vector | i, i+1 | (x, y, o, o), (x, y, o, o)
|
||||
| mat2x3 | three-component vector | i, i+1 | (x, y, z, o), (x, y, z, o)
|
||||
| mat2x4 | four-component vector | i, i+1 | (x, y, z, w), (x, y, z, w)
|
||||
| mat3x2 | two-component vector | i, i+1, i+2 | (x, y, o, o), (x, y, o, o), (x, y, o, o)
|
||||
| mat3 | three-component vector | i, i+1, i+2 | (x, y, z, o), (x, y, z, o), (x, y, z, o)
|
||||
| mat3x4 | four-component vector | i, i+1, i+2 | (x, y, z, w), (x, y, z, w), (x, y, z, w)
|
||||
| mat4x2 | two-component vector | i, i+1, i+2, i+3 | (x, y, o, o), (x, y, o, o), (x, y, o, o), (x, y, o, o)
|
||||
| mat4x3 | three-component vector | i, i+1, i+2, i+3 | (x, y, z, o), (x, y, z, o), (x, y, z, o), (x, y, z, o)
|
||||
| mat4 | four-component vector | i, i+1, i+2, i+3 | (x, y, z, w), (x, y, z, w), (x, y, z, w), (x, y, z, w)
|
||||
|=============================================
|
||||
|
||||
Components indicated by `o' are available for use by other input variables
|
||||
which are sourced from the same attribute, and if used, are either filled
|
||||
with the corresponding component from the input (if present), or
|
||||
the default value.
|
||||
|
||||
When a vertex shader input variable declared using a scalar or vector
|
||||
64-bit data type is assigned a location _i_, its values are taken from
|
||||
consecutive input attributes starting with the corresponding
|
||||
sname:VkVertexInputAttributeDescription::pname:location. The locations
|
||||
and components used depend on the type of variable and the code:Component
|
||||
decoration specified in the variable declaration, as identified in
|
||||
<<fxvertex-attrib-double>>. For 64-bit data types, no default
|
||||
attribute values are provided. Input variables mustnot: use more
|
||||
components than provided by the attribute. Input attributes which have
|
||||
one- or two-component 64-bit formats will consume a single location.
|
||||
Input attributes which have three- or four-component 64-bit formats
|
||||
will consume two consecutive locations. A 64-bit scalar
|
||||
data type will consume two components, and a 64-bit two-component
|
||||
vector data type will consume all four components available within
|
||||
a location. A three- or four-component 64-bit data type mustnot:
|
||||
specify a component. A three-component 64-bit data type will consume
|
||||
all four components of the first location and components 0 and 1 of
|
||||
the second location. This leaves components 2 and 3 available for
|
||||
other component-qualified declarations. A four-component 64-bit
|
||||
data type will consume all four components of the first location
|
||||
and all four components of the second location. It is invalid for
|
||||
a scalar or two-component 64-bit data type to specify a component
|
||||
of 1 or 3.
|
||||
|
||||
[[fxvertex-attrib-double]]
|
||||
.Input attribute locations and components accessed by 64-bit input variables
|
||||
[width="100%",cols="<18%,^12%,<25%,^14%,^18%,<13%",options="header"]
|
||||
|=============================================
|
||||
^.^| Input format | Locations consumed
|
||||
^.^| 64-bit data type |code:Location decoration |code:Component decoration ^| 32-bit components consumed
|
||||
| R64 | i
|
||||
| scalar | i | 0 or unspecified | (x, y, -, -)
|
||||
.3+<.^| R64G64 .3+^.^| i
|
||||
| scalar | i | 0 or unspecified | (x, y, o, o)
|
||||
| scalar | i | 2 | (o, o, z, w)
|
||||
| two-component vector | i | 0 or unspecified | (x, y, z, w)
|
||||
.5+<.^| R64G64B64 .5+^.^| i, i+1
|
||||
| scalar | i | 0 or unspecified | (x, y, o, o), (o, o, -, -)
|
||||
| scalar | i | 2 | (o, o, z, w), (o, o, -, -)
|
||||
| scalar | i+1 | 0 or unspecified | (o, o, o, o), (x, y, -, -)
|
||||
| two-component vector | i | 0 or unspecified | (x, y, z, w), (o, o, -, -)
|
||||
| three-component vector | i | unspecified | (x, y, z, w), (x, y, -, -)
|
||||
.8+<.^| R64G64B64A64 .8+^.^| i, i+1
|
||||
| scalar | i | 0 or unspecified | (x, y, o, o), (o, o, o, o)
|
||||
| scalar | i | 2 | (o, o, z, w), (o, o, o, o)
|
||||
| scalar | i+1 | 0 or unspecified | (o, o, o, o), (x, y, o, o)
|
||||
| scalar | i+1 | 2 | (o, o, o, o), (o, o, z, w)
|
||||
| two-component vector | i | 0 or unspecified | (x, y, z, w), (o, o, o, o)
|
||||
| two-component vector | i+1 | 0 or unspecified | (o, o, o, o), (x, y, z, w)
|
||||
| three-component vector | i | unspecified | (x, y, z, w), (x, y, o, o)
|
||||
| four-component vector | i | unspecified | (x, y, z, w), (x, y, z, w)
|
||||
|=============================================
|
||||
|
||||
Components indicated by `o' are available for use by other input variables
|
||||
which are sourced from the same attribute.
|
||||
Components indicated by `-' are not available for input variables
|
||||
as there are no default values provided for 64-bit data types, and
|
||||
there is no data provided by the input format.
|
||||
|
||||
When a vertex shader input variable declared using a 64-bit floating-point
|
||||
matrix type is assigned a location _i_, its values are taken from
|
||||
consecutive input attribute locations. Such matrices are treated as an array
|
||||
of column vectors with values taken from the input attributes as shown in
|
||||
<<fxvertex-attrib-double>>. Each column vector starts at the location
|
||||
immediately following the last location of the previous column vector. The
|
||||
number of attributes and components assigned to each matrix is determined by
|
||||
the matrix dimensions and ranges from two to eight locations.
|
||||
|
||||
When a vertex shader input variable declared using an array type
|
||||
is assigned a location, its values are taken from consecutive
|
||||
input attributes starting with the corresponding
|
||||
sname:VkVertexInputAttributeDescription::pname:location. The number
|
||||
of attributes and components assigned to each element are determined
|
||||
according to the data type of the array elements and code:Component
|
||||
decoration (if any) specified in the declaration of the array, as described
|
||||
above. Each element of the array, in order, is assigned to consecutive
|
||||
locations, but all at the same specified component within each location.
|
||||
|
||||
Only input variables declared with the data types and component decorations
|
||||
as specified above are supported. _Location aliasing_ is
|
||||
causing two variables to have the same location number. _Component aliasing_
|
||||
is assigning the same (or overlapping) component number for
|
||||
two location aliases. Location aliasing is allowed only if it does
|
||||
not cause compenent aliasing. Further, when location aliasing, the
|
||||
aliases sharing the location must: have the same underlying numerical
|
||||
type (floating-point or integer). Failure to meet these requirements
|
||||
will result in an invalid pipeline.
|
||||
|
||||
|
||||
|
||||
[[fxvertex-input]]
|
||||
== Vertex Input Description
|
||||
|
||||
Applications specify vertex input attribute and vertex input binding
|
||||
descriptions as part of graphics pipeline creation, via the
|
||||
pname:pVertexInputState member of sname:VkGraphicsPipelineCreateInfo, which
|
||||
is of type sname:VkPipelineVertexInputStateCreateInfo:
|
||||
|
||||
include::../structs/VkPipelineVertexInputStateCreateInfo.txt[]
|
||||
|
||||
The members of sname:VkPipelineVertexInputStateCreateInfo have the following
|
||||
meanings:
|
||||
|
||||
* 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:vertexBindingDescriptionCount is the number of vertex binding
|
||||
descriptions provided in pname:pVertexBindingDescriptions.
|
||||
* pname:pVertexBindingDescriptions is a pointer to an array of
|
||||
sname:VkVertexInputBindingDescription structures.
|
||||
* pname:vertexAttributeDescriptionCount is the number of vertex attribute
|
||||
descriptions provided in pname:pVertexAttributeDescriptions.
|
||||
* pname:pVertexAttributeDescriptions is a pointer to an array of
|
||||
sname:VkVertexInputAttributeDescription structures.
|
||||
|
||||
include::../validity/structs/VkPipelineVertexInputStateCreateInfo.txt[]
|
||||
|
||||
Each vertex input binding is specified by an instance of the
|
||||
sname:VkVertexInputBindingDescription structure:
|
||||
|
||||
include::../structs/VkVertexInputBindingDescription.txt[]
|
||||
|
||||
The members of sname:VkVertexInputBindingDescription have the following
|
||||
meanings:
|
||||
|
||||
* pname:binding is the binding number that this structure
|
||||
describes.
|
||||
* pname:stride is the distance in bytes between two
|
||||
consecutive elements within the buffer.
|
||||
* pname:inputRate is a elink:VkVertexInputRate value that specifies
|
||||
whether vertex attribute addressing is a function of the vertex index or
|
||||
of the instance index.
|
||||
|
||||
include::../validity/structs/VkVertexInputBindingDescription.txt[]
|
||||
|
||||
The definition of elink:VkVertexInputRate is:
|
||||
|
||||
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:
|
||||
|
||||
include::../structs/VkVertexInputAttributeDescription.txt[]
|
||||
|
||||
The members of sname:VkVertexInputAttributeDescription have the following
|
||||
meanings:
|
||||
|
||||
* pname:location is the shader binding location number for this
|
||||
attribute.
|
||||
* pname:binding is the binding number which this attribute takes
|
||||
its data from.
|
||||
* pname:format is the size and type of the vertex attribute data.
|
||||
* pname:offset is a byte offset of this attribute relative
|
||||
to the start of an element in the vertex input binding.
|
||||
|
||||
include::../validity/structs/VkVertexInputAttributeDescription.txt[]
|
||||
|
||||
Vertex buffers are bound to a command buffer for use in subsequent draw
|
||||
commands by calling:
|
||||
|
||||
include::../protos/vkCmdBindVertexBuffers.txt[]
|
||||
|
||||
* pname:commandBuffer is the command buffer into which the command is
|
||||
recorded.
|
||||
* pname:firstBinding is the index of the first vertex input binding whose
|
||||
state is updated by the command.
|
||||
* pname:bindingCount is the number of vertex input bindings whose state is
|
||||
updated by the command.
|
||||
* pname:pBuffers is a pointer to an array of buffer handles.
|
||||
* pname:pOffsets is a pointer to an array of buffer offsets.
|
||||
|
||||
The values taken from elements latexmath:[$i$] of pname:pBuffers and
|
||||
pname:pOffsets replace the current state for the vertex input binding
|
||||
latexmath:[$\mathit{firstBinding}+i$], for latexmath:[$i$] in
|
||||
latexmath:[$[0, bindingCount)$]. The vertex input binding is updated to
|
||||
start at the offset indicated by pname:pOffsets[i] from the start of the
|
||||
buffer pname:pBuffers[i]. All vertex input attributes that use each of these
|
||||
bindings will use these updated addresses in their address calculations for
|
||||
subsequent draw commands.
|
||||
|
||||
include::../validity/protos/vkCmdBindVertexBuffers.txt[]
|
||||
|
||||
The address of each attribute for each code:vertexIndex and
|
||||
code:instanceIndex is calculated as follows:
|
||||
|
||||
- Let attribDesc be the member of
|
||||
sname:VkPipelineVertexInputStateCreateInfo::pname:pVertexAttributeDescriptions
|
||||
with sname:VkVertexInputAttributeDescription::pname:location equal to
|
||||
the vertex input attribute number.
|
||||
- Let bindingDesc be the member of
|
||||
sname:VkPipelineVertexInputStateCreateInfo::pname:pVertexBindingDescriptions
|
||||
with sname:VkVertexInputAttributeDescription::pname:binding equal to
|
||||
attribDesc.binding.
|
||||
- Let code:vertexIndex be the index of the vertex within the draw (a value
|
||||
between pname:firstVertex and pname:firstVertex+pname:vertexCount for
|
||||
fname:vkCmdDraw, or a value taken from the index buffer for
|
||||
fname:vkCmdDrawIndexed), and let code:instanceIndex be the instance
|
||||
number of the draw (a value between pname:firstInstance and
|
||||
pname:firstInstance+pname:instanceCount).
|
||||
|
||||
[source,c]
|
||||
---------------------------------------------------
|
||||
bufferBindingAddress = buffer[binding].baseAddress + offset[binding];
|
||||
|
||||
if (bindingDesc.inputRate == VK_VERTEX_INPUT_RATE_VERTEX)
|
||||
vertexOffset = vertexIndex * bindingDesc.stride;
|
||||
else
|
||||
vertexOffset = instanceIndex * bindingDesc.stride;
|
||||
|
||||
attribAddress = bufferBindingAddress + vertexOffset + attribDesc.offset;
|
||||
---------------------------------------------------
|
||||
|
||||
[[fxvertex-input-extraction]]
|
||||
For each attribute, raw data is extracted starting at `attribAddress` and is
|
||||
converted from the sname:VkVertexInputAttributeDescription's pname:format to
|
||||
either to floating-point, unsigned integer, or signed integer based on the
|
||||
base type of the format; the base type of the format must: match the base
|
||||
type of the input variable in the shader. If pname:format is a packed
|
||||
format, `attribAddress` must: be a multiple of the size in bytes of the
|
||||
whole attribute data type as described in <<features-formats-packed,Packed
|
||||
Formats>>. Otherwise, `attribAddress` must: be a multiple of the size in
|
||||
bytes of the component type indicated by pname:format (see
|
||||
<<features-formats,Formats>>). If the format does not include G, B, or A
|
||||
components, then those are filled with (0,0,1) as needed (using either 1.0f
|
||||
or integer 1 based on the format) for attributes that are not 64-bit data
|
||||
types. The number of components in the vertex shader input variable need not
|
||||
exactly match the number of components in the format. If the vertex shader
|
||||
has fewer components, the extra components are discarded.
|
||||
|
||||
|
||||
[[fxvertex-example]]
|
||||
== Example
|
||||
|
||||
To create a graphics pipeline that uses the following vertex description:
|
||||
|
||||
[source,{basebackend@docbook:c++:cpp}]
|
||||
---------------------------------------------------
|
||||
struct Vertex
|
||||
{
|
||||
float x, y, z, w;
|
||||
uint8_t u, v;
|
||||
};
|
||||
---------------------------------------------------
|
||||
|
||||
The application could use the following set of structures:
|
||||
|
||||
[source,{basebackend@docbook:c++:cpp}]
|
||||
---------------------------------------------------
|
||||
const VkVertexInputBindingDescription binding =
|
||||
{
|
||||
0, // binding
|
||||
sizeof(Vertex), // stride
|
||||
VK_VERTEX_INPUT_RATE_VERTEX // inputRate
|
||||
};
|
||||
|
||||
const VkVertexInputAttributeDescription attributes[] =
|
||||
{
|
||||
{
|
||||
0, // location
|
||||
binding.binding, // binding
|
||||
VK_FORMAT_R32G32B32A32_SFLOAT, // format
|
||||
0 // offset
|
||||
},
|
||||
{
|
||||
1, // location
|
||||
binding.binding, // binding
|
||||
VK_FORMAT_R8G8_UNORM, // format
|
||||
4 * sizeof(float) // offset
|
||||
}
|
||||
};
|
||||
|
||||
const VkPipelineVertexInputStateCreateInfo viInfo =
|
||||
{
|
||||
VK_STRUCTURE_TYPE_PIPELINE_VERTEX_INPUT_CREATE_INFO, // sType
|
||||
NULL, // pNext
|
||||
0, // flags
|
||||
1, // vertexBindingDescriptionCount
|
||||
&binding, // pVertexBindingDescriptions
|
||||
2, // vertexAttributeDescriptionCount
|
||||
&attributes[0] // pVertexAttributeDescriptions
|
||||
};
|
||||
---------------------------------------------------
|
||||
|
|
@ -0,0 +1,149 @@
|
|||
// Copyright (c) 2015-2016 The Khronos Group Inc.
|
||||
// Copyright notice at https://www.khronos.org/registry/speccopyright.html
|
||||
|
||||
[[geometry]]
|
||||
= Geometry Shading
|
||||
|
||||
The geometry shader operates on a group of vertices and their associated
|
||||
data assembled from a single input primitive, and emits zero or more
|
||||
output primitives and the group of vertices and their associated data
|
||||
required for each output primitive. Geometry shading is enabled when a
|
||||
geometry shader is included in the pipeline.
|
||||
|
||||
|
||||
[[geometry-input]]
|
||||
== Geometry Shader Input Primitives
|
||||
|
||||
Each geometry shader invocation has access to all vertices in the primitive
|
||||
(and their associated data), which are presented to the shader as an array
|
||||
of inputs. The input primitive type expected by the geometry shader is
|
||||
specified with an code:OpExecutionMode instruction in the geometry shader,
|
||||
and must: be compatible with the primitive topology used by primitive
|
||||
assembly (if tessellation is not in use) or must: match the type of
|
||||
primitive generated by the tessellation primitive generator (if tessellation
|
||||
is in use). Compatibility is defined below, with each input primitive type.
|
||||
The input primitive types accepted by a geometry shader are:
|
||||
|
||||
Points::
|
||||
|
||||
Geometry shaders that operate on points use an code:OpExecutionMode
|
||||
instruction specifing the code:InputPoints input mode. Such a shader is
|
||||
valid only when the pipeline primitive topology is
|
||||
code:VK_PRIMITIVE_TOPOLOGY_POINT_LIST (if tessellation is not in use) or if
|
||||
tessellation is in use and the tessellation evaluation shader uses
|
||||
code:PointMode. There is only a single input vertex available for each
|
||||
geometry shader invocation. However, inputs to the geometry shader are still
|
||||
presented as an array, but this array has a length of one.
|
||||
|
||||
Lines::
|
||||
|
||||
Geometry shaders that operate on line segments are generated by including an
|
||||
code:OpExecutionMode instruction with the code:InputLines mode. Such a
|
||||
shader is valid only for the code:VK_PRIMITIVE_TOPOLOGY_LINE_LIST, and
|
||||
code:VK_PRIMITIVE_TOPOLOGY_LINE_STRIP primitive topologies (if tessellation
|
||||
is not in use) or if tessellation is in use and the tessellation mode is
|
||||
code:Isolines. There are two input vertices available for each geometry
|
||||
shader invocation. The first vertex refers to the vertex at the beginning of
|
||||
the line segment and the second vertex refers to the vertex at the end of
|
||||
the line segment.
|
||||
|
||||
Lines with Adjacency::
|
||||
|
||||
Geometry shaders that operate on line segments with adjacent vertices are
|
||||
generated by including an code:OpExecutionMode instruction with the
|
||||
code:InputLinesAdjacency mode. Such a shader is valid only for the
|
||||
code:VK_PRIMITIVE_TOPOLOGY_LINES_WITH_ADJACENCY and
|
||||
code:VK_PRIMITIVE_TOPOLOGY_LINE_STRIP_WITH_ADJACENCY primitive topologies
|
||||
and mustnot: be used when tessellation is in use.
|
||||
+
|
||||
In this mode, there are four vertices available for each geometry shader
|
||||
invocation. The second vertex refers to attributes of the vertex at the
|
||||
beginning of the line segment and the third vertex refers to the vertex at
|
||||
the end of the line segment. The first and fourth vertices refer to the
|
||||
vertices adjacent to the beginning and end of the line segment,
|
||||
respectively.
|
||||
|
||||
Triangles::
|
||||
|
||||
Geometry shaders that operate on triangles are created by including an
|
||||
code:OpExecutionMode instruction with the code:Triangles mode. Such a
|
||||
shader is valid when the pipeline topology is
|
||||
code:VK_PRIMITIVE_TOPOLOGY_TRIANGLE_LIST,
|
||||
code:VK_PRIMITIVE_TOPOLOGY_TRIANGLE_STRIP, or
|
||||
code:VK_PRIMITIVE_TOPOLOGY_TRIANGLE_FAN (if tessellation is not in use) or
|
||||
when tessellation is in use and the tessellation mode is code:Triangles or
|
||||
code:Quads.
|
||||
+
|
||||
In this mode, there are three vertices available for each geometry shader
|
||||
invocation. The first, second, and third vertices refer to attributes of the
|
||||
first, second, and third vertex of the triangle, respectively.
|
||||
|
||||
Triangles with Adjacency::
|
||||
|
||||
Geometry shaders that operate on triangles with adjacent vertices are
|
||||
created by including an code:OpExecutionMode instruction with the
|
||||
code:InputTrianglesAdjacency mode. Such a shader is valid when the pipeline
|
||||
topology is code:VK_PRIMITIVE_TOPOLOGY_TRIANGLES_WITH_ADJACENCY or
|
||||
code:VK_PRIMITIVE_TOPOLOGY_TRIANGLE_STRIP_WITH_ADJACENCY, and mustnot: be
|
||||
used when tessellation is in use.
|
||||
+
|
||||
In this mode, there are six vertices available for each geometry shader
|
||||
invocation. The first, third and fifth vertices refer to attributes of the
|
||||
first, second and third vertex of the triangle, respectively. The second,
|
||||
fourth and sixth vertices refer to attributes of the vertices adjacent to
|
||||
the edges from the first to the second vertex, from the second to the third
|
||||
vertex, and from the third to the first vertex, respectively.
|
||||
|
||||
|
||||
[[geometry-output]]
|
||||
== Geometry Shader Output Primitives
|
||||
|
||||
A geometry shader generates primitives in one of three output modes: points,
|
||||
line strips, or triangle strips. The primitive mode is specified in the
|
||||
shader using an code:OpExecutionMode instruction with the code:OutputPoints,
|
||||
code:OutputLineStrip or code:OutputTriangleStrip modes, respectively. Each
|
||||
geometry shader must: include exactly one output primitive mode.
|
||||
|
||||
The vertices output by the geometry shader are assembled into points, lines,
|
||||
or triangles based on the output primitive type and the resulting primitives
|
||||
are then further processed as described in <<primsrast>>. If the number of
|
||||
vertices emitted by the geometry shader is not sufficient to produce a
|
||||
single primitive, vertices corresponding to incomplete primitives are not
|
||||
processed by subsequent pipeline stages. The number of vertices output by
|
||||
the geometry shader is limited to a maximum count specified in the shader.
|
||||
|
||||
The maximum output vertex count is specified in the shader using an
|
||||
code:OpExecutionMode instruction with the mode set to code:OutputVertices
|
||||
and the maximum number of vertices that will be produced by the geometry
|
||||
shader specified as a literal. Each geometry shader must: specify a maximum
|
||||
output vertex count.
|
||||
|
||||
|
||||
[[geometry-invocations]]
|
||||
== Multiple Invocations of Geometry Shaders
|
||||
|
||||
Geometry shaders can: be invoked more than one time for each input
|
||||
primitive. This is known as _geometry shader instancing_ and is requested by
|
||||
including an code:OpExecutionMode instruction with code:mode specified as
|
||||
code:Invocations and the number of invocations specified as an integer
|
||||
literal.
|
||||
|
||||
In this mode, the geometry shader will execute latexmath:[$n$] times for
|
||||
each input primitive, where latexmath:[$n$] is the number of invocations
|
||||
specified in the code:OpExecutionMode instruction. The instance number is
|
||||
available to each invocation as a built-in input using code:InvocationID.
|
||||
|
||||
|
||||
[[geometry-ordering]]
|
||||
== Geometry Shader Primitive Ordering
|
||||
|
||||
Limited guarantees are provided for the relative ordering of primitives
|
||||
produced by a geometry shader.
|
||||
|
||||
- For instanced geometry shaders, the output primitives generated from
|
||||
each input primitive are passed to subsequent pipeline stages using the
|
||||
invocation number to order the primitives, from least to greatest.
|
||||
- All output primitives generated from a given input primitive are passed
|
||||
to subsequent pipeline stages before any output primitives generated
|
||||
from subsequent input primitives.
|
||||
|
||||
|
|
@ -0,0 +1,177 @@
|
|||
// Copyright (c) 2015-2016 The Khronos Group Inc.
|
||||
// Copyright notice at https://www.khronos.org/registry/speccopyright.html
|
||||
|
||||
[[initialization]]
|
||||
= Initialization
|
||||
|
||||
Before using {apiname}, an application must: initialize it by loading the
|
||||
{apiname} commands, and creating a slink:VkInstance object.
|
||||
|
||||
[[initialization-functionpointers]]
|
||||
== Command Function Pointers
|
||||
|
||||
{apiname} commands are not necessarily exposed statically on a platform.
|
||||
Function pointers for all {apiname} commands can: be obtained with the
|
||||
command:
|
||||
|
||||
include::../protos/vkGetInstanceProcAddr.txt[]
|
||||
|
||||
* pname:instance is the instance that the function pointer will be
|
||||
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
|
||||
load it dynamically and look up the symbol using platform-specific APIs.
|
||||
Loaders are encouraged to export function symbols for all other core
|
||||
{apiname} commands as well; if this is done, then applications that use only
|
||||
the core {apiname} commands have no need to use fname:vkGetInstanceProcAddr.
|
||||
|
||||
Function pointers to commands that don't 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:
|
||||
|
||||
* fname:vkEnumerateInstanceExtensionProperties
|
||||
* fname:vkEnumerateInstanceLayerProperties
|
||||
* fname:vkCreateInstance
|
||||
|
||||
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
|
||||
dispatchable object (the first parameter) that is a child of pname:instance.
|
||||
|
||||
If pname:pName is not the name of a core {apiname} command, or is an
|
||||
extension command for any extension not supported by any available layer or
|
||||
implementation, then fname:vkGetInstanceProcAddr will return `NULL`.
|
||||
|
||||
ifdef::editing-notes[]
|
||||
[NOTE]
|
||||
.editing-note
|
||||
====
|
||||
(Jon, Bug 14886 / Gitlab issue 4) The WSI group tentatively agreed that the
|
||||
WSI extensions were special, and should get static entry points in link
|
||||
libraries and prototypes in +vulkan.h+, while future extensions would have
|
||||
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
|
||||
neccessity of runtime enabling and testing of each extension before using
|
||||
it.
|
||||
====
|
||||
endif::editing-notes[]
|
||||
|
||||
In order to support systems with multiple {apiname} implementations
|
||||
comprising heterogenous collections of hardware and software, the function
|
||||
pointers returned by fname:vkGetInstanceProcAddr may: point to dispatch
|
||||
code, which calls a different real implementation for different
|
||||
sname:VkDevice objects (and objects created from them). The overhead of this
|
||||
internal dispatch can: be avoided by obtaining device-specific function
|
||||
pointers for any commands that use a device or device-child object as their
|
||||
dispatchable object. Such function pointers can: be obtained with the
|
||||
command:
|
||||
|
||||
include::../protos/vkGetDeviceProcAddr.txt[]
|
||||
|
||||
* pname:device is the logical device that provides the function pointer.
|
||||
* pname:pName is the name of any {apiname} command whose first parameter
|
||||
is one of
|
||||
** sname:VkDevice
|
||||
** sname:VkQueue
|
||||
** sname:VkCommandBuffer
|
||||
|
||||
If pname:pName is not the name of one of these {apiname} 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[]
|
||||
|
||||
[[initialization-instances]]
|
||||
== Instances
|
||||
|
||||
There is no global state in {apiname} and all per-application state is
|
||||
stored in a sname:VkInstance object. Creating a sname:VkInstance object
|
||||
initializes the {apiname} library and allows the application to pass
|
||||
information about itself to the implementation.
|
||||
|
||||
To create an instance object, call:
|
||||
|
||||
include::../protos/vkCreateInstance.txt[]
|
||||
|
||||
* pname:pCreateInfo points to an instance of slink:VkInstanceCreateInfo
|
||||
controlling creation of the instance.
|
||||
* pname:pAllocator controls host memory allocation as described in the
|
||||
<<memory-allocation, Memory Allocation>> chapter.
|
||||
* pname:pInstance points a sname:VkInstance handle in which the resulting
|
||||
instance is returned.
|
||||
|
||||
include::../validity/protos/vkCreateInstance.txt[]
|
||||
|
||||
The definition of sname:VkInstanceCreateInfo is:
|
||||
|
||||
include::../structs/VkInstanceCreateInfo.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:pApplicationInfo is `NULL` or a pointer to an instance of
|
||||
sname:VkApplicationInfo. If not `NULL`, this information helps
|
||||
implementations recognize behavior inherent to classes of applications.
|
||||
slink:VkApplicationInfo is defined in detail below.
|
||||
* pname:enabledLayerCount is the number of global layers to enable.
|
||||
* pname:ppEnabledLayerNames is a pointer to an array of
|
||||
pname:enabledLayerCount null-terminated UTF-8 strings containing the
|
||||
names of layers to enable.
|
||||
* pname:enabledExtensionCount is the number of global extensions to
|
||||
enable.
|
||||
* pname:ppEnabledExtensionNames is a pointer to an array of
|
||||
pname:enabledExtensionCount null-terminated UTF-8 strings containing the
|
||||
names of extensions to enable.
|
||||
|
||||
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.
|
||||
|
||||
The pname:pApplicationInfo member of slink:VkInstanceCreateInfo can: point
|
||||
to an instance of sname:VkApplicationInfo. This structure is defined as:
|
||||
|
||||
include::../structs/VkApplicationInfo.txt[]
|
||||
|
||||
* pname:sType is the type of this structure.
|
||||
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
|
||||
* pname:pApplicationName is a pointer to a null-terminated UTF-8 string
|
||||
containing the name of the application.
|
||||
* pname:applicationVersion is an unsigned integer variable containing the
|
||||
developer-supplied version number of the application.
|
||||
* pname:pEngineName is a pointer to a null-terminated UTF-8 string
|
||||
containing the name of the engine (if any) used to create the
|
||||
application.
|
||||
* pname:engineVersion is an unsigned integer variable containing the
|
||||
developer-supplied version number of the engine used to create the
|
||||
application.
|
||||
* pname:apiVersion is the version of the {apiname} API against which the
|
||||
application expects to run, encoded as described in the
|
||||
<<fundamentals-versionnum,API Version Numbers and Semantics>> section.
|
||||
If pname:apiVersion is 0 the implementation must: ignore it, otherwise
|
||||
if the implementation does not support the requested pname:apiVersion
|
||||
it must: return VK_ERROR_INCOMPATIBLE_DRIVER.
|
||||
|
||||
include::../validity/structs/VkApplicationInfo.txt[]
|
||||
|
||||
To destroy an instance, call:
|
||||
|
||||
include::../protos/vkDestroyInstance.txt[]
|
||||
|
||||
* pname:instance is the handle of the instance to destroy.
|
||||
* pname:pAllocator controls host memory allocation as described in the
|
||||
<<memory-allocation, Memory Allocation>> chapter.
|
||||
|
||||
include::../validity/protos/vkDestroyInstance.txt[]
|
||||
File diff suppressed because it is too large
Load Diff
|
|
@ -0,0 +1,193 @@
|
|||
// Copyright (c) 2015-2016 The Khronos Group Inc.
|
||||
// Copyright notice at https://www.khronos.org/registry/speccopyright.html
|
||||
|
||||
[[introduction]]
|
||||
= Introduction
|
||||
|
||||
This chapter is Informative except for the sections on Terminology and
|
||||
Normative References.
|
||||
|
||||
This document, referred to as the ``{apiname} Specification'' or just the
|
||||
``Specification'' hereafter, describes the {apiname} graphics system: what
|
||||
it is, how it acts, and what is required to implement it. We assume that the
|
||||
reader has at least a rudimentary understanding of computer graphics. This
|
||||
means familiarity with the essentials of computer graphics algorithms and
|
||||
terminology as well as with modern GPUs (Graphic Processing Units).
|
||||
|
||||
The canonical version of the Specification is available in the official
|
||||
{apiname} Registry, located at URL
|
||||
|
||||
http://www.khronos.org/registry/vulkan/
|
||||
|
||||
|
||||
[[introduction-whatis]]
|
||||
== What is the {apiname} Graphics System?
|
||||
|
||||
{apiname} is an API (Application Programming Interface) for graphics and
|
||||
compute hardware. The API consists of many commands that
|
||||
allow a programmer to specify shader programs, compute kernels, objects, and
|
||||
operations involved in producing high-quality graphical images, specifically
|
||||
color images of three-dimensional objects.
|
||||
|
||||
|
||||
[[introduction-programmer]]
|
||||
=== The Programmer's View of {apiname}
|
||||
|
||||
To the programmer, {apiname} is a set of commands that allow the
|
||||
specification of _shader programs_ or _shaders_, _kernels_, data used by
|
||||
kernels or shaders, and state controlling aspects of {apiname} outside the
|
||||
scope of shaders. Typically, the data represents geometry in two or three
|
||||
dimensions and texture images, while the shaders and kernels control the
|
||||
processing of the data, rasterization of the geometry, and the lighting and
|
||||
shading of _fragments_ generated by rasterization, resulting in the
|
||||
rendering of geometry into the framebuffer.
|
||||
|
||||
A typical {apiname} program begins with platform-specific calls to open a
|
||||
window or otherwise prepare a display device onto which the program will
|
||||
draw. Then, calls are made to open _queues_ to which _command buffers_ are
|
||||
submitted. The command buffers contain lists of commands which will be
|
||||
executed by the underlying hardware. The application can: also allocate
|
||||
device memory, associate _resources_ with memory and refer to these
|
||||
resources from within command buffers. Drawing commands cause
|
||||
application-defined shader programs to be invoked, which can: then consume
|
||||
the data in the resources and use them to produce graphical images. To
|
||||
display the resulting images, further platform-specific commands are made to
|
||||
transfer the resulting image to a display device or window.
|
||||
|
||||
|
||||
[[introduction-implementor]]
|
||||
=== The Implementor's View of {apiname}
|
||||
|
||||
To the implementor, {apiname} is a set of commands that allow the
|
||||
construction and submission of command buffers to a device. Modern devices
|
||||
accelerate virtually all {apiname} operations, storing data and framebuffer
|
||||
images in high-speed memory and executing shaders in dedicated GPU
|
||||
processing resources.
|
||||
|
||||
The implementor's task is to provide a software library on the host which
|
||||
implements the {apiname} API, while mapping the work for each {apiname}
|
||||
command to the graphics hardware as appropriate for the capabilities of the
|
||||
device.
|
||||
|
||||
|
||||
[[introduction-ourview]]
|
||||
=== Our View of {apiname}
|
||||
|
||||
We view {apiname} as a pipeline having some programmable stages and some
|
||||
state-driven fixed-function stages that are invoked by a set of specific
|
||||
drawing operations. We expect this model to result in a specification that
|
||||
satisfies the needs of both programmers and implementors. It does not,
|
||||
however, necessarily provide a model for implementation. An implementation
|
||||
must: produce results conforming to those produced by the specified methods,
|
||||
but may: carry out particular computations in ways that are more
|
||||
efficient than the one specified.
|
||||
|
||||
|
||||
[[introduction-bugs]]
|
||||
== Filing Bug Reports
|
||||
|
||||
Issues with and bug reports on the {apiname} Specification and the API
|
||||
Registry can: be filed in the Khronos Vulkan Github repository, located at
|
||||
URL
|
||||
|
||||
http://github.com/KhronosGroup/Vulkan-Docs
|
||||
|
||||
Please tag issues with appropriate labels, such as ``Specification'',
|
||||
``Ref Pages'' or ``Registry'', to help us triage and assign them
|
||||
appropriately.
|
||||
|
||||
|
||||
[[introduction-terminology]]
|
||||
== Terminology
|
||||
|
||||
The key words *must*, *must not*, *required*, *shall*, *shall not*,
|
||||
*should*, *should not*, *recommend*, *may*, and *optional* in this document
|
||||
are to be interpreted as described in RFC 2119:
|
||||
|
||||
http://www.ietf.org/rfc/rfc2119.txt
|
||||
|
||||
*must*:: This word, or the terms *required* or *shall*, mean that the
|
||||
definition is an absolute requirement of the specification.
|
||||
|
||||
*must not*:: This phrase, or the phrase *shall not*, means that the
|
||||
definition is an absolute prohibition of the specification.
|
||||
|
||||
*should*:: This word, or the adjective *recommended*, means that there may
|
||||
exist valid reasons in particular circumstances to ignore a particular item,
|
||||
but the full implications must be understood and carefully weighed before
|
||||
choosing a different course.
|
||||
|
||||
*should not*:: This phrase, or the phrase *not recommended*, means that
|
||||
there may exist valid reasons in particular circumstances when the
|
||||
particular behavior is acceptable or even useful, but the full implications
|
||||
should be understood and the case carefully weighed before implementing any
|
||||
behavior described with this label.
|
||||
|
||||
*may*:: This word, or the adjective *optional*, means that an item is truly
|
||||
optional. One vendor may choose to include the item because a particular
|
||||
marketplace requires it or because the vendor feels that it enhances the
|
||||
product while another vendor may omit the same item. An implementation which
|
||||
does not include a particular option must be prepared to interoperate with
|
||||
another implementation which does include the option, though perhaps with
|
||||
reduced functionality. In the same vein an implementation which does include
|
||||
a particular option must be prepared to interoperate with another
|
||||
implementation which does not include the option (except, of course, for the
|
||||
feature the option provides).
|
||||
|
||||
The additional terms *can* and *cannot* are to be interpreted as follows:
|
||||
|
||||
*can*:: This word means that the particular behavior described is a valid
|
||||
choice for an application, and is never used to refer to implementation
|
||||
behavior.
|
||||
|
||||
*cannot*:: This word means that the particular behavior described is not
|
||||
achievable by an application. For example, an entry point does not exist, or
|
||||
shader code is not capable of expressing an operation.
|
||||
|
||||
[NOTE]
|
||||
.Note
|
||||
==================
|
||||
There is an important distinction between *cannot* and *must not*, as used
|
||||
in this Specification. *Cannot* means something the application literally is
|
||||
unable to express or accomplish through the API, while *must not* means
|
||||
something that the application is capable of expressing through the API, but
|
||||
that the consequences of doing so are undefined and potentially
|
||||
unrecoverable for the implementation.
|
||||
==================
|
||||
|
||||
ifdef::editing-notes[]
|
||||
[NOTE]
|
||||
.editing-note
|
||||
====
|
||||
TODO (Jon) - We might need to augment the RFC 2119 definition of *must not*
|
||||
to include some of the previous note, since at present it is defined solely
|
||||
in terms of implementation behavior. See Gitlab issue #9.
|
||||
====
|
||||
endif::editing-notes[]
|
||||
|
||||
|
||||
[[introduction-normative]]
|
||||
== Normative References
|
||||
|
||||
Normative references are references to external documents or resources to
|
||||
which implementers of {apiname} must: comply.
|
||||
|
||||
[[IEEE 754]]:: _IEEE Standard for Floating-Point Arithmetic_,
|
||||
IEEE Std 754-2008,
|
||||
http://dx.doi.org/10.1109/IEEESTD.2008.4610935,
|
||||
August, 2008.
|
||||
|
||||
[[Khronos Data Format Specification]]:: A. Garrard, _Khronos Data Format
|
||||
Specification, version 1.1_,
|
||||
https://www.khronos.org/registry/dataformat/specs/1.1/dataformat.1.1.html,
|
||||
February 16, 2015.
|
||||
|
||||
[[Khronos SPIR-V Extended Instructions for GLSL Specification]]:: J.
|
||||
Kessenich, _SPIR-V Extended Instructions for GLSL, Version 1.00_,
|
||||
https://www.khronos.org/registry/spir-v/,
|
||||
February 10, 2016.
|
||||
|
||||
[[Khronos SPIR-V Specification]]:: J. Kessenich and B. Ouriel, _The Khronos
|
||||
SPIR-V Specification, Version 1.00_,
|
||||
https://www.khronos.org/registry/spir-v/,
|
||||
February 10, 2016.
|
||||
|
|
@ -0,0 +1,768 @@
|
|||
// Copyright (c) 2015-2016 The Khronos Group Inc.
|
||||
// Copyright notice at https://www.khronos.org/registry/speccopyright.html
|
||||
|
||||
[[memory]]
|
||||
= Memory Allocation
|
||||
|
||||
{apiname} memory is broken up into two categories, _host memory_ and
|
||||
_device memory_.
|
||||
|
||||
|
||||
[[memory-host]]
|
||||
== Host Memory
|
||||
|
||||
Host memory is memory needed by the {apiname} implementation for
|
||||
non-device-visible storage. This storage may: be used for e.g. internal
|
||||
software structures.
|
||||
|
||||
[[memory-allocation]]
|
||||
{apiname} provides applications the opportunity to perform host memory
|
||||
allocations on behalf of the {apiname} implementation. If this feature is
|
||||
not used, the implementation will perform its own memory allocations. Since
|
||||
most memory allocations are off the critical path, this is not meant as a
|
||||
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.
|
||||
|
||||
Allocators are provided by the application as a pointer to a
|
||||
sname:VkAllocationCallbacks structure:
|
||||
|
||||
include::../structs/VkAllocationCallbacks.txt[]
|
||||
|
||||
* pname:pUserData is a value to be interpreted by the implementation of
|
||||
the callbacks. When any of the callbacks in sname:VkAllocationCallbacks
|
||||
are called, the {apiname} implementation will pass this value as the
|
||||
first parameter to the callback. This value can: vary each time an
|
||||
allocator is passed into a command, even when the same object takes an
|
||||
allocator in multiple commands.
|
||||
* pname:pfnAllocation is a pointer to an application-defined memory
|
||||
allocation function of type tlink:PFN_vkAllocationFunction.
|
||||
* pname:pfnReallocation is a pointer to an application-defined memory
|
||||
reallocation function of type tlink:PFN_vkReallocationFunction.
|
||||
* pname:pfnFree is a pointer to an application-defined memory free
|
||||
function of type tlink:PFN_vkFreeFunction.
|
||||
* pname:pfnInternalAllocation is a pointer to an application-defined
|
||||
function that is called by the implementation when the implementation
|
||||
makes internal allocations, and it is of type
|
||||
tlink:PFN_vkInternalAllocationNotification.
|
||||
* pname:pfnInternalFree is a pointer to an application-defined function
|
||||
that is called by the implementation when the implementation frees
|
||||
internal allocations, and it is of type
|
||||
tlink:PFN_vkInternalFreeNotification.
|
||||
|
||||
include::../validity/structs/VkAllocationCallbacks.txt[]
|
||||
|
||||
An allocator indicates an error condition by returning `NULL` from
|
||||
pname:pfnAllocation or pname:pfnReallocation. If this occurs, the
|
||||
implementation should: treat it as a run time error and should: report
|
||||
ename:VK_ERROR_OUT_OF_HOST_MEMORY at the appropriate time for the
|
||||
command in which the condition was detected, as described in
|
||||
<<fundamentals-returncodes>>.
|
||||
|
||||
The type of pname:pfnAllocation is:
|
||||
|
||||
include::../funcpointers/PFN_vkAllocationFunction.txt[]
|
||||
|
||||
* pname:pUserData is the value specified for
|
||||
slink:VkAllocationCallbacks.pUserData in the allocator specified by the
|
||||
application.
|
||||
* pname:size is the size in bytes of the requested allocation.
|
||||
* pname:alignment is the requested alignment of the allocation in bytes
|
||||
and must: be a power of two.
|
||||
* pname:allocationScope is a elink:VkSystemAllocationScope value
|
||||
specifying the scope of the lifetime of the allocation, as described
|
||||
<<memory-host-allocation-scope,here>>.
|
||||
|
||||
pname:pfnAllocation must: either return `NULL` (in case of allocation
|
||||
failure or if pname:size is zero) or a valid pointer to a memory allocation
|
||||
containing at least pname:size bytes, and with the pointer value being a
|
||||
multiple of pname:alignment.
|
||||
|
||||
The type of pname:pfnReallocation is:
|
||||
|
||||
include::../funcpointers/PFN_vkReallocationFunction.txt[]
|
||||
|
||||
* pname:pUserData is the value specified for
|
||||
slink:VkAllocationCallbacks.pUserData in the allocator specified by the
|
||||
application.
|
||||
* pname:pOriginal must: be either `NULL` or a pointer previously returned
|
||||
by pname:pfnReallocation or pname:pfnAllocation of the same allocator.
|
||||
* pname:size is the size in bytes of the requested allocation.
|
||||
* pname:alignment is the requested alignment of the allocation in bytes
|
||||
and must: be a power of two.
|
||||
* pname:allocationScope is a elink:VkSystemAllocationScope value
|
||||
specifying the scope of the lifetime of the allocation, as described
|
||||
<<memory-host-allocation-scope,here>>.
|
||||
|
||||
pname:pfnReallocation must: alter the size of the allocation
|
||||
pname:pOriginal, either by shrinking or growing it, to accommodate the new
|
||||
pname:size.
|
||||
|
||||
If pname:pOriginal is `NULL`, then pname:pfnReallocation must: behave
|
||||
similarly to tlink:PFN_vkAllocationFunction. If pname:size is zero, then
|
||||
pname:pfnReallocation must: behave similarly to tlink:PFN_vkFreeFunction.
|
||||
The contents of the original allocation from bytes zero to
|
||||
latexmath:[$\min(\textrm{original size, new size})-1$], inclusive, must: be
|
||||
preserved in the new allocation. If the new allocation is larger than the
|
||||
old allocation, then the contents of the additional space are undefined.
|
||||
If pname:pOriginal is non-`NULL`, pname:alignment must: be equal to the
|
||||
originally requested alignment. If satisfying these requirements involves
|
||||
creating a new allocation, then the old allocation must: be freed. If this
|
||||
function fails, it must: return `NULL` and not free the old allocation.
|
||||
|
||||
The type of pname:pfnFree is:
|
||||
|
||||
include::../funcpointers/PFN_vkFreeFunction.txt[]
|
||||
|
||||
* pname:pUserData is the value specified for
|
||||
slink:VkAllocationCallbacks.pUserData in the allocator specified by the
|
||||
application.
|
||||
* pname:pMemory is the allocation to be freed.
|
||||
|
||||
pname:pMemory may: be `NULL`, which the callback must: handle safely. If
|
||||
pname:pMemory is non-`NULL`, it must: be a pointer previously allocated by
|
||||
pname:pfnAllocation or pname:pfnReallocation and must: be freed by the
|
||||
function.
|
||||
|
||||
The type of pname:pfnInternalAllocation is:
|
||||
|
||||
include::../funcpointers/PFN_vkInternalAllocationNotification.txt[]
|
||||
|
||||
* pname:pUserData is the value specified for
|
||||
slink:VkAllocationCallbacks.pUserData in the allocator specified by the
|
||||
application.
|
||||
* pname:size is the requested size of an allocation.
|
||||
* pname:allocationType is the requested type of an allocation.
|
||||
* pname:allocationScope is a elink:VkSystemAllocationScope value
|
||||
specifying the scope of the lifetime of the allocation, as described
|
||||
<<memory-host-allocation-scope,here>>.
|
||||
|
||||
This is a purely informational callback.
|
||||
|
||||
The type of pname:pfnInternalFree is:
|
||||
|
||||
include::../funcpointers/PFN_vkInternalFreeNotification.txt[]
|
||||
|
||||
* pname:pUserData is the value specified for
|
||||
slink:VkAllocationCallbacks.pUserData in the allocator specified by the
|
||||
application.
|
||||
* pname:size is the requested size of an allocation.
|
||||
* pname:allocationType is the requested type of an allocation.
|
||||
* pname:allocationScope is a elink:VkSystemAllocationScope value
|
||||
specifying the scope of the lifetime of the allocation, as described
|
||||
<<memory-host-allocation-scope,here>>.
|
||||
|
||||
[[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:
|
||||
|
||||
include::../enums/VkSystemAllocationScope.txt[]
|
||||
|
||||
* ename:VK_SYSTEM_ALLOCATION_SCOPE_COMMAND - The allocation is scoped to
|
||||
the lifetime of the {apiname} command.
|
||||
* ename:VK_SYSTEM_ALLOCATION_SCOPE_OBJECT - The allocation is scoped to
|
||||
the lifetime of the {apiname} object that is being created or used.
|
||||
* ename:VK_SYSTEM_ALLOCATION_SCOPE_CACHE - The allocation is scoped to the
|
||||
lifetime of a sname:VkPipelineCache object.
|
||||
* ename:VK_SYSTEM_ALLOCATION_SCOPE_DEVICE - The allocation is scoped to
|
||||
the lifetime of the {apiname} device.
|
||||
* ename:VK_SYSTEM_ALLOCATION_SCOPE_INSTANCE - The allocation is scoped to
|
||||
the lifetime of the {apiname} instance.
|
||||
|
||||
Most {apiname} commands operate on a single object, or there is a sole
|
||||
object that is being created or manipulated. When an allocation uses a scope
|
||||
of ename:VK_SYSTEM_ALLOCATION_SCOPE_OBJECT or
|
||||
ename:VK_SYSTEM_ALLOCATION_SCOPE_CACHE, the allocation is scoped to the
|
||||
object being created or manipulated.
|
||||
|
||||
When an implementation requires host memory, it will make callbacks to the
|
||||
application using the most specific allocator and scope available:
|
||||
|
||||
* If an allocation is scoped to the duration of a command, the allocator
|
||||
will use the ename:VK_SYSTEM_ALLOCATION_SCOPE_COMMAND scope. The most
|
||||
specific allocator available is used: if the object being created or
|
||||
manipulated has an allocator, that object's allocator will be used, else
|
||||
if the parent sname:VkDevice has an allocator it will be used, else if
|
||||
the parent sname:VkInstance has an allocator it will be used. Else,
|
||||
* If an allocation is associated with an object of type
|
||||
sname:VkPipelineCache, the allocator will use the
|
||||
ename:VK_SYSTEM_ALLOCATION_SCOPE_CACHE scope. The most specific
|
||||
allocator available is used (pipeline cache, else device, else
|
||||
instance). Else,
|
||||
* If an allocation is scoped to the lifetime of an object, that object is
|
||||
being created or manipulated by the command, and that object's type is
|
||||
not sname:VkDevice or sname:VkInstance, the allocator will use a scope
|
||||
of ename:VK_SYSTEM_ALLOCATION_SCOPE_OBJECT. The most specific allocator
|
||||
available is used (object, else device, else instance). Else,
|
||||
* If an allocation is scoped to the lifetime of a device, the allocator
|
||||
will use scope of ename:VK_SYSTEM_ALLOCATION_SCOPE_DEVICE. The most
|
||||
specific allocator available is used (device, else instance). Else,
|
||||
* If the allocation is scoped to the lifetime of an instance and the
|
||||
instance has an allocator, its allocator will be used with a scope of
|
||||
ename:VK_SYSTEM_ALLOCATION_SCOPE_INSTANCE.
|
||||
* Otherwise an implementation will allocate memory through an alternative
|
||||
mechanism that is unspecified.
|
||||
|
||||
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.
|
||||
|
||||
The application is not expected to handle allocating memory that is intended
|
||||
for execution by the host due to the complexities of differing security
|
||||
implementations across multiple platforms. The implementation will allocate
|
||||
such memory internally and invoke an application provided informational
|
||||
callback when these _internal allocations_ are allocated and freed. Upon
|
||||
allocation of executable memory, pname:pfnInternalAllocation will be called.
|
||||
Upon freeing executable memory, pname:pfnInternalFree will be called. An
|
||||
implementation will only call an informational callback for executable
|
||||
memory allocations and frees.
|
||||
|
||||
The pname:allocationType parameter to the pname:pfnInternalAllocation and
|
||||
pname:pfnInternalFree functions may: be one of the following values:
|
||||
|
||||
include::../enums/VkInternalAllocationType.txt[]
|
||||
|
||||
* ename:VK_INTERNAL_ALLOCATION_TYPE_EXECUTABLE - The allocation is
|
||||
intended for execution by the host.
|
||||
|
||||
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
|
||||
that called the provoking API command. The implementation shouldnot:
|
||||
synchronize calls to any of the callbacks. If synchronization is needed, the
|
||||
callbacks must: provide it themselves. The informational callbacks are
|
||||
subject to the same restrictions as the allocation callbacks.
|
||||
|
||||
If an implementation intends to make calls through an
|
||||
sname:VkAllocationCallbacks structure between the time a ftext:vkCreate*
|
||||
command returns and the time a corresponding ftext:vkDestroy* command
|
||||
begins, that implementation must: save a copy of the allocator before the
|
||||
ftext:vkCreate* command returns. The callback functions and any data
|
||||
structures they rely upon must: remain valid for the lifetime of the object
|
||||
they are associated with.
|
||||
|
||||
If an allocator is provided to a ftext:vkCreate* command, a _compatible_
|
||||
allocator must: be provided to the corresponding ftext:vkDestroy* command.
|
||||
Two sname:VkAllocationCallbacks structures are compatible if memory created
|
||||
with pname:pfnAllocation or pname:pfnReallocation in each can: be freed with
|
||||
pname:pfnReallocation or pname:pfnFree in the other. An allocator mustnot:
|
||||
be provided to a ftext:vkDestroy* command if an allocator was not provided
|
||||
to the corresponding ftext:vkCreate* command.
|
||||
|
||||
If a non-`NULL` allocator is used, the pname:pfnAllocation,
|
||||
pname:pfnReallocation and pname:pfnFree members must: be non-`NULL` and
|
||||
point to valid implementations of the callbacks. An application can: choose
|
||||
to not provide informational callbacks by setting both
|
||||
pname:pfnInternalAllocation and pname:pfnInternalFree to `NULL`.
|
||||
pname:pfnInternalAllocation and pname:pfnInternalFree must: either both be
|
||||
`NULL` or both be non-`NULL`.
|
||||
|
||||
If pname:pfnAllocation or pname:pfnReallocation fail, the implementation
|
||||
may: fail object creation and/or generate an
|
||||
ename:VK_ERROR_OUT_OF_HOST_MEMORY error, as appropriate.
|
||||
|
||||
The following sets of rules define when an implementation is permitted to
|
||||
call the allocator callbacks.
|
||||
|
||||
pname:pfnAllocation or pname:pfnReallocation may: be called in the following
|
||||
situations:
|
||||
|
||||
* Host memory scoped to the lifetime of a sname:VkDevice or
|
||||
sname:VkInstance may: be allocated from any API command.
|
||||
* Host memory scoped to the lifetime of a sname:VkPipelineCache may: only
|
||||
be allocated from:
|
||||
** fname:vkCreatePipelineCache
|
||||
** fname:vkMergePipelineCaches for pname:dstCache
|
||||
** fname:vkCreateGraphicsPipelines for pname:pPipelineCache
|
||||
** fname:vkCreateComputePipelines for pname:pPipelineCache
|
||||
* Host memory scoped to the lifetime of a sname:VkDescriptorPool may: only
|
||||
be allocated from:
|
||||
** any command that takes the pool as a direct argument
|
||||
** fname:vkAllocateDescriptorSets for the pname:descriptorPool member of
|
||||
its pname:pAllocateInfo parameter
|
||||
** fname:vkCreateDescriptorPool
|
||||
* Host memory scoped to the lifetime of a sname:VkCommandPool may: only be
|
||||
allocated from:
|
||||
** any command that takes the pool as a direct argument
|
||||
** fname:vkCreateCommandPool
|
||||
** fname:vkAllocateCommandBuffers for the pname:commandPool member of its
|
||||
pname:pAllocateInfo parameter
|
||||
** any ftext:vkCmd* command whose pname:commandBuffer was created from
|
||||
that sname:VkCommandPool
|
||||
* Host memory scoped to the lifetime of any other object may: only be
|
||||
allocated in that object's ftext:vkCreate* command.
|
||||
|
||||
pname:pfnFree may: be called in the following situations:
|
||||
|
||||
* Host memory scoped to the lifetime of a sname:VkDevice or
|
||||
sname:VkInstance may: be freed from any API command.
|
||||
* Host memory scoped to the lifetime of a sname:VkPipelineCache may: be
|
||||
freed from fname:vkDestroyPipelineCache.
|
||||
* Host memory scoped to the lifetime of a sname:VkDescriptorPool may: be
|
||||
freed from
|
||||
** any command that takes the pool as a direct argument
|
||||
* Host memory scoped to the lifetime of a sname:VkCommandPool may: be
|
||||
freed from:
|
||||
** any command that takes the pool as a direct argument
|
||||
** fname:vkResetCommandBuffer whose pname:commandBuffer was created from
|
||||
that sname:VkCommandPool
|
||||
* Host memory scoped to the lifetime of any other object may: be freed in
|
||||
that object's ftext:vkDestroy* command.
|
||||
* Any command that allocates host memory may: also free host memory of the
|
||||
same scope.
|
||||
|
||||
|
||||
[[memory-device]]
|
||||
== Device Memory
|
||||
|
||||
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:
|
||||
|
||||
include::../protos/vkGetPhysicalDeviceMemoryProperties.txt[]
|
||||
|
||||
* pname:physicalDevice is the handle to the device to query.
|
||||
* pname:pMemoryProperties points to an instance of
|
||||
sname:VkPhysicalDeviceMemoryProperties structure in which the properties
|
||||
are returned.
|
||||
|
||||
include::../validity/protos/vkGetPhysicalDeviceMemoryProperties.txt[]
|
||||
|
||||
The definition of sname:VkPhysicalDeviceMemoryProperties is:
|
||||
|
||||
include::../structs/VkPhysicalDeviceMemoryProperties.txt[]
|
||||
|
||||
ifdef::editing-notes[]
|
||||
[NOTE]
|
||||
.editing-note
|
||||
====
|
||||
TODO (Jon) - Need to restructure description like other structs.
|
||||
====
|
||||
endif::editing-notes[]
|
||||
|
||||
include::../validity/structs/VkPhysicalDeviceMemoryProperties.txt[]
|
||||
|
||||
The sname:VkPhysicalDeviceMemoryProperties structure describes a number of
|
||||
_memory heaps_ as well as a number of _memory types_ that can: be used to
|
||||
access memory allocated in those heaps. Each heap describes a memory
|
||||
resource of a particular size, and each memory type describes a set of
|
||||
memory properties (e.g. host cached vs uncached) that can: be used with a
|
||||
given memory heap. Allocations using a particular memory type will consume
|
||||
resources from the heap indicated by that memory type's heap index. More
|
||||
than one memory type may: share each heap, and the heaps and memory types
|
||||
provide a mechanism to advertise an accurate size of the physical memory
|
||||
resources while allowing the memory to be used with a variety of different
|
||||
properties.
|
||||
|
||||
The number of memory heaps is given by pname:memoryHeapCount and is less
|
||||
than or equal to ename:VK_MAX_MEMORY_HEAPS. Each heap is described by an
|
||||
element of the pname:memoryHeaps array, as a sname:VkMemoryHeap structure.
|
||||
The number of memory types available across all memory heaps is given by
|
||||
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 definition of sname:VkMemoryHeap is:
|
||||
|
||||
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[]
|
||||
|
||||
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. If there is only one heap, that heap must: be marked as
|
||||
ename:VK_MEMORY_HEAP_DEVICE_LOCAL_BIT. If there are multiple heaps that all
|
||||
have similar performance characteristics, they may: all be marked as
|
||||
ename:VK_MEMORY_HEAP_DEVICE_LOCAL_BIT, but at least one will be device
|
||||
local.
|
||||
|
||||
The definition of sname:VkMemoryType is:
|
||||
|
||||
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 mustnot: 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:
|
||||
|
||||
* 0
|
||||
* ename:VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT
|
||||
* ename:VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT | ename:VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT | ename:VK_MEMORY_PROPERTY_HOST_COHERENT_BIT
|
||||
* ename:VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT | ename:VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT | ename:VK_MEMORY_PROPERTY_HOST_CACHED_BIT
|
||||
* ename:VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT | ename:VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT | ename:VK_MEMORY_PROPERTY_HOST_CACHED_BIT | ename:VK_MEMORY_PROPERTY_HOST_COHERENT_BIT
|
||||
* ename:VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT | ename:VK_MEMORY_PROPERTY_HOST_COHERENT_BIT
|
||||
* ename:VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT | ename:VK_MEMORY_PROPERTY_HOST_CACHED_BIT
|
||||
* ename:VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT | ename:VK_MEMORY_PROPERTY_HOST_CACHED_BIT | ename:VK_MEMORY_PROPERTY_HOST_COHERENT_BIT
|
||||
* ename:VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT | ename:VK_MEMORY_PROPERTY_LAZILY_ALLOCATED_BIT
|
||||
|
||||
It is guaranteed that there is at least one memory type that has its
|
||||
pname:propertyFlags with the ename:VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT bit
|
||||
set and the ename:VK_MEMORY_PROPERTY_HOST_COHERENT_BIT bit set.
|
||||
|
||||
The memory types are sorted according to a partial order which serves to aid
|
||||
in easily selecting an appropriate memory type. Given two memory types X and
|
||||
Y, the partial order defines latexmath:[$X \leq Y$] if:
|
||||
|
||||
* the memory property bits set for X are a subset of the memory property
|
||||
bits set for Y. Or,
|
||||
* the memory property bits set for X are the same as the memory property
|
||||
bits set for Y, and X uses a memory heap with greater or equal
|
||||
performance (as determined in an implementation-specific manner).
|
||||
|
||||
Memory types are ordered in the list such that X is assigned a lesser
|
||||
pname:memoryTypeIndex than Y if latexmath:[$X \leq Y$] according to the
|
||||
partial order. Note that the list of all allowed memory property flag
|
||||
combinations above satisfies this partial order, but other orders would as
|
||||
well. The goal of this ordering is to enable applications to use a simple
|
||||
search loop in selecting the proper memory type, along the lines of:
|
||||
|
||||
[source,{basebackend@docbook:c++:cpp}]
|
||||
---------------------------------------------------
|
||||
// Searching for the best match for "properties"
|
||||
for (i = 0; i < memoryTypeCount; ++i)
|
||||
if ((memoryTypes[i].propertyFlags & properties) == properties)
|
||||
return i;
|
||||
---------------------------------------------------
|
||||
|
||||
This loop will find the first entry that has all bits requested in
|
||||
code:properties set. If there is no exact match, it will find a closest
|
||||
match (i.e. a memory type with the fewest additional bits set), which has
|
||||
some additional bits set but which are not detrimental to the behaviors
|
||||
requested by code:properties. If there are multiple heaps with the same
|
||||
properties, it will choose the most performant memory.
|
||||
|
||||
A {apiname} 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:
|
||||
|
||||
include::../protos/vkAllocateMemory.txt[]
|
||||
|
||||
* pname:device is the logical device that owns the memory.
|
||||
* pname:pAllocateInfo is a pointer to a structure of type
|
||||
slink:VkMemoryAllocateInfo, which contains parameters of the allocation.
|
||||
A successful returned allocation must: use the requested parameters--no
|
||||
substitution is permitted by the implementation.
|
||||
* pname:pAllocator controls host memory allocation as described in
|
||||
the <<memory-allocation, Memory Allocation>> chapter.
|
||||
* pname:pMemory is a pointer to a sname:VkDeviceMemory structure in which
|
||||
information about the allocated memory is returned.
|
||||
|
||||
include::../validity/protos/vkAllocateMemory.txt[]
|
||||
|
||||
sname:VkMemoryAllocateInfo 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
|
||||
for buffers, the device memory returned through this mechanism would be
|
||||
128-byte aligned. This ensures that applications can: correctly suballocate
|
||||
objects of different types (with potentially different alignment
|
||||
requirements) in the same memory object.
|
||||
|
||||
When memory is allocated, its contents are undefined.
|
||||
|
||||
There is an implementation-dependent maximum number of memory allocations
|
||||
which can: be simultaneously created on a device. This is specified by the
|
||||
<<features-limits-maxMemoryAllocationCount,pname:maxMemoryAllocationCount>>
|
||||
member of the sname:VkPhysicalDeviceLimits structure. If
|
||||
pname:maxMemoryAllocationCount is exceeded, fname:vkAllocateMemory will
|
||||
return ename:VK_ERROR_TOO_MANY_OBJECTS.
|
||||
|
||||
[NOTE]
|
||||
.Note
|
||||
====
|
||||
Some platforms may: have a limit on the maximum size of a single allocation.
|
||||
For example, certain systems may: fail to create allocations with a size
|
||||
greater than or equal to 4GB. Such a limit is implementation-dependent, and
|
||||
if such a failure occurs then the error ename:VK_ERROR_OUT_OF_DEVICE_MEMORY
|
||||
should: be returned.
|
||||
====
|
||||
|
||||
A memory object is freed by calling:
|
||||
|
||||
include::../protos/vkFreeMemory.txt[]
|
||||
|
||||
* pname:device is the logical device that owns the memory.
|
||||
* pname:memory is the sname:VkDeviceMemory object to be freed.
|
||||
* 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
|
||||
buffers at the time the memory object is freed, but any further use of them
|
||||
(on host or device) for anything other than destroying those objects will
|
||||
result in undefined behavior. If there are still any bound images or
|
||||
buffers, the memory maynot: be immediately released by the implementation,
|
||||
but must: be released by the time all bound images and buffers have been
|
||||
destroyed. Once memory is released, it is returned to the heap from which it
|
||||
was allocated.
|
||||
|
||||
How memory objects are bound to Images and Buffers is described in detail in
|
||||
the <<resources-association, Resource Memory Association>> section.
|
||||
|
||||
|
||||
[[memory-device-hostaccess]]
|
||||
=== Host Access to Device Memory Objects
|
||||
|
||||
Memory objects created with fname:vkAllocateMemory are not directly host
|
||||
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:
|
||||
|
||||
include::../protos/vkMapMemory.txt[]
|
||||
|
||||
* pname:device is the logical device that owns the memory.
|
||||
* pname:memory is the sname:VkDeviceMemory object to be mapped.
|
||||
* pname:offset is a zero-based byte offset from the beginning of the
|
||||
memory object.
|
||||
* 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: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.
|
||||
|
||||
ifdef::editing-notes[]
|
||||
[NOTE]
|
||||
.editing-note
|
||||
====
|
||||
TODO (Tobias) - There's a circular section reference in this next section.
|
||||
The information is all covered by both places, but it seems a bit weird to
|
||||
have them reference each other. Not sure how to resolve it.
|
||||
====
|
||||
endif::editing-notes[]
|
||||
|
||||
[[memory-device-hostaccess-hazards]]
|
||||
fname:vkMapMemory does not check whether the device memory is currently in
|
||||
use before returning the host-accessible pointer. The application
|
||||
must: guarantee that any previously submitted command that writes to this
|
||||
sub-range has completed before the host reads from or writes to that
|
||||
sub-range, and that any previously submitted command that reads from that
|
||||
sub-range has completed before the host writes to that region (see
|
||||
<<synchronization-fences-devicewrites, here>>
|
||||
for details on fulfilling such a guarantee). If the device memory was
|
||||
allocated without the ename:VK_MEMORY_PROPERTY_HOST_COHERENT_BIT set,
|
||||
these guarantees must: be made for an extended sub-range: the application
|
||||
must: round down the start of the sub-range to the previous multiple of
|
||||
sname:VkPhysicalDeviceLimits::pname:nonCoherentAtomSize, and round the end
|
||||
of the range up to the nearest multiple of
|
||||
sname:VkPhysicalDeviceLimits::pname:nonCoherentAtomSize.
|
||||
|
||||
While a range of device memory is mapped for host access, the application
|
||||
is responsible for synchronizing both device and host access to that memory
|
||||
range.
|
||||
|
||||
[NOTE]
|
||||
.Note
|
||||
====
|
||||
It is important for the application developer to become meticulously
|
||||
familiar with all of the mechanisms described in the chapter on
|
||||
<<synchronization, Synchronization and Cache Control>> as they are crucial
|
||||
to maintaining memory access ordering.
|
||||
====
|
||||
|
||||
Host-visible memory types that advertise the
|
||||
ename:VK_MEMORY_PROPERTY_HOST_COHERENT_BIT property still require
|
||||
<<synchronization-pipeline-barriers,memory barriers>> between host and
|
||||
device in order to be coherent, but do not require additional cache
|
||||
management operations (fname:vkFlushMappedMemoryRanges or
|
||||
fname:vkInvalidateMappedMemoryRanges) to achieve coherency. For host writes
|
||||
to be seen by subsequent command buffer operations, a pipeline barrier from
|
||||
a source of ename:VK_ACCESS_HOST_WRITE_BIT and
|
||||
ename:VK_PIPELINE_STAGE_HOST_BIT to a destination of the relevant device
|
||||
pipeline stages and access types must: be performed. Note that such a
|
||||
barrier is performed
|
||||
<<synchronization-implicit-ordering-hostwrites,implicitly>> upon each
|
||||
command buffer submission, so an explicit barrier is only rarely needed
|
||||
(e.g. if a command buffer waits upon an event signaled by the host, where
|
||||
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>>.
|
||||
|
||||
In order to enable applications to work with non-coherent memory
|
||||
allocations, two entry points are provided. To flush host write caches, an
|
||||
application must: use fname:vkFlushMappedMemoryRanges, while
|
||||
fname:vkInvalidateMappedMemoryRanges allows invalidating host input caches
|
||||
so that device writes become visible to the host.
|
||||
fname:vkFlushMappedMemoryRanges 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. Similarly,
|
||||
fname:vkInvalidateMappedMemoryRanges 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.
|
||||
|
||||
include::../protos/vkFlushMappedMemoryRanges.txt[]
|
||||
|
||||
* pname:device is the logical device that owns the memory ranges.
|
||||
* pname:memoryRangeCount is the length of the pname:pMemoryRanges array.
|
||||
* pname:pMemoryRanges is a pointer to an array of
|
||||
slink:VkMappedMemoryRange structures describing the memory ranges to
|
||||
flush.
|
||||
|
||||
include::../validity/protos/vkFlushMappedMemoryRanges.txt[]
|
||||
|
||||
include::../protos/vkInvalidateMappedMemoryRanges.txt[]
|
||||
|
||||
* pname:device is the logical device that owns the memory ranges.
|
||||
* pname:memoryRangeCount is the length of the pname:pMemoryRanges array.
|
||||
* pname:pMemoryRanges is a pointer to an array of
|
||||
slink:VkMappedMemoryRange structures describing the memory ranges to
|
||||
invalidate.
|
||||
|
||||
include::../validity/protos/vkInvalidateMappedMemoryRanges.txt[]
|
||||
|
||||
sname:VkMappedMemoryRange is defined as:
|
||||
|
||||
include::../structs/VkMappedMemoryRange.txt[]
|
||||
|
||||
* pname:sType is the type of this structure.
|
||||
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
|
||||
* pname:memory is the memory object to which this range belongs.
|
||||
* pname:offset is the zero-based byte offset from the beginning of the
|
||||
memory object.
|
||||
* pname:size is either the size of range, or ename:VK_WHOLE_SIZE to affect
|
||||
the range from pname:offset to the end of the current mapping of the
|
||||
allocation.
|
||||
|
||||
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.
|
||||
====
|
||||
|
||||
Once host access to a memory object is no longer needed by the application,
|
||||
it can: be unmapped by calling :
|
||||
|
||||
include::../protos/vkUnmapMemory.txt[]
|
||||
|
||||
* pname:device is the logical device that owns the memory.
|
||||
* pname:memory is the memory object to be unmapped.
|
||||
|
||||
include::../validity/protos/vkUnmapMemory.txt[]
|
||||
|
||||
|
||||
[[memory-device-lazy_allocation]]
|
||||
=== Lazily Allocated Memory
|
||||
|
||||
If the memory object is allocated from a heap with the
|
||||
ename:VK_MEMORY_PROPERTY_LAZILY_ALLOCATED_BIT bit set, that object's backing
|
||||
memory may: be provided by the implementation lazily. The actual committed
|
||||
size of the memory may: initially be as small as zero (or as large as the
|
||||
requested size), and monotonically increases as additional memory is
|
||||
needed.
|
||||
|
||||
A memory type with this flag set is only allowed to be bound to a
|
||||
sname:VkImage whose usage flags include
|
||||
ename:VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT.
|
||||
|
||||
[NOTE]
|
||||
.Note
|
||||
====
|
||||
Using lazily allocated memory objects for framebuffer attachments that
|
||||
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:
|
||||
|
||||
include::../protos/vkGetDeviceMemoryCommitment.txt[]
|
||||
|
||||
* pname:device is the logical device that owns the memory.
|
||||
* pname:memory is the memory object being queried.
|
||||
* pname:pCommittedMemoryInBytes is a pointer to a basetype:VkDeviceSize
|
||||
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.
|
||||
|
||||
The implementation guarantees to allocate any committed memory from the
|
||||
heapIndex indicated by the memory type that the memory object was created
|
||||
with.
|
||||
|
||||
|
|
@ -0,0 +1,863 @@
|
|||
// Copyright (c) 2015-2016 The Khronos Group Inc.
|
||||
// Copyright notice at https://www.khronos.org/registry/speccopyright.html
|
||||
|
||||
[[pipelines]]
|
||||
= Pipelines
|
||||
|
||||
The following <<pipelines-block-diagram,figure>> shows a block diagram of
|
||||
the {apiname} pipelines. Some {apiname} commands specify geometric objects
|
||||
to be drawn or computational work to be performed, while others specify
|
||||
state controlling how objects are handled by the various pipeline stages, or
|
||||
control data transfer between memory organized as images and buffers.
|
||||
Commands are effectively sent through a processing pipeline, either a
|
||||
_graphics pipeline_ or a _compute pipeline_.
|
||||
|
||||
The first stage of the <<pipelines-graphics,graphics pipeline>>
|
||||
(<<drawing,Input Assembler>>) assembles vertices to form
|
||||
geometric primitives such as points, lines, and triangles, based on a
|
||||
requested primitive topology. In the next stage (<<shaders-vertex,Vertex
|
||||
Shader>>) vertices can: be transformed, computing positions and attributes
|
||||
for each vertex. If <<tessellation,tessellation>> and/or
|
||||
<<geometry,geometry>> shaders are supported, they can: then generate
|
||||
multiple primitives from a single input primitive, possibly changing the
|
||||
primitive topology or generating additional attribute data in the process.
|
||||
|
||||
The final resulting primitives are <<vertexpostproc-clipping,clipped>> to a
|
||||
clip volume in preparation for the next stage, <<primsrast,Rasterization>>.
|
||||
The rasterizer produces a series of framebuffer addresses and values using a
|
||||
two-dimensional description of a point, line segment, or triangle. Each
|
||||
_fragment_ so produced is fed to the next stage (<<shaders-fragment,Fragment
|
||||
Shader>>) that performs operations on individual fragments before they
|
||||
finally alter the framebuffer. These operations include conditional updates
|
||||
into the framebuffer based on incoming and previously stored depth values
|
||||
(to effect <<fragops-depth,depth buffering>>),
|
||||
<<framebuffer-blending,blending>> of incoming fragment colors with stored
|
||||
colors, as well as <<framebuffer-blendoperations,masking>>,
|
||||
<<fragops-stencil,stenciling>>, and other <<framebuffer-logicop,logical
|
||||
operations>> on fragment values.
|
||||
|
||||
Framebuffer operations read and write the color and depth/stencil
|
||||
attachments of the framebuffer for a given subpass of a
|
||||
<<renderpass,render pass instance>>. The attachments can: be used as input
|
||||
attachments in the fragment shader in a later subpass of the same render
|
||||
pass.
|
||||
|
||||
The <<pipelines-compute,compute pipeline>> is a separate pipeline from the
|
||||
graphics pipeline, which operates on one-, two-, or three-dimensional
|
||||
_work groups_ which can: read from and write to buffer and image memory.
|
||||
|
||||
This ordering is meant only as a tool for describing {apiname}, not as a
|
||||
strict rule of how {apiname} is implemented, and we present it only as a
|
||||
means to organize the various operations of the pipelines.
|
||||
|
||||
[[pipelines-block-diagram]]
|
||||
image::images/pipeline.{svgpdf}[title="Block diagram of the Vulkan pipeline",width="{svgpdf@pdf:500:800}",align="center"]
|
||||
|
||||
Each pipeline is controlled by a monolithic object created from a
|
||||
description of all of the shader stages and any relevant fixed-function
|
||||
stages. <<interfaces,Linking>> the whole pipeline together allows
|
||||
the optimization of shaders based on their input/outputs and eliminates
|
||||
expensive draw time state validation.
|
||||
|
||||
A pipeline object is bound to the device state in command buffers. Any
|
||||
pipeline object state that is marked as dynamic is not applied to the device
|
||||
state when the pipeline is bound. Dynamic state not set by binding the
|
||||
pipeline object can: be modified at any time and persists for the lifetime
|
||||
of the command buffer, or until modified by another dynamic state command or
|
||||
another pipeline bind. No state, including dynamic state, is inherited from
|
||||
one command buffer to another. Only dynamic state that is required: for the
|
||||
operations performed in the command buffer needs to be set. For example, if
|
||||
blending is disabled by the pipeline state then the dynamic color blend
|
||||
constants do not need to be specified in the command buffer, even if this
|
||||
state is marked as dynamic in the pipeline state object. If a new pipeline
|
||||
object is bound with state not marked as dynamic after a previous pipeline
|
||||
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.
|
||||
|
||||
|
||||
[[pipelines-compute]]
|
||||
== Compute Pipelines
|
||||
|
||||
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
|
||||
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:
|
||||
|
||||
include::../protos/vkCreateComputePipelines.txt[]
|
||||
|
||||
* pname:device is the logical device that creates the compute pipelines.
|
||||
* pname:pipelineCache is either sname: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.
|
||||
* pname:createInfoCount is the length of the pname:pCreateInfos and
|
||||
pname:Pipelines arrays.
|
||||
* pname:pCreateInfos is an array of sname:VkComputePipelineCreateInfo
|
||||
structures.
|
||||
* pname:pAllocator controls host memory allocation as described in the
|
||||
<<memory-allocation, Memory Allocation>> chapter.
|
||||
* pname:pPipelines is a pointer to an array in which the resulting compute
|
||||
pipeline objects are returned.
|
||||
+
|
||||
--
|
||||
ifdef::editing-notes[]
|
||||
[NOTE]
|
||||
.editing-note
|
||||
====
|
||||
TODO (Jon) - Should we say something like ``the i'th element of the
|
||||
pname:pPipelines array is created based on the corresponding element of the
|
||||
pname:pCreateInfos array''? Also for flink:vkCreateGraphicsPipelines below.
|
||||
====
|
||||
endif::editing-notes[]
|
||||
--
|
||||
|
||||
include::../validity/protos/vkCreateComputePipelines.txt[]
|
||||
|
||||
The definition of sname:VkComputePipelineCreateInfo is:
|
||||
|
||||
include::../structs/VkComputePipelineCreateInfo.txt[]
|
||||
|
||||
* pname:sType is the type of this structure.
|
||||
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
|
||||
* pname:flags provides options for pipeline creation, and is of type
|
||||
elink:VkPipelineCreateFlagBits.
|
||||
* pname:stage is a slink:VkPipelineShaderStageCreateInfo describing the
|
||||
compute shader.
|
||||
* pname:layout is the description of binding locations used by both the
|
||||
pipeline and descriptor sets used with the pipeline.
|
||||
* pname:basePipelineHandle is a pipeline to derive from
|
||||
* 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>>.
|
||||
|
||||
The parameter pname:stage member of type
|
||||
sname:VkPipelineShaderStageCreateInfo is:
|
||||
|
||||
include::../structs/VkPipelineShaderStageCreateInfo.txt[]
|
||||
|
||||
The members of the sname:VkPipelineShaderStageCreateInfo structure are as
|
||||
follows:
|
||||
|
||||
* 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:module is a sname:VkShaderModule object that contains the
|
||||
shader for this stage.
|
||||
* pname:pName is a null-terminated UTF-8 string specifying the entry point
|
||||
name of the shader for this stage.
|
||||
* pname:pSpecializationInfo is a pointer to slink:VkSpecializationInfo, as
|
||||
described in <<pipelines-specialization-constants,Specialization
|
||||
Constants>>, and can: be `NULL`.
|
||||
|
||||
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:
|
||||
|
||||
include::../protos/vkCreateGraphicsPipelines.txt[]
|
||||
|
||||
* pname:device is the logical device that creates the graphics pipelines.
|
||||
* pname:pipelineCache is either sname: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.
|
||||
* pname:createInfoCount is the length of the pname:pCreateInfos and
|
||||
pname:Pipelines arrays.
|
||||
* pname:pCreateInfos is an array of sname:VkGraphicsPipelineCreateInfo
|
||||
structures.
|
||||
* pname:pAllocator controls host memory allocation as described in the
|
||||
<<memory-allocation, Memory Allocation>> chapter.
|
||||
* 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
|
||||
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. The definition of sname:VkGraphicsPipelineCreateInfo is:
|
||||
|
||||
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
|
||||
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
|
||||
slink:VkPipelineShaderStageCreateInfo describing the set of the shader
|
||||
stages to be included in the graphics pipeline.
|
||||
* pname:pVertexInputState is a pointer to an instance of the
|
||||
slink:VkPipelineVertexInputStateCreateInfo structure.
|
||||
* pname:pInputAssemblyState is a pointer to an instance of the
|
||||
slink:VkPipelineInputAssemblyStateCreateInfo structure which determines
|
||||
input assembly behavior, as described in <<drawing, Drawing Commands>>.
|
||||
* pname:pTessellationState is a pointer to an instance of the
|
||||
slink:VkPipelineTessellationStateCreateInfo structure, or `NULL` if the
|
||||
pipeline does not include a tessellation control shader stage and
|
||||
tessellation evaluation shader stage.
|
||||
* pname:pViewportState is a pointer to an instance of the
|
||||
slink:VkPipelineViewportStateCreateInfo structure, or `NULL` if the
|
||||
pipeline has rasterization disabled.
|
||||
* pname:pRasterState is a pointer to an instance of the
|
||||
slink:VkPipelineRasterizationStateCreateInfo structure.
|
||||
* pname:pMultisampleState is a pointer to an instance of the
|
||||
slink:VkPipelineMultisampleStateCreateInfo, or `NULL` if the pipeline
|
||||
has rasterization disabled.
|
||||
* pname:pDepthStencilState is a pointer to an instance of the
|
||||
slink:VkPipelineDepthStencilStateCreateInfo structure, or `NULL` if the
|
||||
pipeline has rasterization disabled or if the subpass of the render pass
|
||||
the pipeline is created against does not use a depth/stencil attachment.
|
||||
* pname:pColorBlendState is a pointer to an instance of the
|
||||
slink:VkPipelineColorBlendStateCreateInfo structure, or `NULL` if the
|
||||
pipeline has rasterization disabled or if the subpass of the render pass
|
||||
the pipeline is created against does not use any color attachments.
|
||||
* pname:pDynamicState is a pointer to
|
||||
slink:VkPipelineDynamicStateCreateInfo and is used to indicate which
|
||||
properties of the pipeline state object are dynamic and can: be changed
|
||||
independently of the pipeline state. This can: be `NULL`, which means no
|
||||
state in the pipeline is considered dynamic.
|
||||
* pname:layout is the description of binding locations used by both the
|
||||
pipeline and descriptor sets used with the pipeline.
|
||||
* pname:renderPass is a handle to a render pass object describing the
|
||||
environment in which the pipeline will be used; the pipeline can: be
|
||||
used with an instance of any render pass compatible with the one
|
||||
provided. See <<renderpass-compatibility,Render Pass Compatibility>> for
|
||||
more information.
|
||||
* pname:subpass is the index of the subpass in pname:renderPass where this
|
||||
pipeline will be used.
|
||||
* pname:basePipelineHandle is a pipeline to derive from.
|
||||
* 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>>.
|
||||
|
||||
pname:pStages points to an array of slink:VkPipelineShaderStageCreateInfo
|
||||
structures, which were previously described in
|
||||
<<pipelines-compute,Compute Pipelines>>.
|
||||
|
||||
Bits which can: be set in pname:flags are:
|
||||
|
||||
include::../enums/VkPipelineCreateFlagBits.txt[]
|
||||
|
||||
* ename:VK_PIPELINE_CREATE_DISABLE_OPTIMIZATION_BIT specifies that the
|
||||
created pipeline will not be optimized. Using this flag may: reduce
|
||||
the time taken to create the pipeline.
|
||||
* ename:VK_PIPELINE_CREATE_ALLOW_DERIVATIVES_BIT specifies that the
|
||||
pipeline to be created is allowed to be the parent of a pipeline that
|
||||
will be created in a subsequent call to flink:vkCreateGraphicsPipelines.
|
||||
* ename:VK_PIPELINE_CREATE_DERIVATIVE_BIT specifies that the pipeline to
|
||||
be created will be a child of a previously created parent pipeline.
|
||||
|
||||
It is valid to set both ename:VK_PIPELINE_CREATE_ALLOW_DERIVATIVES_BIT and
|
||||
ename:VK_PIPELINE_CREATE_DERIVATIVE_BIT. This allows a pipeline to be both a
|
||||
parent and possibly a child in a pipeline hierarchy. See
|
||||
<<pipelines-pipeline-derivatives,Pipeline Derivatives>> for more
|
||||
information.
|
||||
|
||||
The definition of the pname:pDynamicState member of type
|
||||
sname:VkPipelineDynamicStateCreateInfo is:
|
||||
|
||||
include::../structs/VkPipelineDynamicStateCreateInfo.txt[]
|
||||
|
||||
The members of the sname:VkPipelineDynamicStateCreateInfo structure are as
|
||||
follows:
|
||||
|
||||
* 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:dynamicStateCount is the number of elements in the
|
||||
pname:pDynamicStates array.
|
||||
* pname:pDynamicStates is an array of elink:VkDynamicState enums which
|
||||
indicate which pieces of pipeline state will use the values from dynamic
|
||||
state commands rather than from the pipeline state creation info.
|
||||
|
||||
include::../validity/structs/VkPipelineDynamicStateCreateInfo.txt[]
|
||||
|
||||
The definition of the elink:VkDynamicState enumeration is as follows:
|
||||
|
||||
include::../enums/VkDynamicState.txt[]
|
||||
|
||||
* ename:VK_DYNAMIC_STATE_VIEWPORT indicates that the pname:pViewports
|
||||
state in sname:VkPipelineViewportStateCreateInfo will be ignored and
|
||||
must: be set dynamically with flink:vkCmdSetViewport before any draw
|
||||
commands. The number of viewports used by a pipeline is still
|
||||
specified by the pname:viewportCount member of
|
||||
sname:VkPipelineViewportStateCreateInfo.
|
||||
* ename:VK_DYNAMIC_STATE_SCISSOR indicates that the pname:pScissors
|
||||
state in sname:VkPipelineViewportStateCreateInfo will be ignored and
|
||||
must: be set dynamically with flink:vkCmdSetScissor before any draw
|
||||
commands. The number of scissor rectangles used by a pipeline is still
|
||||
specified by the pname:scissorCount member of
|
||||
sname:VkPipelineViewportStateCreateInfo.
|
||||
* ename:VK_DYNAMIC_STATE_LINE_WIDTH indicates that the pname:lineWidth
|
||||
state in sname:VkPipelineRasterizationStateCreateInfo will be ignored
|
||||
and must: be set dynamically with flink:vkCmdSetLineWidth before any
|
||||
draw commands that generate line primitives for the rasterizer.
|
||||
* ename:VK_DYNAMIC_STATE_DEPTH_BIAS indicates that the
|
||||
pname:depthBiasConstantFactor, pname:depthBiasClamp and
|
||||
pname:depthBiasSlopeFactor states in
|
||||
sname:VkPipelineRasterizationStateCreateInfo will be ignored and must:
|
||||
be set dynamically with flink:vkCmdSetDepthBias before any draws are
|
||||
performed with pname:depthBiasEnable in
|
||||
sname:VkPipelineRasterizationStateCreateInfo set to ename:VK_TRUE.
|
||||
* ename:VK_DYNAMIC_STATE_BLEND_CONSTANTS indicates that the
|
||||
pname:blendConstants state in
|
||||
sname:VkPipelineColorBlendStateCreateInfo will be ignored and must: be
|
||||
set dynamically with flink:vkCmdSetBlendConstants before any draws are
|
||||
performed with a pipeline state with
|
||||
sname:VkPipelineColorBlendAttachmentState member pname:blendEnable set
|
||||
to ename:VK_TRUE and any of the blend functions using a constant blend
|
||||
color.
|
||||
* ename:VK_DYNAMIC_STATE_DEPTH_BOUNDS indicates that the
|
||||
pname:minDepthBounds and pname:maxDepthBounds states of
|
||||
slink:VkPipelineDepthStencilStateCreateInfo will be ignored and must:
|
||||
be set dynamically with flink:vkCmdSetDepthBounds before any draws are
|
||||
performed with a pipeline state with
|
||||
sname:VkPipelineDepthStencilStateCreateInfo member
|
||||
pname:depthBoundsTestEnable set to ename:VK_TRUE.
|
||||
* ename:VK_DYNAMIC_STATE_STENCIL_COMPARE_MASK indicates that the
|
||||
pname:compareMask state in
|
||||
sname:VkPipelineDepthStencilStateCreateInfo for both pname:front and
|
||||
pname:back will be ignored and must: be set dynamically with
|
||||
flink:vkCmdSetStencilCompareMask before any draws are performed with a
|
||||
pipeline state with sname:VkPipelineDepthStencilStateCreateInfo member
|
||||
pname:stencilTestEnable set to ename:VK_TRUE
|
||||
* ename:VK_DYNAMIC_STATE_STENCIL_WRITE_MASK indicates that the
|
||||
pname:writeMask state in sname:VkPipelineDepthStencilStateCreateInfo
|
||||
for both pname:front and pname:back will be ignored and must: be set
|
||||
dynamically with flink:vkCmdSetStencilWriteMask before any draws are
|
||||
performed with a pipeline state with
|
||||
sname:VkPipelineDepthStencilStateCreateInfo member
|
||||
pname:stencilTestEnable set to ename:VK_TRUE
|
||||
* ename:VK_DYNAMIC_STATE_STENCIL_REFERENCE indicates that the
|
||||
pname:reference state in sname:VkPipelineDepthStencilStateCreateInfo
|
||||
for both pname:front and pname:back will be ignored and must: be set
|
||||
dynamically with flink:vkCmdSetStencilReference before any draws are
|
||||
performed with a pipeline state with
|
||||
sname:VkPipelineDepthStencilStateCreateInfo member
|
||||
pname:stencilTestEnable set to ename:VK_TRUE
|
||||
|
||||
If tessellation shader stages are omitted, the tessellation shading and
|
||||
fixed-function stages of the pipeline are skipped.
|
||||
|
||||
If a geometry shader is omitted, the geometry shading stage is skipped.
|
||||
|
||||
If a fragment shader is omitted, the results of fragment processing are
|
||||
undefined. Specifically, any fragment color outputs
|
||||
are considered to have undefined values, and the fragment depth is
|
||||
considered to be unmodified. This can: be useful for depth-only rendering.
|
||||
|
||||
Presence of a shader stage in a pipeline is indicated by including a valid
|
||||
sname:VkPipelineShaderStageCreateInfo with pname:module and pname:pName
|
||||
selecting an entry point from a shader module, where that entry point is
|
||||
valid for the stage specified by pname:stage.
|
||||
|
||||
Presence of some of the fixed-function stages in the pipeline is implicitly
|
||||
derived from enabled shaders and provided state. For example, the
|
||||
fixed-function tessellator is always present when the pipeline has valid
|
||||
Tessellation Control and Tessellation Evaluation shaders.
|
||||
|
||||
.For example:
|
||||
* Depth/stencil-only rendering in a subpass with no color attachments
|
||||
** Active Pipeline Shader Stages
|
||||
*** Vertex Shader
|
||||
** Required: Fixed-Function Pipeline Stages
|
||||
*** slink:VkPipelineVertexInputStateCreateInfo
|
||||
*** slink:VkPipelineInputAssemblyStateCreateInfo
|
||||
*** slink:VkPipelineViewportStateCreateInfo
|
||||
*** slink:VkPipelineRasterizationStateCreateInfo
|
||||
*** slink:VkPipelineMultisampleStateCreateInfo
|
||||
*** slink:VkPipelineDepthStencilStateCreateInfo
|
||||
* Color-only rendering in a subpass with no depth/stencil attachment
|
||||
** Active Pipeline Shader Stages
|
||||
*** Vertex Shader
|
||||
*** Fragment Shader
|
||||
** Required: Fixed-Function Pipeline Stages
|
||||
*** slink:VkPipelineVertexInputStateCreateInfo
|
||||
*** slink:VkPipelineInputAssemblyStateCreateInfo
|
||||
*** slink:VkPipelineViewportStateCreateInfo
|
||||
*** slink:VkPipelineRasterizationStateCreateInfo
|
||||
*** slink:VkPipelineMultisampleStateCreateInfo
|
||||
*** slink:VkPipelineColorBlendStateCreateInfo
|
||||
* Rendering pipeline with tessellation and geometry shaders
|
||||
** Active Pipeline Shader Stages
|
||||
*** Vertex Shader
|
||||
*** Tessellation Control Shader
|
||||
*** Tessellation Evaluation Shader
|
||||
*** Geometry Shader
|
||||
*** Fragment Shader
|
||||
** Required: Fixed-Function Pipeline Stages
|
||||
*** slink:VkPipelineVertexInputStateCreateInfo
|
||||
*** slink:VkPipelineInputAssemblyStateCreateInfo
|
||||
*** slink:VkPipelineTessellationStateCreateInfo
|
||||
*** slink:VkPipelineViewportStateCreateInfo
|
||||
*** slink:VkPipelineRasterizationStateCreateInfo
|
||||
*** slink:VkPipelineMultisampleStateCreateInfo
|
||||
*** slink:VkPipelineDepthStencilStateCreateInfo
|
||||
*** slink:VkPipelineColorBlendStateCreateInfo
|
||||
|
||||
|
||||
[[pipelines-destruction]]
|
||||
== Pipeline destruction
|
||||
|
||||
To destroy a graphics or compute pipeline, call:
|
||||
|
||||
include::../protos/vkDestroyPipeline.txt[]
|
||||
|
||||
* pname:device is the logical device that destroys the pipeline.
|
||||
* pname:pipeline is the handle of the pipeline to destroy.
|
||||
* pname:pAllocator controls host memory allocation as described in the
|
||||
<<memory-allocation, Memory Allocation>> chapter.
|
||||
|
||||
include::../validity/protos/vkDestroyPipeline.txt[]
|
||||
|
||||
|
||||
[[pipelines-multiple]]
|
||||
== Multiple Pipeline Creation
|
||||
|
||||
Multiple pipelines can: be created simultaneously by passing an array of
|
||||
sname:VkGraphicsPipelineCreateInfo or sname:VkComputePipelineCreateInfo
|
||||
structures into the flink:vkCreateGraphicsPipelines and
|
||||
flink:vkCreateComputePipelines commands, respectively. Applications can:
|
||||
group together similar pipelines to be created in a single call, and
|
||||
implementations are encouraged to look for reuse opportunities within a
|
||||
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 sname: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 sname:VK_NULL_HANDLE values for those that
|
||||
actually failed.
|
||||
|
||||
|
||||
[[pipelines-pipeline-derivatives]]
|
||||
== Pipeline Derivatives
|
||||
|
||||
A pipeline derivative is a child pipeline created from a parent pipeline,
|
||||
where the child and parent are expected to have much commonality. The goal
|
||||
of derivative pipelines is that they be cheaper to create using the
|
||||
parent as a starting point, and that it be more efficient (on either host or
|
||||
device) to switch/bind between children of the same parent.
|
||||
|
||||
A derivative pipeline is created by setting the
|
||||
ename:VK_PIPELINE_CREATE_DERIVATIVE_BIT flag in the
|
||||
stext:Vk*PipelineCreateInfo structure. If this is set, then exactly one of
|
||||
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. sname: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
|
||||
been created with the ename:VK_PIPELINE_CREATE_ALLOW_DERIVATIVES_BIT flag
|
||||
set.
|
||||
|
||||
|
||||
[[pipelines-cache]]
|
||||
== Pipeline Cache
|
||||
|
||||
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
|
||||
creating multiple related pipelines. Reuse across runs of an application is
|
||||
achieved by retrieving pipeline cache contents in one run of an application,
|
||||
saving the contents, and using them to preinitialize a pipeline cache on a
|
||||
subsequent run. The contents and size of the pipeline cache objects is
|
||||
managed by the implementation. Applications can: control the amount of data
|
||||
retrieved from a pipeline cache object.
|
||||
|
||||
Pipeline cache objects are created by calling:
|
||||
|
||||
include::../protos/vkCreatePipelineCache.txt[]
|
||||
|
||||
* pname:device is the logical device that creates the pipeline cache
|
||||
object.
|
||||
* pname:pCreateInfo is a pointer to a sname:VkPipelineCacheCreateInfo
|
||||
structure that contains the initial parameters for the pipeline cache
|
||||
object.
|
||||
* pname:pAllocator controls host memory allocation as described in the
|
||||
<<memory-allocation, Memory Allocation>> chapter.
|
||||
* pname:pPipelineCache is a pointer to a sname:VkPipelineCache handle in
|
||||
which the resulting pipeline cache object is returned.
|
||||
|
||||
include::../validity/protos/vkCreatePipelineCache.txt[]
|
||||
|
||||
The definition of sname:VkPipelineCacheCreateInfo is:
|
||||
|
||||
include::../structs/VkPipelineCacheCreateInfo.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:initialDataSize is the number of bytes in pname:pInitialData. If
|
||||
pname:initialDataSize is zero, the pipeline cache will initially be
|
||||
empty.
|
||||
* pname:pInitialData is a pointer to previously retrieved pipeline
|
||||
cache data. If the pipeline cache data is incompatible (as defined
|
||||
below) with the device, the pipeline cache will be initially empty. If
|
||||
pname:initialDataSize is zero, pname:pInitialData is ignored.
|
||||
|
||||
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
|
||||
sname: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.
|
||||
====
|
||||
|
||||
Pipeline cache objects can: be merged using the command:
|
||||
|
||||
include::../protos/vkMergePipelineCaches.txt[]
|
||||
|
||||
* pname:device is the logical device that owns the pipeline cache objects.
|
||||
* pname:dstCache is the handle of the pipeline cache to merge results
|
||||
into.
|
||||
* pname:srcCacheCount is the length of the pname:pSrcCaches array.
|
||||
* pname:pSrcCaches is an array of pipeline cache handles, which will be
|
||||
merged into pname:dstCache. The previous contents of pname:dstCache are
|
||||
included after the merge.
|
||||
|
||||
include::../validity/protos/vkMergePipelineCaches.txt[]
|
||||
|
||||
[NOTE]
|
||||
.Note
|
||||
====
|
||||
The details of the merge operation are implementation dependent, but
|
||||
implementations are recommended: to merge the contents of the specified
|
||||
pipelines and prune duplicate entries.
|
||||
====
|
||||
|
||||
Data can: be retrieved from a pipeline cache object using the command:
|
||||
|
||||
include::../protos/vkGetPipelineCacheData.txt[]
|
||||
|
||||
* pname:device is the logical device that owns the pipeline cache.
|
||||
* pname:pipelineCache is the pipeline cache to retrieve data from.
|
||||
* pname:pDataSize is a pointer to a value related to the amount of data in
|
||||
the pipeline cache, as described below.
|
||||
* pname:pData is either `NULL` or a pointer to a buffer.
|
||||
|
||||
If pname:pData is `NULL`, then the maximum size of the data that can be
|
||||
retrieved from the pipeline cache, in bytes, is returned in pname:pDataSize.
|
||||
Otherwise, pname:pDataSize must: point to a variable set by the user to the
|
||||
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 the value of pname:dataSize 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
|
||||
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
|
||||
pipeline cache objects. The results of pipeline compiles, however,
|
||||
may: depend on the vendor ID, device ID, driver version, and other details
|
||||
of the device. To enable applications to detect when previously retrieved
|
||||
data is incompatible with the device, the initial bytes written to
|
||||
pname:pData must: be a header consisting of the following members:
|
||||
|
||||
.Layout for pipeline cache header version VK_PIPELINE_CACHE_HEADER_VERSION_ONE
|
||||
[width="85%",cols="8%,21%,71%",options="header"]
|
||||
|=====
|
||||
| Offset | Size | Meaning
|
||||
| 0 | 4 | length in bytes of the entire pipeline cache header
|
||||
written as a stream of bytes, with the least
|
||||
significant byte first
|
||||
| 4 | 4 | a elink:VkPipelineCacheHeaderVersion value
|
||||
written as a stream of bytes, with the least
|
||||
significant byte first
|
||||
| 8 | 4 | a vendor ID equal to
|
||||
sname:VkPhysicalDeviceProperties::pname:vendorID
|
||||
written as a stream of bytes, with the least
|
||||
significant byte first
|
||||
| 12 | 4 | a device ID equal to
|
||||
sname:VkPhysicalDeviceProperties::pname:deviceID
|
||||
written as a stream of bytes, with the least
|
||||
significant byte first
|
||||
| 16 | ename:VK_UUID_SIZE | a pipeline cache ID equal to
|
||||
sname:VkPhysicalDeviceProperties::pname:pipelineCacheUUID
|
||||
|=====
|
||||
|
||||
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.
|
||||
|
||||
The next four bytes encode the pipeline cache version.
|
||||
This field is a elink:VkPipelineCacheHeaderVersion value.
|
||||
A consumer of the pipeline cache should use this value to interpret the
|
||||
remainder of the cache header.
|
||||
|
||||
If the value of pname:dataSize 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.
|
||||
|
||||
To destroy a pipeline cache, call:
|
||||
|
||||
include::../protos/vkDestroyPipelineCache.txt[]
|
||||
|
||||
* pname:device is the logical device that destroys the pipeline cache
|
||||
object.
|
||||
* pname:pipelineCache is the handle of the pipeline cache to destroy.
|
||||
* pname:pAllocator controls host memory allocation as described in the
|
||||
<<memory-allocation, Memory Allocation>> chapter.
|
||||
|
||||
include::../validity/protos/vkDestroyPipelineCache.txt[]
|
||||
|
||||
|
||||
[[pipelines-specialization-constants]]
|
||||
== Specialization Constants
|
||||
|
||||
Specialization constants are a mechanism whereby constants in a SPIR-V
|
||||
module can: have their constant value specified at the time the
|
||||
sname:VkPipeline is created. This allows a SPIR-V module to have constants
|
||||
that can: be modified while executing an application that uses the Vulkan
|
||||
API.
|
||||
|
||||
[NOTE]
|
||||
.Note
|
||||
====
|
||||
Specialization constants are useful to allow a compute shader to have
|
||||
its work group size changed at runtime by the user, for example.
|
||||
====
|
||||
|
||||
Each instance of the sname:VkPipelineShaderStageCreateInfo structure
|
||||
contains a parameter pname:pSpecializationInfo, which can: be `NULL` to
|
||||
indicate no specialization constants. The definition of the
|
||||
sname:VkSpecializationInfo structure is:
|
||||
|
||||
include::../structs/VkSpecializationInfo.txt[]
|
||||
|
||||
The members of sname:VkSpecializationInfo are as follows:
|
||||
|
||||
* pname:mapEntryCount is the number of entries in the pname:pMapEntries
|
||||
array.
|
||||
* pname:pMapEntries is a pointer to an array of
|
||||
sname:VkSpecializationMapEntry which maps constant IDs to offsets in
|
||||
pname:pData.
|
||||
* pname:dataSize is the byte size of the pname:pData buffer.
|
||||
* pname:pData contains the actual constant values to specialize with.
|
||||
|
||||
include::../validity/structs/VkSpecializationInfo.txt[]
|
||||
|
||||
The definition of the pname:pMapEntries member of type
|
||||
sname:VkSpecializationMapEntry is:
|
||||
|
||||
include::../structs/VkSpecializationMapEntry.txt[]
|
||||
|
||||
The members of sname:VkSpecializationMapEntry are as follows:
|
||||
|
||||
* pname:constantID ID of the specialization constant in SPIR-V.
|
||||
* pname:offset byte offset of the specialization constant value within the
|
||||
supplied data buffer.
|
||||
* pname:size 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.
|
||||
|
||||
In human readable SPIR-V:
|
||||
|
||||
[source,glsl]
|
||||
---------------------------------------------------
|
||||
OpDecorate %x SpecId 13 ; decorate .x component of WorkgroupSize with ID 13
|
||||
OpDecorate %y SpecId 42 ; decorate .y component of WorkgroupSize with ID 42
|
||||
OpDecorate %z SpecId 3 ; decorate .z component of WorkgroupSize with ID 3
|
||||
OpDecorate %wgsize BuiltIn WorkgroupSize ; decorate WorkgroupSize onto constant
|
||||
%i32 = OpTypeInt 32 0 ; declare an unsigned 32-bit type
|
||||
%uvec3 = OpTypeVector %i32 3 ; declare a 3 element vector type of unsigned 32-bit
|
||||
%x = OpSpecConstant %i32 1 ; declare the .x component of WorkgroupSize
|
||||
%y = OpSpecConstant %i32 1 ; declare the .y component of WorkgroupSize
|
||||
%z = OpSpecConstant %i32 1 ; declare the .z component of WorkgroupSize
|
||||
%wgsize = OpSpecConstantComposite %uvec3 %x %y %z ; declare WorkgroupSize
|
||||
---------------------------------------------------
|
||||
|
||||
From the above we have three specialization constants, one for each of the
|
||||
x, y & z elements of the WorkgroupSize vector.
|
||||
|
||||
Now to specialize the above via the specialization constants mechanism:
|
||||
|
||||
[source,{basebackend@docbook:c++:cpp}]
|
||||
---------------------------------------------------
|
||||
const VkSpecializationMapEntry entries[] =
|
||||
{
|
||||
{
|
||||
13, // constantID
|
||||
0 * sizeof(uint32_t), // offset
|
||||
sizeof(uint32_t) // size
|
||||
},
|
||||
{
|
||||
42, // constantID
|
||||
1 * sizeof(uint32_t), // offset
|
||||
sizeof(uint32_t) // size
|
||||
},
|
||||
{
|
||||
3, // constantID
|
||||
2 * sizeof(uint32_t), // offset
|
||||
sizeof(uint32_t) // size
|
||||
}
|
||||
};
|
||||
|
||||
const uint32_t data[] = { 16, 8, 4 }; // our workgroup size is 16x8x4
|
||||
|
||||
const VkSpecializationInfo info =
|
||||
{
|
||||
3, // mapEntryCount
|
||||
entries, // pMapEntries
|
||||
3 * sizeof(uint32_t), // dataSize
|
||||
data, // pData
|
||||
};
|
||||
---------------------------------------------------
|
||||
|
||||
Then when calling fname:vkCreateComputePipelines, and passing the
|
||||
sname:VkSpecializationInfo we defined as the pname:pSpecializationInfo
|
||||
parameter of sname:VkPipelineShaderStageCreateInfo, we will create a compute
|
||||
pipeline with the runtime specified work group size.
|
||||
|
||||
Another example would be that an application has a SPIR-V module that has
|
||||
some platform-dependent constants they wish to use.
|
||||
|
||||
In human readable SPIR-V:
|
||||
|
||||
// [source,{basebackend@docbook:c:glsl}]
|
||||
[source,glsl]
|
||||
---------------------------------------------------
|
||||
OpDecorate %1 SpecId 0 ; decorate our signed 32-bit integer constant
|
||||
OpDecorate %2 SpecId 12 ; decorate our 32-bit floating-point constant
|
||||
%i32 = OpTypeInt 32 1 ; declare a signed 32-bit type
|
||||
%float = OpTypeFloat 32 ; declare a 32-bit floating-point type
|
||||
%1 = OpSpecConstant %i32 -1 ; some signed 32-bit integer constant
|
||||
%2 = OpSpecConstant %float 0.5 ; some 32-bit floating-point constant
|
||||
---------------------------------------------------
|
||||
|
||||
From the above we have two specialization constants, one is a signed 32-bit
|
||||
integer and the second is a 32-bit floating-point.
|
||||
|
||||
Now to specialize the above via the specialization constants mechanism:
|
||||
|
||||
[source,{basebackend@docbook:c++:cpp}]
|
||||
---------------------------------------------------
|
||||
VkSpecializationMapEntry entries[2];
|
||||
|
||||
const VkSpecializationMapEntry entries[] =
|
||||
{
|
||||
{
|
||||
0, // constantID
|
||||
0 * sizeof(int32_t), // offset
|
||||
sizeof(int32_t) // size
|
||||
},
|
||||
{
|
||||
12, // constantID
|
||||
1 * sizeof(int32_t), // offset
|
||||
sizeof(float) // size
|
||||
}
|
||||
};
|
||||
|
||||
int32_t data[2];
|
||||
|
||||
data[0] = -42; // set the data for the 32-bit integer
|
||||
((float*)data)[1] = 42.0f; // set the data for the 32-bit floating-point
|
||||
|
||||
const VkSpecializationInfo info =
|
||||
{
|
||||
2, // mapEntryCount
|
||||
entries, // pMapEntries
|
||||
2 * sizeof(int32_t), // dataSize
|
||||
data, // pData
|
||||
};
|
||||
---------------------------------------------------
|
||||
|
||||
It is legal for a SPIR-V module with specializations to be compiled into a
|
||||
pipeline where no specialization info was provided. SPIR-V specialization
|
||||
constants contain default values such that if a specialization is not
|
||||
provided, the default value will be used. In the examples above, it would be
|
||||
valid for an application to only specialize some of the specialization
|
||||
constants within the SPIR-V module, and let the other constants use their
|
||||
default values encoded within the OpSpecConstant declarations.
|
||||
|
||||
|
||||
[[pipelines-binding]]
|
||||
== Pipeline Binding
|
||||
|
||||
Once a pipeline has been created, it can: be bound to the command buffer
|
||||
using the command:
|
||||
|
||||
include::../protos/vkCmdBindPipeline.txt[]
|
||||
|
||||
* pname:commandBuffer is the command buffer that the pipeline will be
|
||||
bound to.
|
||||
* pname:pipelineBindPoint specifies the bind point, and must: have one of
|
||||
the values
|
||||
+
|
||||
--
|
||||
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
|
||||
controls the behavior of flink:vkCmdDispatch and
|
||||
flink:vkCmdDispatchIndirect. The pipeline bound to
|
||||
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.
|
||||
|
|
@ -0,0 +1,755 @@
|
|||
// Copyright (c) 2015-2016 The Khronos Group Inc.
|
||||
// Copyright notice at https://www.khronos.org/registry/speccopyright.html
|
||||
|
||||
[[primsrast]]
|
||||
= Rasterization
|
||||
|
||||
Rasterization is the process by which a primitive is converted to a
|
||||
two-dimensional image. Each point of this image contains associated data
|
||||
such as depth, color, or other attributes.
|
||||
|
||||
Rasterizing a primitive begins by determining which squares of an integer
|
||||
grid in framebuffer coordinates are occupied by the primitive, and assigning
|
||||
one or more depth values to each such square. This process is described
|
||||
below for points, lines, and polygons.
|
||||
|
||||
A grid square, including its latexmath:[$(x,y)$] framebuffer coordinates,
|
||||
latexmath:[$z$] (depth), and associated data added by fragment
|
||||
shaders, is called a fragment. A fragment is located by its upper left
|
||||
corner, which lies on integer grid coordinates.
|
||||
|
||||
Rasterization operations also refer to a fragment's sample locations, which
|
||||
are offset by subpixel fractional values from its upper left corner. The
|
||||
rasterization rules for points, lines, and triangles involve testing whether
|
||||
each sample location is inside the primitive. Fragments need not actually be
|
||||
square, and rasterization rules are not affected by the aspect ratio of
|
||||
fragments. Display of non-square grids, however, will cause rasterized
|
||||
points and line segments to appear fatter in one direction than the other.
|
||||
|
||||
We assume that fragments are square, since it simplifies antialiasing and
|
||||
texturing. After rasterization, fragments are processed by the
|
||||
<<fragops-early,early per-fragment tests>>, if enabled.
|
||||
|
||||
Several factors affect rasterization, including the members of
|
||||
sname:VkPipelineRasterizationStateCreateInfo and
|
||||
sname:VkPipelineMultisampleStateCreateInfo.
|
||||
|
||||
The sname:VkPipelineRasterizationStateCreateInfo structure is defined as:
|
||||
|
||||
include::../structs/VkPipelineRasterizationStateCreateInfo.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:depthClampEnable controls whether to clamp the fragment's depth
|
||||
values instead of clipping primitives to the z planes of the frustum, as
|
||||
described in <<vertexpostproc-clipping,Primitive Clipping>>.
|
||||
* pname:rasterizerDiscardEnable controls whether primitives are discarded
|
||||
immediately before the rasterization stage.
|
||||
* pname:polygonMode is the triangle rendering mode. See
|
||||
elink:VkPolygonMode.
|
||||
* pname:cullMode is the triangle facing direction used for primitive
|
||||
culling. See elink:VkCullModeFlagBits.
|
||||
* pname:frontFace is the front-facing triangle orientation to be used for
|
||||
culling. See elink:VkFrontFace.
|
||||
* pname:depthBiasEnable controls whether to bias fragment depth values.
|
||||
* pname:depthBiasConstantFactor is a scalar factor controlling the
|
||||
constant depth value added to each fragment.
|
||||
* pname:depthBiasClamp is the maximum (or minimum) depth bias of a
|
||||
fragment.
|
||||
* pname:depthBiasSlopeFactor is a scalar factor applied to a fragment's
|
||||
slope in depth bias calculations.
|
||||
* pname:lineWidth is the width of rasterized line segments.
|
||||
|
||||
include::../validity/structs/VkPipelineRasterizationStateCreateInfo.txt[]
|
||||
|
||||
The sname:VkPipelineMultisampleStateCreateInfo structure is defined as:
|
||||
|
||||
include::../structs/VkPipelineMultisampleStateCreateInfo.txt[]
|
||||
|
||||
The members of the sname:VkPipelineMultisampleStateCreateInfo structure are
|
||||
as follows:
|
||||
|
||||
* 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:rasterizationSamples is an elink:VkSampleCountFlagBits specifying
|
||||
the number of samples per pixel used in rasterization.
|
||||
* pname:sampleShadingEnable specifies that fragment shading executes
|
||||
per-sample if ename:VK_TRUE, or per-fragment if ename:VK_FALSE, as
|
||||
described in <<primsrast-sampleshading,Sample Shading>>.
|
||||
* pname:minSampleShading is the minimum number of unique samples to shade
|
||||
for each fragment.
|
||||
* pname:pSampleMask is a bitmask of static coverage information that is
|
||||
ANDed with the coverage information generated during rasterization, as
|
||||
described in <<fragops-samplemask,Sample Mask>>.
|
||||
* pname:alphaToCoverageEnable controls whether a temporary coverage value
|
||||
is generated based on the value of the alpha component of the fragment's
|
||||
first color output as specified in the <<fragops-covg,Multisample
|
||||
Coverage>> section.
|
||||
* pname:alphaToOne controls whether the value of the alpha component of
|
||||
the fragment's first color output is replaced with one as described in
|
||||
<<fragops-covg,Multisample Coverage>>.
|
||||
|
||||
include::../validity/structs/VkPipelineMultisampleStateCreateInfo.txt[]
|
||||
|
||||
Rasterization only produces fragments corresponding to pixels in the
|
||||
framebuffer. Fragments which would be produced by application of any of the
|
||||
primitive rasterization rules described below but which lie outside the
|
||||
framebuffer are not produced, nor are they processed by any later stage of
|
||||
the pipeline, including any of the early per-fragment tests described in
|
||||
<<fragops-early,Early Per-Fragment Tests>>.
|
||||
|
||||
Surviving fragments are processed by fragment shaders. Fragment shaders
|
||||
determine associated data for fragments, and can: also modify or replace
|
||||
their assigned depth values.
|
||||
|
||||
If the subpass for which this pipeline is being created uses
|
||||
color and/or depth/stencil attachments, then the value of
|
||||
pname:rasterizationSamples must: be the same as the sample count for
|
||||
those subpass attachments. Otherwise, the value of
|
||||
pname:rasterizationSamples must: follow the rules for a
|
||||
<<renderpass-noattachments, zero-attachment subpass>>.
|
||||
|
||||
|
||||
[[primsrast-discard]]
|
||||
== Discarding Primitives Before Rasterization
|
||||
|
||||
Primitives are discarded before rasterization if the
|
||||
pname:rasterizerDiscardEnable member of
|
||||
slink:VkPipelineRasterizationStateCreateInfo is enabled. When enabled,
|
||||
primitives are discarded after they are processed by the last active shader
|
||||
stage in the pipeline before rasterization.
|
||||
|
||||
|
||||
[[primsrast-multisampling]]
|
||||
== Multisampling
|
||||
|
||||
Multisampling is a mechanism to antialias all {apiname} primitives: points,
|
||||
lines, and polygons. The technique is to sample all primitives multiple
|
||||
times at each pixel. Each sample in each framebuffer attachment has storage
|
||||
for a color, depth, and/or stencil value, such that per-fragment operations
|
||||
apply to each sample independently. The color sample values can: be later
|
||||
_resolved_ to a single color (see <<copies-resolve,Resolving Multisample
|
||||
Images>> and the <<renderpass,Render Pass>> chapter for more details on how
|
||||
to resolve multisample images to non-multisample images).
|
||||
|
||||
{apiname} defines rasterization rules for single-sample modes in a way that
|
||||
is equivalent to a multisample mode with a single sample in the center of
|
||||
each pixel.
|
||||
|
||||
Each fragment includes a coverage value with pname:rasterizationSamples bits
|
||||
(see <<fragops-samplemask,Sample Mask>>). Each fragment includes
|
||||
pname:rasterizationSamples depth values and sets of associated data. An
|
||||
implementation may: choose to assign the same associated data to more than
|
||||
one sample. The location for evaluating such associated data may: be
|
||||
anywhere within the pixel including the pixel center or any of the sample
|
||||
locations. When pname:rasterizationSamples is ename:VK_SAMPLE_COUNT_1_BIT,
|
||||
the pixel center must: be used. The different associated data values need
|
||||
not all be evaluated at the same location. Each pixel fragment thus consists
|
||||
of integer x and y grid coordinates, pname:rasterizationSamples depth values
|
||||
and sets of associated data, and a coverage value with
|
||||
pname:rasterizationSamples bits.
|
||||
|
||||
It is understood that each pixel has pname:rasterizationSamples locations
|
||||
associated with it. These locations are exact positions, rather than regions
|
||||
or areas, and each is referred to as a sample point. The sample points
|
||||
associated with a pixel must: be located inside or on the boundary of the
|
||||
unit square that is considered to bound the pixel. Furthermore, the relative
|
||||
locations of sample points may: be identical for each pixel in the
|
||||
framebuffer, or they may: differ. If the current pipeline includes a
|
||||
fragment shader with one or more variables in its interface decorated with
|
||||
code:Sample and code:Input, the data associated with those variables will be
|
||||
assigned independently for each sample. The values for each sample must: be
|
||||
evaluated at the location of the sample. The data associated with any other
|
||||
variables not decorated with code:Sample and code:Input need not be
|
||||
evaluated independently for each sample.
|
||||
|
||||
If the pname:standardSampleLocations member of
|
||||
slink:VkPhysicalDeviceFeatures is ename:VK_TRUE, then the sample counts
|
||||
ename:VK_SAMPLE_COUNT_1_BIT, ename:VK_SAMPLE_COUNT_2_BIT,
|
||||
ename:VK_SAMPLE_COUNT_4_BIT, ename:VK_SAMPLE_COUNT_8_BIT, and
|
||||
ename:VK_SAMPLE_COUNT_16_BIT have sample locations as listed in the
|
||||
following table, with the latexmath:[$i$]th entry in the table corresponding
|
||||
to bit latexmath:[$i$] in the sample masks. ename:VK_SAMPLE_COUNT_32_BIT and
|
||||
ename:VK_SAMPLE_COUNT_64_BIT do not have standard sample locations.
|
||||
Locations are defined relative to an origin in the upper left corner of the
|
||||
pixel.
|
||||
|
||||
<<<
|
||||
|
||||
.Standard sample locations
|
||||
[align="center"]
|
||||
|========================================
|
||||
|ename:VK_SAMPLE_COUNT_1_BIT|ename:VK_SAMPLE_COUNT_2_BIT|ename:VK_SAMPLE_COUNT_4_BIT|ename:VK_SAMPLE_COUNT_8_BIT|ename:VK_SAMPLE_COUNT_16_BIT
|
||||
|
|
||||
latexmath:[$(0.5,0.5)$]
|
||||
|
|
||||
latexmath:[$(0.25,0.25)$] +
|
||||
latexmath:[$(0.75,0.75)$]
|
||||
|
|
||||
latexmath:[$( 0.375, 0.125)$] +
|
||||
latexmath:[$( 0.875, 0.375)$] +
|
||||
latexmath:[$( 0.125, 0.625)$] +
|
||||
latexmath:[$( 0.625, 0.875)$]
|
||||
|
|
||||
latexmath:[$( 0.5625, 0.3125)$] +
|
||||
latexmath:[$( 0.4375, 0.6875)$] +
|
||||
latexmath:[$( 0.8125, 0.5625)$] +
|
||||
latexmath:[$( 0.3125, 0.1875)$] +
|
||||
latexmath:[$( 0.1875, 0.8125)$] +
|
||||
latexmath:[$( 0.0625, 0.4375)$] +
|
||||
latexmath:[$( 0.6875, 0.9375)$] +
|
||||
latexmath:[$( 0.9375, 0.0625)$]
|
||||
|
|
||||
latexmath:[$( 0.5625, 0.5625)$] +
|
||||
latexmath:[$( 0.4375, 0.3125)$] +
|
||||
latexmath:[$( 0.3125, 0.625)$] +
|
||||
latexmath:[$( 0.75, 0.4375)$] +
|
||||
latexmath:[$( 0.1875, 0.375)$] +
|
||||
latexmath:[$( 0.625, 0.8125)$] +
|
||||
latexmath:[$( 0.8125, 0.6875)$] +
|
||||
latexmath:[$( 0.6875, 0.1875)$] +
|
||||
latexmath:[$( 0.375, 0.875)$] +
|
||||
latexmath:[$( 0.5, 0.0625)$] +
|
||||
latexmath:[$( 0.25, 0.125)$] +
|
||||
latexmath:[$( 0.125, 0.75)$] +
|
||||
latexmath:[$( 0.0, 0.5)$] +
|
||||
latexmath:[$( 0.9375, 0.25)$] +
|
||||
latexmath:[$( 0.875, 0.9375)$] +
|
||||
latexmath:[$( 0.0625, 0.0)$]
|
||||
|========================================
|
||||
|
||||
|
||||
[[primsrast-sampleshading]]
|
||||
== Sample Shading
|
||||
|
||||
Sample shading can: be used to specify a minimum number of unique samples to
|
||||
process for each fragment. Sample shading is controlled by the
|
||||
pname:sampleShadingEnable member of
|
||||
slink:VkPipelineMultisampleStateCreateInfo. If pname:sampleShadingEnable is
|
||||
ename:VK_FALSE, sample shading is considered disabled and has no effect.
|
||||
Otherwise, an implementation must: provide a minimum of
|
||||
latexmath:[$\max(\lceil{minSampleShading \times rasterizationSamples}\rceil,
|
||||
1)$] unique associated data for each fragment, where pname:minSampleShading
|
||||
is the minimum fraction of sample shading and pname:rasterizationSamples is
|
||||
the number of samples requested in
|
||||
slink:VkPipelineMultisampleStateCreateInfo. These are associated with the
|
||||
samples in an implementation-dependent manner. pname:minSampleShading must:
|
||||
be in the range latexmath:[$[0,1\]$]. When the sample shading fraction is
|
||||
1.0, a separate set of associated data are evaluated for each sample, and
|
||||
each set of values is evaluated at the sample location.
|
||||
|
||||
|
||||
[[primsrast-points]]
|
||||
== Points
|
||||
|
||||
A point is drawn by generating a set of fragments in the shape of a square
|
||||
centered around the vertex of the point. Each vertex has an associated point
|
||||
size that controls the width/height of that square. The point size is taken
|
||||
from the (potentially clipped) shader built-in code:PointSize written by:
|
||||
|
||||
* the geometry shader, if active;
|
||||
* the tessellation evaluation shader, if active and no geometry shader is
|
||||
active;
|
||||
* the tessellation control shader, if active and no geometry or
|
||||
tessellation evaluation shader is active; or
|
||||
* the vertex shader, otherwise
|
||||
|
||||
and clamped to the implementation-dependent point size range
|
||||
latexmath:[$[pointSizeRange[0\],pointSizeRange[1\]\]$]. If the value written
|
||||
to code:PointSize is less than or equal to zero, or if no value was written
|
||||
to code:PointSize, results are undefined.
|
||||
|
||||
Not all point sizes need be supported, but the size 1.0 must: be supported.
|
||||
The range of supported sizes and the size of evenly-spaced gradations within
|
||||
that range are implementation-dependent. The range and gradations are
|
||||
obtained from the pname:pointSizeRange and pname:pointSizeGranularity
|
||||
members of slink:VkPhysicalDeviceLimits. If, for instance, the size range is
|
||||
from 0.1 to 2.0 and the gradation size is 0.1, then the size 0.1, 0.2, ...,
|
||||
1.9, 2.0 are supported. Additional point sizes may: also be supported. There
|
||||
is no requirement that these sizes be equally spaced. If an unsupported
|
||||
size is requested, the nearest supported size is used instead.
|
||||
|
||||
|
||||
[[primsrast-points-basic]]
|
||||
=== Basic Point Rasterization
|
||||
|
||||
Point rasterization produces a fragment for each framebuffer pixel with one
|
||||
or more sample points that intersect a region centered at the point's
|
||||
latexmath:[$(x_f,y_f)$]. This region is a square with side equal to the
|
||||
current point size. Coverage bits that correspond to sample points that
|
||||
intersect the region are 1, other coverage bits are 0.
|
||||
|
||||
All fragments produced in rasterizing a point are assigned the same
|
||||
associated data, which are those of the vertex corresponding to the point.
|
||||
However, the fragment shader built-in code:PointCoord contains point sprite
|
||||
texture coordinates. The latexmath:[$s$] and latexmath:[$t$] point sprite
|
||||
texture coordinates vary from zero to one across the point horizontally
|
||||
left-to-right and top-to-bottom, respectively. The following formulas are
|
||||
used to evaluate latexmath:[$s$] and latexmath:[$t$]:
|
||||
|
||||
[latexmath]
|
||||
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
|
||||
\[
|
||||
s = {1 \over 2} + { \left( x_p - x_f \right) \over size }
|
||||
\]
|
||||
\[
|
||||
t = {1 \over 2} + { \left( y_p - y_f \right) \over size }.
|
||||
\]
|
||||
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
|
||||
|
||||
where size is the point's size, latexmath:[$(x_p,y_p)$] is the location at
|
||||
which the point sprite coordinates are evaluated - this may: be the
|
||||
framebuffer coordinates of the pixel center (i.e. at the half-integer) or
|
||||
the location of a sample, and latexmath:[$(x_f,y_f)$] is the exact,
|
||||
unrounded framebuffer coordinate of the vertex for the point. When
|
||||
pname:rasterizationSamples is ename:VK_SAMPLE_COUNT_1_BIT, the pixel center
|
||||
must: be used.
|
||||
|
||||
|
||||
[[primsrast-lines]]
|
||||
== Line Segments
|
||||
|
||||
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.
|
||||
|
||||
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
|
||||
ename:VK_DYNAMIC_STATE_LINE_WIDTH enabled. Otherwise, the line width is set
|
||||
by calling fname:vkCmdSetLineWidth:
|
||||
|
||||
include::../protos/vkCmdSetLineWidth.txt[]
|
||||
|
||||
* pname:commandBuffer is the command buffer into which the command will be
|
||||
recorded.
|
||||
* pname:lineWidth is the width of rasterized line segments.
|
||||
|
||||
include::../validity/protos/vkCmdSetLineWidth.txt[]
|
||||
|
||||
Not all line widths need be supported for line segment rasterization, but
|
||||
width 1.0 antialiased segments must: be provided. The range and gradations
|
||||
are obtained from the pname:lineWidthRange and pname:lineWidthGranularity
|
||||
members of slink:VkPhysicalDeviceLimits. If, for instance, the size range is
|
||||
from 0.1 to 2.0 and the gradation size is 0.1, then the size 0.1, 0.2, ...,
|
||||
1.9, 2.0 are supported. Additional line widths may: also be supported. There
|
||||
is no requirement that these widths be equally spaced. If an unsupported
|
||||
width is requested, the nearest supported width is used instead.
|
||||
|
||||
|
||||
[[primsrast-lines-basic]]
|
||||
=== Basic Line Segment Rasterization
|
||||
|
||||
Rasterized line segments produce fragments which intersect a rectangle
|
||||
centered on the line segment. Two of the edges are parallel to the specified
|
||||
line segment; each is at a distance of one-half the current width from that
|
||||
segment in directions perpendicular to the direction of the line. The other
|
||||
two edges pass through the line endpoints and are perpendicular to the
|
||||
direction of the specified line segment. Coverage bits that correspond to
|
||||
sample points that intersect the rectangle are 1, other coverage bits are 0.
|
||||
|
||||
Next we specify how the data associated with each rasterized fragment
|
||||
are obtained. Let latexmath:[$\mathbf{p}_r = (x_d, y_d)$] be the
|
||||
framebuffer coordinates at which associated data are evaluated. This may: be
|
||||
the pixel center of a fragment or the location of a sample within the
|
||||
fragment. When pname:rasterizationSamples is ename:VK_SAMPLE_COUNT_1_BIT,
|
||||
the pixel center must: be used. Let latexmath:[$\mathbf{p}_a = (x_a, y_a)$]
|
||||
and latexmath:[$\mathbf{p}_b = (x_b,y_b)$] be initial and final endpoints of
|
||||
the line segment, respectively. Set
|
||||
|
||||
// Equation {linet:eq}
|
||||
[latexmath]
|
||||
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
|
||||
\[
|
||||
t = {{( \mathbf{p}_r - \mathbf{p}_a ) \cdot ( \mathbf{p}_b - \mathbf{p}_a )}
|
||||
\over {\| \mathbf{p}_b - \mathbf{p}_a \|^2 }}
|
||||
\]
|
||||
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
|
||||
|
||||
(Note that latexmath:[$t=0$] at latexmath:[$\mathbf{p}_a$] and
|
||||
latexmath:[$t=1$] at latexmath:[$\mathbf{p}_b$]. Also note that this
|
||||
calculation projects the vector from latexmath:[$\mathbf{p}_a$] to
|
||||
latexmath:[$\mathbf{p}_r$] onto the line, and thus computes the normalized
|
||||
distance of the fragment along the line.)
|
||||
|
||||
The value of an associated datum latexmath:[$f$] for the fragment, whether
|
||||
it be a shader output or the clip latexmath:[$w$] coordinate, is found as
|
||||
|
||||
[[line_perspective_interpolation,Equation line_perspective_interpolation]]
|
||||
.line_perspective_interpolation
|
||||
[latexmath]
|
||||
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
|
||||
\[
|
||||
f = {{ (1-t) {f_a / w_a} + t { f_b / w_b} } \over
|
||||
{(1-t) / w_a + t / w_b }}
|
||||
\]
|
||||
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
|
||||
|
||||
where latexmath:[$f_a$] and latexmath:[$f_b$] are the data associated with
|
||||
the starting and ending endpoints of the segment, respectively;
|
||||
latexmath:[$w_a$] and latexmath:[$w_b$] are the clip latexmath:[$w$]
|
||||
coordinates of the starting and ending endpoints of the segments,
|
||||
respectively. However, depth values for lines must: be interpolated by
|
||||
|
||||
[[line_noperspective_interpolation,Equation line_noperspective_interpolation]]
|
||||
.line_noperspective_interpolation
|
||||
[latexmath]
|
||||
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
|
||||
\[ z = (1-t) z_a + t z_b \]
|
||||
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
|
||||
|
||||
where latexmath:[$z_a$] and latexmath:[$z_b$] are the depth values of the
|
||||
starting and ending endpoints of the segment, respectively.
|
||||
|
||||
The code:NoPerspective and code:Flat
|
||||
<<shaders-interpolation-decorations,interpolation decorations>> can: be used
|
||||
with fragment shader inputs to declare how they are interpolated. When
|
||||
neither decoration is applied, interpolation is performed as described in
|
||||
<<line_perspective_interpolation>>. When the code:NoPerspective decoration
|
||||
is used, interpolation is performed in the same fashion as for depth values,
|
||||
as described in <<line_noperspective_interpolation>>. When the code:Flat
|
||||
decoration is used, no interpolation is performed, and outputs are taken
|
||||
from the corresponding input value of the
|
||||
<<vertexpostproc-flatshading,provoking vertex>> corresponding to that
|
||||
primitive.
|
||||
|
||||
The above description documents the preferred method of line rasterization,
|
||||
and must: be used when the implementation advertises the pname:strictLines
|
||||
limit in slink:VkPhysicalDeviceLimits as ename:VK_TRUE.
|
||||
|
||||
When pname:strictLines is ename:VK_FALSE, the edges of the lines are
|
||||
generated as a parallelogram surrounding the original line. The major axis
|
||||
is chosen by noting the axis in which there is the greatest distance between
|
||||
the line start and end points. If the difference is equal in both directions
|
||||
then the X axis is chosen as the major axis. Edges 2 and 3 are aligned to
|
||||
the minor axis and are centered on the endpoints of the line as in
|
||||
<<fig-non-strict-lines>>, and each is pname:lineWidth long. Edges 0 and 1
|
||||
are parallel to the line and connect the endpoints of edges 2 and 3.
|
||||
Coverage bits that correspond to sample points that intersect the
|
||||
parallelogram are 1, other coverage bits are 0.
|
||||
|
||||
Samples that fall exactly on the edge of the parallelogram follow the
|
||||
polygon rasterization rules.
|
||||
|
||||
Interpolation occurs as if the parallelogram was decomposed into two
|
||||
triangles where each pair of vertices at each end of the line has identical
|
||||
attributes.
|
||||
|
||||
[[fig-non-strict-lines]]
|
||||
.Non strict lines
|
||||
image:images/non_strict_lines.{svgpdf}["Non strict lines",{fullimagewidth}]
|
||||
|
||||
|
||||
[[primsrast-polygons]]
|
||||
== Polygons
|
||||
|
||||
A polygon results from the decomposition of a triangle strip, triangle fan
|
||||
or a series of independent triangles. Like points and line segments,
|
||||
polygon rasterization is controled by several variables in the
|
||||
slink:VkPipelineRasterizationStateCreateInfo structure.
|
||||
|
||||
|
||||
[[primsrast-polygons-basic]]
|
||||
=== Basic Polygon Rasterization
|
||||
|
||||
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
|
||||
coordinates. One way to compute this area is:
|
||||
|
||||
[latexmath]
|
||||
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
|
||||
\[
|
||||
a = -{1 \over 2}\sum_{i=0}^{n-1}
|
||||
x_f^i y_f^{i \oplus 1} -
|
||||
x_f^{i \oplus 1} y_f^i
|
||||
\]
|
||||
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
|
||||
|
||||
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:
|
||||
|
||||
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
|
||||
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.
|
||||
|
||||
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:
|
||||
|
||||
include::../enums/VkCullModeFlagBits.txt[]
|
||||
|
||||
If the pname:cullMode is set to ename:VK_CULL_MODE_NONE no triangles are
|
||||
discarded, if it is set to ename:VK_CULL_MODE_FRONT_BIT front-facing
|
||||
triangles are discarded, if it is set to ename:VK_CULL_MODE_BACK_BIT then
|
||||
back-facing triangles are discarded and if it is set to
|
||||
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.
|
||||
|
||||
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
|
||||
vertices is formed. Fragments are produced for any pixels for which any
|
||||
sample points lie inside of this polygon. Coverage bits that correspond to
|
||||
sample points that satisfy the point sampling criteria are 1, other coverage
|
||||
bits are 0. Special treatment is given to a sample whose sample location
|
||||
lies on a polygon edge. In such a case, if two polygons lie on either side
|
||||
of a common edge (with identical endpoints) on which a sample point lies,
|
||||
then exactly one of the polygons must: result in a covered sample for that
|
||||
fragment during rasterization. As for the data associated with each fragment
|
||||
produced by rasterizing a polygon, we begin by specifying how these values
|
||||
are produced for fragments in a triangle. Define _barycentric coordinates_
|
||||
for a triangle. Barycentric coordinates are a set of three numbers,
|
||||
latexmath:[$a$], latexmath:[$b$], and latexmath:[$c$], each in the range
|
||||
latexmath:[$\lbrack 0, 1\rbrack$], with latexmath:[$a + b + c = 1$]. These
|
||||
coordinates uniquely specify any point latexmath:[$p$] within the triangle
|
||||
or on the triangle's boundary as
|
||||
|
||||
[latexmath]
|
||||
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
|
||||
\[ p = ap_a + bp_b + cp_c \]
|
||||
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
|
||||
|
||||
where latexmath:[$p_a$], latexmath:[$p_b$], and latexmath:[$p_c$] are the
|
||||
vertices of the triangle. latexmath:[$a$], latexmath:[$b$], and
|
||||
latexmath:[$c$] are determined by:
|
||||
|
||||
[latexmath]
|
||||
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
|
||||
\[
|
||||
a = {{\rm A}(p p_b p_c) \over {\rm A}(p_a p_b p_c)}, \quad
|
||||
b = {{\rm A}(p p_a p_c) \over {\rm A}(p_a p_b p_c)}, \quad
|
||||
c = {{\rm A}(p p_a p_b) \over {\rm A}(p_a p_b p_c)},
|
||||
\]
|
||||
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
|
||||
|
||||
where latexmath:[$A(lmn)$] denotes the area in framebuffer coordinates of
|
||||
the triangle with vertices latexmath:[$l$], latexmath:[$n$], and
|
||||
latexmath:[$n$].
|
||||
|
||||
Denote an associated datum at latexmath:[$p_a$], latexmath:[$p_b$], or
|
||||
latexmath:[$p_c$] as latexmath:[$f_a$], latexmath:[$f_b$], or
|
||||
latexmath:[$f_c$], respectively. Then the value latexmath:[$f$] of a datum
|
||||
at a fragment produced by rasterizing a triangle is given by:
|
||||
|
||||
[[triangle_perspective_interpolation,Equation triangle_perspective_interpolation]]
|
||||
.triangle_perspective_interpolation
|
||||
[latexmath]
|
||||
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
|
||||
\[
|
||||
f = {{a{f_a / w_a} + b{f_b / w_b} + c{f_c / w_c}} \over
|
||||
{a / w_a} + {b / w_b} + {c / w_c}}
|
||||
\]
|
||||
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
|
||||
|
||||
where latexmath:[$w_a$], latexmath:[$w_b$], and latexmath:[$w_c$] are the
|
||||
clip latexmath:[$w$] coordinates of latexmath:[$p_a$], latexmath:[$p_b$],
|
||||
and latexmath:[$p_c$], respectively. latexmath:[$a$], latexmath:[$b$], and
|
||||
latexmath:[$c$] are the barycentric coordinates of the location at which
|
||||
the data are produced - this must: be a pixel center or the location of
|
||||
a sample. When pname:rasterizationSamples is
|
||||
ename:VK_SAMPLE_COUNT_1_BIT, the pixel center must: be used. Depth values
|
||||
for triangles must: be interpolated by
|
||||
|
||||
[[triangle_noperspective_interpolation,Equation triangle_noperspective_interpolation]]
|
||||
.triangle_noperspective_interpolation
|
||||
[latexmath]
|
||||
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
|
||||
\[ z = a z_a + b z_b + c z_c \]
|
||||
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
|
||||
|
||||
where latexmath:[$z_a$], latexmath:[$z_b$], and latexmath:[$z_c$] are the
|
||||
depth values of latexmath:[$p_a$], latexmath:[$p_b$], and latexmath:[$p_c$],
|
||||
respectively.
|
||||
|
||||
The code:NoPerspective and code:Flat
|
||||
<<shaders-interpolation-decorations,interpolation decorations>> can: be used
|
||||
with fragment shader inputs to declare how they are interpolated. When
|
||||
neither decoration is applied, interpolation is performed as described in
|
||||
<<triangle_perspective_interpolation>>. When the code:NoPerspective
|
||||
decoration is used, interpolation is performed in the same fashion as for
|
||||
depth values, as described in <<triangle_noperspective_interpolation>>. When
|
||||
the code:Flat decoration is used, no interpolation is performed, and outputs
|
||||
are taken from the corresponding input value of the
|
||||
<<vertexpostproc-flatshading,provoking vertex>> corresponding to that
|
||||
primitive.
|
||||
|
||||
For a polygon with more than three edges, such as are produced by clipping a
|
||||
triangle, a convex combination of the values of the datum at the polygon's
|
||||
vertices must: be used to obtain the value assigned to each fragment
|
||||
produced by the rasterization algorithm. That is, it must: be the case that
|
||||
at every fragment
|
||||
|
||||
[latexmath]
|
||||
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
|
||||
\[ f = \sum_{i=1}^{n} a_i f_i \]
|
||||
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
|
||||
|
||||
where latexmath:[$n$] is the number of vertices in the polygon and
|
||||
latexmath:[$f_i$] is the value of the latexmath:[$f$] at vertex
|
||||
latexmath:[$i$]. For each latexmath:[$i$], latexmath:[$0 \leq a_i \leq 1$]
|
||||
and latexmath:[$\sum_{i=1}^{n}a_i = 1$]. The values of latexmath:[$a_i$]
|
||||
may: differ from fragment to fragment, but at vertex latexmath:[$i$],
|
||||
latexmath:[$a_i = 1$] and latexmath:[$a_j = 0$] for latexmath:[$j \neq i$].
|
||||
|
||||
[NOTE]
|
||||
.Note
|
||||
====
|
||||
One algorithm that achieves the required behavior is to triangulate a
|
||||
polygon (without adding any vertices) and then treat each triangle
|
||||
individually as already discussed. A scan-line rasterizer that linearly
|
||||
interpolates data along each edge and then linearly interpolates data across
|
||||
each horizontal span from edge to edge also satisfies the restrictions (in
|
||||
this case, the numerator and denominator of equation
|
||||
<<triangle_perspective_interpolation>> are iterated independently and
|
||||
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:
|
||||
|
||||
include::../enums/VkPolygonMode.txt[]
|
||||
|
||||
The pname:polygonMode selects which method of rasterization is used for
|
||||
polygons. If pname:polygonMode is ename:VK_POLYGON_MODE_POINT, then the
|
||||
vertices of polygons are treated, for rasterization purposes, as if they had
|
||||
been drawn as points. ename:VK_POLYGON_MODE_LINE causes polygon edges to be
|
||||
drawn as line segments. ename:VK_POLYGON_MODE_FILL causes polygons to render
|
||||
using the polygon rasterization rules in this section.
|
||||
|
||||
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.
|
||||
|
||||
|
||||
[[primsrast-depthbias]]
|
||||
=== Depth Bias
|
||||
|
||||
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,
|
||||
pname:depthBiasConstantFactor, pname:depthBiasClamp, and
|
||||
pname:depthBiasSlopeFactor members of
|
||||
slink:VkPipelineRasterizationStateCreateInfo, or by the corresponding
|
||||
parameters to the fname:vkCmdSetDepthBias command if depth bias state is
|
||||
dynamic.
|
||||
|
||||
include::../protos/vkCmdSetDepthBias.txt[]
|
||||
|
||||
* pname:commandBuffer is the command buffer into which the command will be
|
||||
recorded.
|
||||
* pname:depthBiasConstantFactor is a scalar factor controlling the
|
||||
constant depth value added to each fragment.
|
||||
* pname:depthBiasClamp is the maximum (or minimum) depth bias of a
|
||||
fragment.
|
||||
* 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.
|
||||
|
||||
pname:depthBiasSlopeFactor scales the maximum depth slope of the polygon,
|
||||
and pname:depthBiasConstantFactor scales an implementation-dependent
|
||||
constant that relates to the usable resolution of the depth buffer. The
|
||||
resulting values are summed to produce the depth bias value which is then
|
||||
clamped to a minimum or maximum value specified by pname:depthBiasClamp.
|
||||
pname:depthBiasSlopeFactor, pname:depthBiasConstantFactor, and
|
||||
pname:depthBiasClamp can: each be positive, negative, or zero.
|
||||
|
||||
The maximum depth slope latexmath:[$m$] of a triangle is
|
||||
|
||||
[latexmath]
|
||||
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
|
||||
\begin{equation}
|
||||
m = \sqrt{ \left({\partial z_f \over \partial x_f}\right)^2
|
||||
+ \left({\partial z_f \over \partial y_f}\right)^2}
|
||||
\end{equation}
|
||||
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
|
||||
|
||||
where latexmath:[$(x_f, y_f, z_f)$] is a point on the triangle.
|
||||
latexmath:[$m$] may: be approximated as
|
||||
|
||||
[latexmath]
|
||||
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
|
||||
\begin{equation}
|
||||
m = \max \left \{ \left |{\partial z_f \over \partial x_f} \right |,
|
||||
\left |{\partial z_f \over \partial y_f} \right | \right \}.
|
||||
\end{equation}
|
||||
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
|
||||
|
||||
The minimum resolvable difference latexmath:[$r$] is an
|
||||
implementation-dependent parameter that depends on the depth buffer
|
||||
representation. It is the smallest difference in framebuffer coordinate
|
||||
latexmath:[$z$] values that is guaranteed to remain distinct throughout
|
||||
polygon rasterization and in the depth buffer. All pairs of fragments
|
||||
generated by the rasterization of two polygons with otherwise identical
|
||||
vertices, but latexmath:[$z_f$] values that differ by $r$, will have
|
||||
distinct depth values.
|
||||
|
||||
For fixed-point depth buffer representations, latexmath:[$r$] is constant
|
||||
throughout the range of the entire depth buffer. For floating-point depth
|
||||
buffers, there is no single minimum resolvable difference. In this case, the
|
||||
minimum resolvable difference for a given polygon is dependent on the
|
||||
maximum exponent, latexmath:[$e$], in the range of latexmath:[$z$] values
|
||||
spanned by the primitive. If latexmath:[$n$] is the number of bits in the
|
||||
floating-point mantissa, the minimum resolvable difference, latexmath:[$r$],
|
||||
for the given primitive is defined as
|
||||
|
||||
[latexmath]
|
||||
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
|
||||
\begin{equation}
|
||||
r = 2^{e - n}
|
||||
\end{equation}
|
||||
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
|
||||
|
||||
If no depth buffer is present, latexmath:[$r$] is undefined.
|
||||
|
||||
The bias value latexmath:[$o$] for a polygon is
|
||||
|
||||
[latexmath]
|
||||
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
|
||||
\begin{equation}
|
||||
o =
|
||||
\begin{cases}
|
||||
m \times depthBiasSlopeFactor +
|
||||
r \times depthBiasConstantFactor & depthBiasClamp = 0\ or\ NaN \\
|
||||
\min(m \times depthBiasSlopeFactor +
|
||||
r \times depthBiasConstantFactor,
|
||||
depthBiasClamp) & depthBiasClamp > 0 \\
|
||||
\max(m \times depthBiasSlopeFactor +
|
||||
r \times depthBiasConstantFactor,
|
||||
depthBiasClamp) & depthBiasClamp < 0 \\
|
||||
\end{cases}
|
||||
\end{equation}
|
||||
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
|
||||
|
||||
latexmath:[$m$] is computed as described above. If the depth buffer uses a
|
||||
fixed-point representation, latexmath:[$m$] is a function of depth values in
|
||||
the range latexmath:[$[0,1\]$], and latexmath:[$o$] is applied to depth
|
||||
values in the same range.
|
||||
|
||||
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.
|
||||
|
|
@ -0,0 +1,648 @@
|
|||
// Copyright (c) 2015-2016 The Khronos Group Inc.
|
||||
// Copyright notice at https://www.khronos.org/registry/speccopyright.html
|
||||
|
||||
[[queries]]
|
||||
= Queries
|
||||
|
||||
_Queries_ provide a mechanism to return information about the processing of
|
||||
a sequence of {apiname} commands. Query operations are asynchronous, and as
|
||||
such, their results are not returned immediately. Instead, their results,
|
||||
and their availability status, are stored in a <<queries-pools, Query
|
||||
Pool>>. The state of these queries can: be read back on the host, or copied
|
||||
to a buffer object on the device.
|
||||
|
||||
The supported query types are <<queries-occlusion,Occlusion Queries>>,
|
||||
<<queries-pipestats,Pipeline Statistics Queries>>, and
|
||||
<<queries-timestamps, Timestamp Queries>>.
|
||||
|
||||
|
||||
[[queries-pools]]
|
||||
== Query Pools
|
||||
|
||||
Queries are managed using _query pool_ objects. Each query pool is a
|
||||
collection of a specific number of queries of a particular type.
|
||||
|
||||
To create a query pool, call:
|
||||
|
||||
include::../protos/vkCreateQueryPool.txt[]
|
||||
|
||||
* pname:device is the logical device that creates the query pool.
|
||||
* pname:pCreateInfo is a pointer to an instance of the
|
||||
sname:VkQueryPoolCreateInfo structure containing the number and type of
|
||||
queries to be managed by the pool.
|
||||
* pname:pAllocator controls host memory allocation as described in the
|
||||
<<memory-allocation, Memory Allocation>> chapter.
|
||||
* pname:pQueryPool is a pointer to a sname:VkQueryPool handle in which the
|
||||
resulting query pool object is returned.
|
||||
|
||||
include::../validity/protos/vkCreateQueryPool.txt[]
|
||||
|
||||
The definition of sname:VkQueryPoolCreateInfo is:
|
||||
|
||||
include::../structs/VkQueryPoolCreateInfo.txt[]
|
||||
|
||||
The members of sname:VkQueryPoolCreateInfo have the following meanings:
|
||||
|
||||
* 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:queryType is the type of queries managed by the pool,
|
||||
and must: be one of the values
|
||||
+
|
||||
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
|
||||
<<queries-pipestats>>. pname:pipelineStatistics is ignored if
|
||||
pname:queryType is not ename:VK_QUERY_TYPE_PIPELINE_STATISTICS.
|
||||
|
||||
include::../validity/structs/VkQueryPoolCreateInfo.txt[]
|
||||
|
||||
To destroy a query pool, call:
|
||||
|
||||
include::../protos/vkDestroyQueryPool.txt[]
|
||||
|
||||
* pname:device is the logical device that destroys the query pool.
|
||||
* pname:queryPool is the query pool to destroy.
|
||||
* pname:pAllocator controls host memory allocation as described in the
|
||||
<<memory-allocation, Memory Allocation>> chapter.
|
||||
|
||||
include::../validity/protos/vkDestroyQueryPool.txt[]
|
||||
|
||||
|
||||
[[queries-operation]]
|
||||
== Query Operation
|
||||
|
||||
The operation of queries is controlled by the commands
|
||||
flink:vkCmdBeginQuery, flink:vkCmdEndQuery, flink:vkCmdResetQueryPool,
|
||||
flink:vkCmdCopyQueryPoolResults, and flink:vkCmdWriteTimestamp.
|
||||
|
||||
In order for a sname:VkCommandBuffer to record query management commands,
|
||||
the queue family for which its sname:VkCommandPool was created must:
|
||||
support the appropriate type of operations (graphics, compute) suitable
|
||||
for the query type of a given query pool.
|
||||
|
||||
Each query in a query pool has a status that is either _unavailable_ or
|
||||
_available_, and also has state to store the numerical results of a query
|
||||
operation of the type requested when the query pool was created. Resetting a
|
||||
query via flink:vkCmdResetQueryPool sets the status to unavailable and
|
||||
makes the numerical results undefined. Performing a query operation with
|
||||
flink:vkCmdBeginQuery and flink:vkCmdEndQuery changes the status to
|
||||
available when the query <<queries-operation-finished,finishes>>,
|
||||
and updates the numerical results.
|
||||
Both the availability status and numerical results are retrieved by calling
|
||||
either flink:vkGetQueryPoolResults or flink:vkCmdCopyQueryPoolResults.
|
||||
|
||||
All query commands execute in order and are guaranteed to see the effects of
|
||||
each other's memory accesses, with one significant exception:
|
||||
fname:vkCmdCopyQueryPoolResults may: execute before the results of
|
||||
fname:vkCmdEndQuery are available. However, if
|
||||
ename:VK_QUERY_RESULT_WAIT_BIT is used, then fname:vkCmdCopyQueryPoolResults
|
||||
must: reflect the result of any previously executed queries. Other sequences
|
||||
of commands, such as fname:vkCmdResetQueryPool followed by
|
||||
fname:vkCmdBeginQuery, must: make the effects of the first command visible
|
||||
to the second command.
|
||||
|
||||
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.
|
||||
|
||||
To reset a range of queries in a query pool, call:
|
||||
|
||||
include::../protos/vkCmdResetQueryPool.txt[]
|
||||
|
||||
* pname:commandBuffer is the command buffer into which this command will
|
||||
be recorded.
|
||||
* pname:queryPool is the handle of the query pool managing the queries
|
||||
being reset.
|
||||
* pname:firstQuery is the initial query index to reset.
|
||||
* pname:queryCount is the number of queries to reset.
|
||||
|
||||
When executed on a queue, this command sets the status of query indices
|
||||
latexmath:[$firstQuery,firstQuery+queryCount-1$] to unavailable.
|
||||
|
||||
include::../validity/protos/vkCmdResetQueryPool.txt[]
|
||||
|
||||
Once queries are reset and ready for use, query commands can: be
|
||||
issued to a command buffer. Occlusion queries and pipeline statistics
|
||||
queries count events - drawn samples and pipeline stage invocations,
|
||||
respectively - resulting from commands that are recorded between a
|
||||
flink:vkCmdBeginQuery command and a flink:vkCmdEndQuery command within
|
||||
a specified command buffer, effectively scoping a set of drawing and/or
|
||||
compute commands. Timestamp queries write timestamps to a query pool.
|
||||
|
||||
A query must: begin and end in the same command buffer, although if it is a
|
||||
primary command buffer, and the
|
||||
<<features-features-inherited-queries,inherited queries>> feature is
|
||||
enabled, it can: execute secondary command buffers during the query
|
||||
operation. For a secondary command buffer to be executed while a query is
|
||||
active, it must: set the pname:occlusionQueryEnable, pname:queryFlags,
|
||||
and/or pname:pipelineStatistics members of slink:VkCommandBufferBeginInfo to
|
||||
conservative values, as described in the <<commandbuffers-recording, Command
|
||||
Buffer Recording>> section. A query must: either begin and end inside the
|
||||
same subpass of a render pass instance, or must: both begin and end outside
|
||||
of a render pass instance (i.e. contain entire render pass instances).
|
||||
|
||||
Begin a query by calling:
|
||||
|
||||
include::../protos/vkCmdBeginQuery.txt[]
|
||||
|
||||
* pname:commandBuffer is the command buffer into which this command will
|
||||
be recorded.
|
||||
* pname:queryPool is the query pool that will manage the results of the
|
||||
query.
|
||||
* 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:
|
||||
+
|
||||
include::../enums/VkQueryControlFlagBits.txt[]
|
||||
|
||||
If the pname:queryType of the pool is ename:VK_QUERY_TYPE_OCCLUSION and
|
||||
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
|
||||
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::../protos/vkCmdEndQuery.txt[]
|
||||
|
||||
* pname:commandBuffer is the command buffer into which this command will
|
||||
be recorded.
|
||||
* pname:queryPool is the query pool that is managing the results of the
|
||||
query.
|
||||
* 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_
|
||||
when the final results of the query are ready to be retrieved by
|
||||
flink:vkGetQueryPoolResults and flink:vkCmdCopyQueryPoolResults, and this
|
||||
is when the query's status is set to available.
|
||||
|
||||
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.
|
||||
|
||||
[[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
|
||||
sname:VkBuffer. In either case, the layout in memory is defined as follows:
|
||||
|
||||
* The first query's result is written starting at the first byte requested
|
||||
by the command, and each subsequent query's result begins pname:stride
|
||||
bytes later.
|
||||
* Each query's result is a tightly packed array of unsigned integers,
|
||||
either 32- or 64-bits as requested by the command, storing the numerical
|
||||
results and, if requested, the availability status.
|
||||
* If ename:VK_QUERY_RESULT_WITH_AVAILABILITY_BIT is used, the final
|
||||
element of each query's result is an integer indicating whether the
|
||||
query's result is available, with any non-zero value indicating that
|
||||
it is available.
|
||||
* Occlusion queries write one integer value - the number of samples
|
||||
passed. Pipeline statistics queries write one integer value for each bit
|
||||
that is enabled in the pname:pipelineStatistics when the pool is
|
||||
created, and the statistics values are written in bit order starting
|
||||
from the least significant bit. Timestamps write one integer value.
|
||||
* If more than one query is retrieved and pname:stride is not at least as
|
||||
large as the size of the array of integers corresponding to a single
|
||||
query, the values written to memory are undefined.
|
||||
|
||||
To retrieve status and results for a set of queries, call:
|
||||
|
||||
include::../protos/vkGetQueryPoolResults.txt[]
|
||||
|
||||
* pname:device is the logical device that owns the query pool.
|
||||
* pname:queryPool is the query pool managing the queries containing the
|
||||
desired results.
|
||||
* pname:firstQuery is the initial query index.
|
||||
* pname:queryCount is the number of queries. pname:firstQuery and
|
||||
pname:queryCount together define a range of queries.
|
||||
* pname:dataSize is the size in bytes of the buffer pointed to by
|
||||
pname:pData.
|
||||
* pname:pData is a pointer to a user-allocated buffer
|
||||
where the results will be written
|
||||
* 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:
|
||||
|
||||
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 {apiname} 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
|
||||
32-bit unsigned integer values. The behavior when not all queries
|
||||
are available, is described <<queries-wait-bit-not-set, below>>.
|
||||
|
||||
If ename:VK_QUERY_RESULT_64_BIT is not set and the result overflows a
|
||||
32-bit value, the value may: either wrap or saturate. Similarly, if
|
||||
ename:VK_QUERY_RESULT_64_BIT is set and the result overflows a 64-bit
|
||||
value, the value may: either wrap or saturate.
|
||||
|
||||
If ename:VK_QUERY_RESULT_WAIT_BIT is set, {apiname} will wait for each
|
||||
query to be in the available state before retrieving the numerical
|
||||
results for that query. In this case, fname:vkGetQueryPoolResults is
|
||||
guaranteed to succeed and return ename:VK_SUCCESS if the queries
|
||||
become available in a finite time (i.e. if they have been issued and not
|
||||
reset). If queries will never finish (e.g. due to being reset but not
|
||||
issued), then fname:vkGetQueryPoolResults maynot: return in finite time.
|
||||
|
||||
[[queries-wait-bit-not-set]]
|
||||
If ename:VK_QUERY_RESULT_WAIT_BIT and ename:VK_QUERY_RESULT_PARTIAL_BIT
|
||||
are both not set then no result values are written to pname:pData for
|
||||
queries that are in the unavailable state at the time of the call,
|
||||
and fname:vkGetQueryPoolResults returns ename:VK_NOT_READY.
|
||||
However, availability state is still written to pname:pData for those
|
||||
queries if ename:VK_QUERY_RESULT_WITH_AVAILABILITY_BIT is set.
|
||||
|
||||
[NOTE]
|
||||
.Note
|
||||
====
|
||||
Applications must: take care to ensure that use of the
|
||||
ename:VK_QUERY_RESULT_WAIT_BIT bit has the desired effect.
|
||||
|
||||
For example, if a query has been used previously and a command buffer
|
||||
records the commands fname:vkCmdResetQueryPool, fname:vkCmdBeginQuery, and
|
||||
fname:vkCmdEndQuery for that query, then the query will remain
|
||||
in the available state until the fname:vkCmdResetQueryPool command
|
||||
executes on a queue. Applications can: use fences or events to ensure that
|
||||
an query has already been reset before checking for its results or
|
||||
availability status. Otherwise, a stale value could be returned from a
|
||||
previous use of the query.
|
||||
|
||||
The above also applies when ename:VK_QUERY_RESULT_WAIT_BIT is used in
|
||||
combination with ename:VK_QUERY_RESULT_WITH_AVAILABILITY_BIT. In this
|
||||
case, the returned availability status may: reflect the result of a
|
||||
previous use of the query unless the fname:vkCmdResetQueryPool command
|
||||
has been executed since the last use of the query.
|
||||
====
|
||||
|
||||
[NOTE]
|
||||
.Note
|
||||
====
|
||||
Applications can: double-buffer query pool usage, with a pool per
|
||||
frame, and reset queries at the end of the frame in which they
|
||||
are read.
|
||||
====
|
||||
|
||||
If ename:VK_QUERY_RESULT_PARTIAL_BIT is set, ename:VK_QUERY_RESULT_WAIT_BIT
|
||||
is not set, and the query's status is unavailable, an intermediate
|
||||
result value between zero and the final result value is written to
|
||||
pname:pData for that query.
|
||||
|
||||
ename:VK_QUERY_RESULT_PARTIAL_BIT mustnot: be used if the pool's
|
||||
pname:queryType is ename:VK_QUERY_TYPE_TIMESTAMP.
|
||||
|
||||
If ename:VK_QUERY_RESULT_WITH_AVAILABILITY_BIT is set, the final integer
|
||||
value written for each query is non-zero if the query's status was
|
||||
available or zero if the status was unavailable. When
|
||||
ename:VK_QUERY_RESULT_WITH_AVAILABILITY_BIT is used, implementations must:
|
||||
guarantee that if they return a non-zero availability value then the
|
||||
numerical results must: be valid, assuming the results are not reset by a
|
||||
subsequent command.
|
||||
|
||||
[NOTE]
|
||||
.Note
|
||||
====
|
||||
Satisfying this guarantee may: require careful ordering by the application,
|
||||
e.g. to read the availability status before reading the results.
|
||||
====
|
||||
|
||||
include::../validity/protos/vkGetQueryPoolResults.txt[]
|
||||
|
||||
To copy query statuses and numerical results directly to buffer memory,
|
||||
call:
|
||||
|
||||
include::../protos/vkCmdCopyQueryPoolResults.txt[]
|
||||
|
||||
* pname:commandBuffer is the command buffer into which this command will
|
||||
be recorded.
|
||||
* pname:queryPool is the query pool managing the queries containing the
|
||||
desired results.
|
||||
* pname:firstQuery is the initial query index.
|
||||
* pname:queryCount is the number of queries. pname:firstQuery and
|
||||
pname:queryCount together define a range of queries.
|
||||
* pname:dstBuffer is a sname:VkBuffer object that will receive the results
|
||||
of the copy command.
|
||||
* pname:dstOffset is an offset into pname:dstBuffer.
|
||||
* pname:stride is the stride in bytes between results for individual
|
||||
queries within pname:dstBuffer. The required size of the backing memory
|
||||
for pname:dstBuffer is determined as described above for
|
||||
flink:vkGetQueryPoolResults.
|
||||
* pname:flags is a bitmask of elink:VkQueryResultFlagBits specifying how
|
||||
and when results are returned.
|
||||
|
||||
fname:vkCmdCopyQueryPoolResults is guaranteed to see the effect of previous
|
||||
uses of fname:vkCmdResetQueryPool in the same queue, without any additional
|
||||
synchronization. Thus, the results will always reflect the most
|
||||
recent use of the query.
|
||||
|
||||
pname:flags has the same possible values described above for the param:flags
|
||||
parameter of flink:vkGetQueryPoolResults, but the different style of
|
||||
execution causes some subtle behavioral differences. Because
|
||||
fname:vkCmdCopyQueryPoolResults executes in order with respect to other
|
||||
query commands, there is less ambiguity about which use of a query is being
|
||||
requested.
|
||||
|
||||
If no bits are set in pname:flags, results for all requested queries in the
|
||||
available state are written as 32-bit unsigned integer values, and nothing
|
||||
is written for queries in the unavailable state.
|
||||
|
||||
If ename:VK_QUERY_RESULT_64_BIT is set, the results are written as an array
|
||||
of 64-bit unsigned integer values as described for
|
||||
flink:vkGetQueryPoolResults.
|
||||
|
||||
If ename:VK_QUERY_RESULT_WAIT_BIT is set, the implementation will wait for
|
||||
each query's status to be in the available state before retrieving the
|
||||
numerical results for that query. This is guaranteed to reflect the most
|
||||
recent use of the query on the same queue, assuming that the query is
|
||||
not being simultaneously used by other queues. If the query does not become
|
||||
available in a finite amount of time (e.g. due to not issuing a query
|
||||
since the last reset), a ename:VK_ERROR_DEVICE_LOST error may: occur.
|
||||
|
||||
Similarly, if ename:VK_QUERY_RESULT_WITH_AVAILABILITY_BIT is set and
|
||||
ename:VK_QUERY_RESULT_WAIT_BIT is not set, the availability is guaranteed to
|
||||
reflect the most recent use of the query on the same queue, assuming
|
||||
that the query is not being simultaneously used by other queues. As with
|
||||
fname:vkGetQueryPoolResults, implementations must: guarantee that if they
|
||||
return a non-zero availability value, then the numerical results are valid.
|
||||
|
||||
If ename:VK_QUERY_RESULT_PARTIAL_BIT is set, ename:VK_QUERY_RESULT_WAIT_BIT
|
||||
is not set, and the query's status is unavailable, an intermediate
|
||||
result value between zero and the final result value is written for that
|
||||
query.
|
||||
|
||||
ename:VK_QUERY_RESULT_PARTIAL_BIT mustnot: be used if the pool's
|
||||
pname:queryType is ename:VK_QUERY_TYPE_TIMESTAMP.
|
||||
|
||||
fname:vkCmdCopyQueryPoolResults is considered to be a transfer operation,
|
||||
and its writes to buffer memory must: be synchronized using
|
||||
ename:VK_PIPELINE_STAGE_TRANSFER_BIT and
|
||||
ename:VK_ACCESS_TRANSFER_WRITE_BIT before using the results.
|
||||
|
||||
include::../validity/protos/vkCmdCopyQueryPoolResults.txt[]
|
||||
|
||||
|
||||
[[queries-operation-undefined]]
|
||||
Rendering operations such as clears, MSAA resolves, attachment load/store
|
||||
operations, and blits may: or maynot: count towards the results of queries.
|
||||
This behavior is implementation-dependent and may: vary depending on the
|
||||
path used within an implementation. For example, some implementations have
|
||||
several types of clears, some of which may: include vertices and some not.
|
||||
|
||||
|
||||
[[queries-occlusion]]
|
||||
== Occlusion Queries
|
||||
|
||||
Occlusion queries track the number of samples that pass the per-fragment
|
||||
tests for a set of drawing commands. As such, occlusion queries are only
|
||||
available on queue families supporting graphics operations. The application
|
||||
can: then use these results to inform future rendering decisions. An
|
||||
occlusion query is begun and ended by calling fname:vkCmdBeginQuery and
|
||||
fname:vkCmdEndQuery, respectively. When an occlusion query begins, the count
|
||||
of passing samples always starts at zero. For each drawing command, the
|
||||
count is incremented as described in <<fragops-samplecount,Sample
|
||||
Counting>>. If pname:flags does not contain
|
||||
ename:VK_QUERY_CONTROL_PRECISE_BIT an implementation may: generate any
|
||||
non-zero result value for the query if the count of passing samples is
|
||||
non-zero.
|
||||
|
||||
[NOTE]
|
||||
.Note
|
||||
====
|
||||
Not setting ename:VK_QUERY_CONTROL_PRECISE_BIT mode may: be more efficient
|
||||
on some implementations, and should: be used where it is sufficient to know
|
||||
a boolean result on whether any samples passed the per-fragment tests. In
|
||||
this case, some implementations may: only return zero or one, indifferent of
|
||||
the actual number of samples passing the per-fragment tests.
|
||||
====
|
||||
|
||||
When an occlusion query finishes, the result for that query is marked
|
||||
as available. The application can: then either copy the result to a buffer
|
||||
(via fname:vkCmdCopyQueryPoolResults) or request it be put into host memory
|
||||
(via fname:vkGetQueryPoolResults).
|
||||
|
||||
[NOTE]
|
||||
.Note
|
||||
====
|
||||
If occluding geometry is not drawn first, samples can: pass the depth test,
|
||||
but still not be visible in a final image.
|
||||
====
|
||||
|
||||
|
||||
[[queries-pipestats]]
|
||||
== Pipeline Statistics Queries
|
||||
|
||||
Pipeline statistics queries allow the application to sample a specified set
|
||||
of sname:VkPipeline counters. These counters are accumulated by {apiname}
|
||||
for a set of either draw or dispatch commands while a pipeline statistics
|
||||
query is active. As such, pipeline statistics queries are available on
|
||||
queue families supporting either graphics or compute operations. Further,
|
||||
the availability of pipeline statistics queries is indicated by the
|
||||
pname:pipelineStatisticsQuery member of the sname:VkPhysicalDeviceFeatures
|
||||
object (see fname:vkGetPhysicalDeviceFeatures and fname:vkCreateDevice for
|
||||
detecting and requesting this query type on a sname:VkDevice).
|
||||
|
||||
A pipeline statistics query is begun and ended by calling
|
||||
fname:vkCmdBeginQuery and fname:vkCmdEndQuery, respectively. When a pipeline
|
||||
statistics query begins, all statistics counters are set to zero. While the
|
||||
query is active, the pipeline type determines which set of statistics are
|
||||
available, but these must: be configured on the query pool when it is
|
||||
created. If a statistic counter is issued on a command buffer that does
|
||||
not support the corresponding operation, the value of that counter is
|
||||
undefined after the query has finished. At least one statistic counter
|
||||
relevant to the operations supported on the recording command buffer
|
||||
must: be enabled.
|
||||
|
||||
pname:pipelineStatisticsQuery is a bitmask indicating different
|
||||
possible pipeline statistics.
|
||||
|
||||
Valid bits in pname:flags include:
|
||||
|
||||
include::../enums/VkQueryPipelineStatisticFlagBits.txt[]
|
||||
|
||||
These bits have the following meanings:
|
||||
|
||||
* If ename:VK_QUERY_PIPELINE_STATISTIC_INPUT_ASSEMBLY_VERTICES_BIT is set,
|
||||
queries managed by the pool will count the number of vertices processed
|
||||
by the <<drawing,input assembly>> stage. Vertices
|
||||
corresponding to incomplete primitives may: or maynot: contribute to the
|
||||
count.
|
||||
* If ename:VK_QUERY_PIPELINE_STATISTIC_INPUT_ASSEMBLY_PRIMITIVES_BIT is
|
||||
set, queries managed by the pool will count the number of primitives
|
||||
processed by the <<drawing,input assembly>> stage. If
|
||||
primitive restart is enabled, restarting the primitive topology has no
|
||||
effect on the count. Incomplete primitives may: or maynot: be counted.
|
||||
* If ename:VK_QUERY_PIPELINE_STATISTIC_VERTEX_SHADER_INVOCATIONS_BIT is
|
||||
set, queries managed by the pool will count the number of vertex shader
|
||||
invocations. This counter's value is incremented each time a vertex
|
||||
shader is <<shaders-vertex-execution,invoked>>.
|
||||
* If ename:VK_QUERY_PIPELINE_STATISTIC_GEOMETRY_SHADER_INVOCATIONS_BIT is
|
||||
set, queries managed by the pool will count the number of geometry
|
||||
shader invocations. This counter's value is incremented each time a
|
||||
geometry shader is <<shaders-geometry-execution,invoked>>. In case of
|
||||
of <<geometry-invocations,instanced geometry shaders>>, the geometry
|
||||
shader invocations count is incremented for each separate instanced
|
||||
invocation.
|
||||
* If ename:VK_QUERY_PIPELINE_STATISTIC_GEOMETRY_SHADER_PRIMITIVES_BIT is
|
||||
set, queries managed by the pool will count the number of primitives
|
||||
generated by geometry shader invocations. The counter's value is
|
||||
incremented each time the geometry shader emits a primitive. Restarting
|
||||
primitive topology using the SPIR-V instructions code:OpEndPrimitive or
|
||||
code:OpEndStreamPrimitive has no effect on the geometry shader output
|
||||
primitives count.
|
||||
* If ename:VK_QUERY_PIPELINE_STATISTIC_CLIPPING_INVOCATIONS_BIT is set,
|
||||
queries managed by the pool will count the number of primitives
|
||||
processed by the <<vertexpostproc-clipping,Primitive Clipping>> stage of
|
||||
the pipeline. The counter's value is incremented each time a primitive
|
||||
reaches the primitive clipping stage.
|
||||
* If ename:VK_QUERY_PIPELINE_STATISTIC_CLIPPING_PRIMITIVES_BIT is set,
|
||||
queries managed by the pool will count the number of primitives output
|
||||
by the <<vertexpostproc-clipping,Primitive Clipping>> stage of the
|
||||
pipeline. The counter's value is incremented each time a primitive
|
||||
passes the primitive clipping stage. The actual number of primitives
|
||||
output by the primitive clipping stage for a particular input primitive
|
||||
is implementation-dependent but must: satisfy the following conditions:
|
||||
** If at least one vertex of the input primitive lies inside the clipping
|
||||
volume, the counter is incremented by one or more.
|
||||
** Otherwise, the counter is incremented by zero or more.
|
||||
* If ename:VK_QUERY_PIPELINE_STATISTIC_FRAGMENT_SHADER_INVOCATIONS_BIT is
|
||||
set, queries managed by the pool will count the number of fragment
|
||||
shader invocations. The counter's value is incremented each time the
|
||||
fragment shader is <<shaders-fragment-execution,invoked>>.
|
||||
* If
|
||||
ename:VK_QUERY_PIPELINE_STATISTIC_TESSELLATION_CONTROL_SHADER_PATCHES_BIT
|
||||
is set, queries managed by the pool will count the number of patches
|
||||
processed by the tessellation control shader. The counter's value is
|
||||
incremented once for each patch for which a tessellation control shader
|
||||
is <<shaders-tessellation-control-execution,invoked>>.
|
||||
* If
|
||||
ename:VK_QUERY_PIPELINE_STATISTIC_TESSELLATION_EVALUATION_SHADER_INVOCATIONS_BIT
|
||||
is set, queries managed by the pool will count the number of invocations
|
||||
of the tessellation evaluation shader. The counter's value is
|
||||
incremented each time the tessellation evaluation shader is
|
||||
<<shaders-tessellation-evaluation-execution,invoked>>.
|
||||
* If ename:VK_QUERY_PIPELINE_STATISTIC_COMPUTE_SHADER_INVOCATIONS_BIT is
|
||||
set, queries managed by the pool will count the number of compute shader
|
||||
invocations. The counter's value is incremented every time the compute
|
||||
shader is invoked. Implementations may: skip the execution of certain
|
||||
compute shader invocations or execute additional compute shader
|
||||
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
|
||||
<<queries-operation-undefined,Query Operation>>.
|
||||
|
||||
[NOTE]
|
||||
.Note
|
||||
====
|
||||
For example, tile-based rendering devices may: need to replay the scene
|
||||
multiple times, affecting some of the counts.
|
||||
====
|
||||
|
||||
If a pipeline has pname:rasterizerDiscardEnable enabled, implementations
|
||||
may: discard primitives after the final vertex processing stage. As a
|
||||
result, if pname:rasterizerDiscardEnable is enabled, the clipping input and
|
||||
output primitives counters maynot: be incremented.
|
||||
|
||||
When a pipeline statistics query finishes, the result for that query is
|
||||
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).
|
||||
|
||||
|
||||
[[queries-timestamps]]
|
||||
== Timestamp Queries
|
||||
|
||||
_Timestamps_ provide applications with a mechanism for timing the execution
|
||||
of commands. A timestamp is an integer value generated by the
|
||||
sname:VkPhysicalDevice. Unlike other queries, timestamps do not operate over
|
||||
a range, and so do not use flink:vkCmdBeginQuery or flink:vkCmdEndQuery. The
|
||||
mechanism is built around a set of commands that allow the application to
|
||||
tell the sname:VkPhysicalDevice to write timestamp values to a
|
||||
<<queries-pools,query pool>> and then either read timestamp values on the
|
||||
host (using flink:vkGetQueryPoolResults) or copy timestamp values to a
|
||||
sname:VkBuffer (using flink:vkCmdCopyQueryPoolResults). The application can:
|
||||
then compute differences between timestamps to determine execution time.
|
||||
|
||||
The number of valid bits in a timestamp value is determined by the
|
||||
sname:VkQueueFamilyProperties::pname:timestampValidBits property of the
|
||||
queue on which the timestamp is written. Timestamps are supported on any
|
||||
queue which reports a non-zero value for pname:timestampValidBits via
|
||||
flink:vkGetPhysicalDeviceQueueFamilyProperties.
|
||||
If the <<features-limits-timestampComputeAndGraphics,
|
||||
pname:timestampComputeAndGraphics>> limit is ename:VK_TRUE, timestamps
|
||||
are supported by every queue family that supports either
|
||||
graphics or compute operations (see slink:VkQueueFamilyProperties).
|
||||
|
||||
The number of nanoseconds it takes for a timestamp value to be
|
||||
incremented by 1 can: be obtained from
|
||||
sname:VkPhysicalDeviceLimits::pname:timestampPeriod after a call to
|
||||
fname:vkGetPhysicalDeviceProperties.
|
||||
|
||||
A timestamp is requested by calling:
|
||||
|
||||
include::../protos/vkCmdWriteTimestamp.txt[]
|
||||
|
||||
* pname:commandBuffer is the command buffer into which the command will be
|
||||
recorded.
|
||||
* pname:pipelineStage is one of the elink:VkPipelineStageFlagBits,
|
||||
specifying a stage of the pipeline.
|
||||
* pname:queryPool is the query pool that will manage the timestamp.
|
||||
* pname:query is the query within the query pool that will contain the
|
||||
timestamp.
|
||||
|
||||
fname:vkCmdWriteTimestamp latches the value of the timer when all previous
|
||||
commands have completed executing as far as the specified pipeline stage,
|
||||
and writes the timestamp value to memory. When the timestamp value is
|
||||
written, the availability status of the query is set to available.
|
||||
|
||||
[NOTE]
|
||||
.Note
|
||||
====
|
||||
If an implementation is unable to detect completion and latch the timer at
|
||||
any specific stage of the pipeline, it may: instead do so at any logically
|
||||
later stage.
|
||||
====
|
||||
|
||||
flink:vkCmdCopyQueryPoolResults can: then be called to copy the timestamp
|
||||
value from the query pool into buffer memory, with ordering and
|
||||
synchronization behavior equivalent to how other queries operate. Timestamp
|
||||
values can: also be retrieved from the query pool using
|
||||
flink:vkGetQueryPoolResults. As with other queries, the query must: be reset
|
||||
using flink:vkCmdResetQueryPool before requesting the timestamp value be
|
||||
written to it.
|
||||
|
||||
While fname:vkCmdWriteTimestamp can: be called inside or outside of a render
|
||||
pass instance, flink:vkCmdCopyQueryPoolResults must: only be called outside
|
||||
of a render pass instance.
|
||||
|
||||
include::../validity/protos/vkCmdWriteTimestamp.txt[]
|
||||
|
|
@ -0,0 +1,856 @@
|
|||
// Copyright (c) 2015-2016 The Khronos Group Inc.
|
||||
// Copyright notice at https://www.khronos.org/registry/speccopyright.html
|
||||
|
||||
[[renderpass]]
|
||||
= Render Pass
|
||||
|
||||
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_.
|
||||
|
||||
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.
|
||||
|
||||
A _subpass_ represents a phase of rendering that reads and writes a
|
||||
subset of the attachments in a render pass. Rendering commands are
|
||||
recorded into a particular subpass of a render pass instance.
|
||||
|
||||
A _subpass description_ describes the subset of attachments that is involved
|
||||
in the execution of a subpass. Each subpass can: read from some attachments
|
||||
as _input attachments_, write to some as _color attachments_ or
|
||||
_depth/stencil attachments_, and do resolve operations to others as _resolve
|
||||
attachments_. A subpass description can: also include a set of _preserve
|
||||
attachments_, which are attachments that are not read or written by the
|
||||
subpass but whose contents must: be preserved throughout the subpass.
|
||||
|
||||
A subpass _uses_ an attachment if the attachment is a color, depth/stencil,
|
||||
resolve, or input attachment for that subpass. A subpass does not use an
|
||||
attachment if that attachment is preserved by the subpass. The first use of
|
||||
an attachment is in the lowest numbered subpass that uses that attachment.
|
||||
Similarly, the last use of an attachment is in the highest numbered subpass
|
||||
that uses that attachment.
|
||||
|
||||
The subpasses in a render pass all render to the same dimensions, and
|
||||
fragments for pixel (x,y,layer) in one subpass can: only read attachment
|
||||
contents written by previous subpasses at that same (x,y,layer) location.
|
||||
|
||||
[NOTE]
|
||||
.Note
|
||||
====
|
||||
By describing a complete set of subpasses a priori, render passes provide
|
||||
the implementation an opportunity to optimize the storage and transfer of
|
||||
attachment data between subpasses.
|
||||
|
||||
In practice, this means that subpasses with a simple framebuffer-space
|
||||
dependency may: be merged into a single tiled rendering pass, keeping the
|
||||
attachment data on-chip for the duration of a render pass instance. However,
|
||||
it is also quite common for a render pass to only contain a single subpass.
|
||||
====
|
||||
|
||||
_Subpass dependencies_ describe ordering restrictions between pairs of
|
||||
subpasses. If no dependencies are specified, implementations may: reorder or
|
||||
overlap portions (e.g., certain shader stages) of the execution of
|
||||
subpasses. Dependencies limit the extent of overlap or reordering, and are
|
||||
defined using masks of pipeline stages and memory access types. Each
|
||||
dependency acts as an
|
||||
<<synchronization-execution-and-memory-dependencies,execution and memory
|
||||
dependency>>, similarly to how <<synchronization-pipeline-barriers,pipeline
|
||||
barriers>> are defined. Dependencies are needed if two subpasses operate on
|
||||
attachments with overlapping ranges of the same sname:VkDeviceMemory object
|
||||
and at least one subpass writes to that range.
|
||||
|
||||
A _subpass dependency chain_ is a sequence of subpass dependencies in a
|
||||
render pass, where the source subpass of each subpass dependency (after the
|
||||
first) equals the destination subpass of the previous dependency.
|
||||
|
||||
A render pass describes the structure of subpasses and attachments
|
||||
independent of any specific image views for the attachments.
|
||||
The specific image views that will be used for the attachments, and their
|
||||
dimensions, are specified in sname:VkFramebuffer objects. Framebuffers
|
||||
are created with respect to a specific render pass that the framebuffer
|
||||
is compatible with (see <<renderpass-compatibility,Render Pass
|
||||
Compatibility>>). Collectively, a render pass and a framebuffer define the
|
||||
complete render target state for one or more subpasses as well as the
|
||||
algorithmic dependencies between the subpasses.
|
||||
|
||||
The various pipeline stages of the drawing commands for a given subpass may:
|
||||
execute concurrently and/or out of order, both within and across drawing
|
||||
commands. However for a given (x,y,layer,sample) sample location, certain
|
||||
per-sample operations are performed in
|
||||
<<fundamentals-queueoperation-apiorder,API order>>.
|
||||
|
||||
|
||||
[[renderpass-creation]]
|
||||
== Render Pass Creation
|
||||
|
||||
A render pass is created by calling:
|
||||
|
||||
include::../protos/vkCreateRenderPass.txt[]
|
||||
|
||||
* pname:device is the logical device that creates the render pass.
|
||||
* pname:pCreateInfo is a pointer to an instance of the
|
||||
sname:VkRenderPassCreateInfo structure that describes the parameters of
|
||||
the render pass.
|
||||
* pname:pAllocator controls host memory allocation as described in the
|
||||
<<memory-allocation, Memory Allocation>> chapter.
|
||||
* pname:pRenderPass points to a sname:VkRenderPass handle in which the
|
||||
resulting render pass object is returned.
|
||||
|
||||
include::../validity/protos/vkCreateRenderPass.txt[]
|
||||
|
||||
The sname:VkRenderPassCreateInfo structure is defined as:
|
||||
|
||||
include::../structs/VkRenderPassCreateInfo.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:attachmentCount is the number of attachments used by this
|
||||
render pass, or zero indicating no attachments. Attachments are referred
|
||||
to by zero-based indices in the range [0,pname:attachmentCount).
|
||||
* pname:pAttachments points to an array of pname:attachmentCount number of
|
||||
slink:VkAttachmentDescription structures describing properties of the
|
||||
attachments, or `NULL` if pname:attachmentCount is zero.
|
||||
* pname:subpassCount is the number of subpasses to create for this render
|
||||
pass. Subpasses are referred to by zero-based indices in the range
|
||||
[0,pname:subpassCount). A render pass must: have at least one subpass.
|
||||
* pname:pSubpasses points to an array of pname:subpassCount number of
|
||||
slink:VkSubpassDescription structures describing properties of the
|
||||
subpasses.
|
||||
* pname:dependencyCount is the number of dependencies between pairs of
|
||||
subpasses, or zero indicating no dependencies.
|
||||
* pname:pDependencies points to an array of pname:dependencyCount number
|
||||
of slink:VkSubpassDependency structures describing dependencies
|
||||
between pairs of subpasses, or `NULL` if pname:dependencyCount is zero.
|
||||
|
||||
include::../validity/structs/VkRenderPassCreateInfo.txt[]
|
||||
|
||||
sname:VkAttachmentDescription is defined as:
|
||||
|
||||
include::../structs/VkAttachmentDescription.txt[]
|
||||
|
||||
* pname:format is a elink:VkFormat value specifying the format of the
|
||||
image that will be used for the attachment.
|
||||
* pname:samples is the number of samples of the image as defined
|
||||
in elink:VkSampleCountFlagBits.
|
||||
* pname:loadOp specifies how the contents of color and depth components of
|
||||
the attachment are treated at the beginning of the subpass where it is
|
||||
first used:
|
||||
+
|
||||
--
|
||||
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.
|
||||
--
|
||||
* 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:
|
||||
+
|
||||
--
|
||||
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.
|
||||
--
|
||||
* 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
|
||||
pname:loadOp above.
|
||||
* pname:stencilStoreOp specifies how the contents of stencil components of
|
||||
the attachment are treated at the end of the last subpass where it
|
||||
is used, and must: be one of the same values allowed for pname:storeOp
|
||||
above.
|
||||
* pname:initialLayout is the layout the attachment image subresource will
|
||||
be in when a render pass instance begins.
|
||||
* pname:finalLayout is the layout the attachment image subresource will be
|
||||
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:
|
||||
|
||||
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
|
||||
the format has depth and/or stencil components, pname:loadOp and
|
||||
pname:storeOp apply only to the depth data, while pname:stencilLoadOp and
|
||||
pname:stencilStoreOp define how the stencil data is handled.
|
||||
|
||||
[[renderpass-precision]]
|
||||
During a renderpass instance, input/color attachments with color formats
|
||||
that have a component size of 8, 16, or 32 bits must: be represented in the
|
||||
attachment's format throughout the instance. Attachments with other
|
||||
floating- or fixed-point color formats, or with depth components may: be
|
||||
represented in a format with a precision higher than the attachment format,
|
||||
but must: be represented with the same range. When such a component is
|
||||
loaded via the pname:loadOp, it will be converted into an
|
||||
implementation-dependent format used by the render pass. Such components
|
||||
must: be converted from the render pass format, to the format of the
|
||||
attachment, before they are stored or resolved at the end of a render pass
|
||||
instance via pname:storeOp. Conversions occur as described in
|
||||
<<fundamentals-numerics,Numeric Representation and Computation>> and
|
||||
<<fundamentals-fixedconv, Fixed-Point Data Conversions>>.
|
||||
|
||||
[[renderpass-aliasing]]
|
||||
If pname:flags includes ename:VK_ATTACHMENT_DESCRIPTION_MAY_ALIAS_BIT, then
|
||||
the attachment is treated as if it shares physical memory with another
|
||||
attachment in the same render pass. This information limits the ability of
|
||||
the implementation to reorder certain operations (like layout transitions
|
||||
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.
|
||||
|
||||
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
|
||||
description flags. Attachments aliasing the same memory occurs in
|
||||
multiple ways:
|
||||
|
||||
* Multiple attachments being assigned the same image view as part of
|
||||
framebuffer creation.
|
||||
* Attachments using distinct image views that correspond to the same
|
||||
subresource of an image.
|
||||
* Attachments using views of distinct image subresources which are bound
|
||||
to overlapping memory.
|
||||
|
||||
Render passes must: include subpass dependencies (either directly or via
|
||||
a subpass dependency chain) between any two subpasses that operate on the
|
||||
same attachment or aliasing attachments and those subpass dependencies must:
|
||||
include execution and memory dependencies separating uses of the aliases, if
|
||||
at least one of those subpasses writes to one of the aliases. Those
|
||||
dependencies mustnot: include the ename:VK_DEPENDENCY_BY_REGION_BIT if the
|
||||
aliases are views of distinct image subresources which overlap in memory.
|
||||
|
||||
Multiple attachments that alias the same memory mustnot: be used in a single
|
||||
subpass. A given attachment index mustnot: be used multiple times in a
|
||||
single subpass, with one exception: two subpass attachments can: use the
|
||||
same attachment index if at least one use is as an input attachment and
|
||||
neither use is as a resolve or preserve attachment. In other words, the same
|
||||
view can: be used simultaneously as an input and color or depth/stencil
|
||||
attachment, but mustnot: be used as multiple color or depth/stencil
|
||||
attachments nor as resolve or preserve attachments. This valid scenario is
|
||||
described in more detail <<renderpass-feedbackloop, below>>.
|
||||
|
||||
If a set of attachments alias each other, then all except the first to be
|
||||
used in the render pass must: use an pname:initialLayout of
|
||||
ename:VK_IMAGE_LAYOUT_UNDEFINED, since the earlier uses of the other aliases
|
||||
make their contents undefined. Once an alias has been used and a different
|
||||
alias has been used after it, the first alias mustnot: be used in any later
|
||||
subpasses. However, an application can: assign the same image view to
|
||||
multiple aliasing attachment indices, which allows that image view to be
|
||||
used multiple times even if other aliases are used in between. Once an
|
||||
attachment needs the ename:VK_ATTACHMENT_DESCRIPTION_MAY_ALIAS_BIT bit,
|
||||
there should: be no additional cost of introducing additional aliases, and
|
||||
using these additional aliases may: allow more efficient clearing of the
|
||||
attachments on multiple uses via ename:VK_ATTACHMENT_LOAD_OP_CLEAR.
|
||||
|
||||
[NOTE]
|
||||
.Note
|
||||
====
|
||||
The exact set of attachment indices that alias with each other is not known
|
||||
until a framebuffer is created using the render pass, so the above
|
||||
conditions cannot: be validated at render pass creation time.
|
||||
====
|
||||
|
||||
sname:VkSubpassDescription is defined as:
|
||||
|
||||
include::../structs/VkSubpassDescription.txt[]
|
||||
|
||||
* pname:flags is reserved for future use.
|
||||
* pname:pipelineBindPoint is a elink:VkPipelineBindPoint value specifying
|
||||
whether this is a compute or graphics subpass. Currently, only graphics
|
||||
subpasses are supported.
|
||||
* pname:inputAttachmentCount is the number of input attachments.
|
||||
* pname:pInputAttachments is an array of slink:VkAttachmentReference
|
||||
structures (defined below) that lists which of the render pass's
|
||||
attachments can: be read in the shader during the subpass, and what
|
||||
layout the attachment images will be in during the subpass. Each element
|
||||
of the array corresponds to an input attachment unit number in the
|
||||
shader, i.e. if the shader declares an input variable
|
||||
`layout(input_attachment_index=X, set=Y, binding=Z)` then it uses the
|
||||
attachment provided in pname:pInputAttachments[X]. Input attachments
|
||||
must: also be bound to the pipeline with a descriptor set, with the
|
||||
input attachment descriptor written in the location (set=Y, binding=Z).
|
||||
* pname:colorAttachmentCount is the number of color attachments.
|
||||
* pname:pColorAttachments is an array of pname:colorAttachmentCount
|
||||
slink:VkAttachmentReference structures that lists which of the render
|
||||
pass's attachments will be used as color attachments in the subpass, and
|
||||
what layout the attachment images will be in during the subpass. Each
|
||||
element of the array correponds to a fragment shader output location,
|
||||
i.e. if the shader declared an output variable `layout(location=X)` then
|
||||
it uses the attachment provided in pname:pColorAttachments[X].
|
||||
* pname:pResolveAttachments is `NULL` or a pointer to an array of
|
||||
sname:VkAttachmentReference structures. If pname:pResolveAttachments is
|
||||
not `NULL`, each of its elements corresponds to a color attachment (the
|
||||
element in pname:pColorAttachments at the same index). At the end of
|
||||
each subpass, the subpass's color attachments are resolved to
|
||||
corresponding resolve attachments, unless the resolve attachment index
|
||||
is ename:VK_ATTACHMENT_UNUSED or pname:pResolveAttachments is `NULL`. If
|
||||
the first use of an attachment in a render pass is as a resolve
|
||||
attachment, then the pname:loadOp is effectively ignored as the resolve
|
||||
is guaranteed to overwrite all pixels in the render area.
|
||||
* pname:pDepthStencilAttachment is a pointer to a
|
||||
slink:VkAttachmentReference specifying which attachment will be used for
|
||||
depth/stencil data and the layout it will be in during the subpass.
|
||||
Setting the attachment index to ename:VK_ATTACHMENT_UNUSED or leaving
|
||||
this pointer as `NULL` indicates that no depth/stencil attachment will
|
||||
be used in the subpass.
|
||||
* pname:preserveAttachmentCount is the number of preserved attachments.
|
||||
* pname:pPreserveAttachments is an array of pname:preserveAttachmentCount
|
||||
render pass attachment indices describing the attachments that
|
||||
are not used by a subpass, but whose contents must: be preserved
|
||||
throughout the subpass.
|
||||
|
||||
The contents of an attachment within the render area become undefined at
|
||||
the start of a subpass S if all of the following conditions are true:
|
||||
|
||||
* The attachment is used as a color, depth/stencil, or resolve attachment
|
||||
in any subpass in the render pass.
|
||||
* There is a subpass S1 that uses or preserves the attachment, and a
|
||||
subpass dependency from S1 to S.
|
||||
* The attachment is not used or preserved in subpass S.
|
||||
|
||||
Once the contents of an attachment become undefined in subpass S, they
|
||||
remain undefined for subpasses in subpass dependency chains starting with
|
||||
subpass S until they are written again. However, they remain valid for
|
||||
subpasses in other subpass dependency chains starting with subpass S1 if
|
||||
those subpasses use or preserve the attachment.
|
||||
|
||||
include::../validity/structs/VkSubpassDescription.txt[]
|
||||
|
||||
The sname:VkAttachmentReference structure is defined as:
|
||||
|
||||
include::../structs/VkAttachmentReference.txt[]
|
||||
|
||||
* pname:attachment is the index of the attachment of the render pass, and
|
||||
corresponds to the index of the corresponding element in the
|
||||
pname:pAttachments array of the sname:VkRenderPassCreateInfo structure.
|
||||
If any color or depth/stencil attachments are
|
||||
ename:VK_ATTACHMENT_UNUSED, then no writes occur for those attachments.
|
||||
* pname:layout is a elink:VkImageLayout value specifying the layout the
|
||||
attachment uses during the subpass. The implementation will
|
||||
automatically perform layout transitions as needed between subpasses to
|
||||
make each subpass use the requested layouts.
|
||||
|
||||
include::../validity/structs/VkAttachmentReference.txt[]
|
||||
|
||||
The sname:VkSubpassDependency structure is defined as:
|
||||
|
||||
include::../structs/VkSubpassDependency.txt[]
|
||||
|
||||
* pname:srcSubpass and pname:dstSubpass are the subpass indexes of the
|
||||
producer and consumer subpasses, respectively. pname:srcSubpass and
|
||||
pname:dstSubpass can: also have the special value
|
||||
ename:VK_SUBPASS_EXTERNAL. The source subpass must: always be a lower
|
||||
numbered subpass than the destination subpass (excluding external
|
||||
subpasses and
|
||||
<<synchronization-pipeline-barriers-subpass-self-dependencies,
|
||||
self-dependencies>>), so that the order of subpass descriptions is a
|
||||
valid execution ordering, avoiding cycles in the dependency graph.
|
||||
* pname:srcStageMask, pname:dstStageMask, pname:srcAccessMask,
|
||||
pname:dstAccessMask, and pname:dependencyFlags describe an
|
||||
<<synchronization-execution-and-memory-dependencies,execution and memory
|
||||
dependency>> between subpasses. The bits that can: be included in
|
||||
pname:dependencyFlags are:
|
||||
+
|
||||
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>>.
|
||||
|
||||
Each subpass dependency defines an execution and memory dependency
|
||||
between two sets of commands, with the second set depending on the first
|
||||
set. When pname:srcSubpass does not equal pname:dstSubpass then the first
|
||||
set of commands is:
|
||||
|
||||
* All commands in the subpass indicated by pname:srcSubpass, if
|
||||
pname:srcSubpass is not ename:VK_SUBPASS_EXTERNAL.
|
||||
* All commands before the render pass instance, if pname:srcSubpass is
|
||||
ename:VK_SUBPASS_EXTERNAL.
|
||||
|
||||
While the corresponding second set of commands is:
|
||||
|
||||
* All commands in the subpass indicated by pname:dstSubpass, if
|
||||
pname:dstSubpass is not ename:VK_SUBPASS_EXTERNAL.
|
||||
* All commands after the render pass instance, if pname:dstSubpass is
|
||||
ename:VK_SUBPASS_EXTERNAL.
|
||||
|
||||
When pname:srcSubpass equals pname:dstSubpass then the first set consists of
|
||||
commands in the subpass before a call to flink:vkCmdPipelineBarrier and the
|
||||
second set consists of commands in the subpass following that same call as
|
||||
described in the
|
||||
<<synchronization-pipeline-barriers-subpass-self-dependencies, Subpass
|
||||
Self-dependency>> section.
|
||||
|
||||
The pname:srcStageMask, pname:dstStageMask, pname:srcAccessMask,
|
||||
pname:dstAccessMask, and pname:dependencyFlags parameters of the dependency
|
||||
are interpreted the same way as for other dependencies, as described in
|
||||
<<synchronization, Synchronization and Cache Control>>.
|
||||
|
||||
include::../validity/structs/VkSubpassDependency.txt[]
|
||||
|
||||
Automatic image layout transitions between subpasses also interact with the
|
||||
subpass dependencies. If two subpasses are connected by a dependency and
|
||||
those two subpasses use the same attachment in a different layout, then the
|
||||
layout transition will occur after the memory accesses via
|
||||
pname:srcAccessMask have completed in all pipeline stages included in
|
||||
pname:srcStageMask in the source subpass, and before any memory accesses
|
||||
via pname:dstAccessMask occur in any pipeline stages included in
|
||||
pname:dstStageMask in the destination subpass.
|
||||
|
||||
The automatic image layout transitions from pname:initialLayout to the first
|
||||
used layout (if it is different) are performed according to the following
|
||||
rules:
|
||||
|
||||
* If the attachment does not include the
|
||||
ename:VK_ATTACHMENT_DESCRIPTION_MAY_ALIAS_BIT bit and there is no
|
||||
subpass dependency from ename:VK_SUBPASS_EXTERNAL to the first subpass
|
||||
that uses the attachment, then it is as if there were such a dependency
|
||||
with pname:srcStageMask = pname:srcAccessMask = 0 and pname:dstStageMask
|
||||
and pname:dstAccessMask including all relevant bits (all graphics
|
||||
pipeline stages and all access types that use image resources), with the
|
||||
transition executing as part of that dependency. In other words, it may:
|
||||
overlap work before the render pass instance and is complete before the
|
||||
subpass begins.
|
||||
* If the attachment does not include the
|
||||
ename:VK_ATTACHMENT_DESCRIPTION_MAY_ALIAS_BIT bit and there is a subpass
|
||||
dependency from ename:VK_SUBPASS_EXTERNAL to the first subpass that uses
|
||||
the attachment, then the transition executes as part of that dependency
|
||||
and according to its stage and access masks. It mustnot: overlap work
|
||||
that came before the render pass instance that is included in the source
|
||||
masks, but it may: overlap work in previous subpasses.
|
||||
* If the attachment includes the
|
||||
ename:VK_ATTACHMENT_DESCRIPTION_MAY_ALIAS_BIT bit, then the transition
|
||||
executes according to all the subpass dependencies with pname:dstSubpass
|
||||
equal to the first subpass index that the attachment is used in. That
|
||||
is, it occurs after all memory accesses in the source stages and masks
|
||||
from all the source subpasses have completed and are available, and
|
||||
before the union of all the destination stages begin, and the new layout
|
||||
is visible to the union of all the destination access types. If there
|
||||
are no incoming subpass dependencies, then this case follows the first
|
||||
rule.
|
||||
|
||||
Similar rules apply for the transition to the pname:finalLayout, using
|
||||
dependencies with pname:dstSubpass equal to ename:VK_SUBPASS_EXTERNAL
|
||||
|
||||
If an attachment specifies the ename:VK_ATTACHMENT_LOAD_OP_CLEAR load
|
||||
operation, then it will logically be cleared at the start of the first
|
||||
subpass where it is used.
|
||||
|
||||
[NOTE]
|
||||
.Note
|
||||
====
|
||||
Implementations may: move clears earlier as long as it does not affect the
|
||||
operation of a render pass instance. For example, an implementation may:
|
||||
choose to clear all attachments at the start of the render pass instance. If
|
||||
an attachment has the ename:VK_ATTACHMENT_DESCRIPTION_MAY_ALIAS_BIT flag
|
||||
set, then the clear must: occur at the start of subpass where the attachment
|
||||
is first used, in order to preserve the operation of the render pass
|
||||
instance.
|
||||
====
|
||||
|
||||
The first use of an attachment mustnot: specify a layout equal to
|
||||
ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL or
|
||||
ename:VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL if the attachment specifies
|
||||
that the pname:loadOp is ename:VK_ATTACHMENT_LOAD_OP_CLEAR. If a subpass
|
||||
uses the same attachment as both an input attachment and either a color
|
||||
attachment or a depth/stencil attachment, then both uses must: observe the
|
||||
result of the clear.
|
||||
|
||||
Similarly, if an attachment specifies that the pname:storeOp is
|
||||
ename:VK_ATTACHMENT_STORE_OP_STORE, then it will logically be stored at the
|
||||
end of the last subpass where it is used.
|
||||
|
||||
[NOTE]
|
||||
.Note
|
||||
====
|
||||
Implementations may: move stores
|
||||
later as long as it does not affect the operation of a render pass instance.
|
||||
If an attachment has the ename:VK_ATTACHMENT_DESCRIPTION_MAY_ALIAS_BIT flag
|
||||
set, then the store must: occur at the end of the highest numbered subpass
|
||||
that uses the attachment.
|
||||
====
|
||||
|
||||
If an attachment is not used by any subpass, then the pname:loadOp and the
|
||||
pname:storeOp are ignored and the attachment's memory contents will not be
|
||||
modified by execution of a render pass instance.
|
||||
|
||||
It will be common for a render pass to consist of a simple linear graph of
|
||||
dependencies, where subpass N depends on subpass N-1 for all N, and the
|
||||
operation of the memory barriers and layout transitions is fairly
|
||||
straightforward to reason about for those simple cases. But for more complex
|
||||
graphs, there are some rules that govern when there must be dependencies
|
||||
between subpasses.
|
||||
|
||||
As stated earlier, render passes must: include subpass dependencies which
|
||||
(either directly or via a subpass dependency chain) separate any two
|
||||
subpasses that operate on the same attachment or aliasing attachments, if at
|
||||
least one of those subpasses writes to the attachment. If an image layout
|
||||
changes between those two subpasses, the implementation uses the stageMasks
|
||||
and accessMasks indicated by the subpass dependency as the masks that
|
||||
control when the layout transition must: occur. If there is not a layout
|
||||
change on the attachment, or if an implementation treats the two layouts
|
||||
identically, then it may: treat the dependency as a simple execution/memory
|
||||
barrier.
|
||||
|
||||
If two subpasses use the same attachment in different layouts but both uses
|
||||
are read-only (i.e. input attachment, or read-only depth/stencil
|
||||
attachment), the application does not need to express a dependency between
|
||||
the two subpasses. Implementations that treat the two layouts differently
|
||||
may: deduce and insert a dependency between the subpasses, with the
|
||||
implementation choosing the appropriate stage masks and access masks based
|
||||
on whether the attachment is used as an input or depth/stencil attachment,
|
||||
and may: insert the appropriate layout transition along with the
|
||||
execution/memory barrier. Implementations that treat the two layouts
|
||||
identically need not insert a barrier, and the two subpasses may: execute
|
||||
simultaneously. The stage masks and access masks are chosen as follows:
|
||||
|
||||
- for input attachments, stage mask =
|
||||
ename:VK_PIPELINE_STAGE_FRAGMENT_SHADER_BIT, access mask =
|
||||
ename:VK_ACCESS_INPUT_ATTACHMENT_READ_BIT.
|
||||
- for depth/stencil attachments, stage mask =
|
||||
ename:VK_PIPELINE_STAGE_EARLY_FRAGMENT_TESTS_BIT |
|
||||
ename:VK_PIPELINE_STAGE_LATE_FRAGMENT_TESTS_BIT, access mask =
|
||||
ename:VK_ACCESS_DEPTH_STENCIL_ATTACHMENT_READ_BIT
|
||||
|
||||
where pname:srcStageMask and pname:srcAccessMask are taken based on usage in
|
||||
the source subpass and pname:dstStageMask and pname:dstAccessMask are taken
|
||||
based on usage in the destination subpass.
|
||||
|
||||
[[renderpass-feedbackloop]]
|
||||
If a subpass uses the same attachment as both an input attachment and either
|
||||
a color attachment or a depth/stencil attachment, reads from the input
|
||||
attachment are not automatically coherent with writes through the color or
|
||||
depth/stencil attachment. In order to achieve well-defined results, one of
|
||||
two criteria must: be satisfied. First, if the color components or
|
||||
depth/stencil components read by the input attachment are mutually exclusive
|
||||
with the components written by the color or depth/stencil
|
||||
attachment then there is no _feedback loop_ and the reads and writes both
|
||||
function normally, with the reads observing values from the previous
|
||||
subpass(es) or from memory. This option requires the graphics pipelines
|
||||
used by the subpass to disable writes to color components that are read as
|
||||
inputs via the pname:colorWriteMask, and to disable writes to depth/stencil
|
||||
components that are read as inputs via pname:depthWriteEnable or
|
||||
pname:stencilTestEnable.
|
||||
|
||||
Second, if the input attachment reads components that are written by the
|
||||
color or depth/stencil attachment, then there is a feedback loop and a
|
||||
pipeline barrier must: be used between when the attachment is written and
|
||||
when it is subsequently read by later fragments. This pipeline barrier must:
|
||||
follow the rules of a self-dependency as described in
|
||||
<<synchronization-pipeline-barriers-subpass-self-dependencies,Subpass
|
||||
Self-dependency>>, where the barrier's flags include:
|
||||
|
||||
* pname:dstStageMask = ename:VK_PIPELINE_STAGE_FRAGMENT_SHADER_BIT,
|
||||
* pname:dstAccessMask = ename:VK_ACCESS_INPUT_ATTACHMENT_READ_BIT, and
|
||||
* pname:srcAccessMask = ename:VK_ACCESS_COLOR_ATTACHMENT_WRITE_BIT (for
|
||||
color attachments) or pname:srcAccessMask =
|
||||
ename:VK_ACCESS_DEPTH_STENCIL_ATTACHMENT_WRITE_BIT (for depth/stencil
|
||||
attachments).
|
||||
* pname:srcStageMask = ename:VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT
|
||||
(for color attachments) or pname:srcStageMask =
|
||||
ename:VK_PIPELINE_STAGE_LATE_FRAGMENT_TESTS_BIT |
|
||||
ename:VK_PIPELINE_STAGE_EARLY_FRAGMENT_TESTS_BIT (for depth/stencil
|
||||
attachments).
|
||||
* pname:dependencyFlags = ename:VK_DEPENDENCY_BY_REGION_BIT.
|
||||
|
||||
A pipeline barrier is needed each time a fragment will read a particular
|
||||
(x,y,layer,sample) location if that location has been written since the most
|
||||
recent pipeline barrier, or since the start of the subpass if there have
|
||||
been no pipeline barriers since the start of the subpass.
|
||||
|
||||
An attachment used as both an input attachment and color attachment must: be
|
||||
in the ename:VK_IMAGE_LAYOUT_GENERAL layout. An attachment used as both an
|
||||
input attachment and depth/stencil attachment must: be in either the
|
||||
ename:VK_IMAGE_LAYOUT_GENERAL or
|
||||
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.
|
||||
|
||||
To destroy a render pass, call:
|
||||
|
||||
include::../protos/vkDestroyRenderPass.txt[]
|
||||
|
||||
* pname:device is the logical device that destroys the render pass.
|
||||
* pname:renderPass is the handle of the render pass to destroy.
|
||||
* pname:pAllocator controls host memory allocation as described in the
|
||||
<<memory-allocation, Memory Allocation>> chapter.
|
||||
|
||||
include::../validity/protos/vkDestroyRenderPass.txt[]
|
||||
|
||||
|
||||
[[renderpass-compatibility]]
|
||||
== Render Pass Compatibility
|
||||
|
||||
Framebuffers and graphics pipelines are created based on a specific
|
||||
render pass object. They must: only be used with that render pass object, or
|
||||
one compatible with it.
|
||||
|
||||
Two attachment references are compatible if they have matching format and
|
||||
sample count, or are both ename:VK_ATTACHMENT_UNUSED or the pointer that
|
||||
would contain the reference is `NULL`.
|
||||
|
||||
Two arrays of attachment references are compatible if all corresponding
|
||||
pairs of attachments are compatible. If the arrays are of different lengths,
|
||||
attachment references not present in the smaller array are treated as
|
||||
ename:VK_ATTACHMENT_UNUSED.
|
||||
|
||||
Two render passes that contain only a single subpass are compatible if
|
||||
their corresponding color, input, resolve, and depth/stencil attachment
|
||||
references are compatible.
|
||||
|
||||
If two render passes contain more than one subpass, they are compatible if
|
||||
they are identical except for:
|
||||
|
||||
* Initial and final image layout in attachment descriptions
|
||||
* Load and store operations in attachment descriptions
|
||||
* Image layout in attachment references
|
||||
|
||||
A framebuffer is compatible with a render pass if it was created using the
|
||||
same render pass or a compatible render pass.
|
||||
|
||||
|
||||
== Framebuffers
|
||||
|
||||
Render passes operate in conjunction with framebuffers, which represent a
|
||||
collection of specific memory attachments that a render pass instance uses.
|
||||
|
||||
An application creates a framebuffer by calling:
|
||||
|
||||
include::../protos/vkCreateFramebuffer.txt[]
|
||||
|
||||
* pname:device is the logical device that creates the framebuffer.
|
||||
* pname:pCreateInfo points to a sname:VkFramebufferCreateInfo structure
|
||||
which describes additional information about framebuffer creation.
|
||||
* pname:pAllocator controls host memory allocation as described in the
|
||||
<<memory-allocation, Memory Allocation>> chapter.
|
||||
* pname:pFramebuffer points to a sname:VkFramebuffer handle in which the
|
||||
resulting framebuffer object is returned.
|
||||
|
||||
include::../validity/protos/vkCreateFramebuffer.txt[]
|
||||
|
||||
The sname:VkFramebufferCreateInfo structure is defined as:
|
||||
|
||||
include::../structs/VkFramebufferCreateInfo.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:renderPass is a render pass that defines what render passes the
|
||||
framebuffer will be compatible with. See
|
||||
<<renderpass-compatibility,Render Pass Compatibility>> for details.
|
||||
* pname:attachmentCount is the number of attachments.
|
||||
* pname:pAttachments is an array of sname:VkImageView handles, each of
|
||||
which will be used as the corresponding attachment in a render pass
|
||||
instance.
|
||||
* 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.
|
||||
|
||||
[NOTE]
|
||||
.Note
|
||||
====
|
||||
This restriction means that the render pass has full knowledge of all uses
|
||||
of all of the attachments, so that the implementation is able to make
|
||||
correct decisions about when and how to perform layout transitions, when to
|
||||
overlap execution of subpasses, etc.
|
||||
====
|
||||
|
||||
[[renderpass-noattachments]]
|
||||
It is legal for a subpass to use no color or depth/stencil attachments, and
|
||||
rather use shader side effects such as image stores and atomics to produce
|
||||
an output. In this case, the subpass continues to use the pname:width,
|
||||
pname:height, and pname:layers of the framebuffer to define the dimensions
|
||||
of the rendering area, and the pname:rasterizationSamples from each
|
||||
pipeline's sname:VkPipelineMultisampleStateCreateInfo to define the number
|
||||
of samples used in rasterization; however, if
|
||||
sname:VkPhysicalDeviceFeatures::pname:variableMultisampleRate is
|
||||
code:VK_FALSE, then all pipelines to be bound with a given zero-attachment
|
||||
subpass must: have the same value for
|
||||
sname:VkPipelineMultisampleStateCreateInfo::pname:rasterizationSamples.
|
||||
|
||||
To destroy a framebuffer, call:
|
||||
|
||||
include::../protos/vkDestroyFramebuffer.txt[]
|
||||
|
||||
* pname:device is the logical device that destroys the framebuffer.
|
||||
* pname:framebuffer is the handle of the framebuffer to destroy.
|
||||
* pname:pAllocator controls host memory allocation as described in the
|
||||
<<memory-allocation, Memory Allocation>> chapter.
|
||||
|
||||
include::../validity/protos/vkDestroyFramebuffer.txt[]
|
||||
|
||||
|
||||
[[renderpass-commands]]
|
||||
== Render Pass Commands
|
||||
|
||||
An application records the commands for a render pass instance one subpass
|
||||
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.
|
||||
|
||||
To begin a render pass instance, call:
|
||||
|
||||
include::../protos/vkCmdBeginRenderPass.txt[]
|
||||
|
||||
* pname:commandBuffer is the command buffer in which to record the
|
||||
command.
|
||||
* pname:pRenderPassBegin is a pointer to a sname:VkRenderPassBeginInfo
|
||||
structure (defined below) which indicates the render pass to begin an
|
||||
instance of, and the framebuffer the instance uses.
|
||||
* pname:contents specifies how the commands in the first subpass will be
|
||||
provided, and is one of the values:
|
||||
+
|
||||
--
|
||||
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
|
||||
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.
|
||||
|
||||
[[renderpass-VkRenderPassBeginInfo]]
|
||||
The sname:VkRenderPassBeginInfo structure is defined as:
|
||||
|
||||
include::../structs/VkRenderPassBeginInfo.txt[]
|
||||
|
||||
* pname:sType is the type of this structure.
|
||||
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
|
||||
* pname:renderPass is the render pass to begin an instance of.
|
||||
* pname:framebuffer is the framebuffer containing the attachments that are
|
||||
used with the render pass.
|
||||
* pname:renderArea is the render area that is affected by the render pass
|
||||
instance, and is described in more detail below.
|
||||
* pname:clearValueCount is the number of elements in pname:pClearValues.
|
||||
* pname:pClearValues is an array of sname:VkClearValue structures that
|
||||
contains clear values for each attachment, if the attachment uses a
|
||||
pname:loadOp value of ename:VK_ATTACHMENT_LOAD_OP_CLEAR. The array is
|
||||
indexed by attachment number, with elements corresponding to uncleared
|
||||
attachments being unused.
|
||||
|
||||
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
|
||||
area on all attachments. The render area extends to all layers of
|
||||
pname:framebuffer. The application must: ensure (using scissor if necessary)
|
||||
that all rendering is contained within the render area, otherwise the pixels
|
||||
outside of the render area become undefined and shader side effects may: or
|
||||
maynot: occur for fragments outside the render area. The render area must:
|
||||
be contained within the framebuffer dimensions.
|
||||
|
||||
[NOTE]
|
||||
.Note
|
||||
====
|
||||
There may: be a performance cost for using a render area smaller than the
|
||||
framebuffer, unless it matches the render area granularity for the render
|
||||
pass.
|
||||
====
|
||||
|
||||
The render area granularity is queried by calling:
|
||||
|
||||
include::../protos/vkGetRenderAreaGranularity.txt[]
|
||||
|
||||
* pname:device is the logical device that owns the render pass.
|
||||
* pname:renderPass is a handle to a render pass.
|
||||
* pname:pGranularity points to a sname: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
|
||||
pname:width member of the returned sname:VkExtent2D (the horizontal
|
||||
granularity).
|
||||
* the pname:offset.y member in pname:renderArea is a multiple of the
|
||||
pname:height of the returned sname:VkExtent2D (the vertical
|
||||
granularity).
|
||||
* either the pname:offset.width member in pname:renderArea is a multiple
|
||||
of the horizontal granularity or pname:offset.x+pname:offset.width is
|
||||
equal to the pname:width of the pname:framebuffer in the
|
||||
sname:VkRenderPassBeginInfo.
|
||||
* either the pname:offset.height member in pname:renderArea is a multiple
|
||||
of the vertical granularity or pname:offset.y+pname:offset.height is
|
||||
equal to the pname:height of the pname:framebuffer in the
|
||||
sname:VkRenderPassBeginInfo.
|
||||
|
||||
After recording the commands for a subpass, an application transitions to
|
||||
the next subpass in the render pass instance by calling:
|
||||
|
||||
include::../protos/vkCmdNextSubpass.txt[]
|
||||
|
||||
* pname:commandBuffer is the command buffer in which to record the
|
||||
command.
|
||||
* pname:contents specifies how the commands in the first subpass will be
|
||||
provided, in the same fashion as the corresponding parameter of
|
||||
flink:vkCmdBeginRenderPass.
|
||||
|
||||
include::../validity/protos/vkCmdNextSubpass.txt[]
|
||||
|
||||
The subpasses indices for a render pass begin at zero when
|
||||
fname:vkCmdBeginRenderPass is recorded, and increments each time
|
||||
fname:vkCmdNextSubpass is recorded.
|
||||
|
||||
Moving to the next subpass automatically performs any multisample resolve
|
||||
operations in the subpass being ended. End-of-subpass multisample resolves
|
||||
are treated as color attachment writes for the purposes of synchronization.
|
||||
That is, they are considered to execute in the
|
||||
ename:VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT pipeline stage and their
|
||||
writes are synchronized with ename:VK_ACCESS_COLOR_ATTACHMENT_WRITE_BIT.
|
||||
Synchronization between rendering within a subpass and any resolve
|
||||
operations at the end of the subpass occurs automatically, without need for
|
||||
explicit dependencies or pipeline barriers. However, if the resolve
|
||||
attachment is also used in a different subpass, an explicit dependency is
|
||||
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::../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.
|
||||
File diff suppressed because it is too large
Load Diff
|
|
@ -0,0 +1,183 @@
|
|||
// Copyright (c) 2015-2016 The Khronos Group Inc.
|
||||
// Copyright notice at https://www.khronos.org/registry/speccopyright.html
|
||||
|
||||
[[samplers]]
|
||||
= Samplers
|
||||
|
||||
sname:VkSampler objects encapsulate 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.
|
||||
|
||||
To create a sampler object, call:
|
||||
|
||||
include::../protos/vkCreateSampler.txt[]
|
||||
|
||||
* pname:device is the logical device that creates the sampler.
|
||||
* pname:pCreateInfo is a pointer to an instance of the
|
||||
slink:VkSamplerCreateInfo structure specifying the state of the sampler
|
||||
object.
|
||||
* pname:pAllocator controls host memory allocation as described in the
|
||||
<<memory-allocation, Memory Allocation>> chapter.
|
||||
* pname:pSampler points to a sname:VkSampler handle in which the resulting
|
||||
sampler object is returned.
|
||||
|
||||
include::../validity/protos/vkCreateSampler.txt[]
|
||||
|
||||
The sname:VkSamplerCreateInfo structure is defined as follows:
|
||||
|
||||
include::../structs/VkSamplerCreateInfo.txt[]
|
||||
|
||||
The members of sname:VkSamplerCreateInfo are described as follows:
|
||||
|
||||
* 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:magFilter is the magnification filter to apply to lookups, and
|
||||
is of type:
|
||||
+
|
||||
--
|
||||
include::../enums/VkFilter.txt[]
|
||||
--
|
||||
+
|
||||
* pname:minFilter is the minification filter to apply to lookups, and is
|
||||
of type elink:VkFilter.
|
||||
* pname:mipmapMode is the mipmap filter to apply to lookups as described
|
||||
in the <<texture-texel-filtering, Texel Filtering>> section, and is of
|
||||
type:
|
||||
+
|
||||
--
|
||||
include::../enums/VkSamplerMipmapMode.txt[]
|
||||
--
|
||||
+
|
||||
* pname:addressModeU is the addressing mode for outside [0..1] range for U
|
||||
coordinate. See elink:VkSamplerAddressMode.
|
||||
* pname:addressModeV is the addressing mode for outside [0..1] range for V
|
||||
coordinate. See elink:VkSamplerAddressMode.
|
||||
* pname:addressModeW is the addressing mode for outside [0..1] range for W
|
||||
coordinate. See elink:VkSamplerAddressMode.
|
||||
* [[samplers-mipLodBias]] pname:mipLodBias is the bias to be added to
|
||||
mipmap LOD calculation and bias provided by image sampling functions in
|
||||
SPIR-V, as described in the <<textures-level-of-detail-operation,
|
||||
Level-of-Detail Operation>> section.
|
||||
* [[samplers-maxAnisotropy]] pname:anisotropyEnable is ename:VK_TRUE to
|
||||
enable anisotropic filtering, as described in the
|
||||
<<texture-anisotropic-texel-selection, Anisotropic Texel Selection>>
|
||||
section, or ename:VK_FALSE otherwise.
|
||||
* pname:maxAnisotropy is the anisotropy value clamp.
|
||||
* pname:compareEnable is ename:VK_TRUE to enable comparison against a
|
||||
reference value during lookups, or ename:VK_FALSE otherwise.
|
||||
** Note: Some implementations will default to shader state if this member
|
||||
does not match.
|
||||
* pname:compareOp is the comparison function to apply to fetched data
|
||||
before filtering as described in the <<texture-depth-compare-operation,
|
||||
Depth Compare Operation>> section. See elink:VkCompareOp.
|
||||
* pname:minLod and pname:maxLod are the values used to clamp the computed
|
||||
level-of-detail value, as described in the
|
||||
<<textures-level-of-detail-operation, Level-of-Detail Operation>>
|
||||
section. pname:maxLod must: be greater than or equal to pname:minLod.
|
||||
* pname:borderColor is the predefined border color to use, as described
|
||||
in the <<texture-texel-replacement, Texel Replacement>>
|
||||
section, and is of type:
|
||||
+
|
||||
--
|
||||
include::../enums/VkBorderColor.txt[]
|
||||
--
|
||||
+
|
||||
* [[samplers-unnormalizedCoordinates]] pname:unnormalizedCoordinates
|
||||
controls whether to use unnormalized or normalized texel coordinates to
|
||||
address texels of the image. When set to ename:VK_TRUE, the range of the
|
||||
image coordinates used to lookup the texel is in the range of zero to
|
||||
the image dimensions for x, y and z. When set to ename:VK_FALSE the
|
||||
range of image coordinates is zero to one. When
|
||||
pname:unnormalizedCoordinates is ename:VK_TRUE, samplers have the
|
||||
following requirements:
|
||||
** pname:minFilter and pname:magFilter must: be equal.
|
||||
** pname:mipmapMode must: be ename:VK_SAMPLER_MIPMAP_MODE_NEAREST.
|
||||
** pname:minLod and pname:maxLod must: be zero.
|
||||
** pname:addressModeU and pname:addressModeV must: each
|
||||
be either ename:VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_EDGE or
|
||||
ename:VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_BORDER.
|
||||
** pname:anisotropyEnable must: be ename:VK_FALSE.
|
||||
** pname:compareEnable must: be ename:VK_FALSE.
|
||||
* When pname:unnormalizedCoordinates is ename:VK_TRUE, images the sampler
|
||||
is used with in the shader have the following requirements:
|
||||
** The pname:viewType must: be either ename:VK_IMAGE_VIEW_TYPE_1D or
|
||||
ename:VK_IMAGE_VIEW_TYPE_2D.
|
||||
** The image view must: have a single layer and a single mip level.
|
||||
* When pname:unnormalizedCoordinates is ename:VK_TRUE, image built-in
|
||||
functions in the shader that use the sampler have the following
|
||||
requirements:
|
||||
** The functions mustnot: use projection.
|
||||
** The functions mustnot: use offsets.
|
||||
|
||||
[NOTE]
|
||||
.Mapping of OpenGL to {apiname} filter modes
|
||||
==================
|
||||
pname:magFilter values of ename:VK_FILTER_NEAREST and ename:VK_FILTER_LINEAR
|
||||
directly correspond to code:GL_NEAREST and code:GL_LINEAR magnification
|
||||
filters. pname:minFilter and pname:mipmapMode combine to correspond to the
|
||||
similarly named OpenGL minification filter of
|
||||
code:GL_minFilter_MIPMAP_mipmapMode (e.g. pname:minFilter of
|
||||
ename:VK_FILTER_LINEAR and pname:mipmapMode of
|
||||
ename:VK_SAMPLER_MIPMAP_MODE_NEAREST correspond to
|
||||
code:GL_LINEAR_MIPMAP_NEAREST).
|
||||
|
||||
There are no {apiname} filter modes that directly correspond to OpenGL
|
||||
minification filters of code:GL_LINEAR or code:GL_NEAREST, but they can be
|
||||
emulated using ename:VK_SAMPLER_MIPMAP_MODE_NEAREST, pname:minLod = 0, and
|
||||
pname:maxLod = 0.25, and using pname:minFilter = ename:VK_FILTER_LINEAR or
|
||||
pname:minFilter = ename:VK_FILTER_NEAREST, respectively.
|
||||
|
||||
Note that using a pname:maxLod of zero would cause
|
||||
<<textures-texel-filtering,magnification>> to always be performed, and the
|
||||
pname:magFilter to always be used. This is valid, just not an exact match
|
||||
for OpenGL behavior. Clamping the maximum lod to 0.25 allows the
|
||||
latexmath:[$\lambda$] value to be non-zero and minification to be performed,
|
||||
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:
|
||||
|
||||
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
|
||||
<<texture-wrapping-operation, Wrapping Operation>> section.
|
||||
|
||||
* ename:VK_SAMPLER_ADDRESS_MODE_REPEAT indicates that the repeat wrap mode
|
||||
will be used.
|
||||
* ename:VK_SAMPLER_ADDRESS_MODE_MIRRORED_REPEAT indicates that the
|
||||
mirrored repeat wrap mode will be used.
|
||||
* ename:VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_EDGE indicates that the clamp to
|
||||
edge wrap mode will be used.
|
||||
* ename:VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_BORDER indicates that the clamp
|
||||
to border wrap mode will be used.
|
||||
* ename:VK_SAMPLER_ADDRESS_MODE_MIRROR_CLAMP_TO_EDGE indicates that the
|
||||
mirror clamp to edge wrap mode will be used.
|
||||
|
||||
The maximum number of sampler objects which can: be simultaneously created
|
||||
on a device is implementation-dependent and specified by the
|
||||
<<features-limits-maxSamplerAllocationCount,pname:maxSamplerAllocationCount>>
|
||||
member of the sname:VkPhysicalDeviceLimits structure. If
|
||||
pname:maxSamplerAllocationCount is exceeded, fname:vkCreateSampler will
|
||||
return ename:VK_ERROR_TOO_MANY_OBJECTS.
|
||||
|
||||
Since sname:VkSampler is a non-dispatchable handle type, implementations
|
||||
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.
|
||||
|
||||
To destroy a sampler, call:
|
||||
|
||||
include::../protos/vkDestroySampler.txt[]
|
||||
|
||||
* pname:device is the logical device that destroys the sampler.
|
||||
* pname:sampler is the sampler to destroy.
|
||||
* pname:pAllocator controls host memory allocation as described in the
|
||||
<<memory-allocation, Memory Allocation>> chapter.
|
||||
|
||||
include::../validity/protos/vkDestroySampler.txt[]
|
||||
|
|
@ -0,0 +1,454 @@
|
|||
// Copyright (c) 2015-2016 The Khronos Group Inc.
|
||||
// Copyright notice at https://www.khronos.org/registry/speccopyright.html
|
||||
|
||||
[[shaders]]
|
||||
= Shaders
|
||||
|
||||
A shader specifies programmable operations that execute for each vertex,
|
||||
control point, tessellated vertex, primitive, fragment, or workgroup in
|
||||
the corresponding stage(s) of the graphics and compute pipelines.
|
||||
|
||||
Graphics pipelines include vertex shader execution as a result of
|
||||
<<drawing,primitive assembly>>, followed, if enabled, by tessellation
|
||||
control and evaluation shaders operating on
|
||||
<<drawing-primitive-topologies-patches,patches>>, geometry shaders, if
|
||||
enabled, operating on primitives, and fragment shaders, if present,
|
||||
operating on fragments generated by <<primsrast,Rasterization>>. In this
|
||||
specification, vertex, tessellation control, tessellation evaluation and
|
||||
geometry shaders are collectively referred to as vertex processing stages
|
||||
and occur in the logical pipeline before rasterization. The fragment shader
|
||||
occurs logically after rasterization.
|
||||
|
||||
Only the compute shader stage is included in a compute pipeline. Compute
|
||||
shaders operate on compute invocations in a workgroup.
|
||||
|
||||
Shaders can: read from input variables, and read from and write to
|
||||
output variables. Input and output variables can: be used to transfer data
|
||||
between shader stages, or to allow the shader to interact with values that
|
||||
exist in the execution environment. Similarly, the execution environment
|
||||
provides constants that describe capabilities.
|
||||
|
||||
Shader variables are associated with execution environment-provided inputs
|
||||
and outputs using _built-in_ decorations in the shader. The available
|
||||
decorations for each stage are documented in the following subsections.
|
||||
|
||||
|
||||
[[shader-modules]]
|
||||
== Shader Modules
|
||||
|
||||
_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
|
||||
that come from different modules. The shader code defining a shader module
|
||||
must: be in the SPIR-V format, as described by the <<spirvenv,{apiname}
|
||||
Environment for SPIR-V>> appendix.
|
||||
|
||||
A shader module is created by calling:
|
||||
|
||||
include::../protos/vkCreateShaderModule.txt[]
|
||||
|
||||
* pname:device is the logical device that creates the shader module.
|
||||
* pname:pCreateInfo parameter is a pointer to an instance of the
|
||||
sname:VkShaderModuleCreateInfo structure.
|
||||
* pname:pAllocator controls host memory allocation as described in the
|
||||
<<memory-allocation, Memory Allocation>> chapter.
|
||||
* pname:pShaderModule points to a sname:VkShaderModule handle in which the
|
||||
resulting render pass object is returned.
|
||||
|
||||
include::../validity/protos/vkCreateShaderModule.txt[]
|
||||
|
||||
The sname:VkShaderModuleCreateInfo structure is defined as:
|
||||
|
||||
include::../structs/VkShaderModuleCreateInfo.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:codeSize is the size, in bytes, of the code pointed to by
|
||||
pname:pCode.
|
||||
* pname:pCode points to code that is used to create the shader
|
||||
module. The type and format of the code is determined from the content
|
||||
of the memory addressed by pname:pCode.
|
||||
|
||||
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>>.
|
||||
|
||||
To destroy a shader module, call:
|
||||
|
||||
include::../protos/vkDestroyShaderModule.txt[]
|
||||
|
||||
* pname:device is the logical device that destroys the shader module.
|
||||
* pname:shaderModule is the handle of the shader module to destroy.
|
||||
* pname:pAllocator controls host memory allocation as described in the
|
||||
<<memory-allocation, Memory Allocation>> chapter.
|
||||
|
||||
A shader module can: be destroyed while pipelines created using its
|
||||
shaders are still in use.
|
||||
|
||||
include::../validity/protos/vkDestroyShaderModule.txt[]
|
||||
|
||||
|
||||
[[shaders-execution]]
|
||||
== Shader Execution
|
||||
|
||||
At each stage of the pipeline, multiple invocations of a shader may: execute
|
||||
simultaneously. Further, invocations of a single shader produced as the
|
||||
result of different commands may: execute simultaneously. The relative
|
||||
execution order of invocations of the same shader type is undefined. Shader
|
||||
invocations may: complete in a different order than that in which the
|
||||
primitives they originated from were drawn or dispatched by the application.
|
||||
However, fragment shader outputs are written to attachments in
|
||||
<<fundamentals-queueoperation-apiorder,API order>>.
|
||||
|
||||
The relative order of invocations of different shader types is largely
|
||||
undefined. However, when invoking a shader whose inputs are generated from a
|
||||
previous pipeline stage, the shader invocations from the previous stage are
|
||||
guaranteed to have executed far enough to generate input values for all
|
||||
required inputs.
|
||||
|
||||
|
||||
[[shaders-execution-memory-ordering]]
|
||||
== Shader Memory Access Ordering
|
||||
|
||||
The order in which image or buffer memory is read or written by shaders is
|
||||
largely undefined. For some shader types (vertex, tessellation evaluation,
|
||||
and in some cases, fragment), even the number of shader invocations that
|
||||
may: perform loads and stores is undefined.
|
||||
|
||||
In particular, the following rules apply:
|
||||
|
||||
* <<shaders-vertex-execution,Vertex>> and
|
||||
<<shaders-tessellation-evaluation-execution,tessellation evaluation>>
|
||||
shaders will be invoked at least once for each unique vertex, as defined
|
||||
in those sections.
|
||||
* <<shaders-fragment-execution,Fragment>> shaders will be invoked zero or
|
||||
more times, as defined in that section.
|
||||
* The relative order of invocations of the same shader type are undefined.
|
||||
A store issued by a shader when working on primitive B might complete
|
||||
prior to a store for primitive A, even if primitive A is specified prior
|
||||
to primitive B. This applies even to fragment shaders; while fragment
|
||||
shader outputs are always written to the framebuffer
|
||||
<<fundamentals-queueoperation-apiorder,in primitive order>>, stores
|
||||
executed by fragment shader invocations are not.
|
||||
* The relative order of invocations of different shader types is largely
|
||||
undefined.
|
||||
|
||||
[NOTE]
|
||||
.Note
|
||||
====
|
||||
The above limitations on shader invocation order make some forms of
|
||||
synchronization between shader invocations within a single set of primitives
|
||||
unimplementable. For example, having one invocation poll memory written by
|
||||
another invocation assumes that the other invocation has been launched and
|
||||
will complete its writes in finite time.
|
||||
====
|
||||
|
||||
Stores issued to different memory locations within a single shader
|
||||
invocation maynot: be visible to other invocations in the order they were
|
||||
performed. The OpMemoryBarrier instruction can: be used to provide stronger
|
||||
ordering of reads and writes performed by a single invocation.
|
||||
OpMemoryBarrier guarantees that any memory transactions issued by the shader
|
||||
invocation prior to the instruction complete prior to the memory
|
||||
transactions issued after the instruction. Memory barriers are needed for
|
||||
algorithms that require multiple invocations to access the same memory and
|
||||
require the operations to be performed in a partially-defined relative
|
||||
order. For example, if one shader invocation does a series of writes,
|
||||
followed by an OpMemoryBarrier instruction, followed by another write, then
|
||||
another invocation that sees the results of the final write will also see
|
||||
the previous writes. Without the memory barrier, the final write may: be
|
||||
visible before the previous writes.
|
||||
|
||||
The built-in atomic memory transaction instructions can: be used to read and
|
||||
write a given memory address atomically. While built-in atomic functions
|
||||
issued by multiple shader invocations are executed in undefined order
|
||||
relative to each other, these functions perform both a read and a write of a
|
||||
memory address and guarantee that no other memory transaction will write to
|
||||
the underlying memory between the read and write.
|
||||
|
||||
[NOTE]
|
||||
.Note
|
||||
====
|
||||
Atomics allow shaders to use shared global addresses for mutual exclusion or
|
||||
as counters, among other uses.
|
||||
====
|
||||
|
||||
|
||||
[[shaders-inputs]]
|
||||
== Shader Inputs and Outputs
|
||||
|
||||
Data is passed into and out of shaders using variables with input or output
|
||||
storage class, respectively. User-defined inputs and outputs are connected
|
||||
between stages by matching their code:Location decorations. Additionally,
|
||||
data can: be provided by or communicated to special functions provided by
|
||||
the execution environment using code:BuiltIn decorations.
|
||||
|
||||
In many cases, the same code:BuiltIn decoration can: be used in multiple
|
||||
shader stages with similar meaning. The specific behavior of variables
|
||||
decorated as code:BuiltIn is documented in the following sections.
|
||||
|
||||
|
||||
[[shaders-vertex]]
|
||||
== Vertex Shaders
|
||||
|
||||
Each vertex shader invocation operates on one vertex and its associated
|
||||
<<fxvertex-attrib,vertex attribute>> data, and outputs one vertex and
|
||||
associated data. Graphics pipelines must: include a vertex shader, and
|
||||
the vertex shader stage is always the first shader stage in the graphics
|
||||
pipeline.
|
||||
|
||||
|
||||
[[shaders-vertex-execution]]
|
||||
=== Vertex Shader Execution
|
||||
|
||||
A vertex shader must: be executed at least once for each vertex specified by
|
||||
a draw command. During execution, the shader is presented with the index of
|
||||
the vertex and instance for which it has been invoked. Input variables
|
||||
declared in the vertex shader are filled by the implementation with the
|
||||
values of vertex attributes associated with the invocation being executed.
|
||||
|
||||
If a vertex is a part of more than one input primitive, for example
|
||||
by including the same index value multiple times in an index buffer, the
|
||||
vertex shader may: be invoked only once and the results shared amongst the
|
||||
resulting primitives. This is known as _vertex reuse_.
|
||||
|
||||
ifdef::implementation-guide[]
|
||||
.Implementor's Note
|
||||
****
|
||||
If a vertex is repeated in a draw command (i.e. the same index is repeated
|
||||
in an indexed draw), the shader may: be executed anywhere from one to the
|
||||
number of repetitions times for that vertex, depending on the
|
||||
implementation's ability to reuse shader results.
|
||||
****
|
||||
endif::implementation-guide[]
|
||||
|
||||
|
||||
[[shaders-tessellation-control]]
|
||||
== Tessellation Control Shaders
|
||||
|
||||
The tessellation control shader is used to read an input patch provided by
|
||||
the application and to produce an output patch. Each tessellation control
|
||||
shader invocation operates on an input patch (after all control points in
|
||||
the patch are processed by a vertex shader) and its associated data, and
|
||||
outputs a single control point of the output patch and its associated data,
|
||||
and can: also output additional per-patch data. The input patch is sized
|
||||
according to the pname:patchControlPoints member of
|
||||
slink:VkPipelineTessellationStateCreateInfo, as part of input assembly. The
|
||||
size of the output patch is controlled by the code:OpExecutionMode
|
||||
code:OutputVertices specified in the tessellation control or tessellation
|
||||
evaluation shaders, which must: be specified in at least one of the shaders.
|
||||
The size of the input and output patches must: each be greater than zero and
|
||||
less than or equal to
|
||||
sname:VkPhysicalDeviceLimits::pname:maxTessellationPatchSize.
|
||||
|
||||
|
||||
[[shaders-tessellation-control-execution]]
|
||||
=== Tessellation Control Shader Execution
|
||||
|
||||
A tessellation control shader is invoked at least once for each _output_
|
||||
vertex in a patch.
|
||||
|
||||
Inputs to the tessellation control shader are generated by the vertex
|
||||
shader. Each invocation of the tessellation control shader can: read the
|
||||
attributes of any incoming vertices and their associated data. The
|
||||
invocations corresponding to a given patch execute logically in parallel,
|
||||
with undefined relative execution order. However, the code:OpControlBarrier
|
||||
instruction can: be used to provide limited control of the execution order
|
||||
by synchronizing invocations within a patch, effectively dividing
|
||||
tessellation control shader execution into a set of phases. Tessellation
|
||||
control shaders will read undefined values if one invocation reads a
|
||||
per-vertex or per-patch attribute written by another invocation at any point
|
||||
during the same phase, or if two invocations attempt to write different
|
||||
values to the same per-patch output in a single phase.
|
||||
|
||||
|
||||
[[shaders-tessellation-evaluation]]
|
||||
== Tessellation Evaluation Shaders
|
||||
|
||||
The Tessellation Evaluation Shader operates on an input patch of control
|
||||
points and their associated data, and a single input barycentric coordinate
|
||||
indicating the invocation's relative position within the subdivided patch,
|
||||
and outputs a single vertex and its associated data.
|
||||
|
||||
|
||||
[[shaders-tessellation-evaluation-execution]]
|
||||
=== Tessellation Evaluation Shader Execution
|
||||
|
||||
A tessellation evaluation shader is invoked at least once for each
|
||||
unique vertex generated by the tessellator.
|
||||
|
||||
|
||||
[[shaders-geometry]]
|
||||
== Geometry Shaders
|
||||
|
||||
The geometry shader operates on a group of vertices and their associated
|
||||
data assembled from a single input primitive, and emits zero or more
|
||||
output primitives and the group of vertices and their associated data
|
||||
required for each output primitive.
|
||||
|
||||
|
||||
[[shaders-geometry-execution]]
|
||||
=== Geometry Shader Execution
|
||||
|
||||
A geometry shader is invoked at least once for each primitive produced by
|
||||
the tessellation stages, or at least once for each primitive generated by
|
||||
<<drawing,primitive assembly>> when tessellation is not in use. The number
|
||||
of geometry shader invocations per input primitive is determined from the
|
||||
invocation count of the geometry shader specified by the
|
||||
code:OpExecutionMode code:Invocations in the geometry shader. If the
|
||||
invocation count is not specified, then a default of one invocation is
|
||||
executed.
|
||||
|
||||
|
||||
[[shaders-fragment]]
|
||||
== Fragment Shaders
|
||||
|
||||
Fragment shaders are invoked as the result of rasterization in a graphics
|
||||
pipeline. Each fragment shader invocation operates on a single fragment and
|
||||
its associated data. With few exceptions, fragment shaders do not have
|
||||
access to any data associated with other fragments and is considered to
|
||||
execute in isolation of fragment shader invocations associated with other
|
||||
fragments.
|
||||
|
||||
|
||||
[[shaders-fragment-execution]]
|
||||
=== Fragment Shader Execution
|
||||
|
||||
For each fragment generated by rasterization, a fragment shader may: or
|
||||
maynot: be invoked. A fragment shader mustnot: be invoked if the
|
||||
<<fragops-early,Early Per-Fragment Tests>> cause it to have no coverage.
|
||||
|
||||
Furthermore, if it is determined that a fragment generated as the result of
|
||||
rasterizing a first primitive will have its outputs entirely overwritten by
|
||||
a fragment generated as the result of rasterizing a second primitive in the
|
||||
same subpass, and the fragment shader used for the fragment has no other
|
||||
side effects, then the fragment shader maynot: be executed for the fragment
|
||||
from the first primitive.
|
||||
|
||||
Relative ordering of execution of different fragment shader invocations is
|
||||
not defined.
|
||||
|
||||
The number of fragment shader invocations produced per-pixel is determined
|
||||
as follows:
|
||||
|
||||
- If per-sample shading is enabled, the fragment shader is invoked once
|
||||
per covered sample.
|
||||
- Otherwise, the fragment shader is invoked at least once per fragment but
|
||||
no more than once per covered sample.
|
||||
|
||||
In addition to the conditions outlined above for the invocation of a
|
||||
fragment shader, a fragment shader invocation may: be produced as a _helper
|
||||
invocation_. A helper invocation is a fragment shader invocation that is
|
||||
created solely for the purposes of evaluating derivatives for use in
|
||||
non-helper fragment shader invocations. Stores and atomics performed by
|
||||
helper invocations mustnot: have any effect on memory, and values returned
|
||||
by atomic instructions in helper invocations are undefined.
|
||||
|
||||
|
||||
[[shaders-fragment-earlytest]]
|
||||
=== Early Fragment Tests
|
||||
|
||||
An explicit control is provided to allow fragment shaders to enable early
|
||||
fragment tests. If the fragment shader specifies the
|
||||
code:EarlyFragmentTests code:OpExecutionMode, the per-fragment tests
|
||||
described in <<fragops-early-mode,Early Fragment Test Mode>> are
|
||||
performed prior to fragment shader execution. Otherwise, they are performed
|
||||
after fragment shader execution.
|
||||
|
||||
|
||||
[[shaders-compute]]
|
||||
== Compute Shaders
|
||||
|
||||
Compute shaders are invoked via flink:vkCmdDispatch and
|
||||
flink:vkCmdDispatchIndirect commands. In general, they have access to
|
||||
similar resources as shader stages executing as part of a graphics pipeline.
|
||||
|
||||
Compute workloads are formed from groups of work items called _workgroups_
|
||||
and processed by the compute shader in the current compute pipeline. A
|
||||
workgroup is a collection of shader invocations that execute the same
|
||||
shader, potentially in parallel. Compute shaders execute in global
|
||||
workgroups which are divided into a number of _local workgroups_ with a size
|
||||
that can: be set by assigning a value to the code:LocalSize execution mode
|
||||
either in the shader code or via
|
||||
<<pipelines-specialization-constants,Specialization Constants>>. An
|
||||
invocation within a local workgroup can: share data with other members of
|
||||
the local workgroup through shared variables and issue memory and control
|
||||
flow barriers to synchronize with other members of the local workgroup.
|
||||
|
||||
|
||||
[[shaders-interpolation-decorations]]
|
||||
== Interpolation Decorations
|
||||
|
||||
Interpolation decorations control the behavior of attribute interpolation in
|
||||
the fragment shader stage. Interpolation decorations can: be applied to
|
||||
code:Input storage class variables in the fragment shader stage's interface,
|
||||
and control the interpolation behavior of those variables.
|
||||
|
||||
Inputs that could be interpolated can: be decorated by at most one
|
||||
of the following decorations:
|
||||
|
||||
* code:Flat: no interpolation
|
||||
* code:NoPerspective: linear interpolation (for
|
||||
<<line_noperspective_interpolation,lines>> and
|
||||
<<triangle_noperspective_interpolation,polygons>>).
|
||||
|
||||
Fragment input variables decorated with neither code:Flat nor
|
||||
code:NoPerspective use perspective-correct interpolation (for
|
||||
<<line_perspective_interpolation,lines>> and
|
||||
<<triangle_perspective_interpolation,polygons>>).
|
||||
|
||||
The presence of and type of interpolation is controlled by the above
|
||||
interpolation decorations as well as the auxiliary decorations code:Centroid
|
||||
and code:Sample.
|
||||
|
||||
A variable decorated with code:Flat will not be interpolated. Instead, it
|
||||
will have the same value for every fragment within a triangle. This value
|
||||
will come from a single <<vertexpostproc-flatshading,provoking vertex>>. A
|
||||
variable decorated with code:Flat can: also be decorated with code:Centroid
|
||||
or code:Sample, which will mean the same thing as decorating it only as
|
||||
code:Flat.
|
||||
|
||||
For fragment shader input variables decorated with neither code:Centroid nor
|
||||
code:Sample, the value of the assigned variable may: be interpolated
|
||||
anywhere within the pixel and a single value may: be assigned to each sample
|
||||
within the pixel.
|
||||
|
||||
code:Centroid and code:Sample can: be used to control the location and
|
||||
frequency of the sampling of the decorated fragment shader input. If a
|
||||
fragment shader input is decorated with code:Centroid, a single value may:
|
||||
be assigned to that variable for all samples in the pixel, but that value
|
||||
must: be interpolated to a location that lies in both the pixel and in the
|
||||
primitive being rendered, including any of the pixel's samples covered by
|
||||
the primitive. Because the location at which the variable is interpolated
|
||||
may be different in neighboring pixels, and derivatives may be computed by
|
||||
computing differences between neighboring pixels, derivatives of
|
||||
centroid-sampled inputs may: be less accurate than those for non-centroid
|
||||
interpolated variables. If a fragment shader input is decorated with
|
||||
code:Sample, a separate value must: be assigned to that variable for each
|
||||
covered sample in the pixel, and that value must: be sampled at the location
|
||||
of the individual sample. When pname:rasterizationSamples is
|
||||
ename:VK_SAMPLE_COUNT_1_BIT, the pixel center must: be used for
|
||||
code:Centroid, code:Sample, and undecorated attribute interpolation.
|
||||
|
||||
Fragment shader inputs that are signed or unsigned integers, integer
|
||||
vectors, or any double-precision floating-point type must: be decorated with
|
||||
code:Flat.
|
||||
|
||||
|
||||
[[shaders-staticuse]]
|
||||
== Static Use
|
||||
|
||||
A SPIR-V module declares a global object in memory using the code:OpVariable
|
||||
instruction, which results in a pointer code:x to that object. A specific
|
||||
entry point in a SPIR-V module is said to _statically use_ that object if
|
||||
that entry-point's call tree contains a function that contains a memory
|
||||
instruction or image instruction with code:x as an code:id operand. See the
|
||||
``Memory Instructions'' and ``Image Instructions'' subsections of section 3
|
||||
``Binary Form'' of the SPIR-V specification for the complete list of SPIR-V
|
||||
memory instructions.
|
||||
|
||||
Static use is not used to control the behavior of variables with code:Input
|
||||
and code:Output storage. The effects of those variables are applied based
|
||||
only on whether they are present in a shader entry point's interface.
|
||||
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
|
|
@ -0,0 +1,440 @@
|
|||
// Copyright (c) 2015-2016 The Khronos Group Inc.
|
||||
// Copyright notice at https://www.khronos.org/registry/speccopyright.html
|
||||
|
||||
[[tessellation]]
|
||||
= Tessellation
|
||||
|
||||
Tessellation involves three pipeline stages. First, a
|
||||
<<shaders-tessellation-control,tessellation control shader>> transforms
|
||||
control points of a patch and can: produce per-patch data. Second, a
|
||||
fixed-function tessellator generates multiple primitives corresponding to a
|
||||
tessellation of the patch in (u,v) or (u,v,w) parameter space. Third, a
|
||||
<<shaders-tessellation-evaluation,tessellation evaluation shader>>
|
||||
transforms the vertices of the tessellated patch, for example to compute
|
||||
their positions and attributes as part of the tessellated surface. The
|
||||
tessellator is enabled when the pipeline contains both a tessellation
|
||||
control shader and a tessellation evaluation shader.
|
||||
|
||||
|
||||
== Tessellator
|
||||
|
||||
If a pipeline includes both tessellation shaders (control and evaluation),
|
||||
the tessellator consumes each input patch (after vertex shading) and
|
||||
produces a new set of independent primitives (points, lines, or triangles).
|
||||
These primitives are logically produced by subdividing a geometric primitive
|
||||
(rectangle or triangle) according to the per-patch tessellation levels
|
||||
written by the tessellation control shader. This subdivision is performed in
|
||||
an implementation-dependent manner. If no tessellation shaders are present
|
||||
in the pipeline, the tessellator is disabled and incoming primitives are
|
||||
passed through without modification.
|
||||
|
||||
The type of subdivision performed by the tessellator is
|
||||
specified by an code:OpExecutionMode instruction in the tessellation
|
||||
evaluation or tessellation control shader using one of execution modes
|
||||
code:Triangles, code:Quads, and code:IsoLines. Other
|
||||
tessellation-related execution modes can: also be specified in either the
|
||||
tessellation control or tessellation evaluation shaders, and if they are
|
||||
specified in both then the modes must: be the same.
|
||||
|
||||
Tessellation execution modes include:
|
||||
|
||||
* code:Triangles, code:Quads, and code:IsoLines. These control the type of
|
||||
subdivision and topology of the output primitives. One mode must: be set
|
||||
in at least one of the tessellation shader stages.
|
||||
* code:VertexOrderCw and code:VertexOrderCcw. These control the
|
||||
orientation of triangles generated by the tessellator. One mode must: be
|
||||
set in at least one of the tessellation shader stages.
|
||||
* code:PointMode. Controls generation of points rather than triangles or
|
||||
lines. This functionality defaults to disabled, and is enabled if either
|
||||
shader stage includes the execution mode.
|
||||
* code:SpacingEqual, code:SpacingFractionalEven, and
|
||||
code:SpacingFractionalOdd. Controls the spacing of segments on the edges
|
||||
of tessellated primitives. One mode must: be set in at least one of the
|
||||
tessellation shader stages.
|
||||
* code:OutputVertices. Controls the size of the output patch of the
|
||||
tessellation control shader. One value must: be set in at least one of
|
||||
the tessellation shader stages.
|
||||
|
||||
For triangles, the tessellator subdivides a triangle primitive into
|
||||
smaller triangles. For quads, the tessellator subdivides a rectangle
|
||||
primitive into smaller triangles. For isolines, the tessellator
|
||||
subdivides a rectangle primitive into a collection of line segments arranged
|
||||
in strips stretching across the rectangle in the latexmath:[$u$] dimension
|
||||
(i.e. the coordinates in code:TessCoord are of the form (0,x) through (1,x)
|
||||
for all tessellation evaluation shader invocations that share a line).
|
||||
|
||||
Each vertex produced by the tessellator has an associated (u,v,w) or (u,v)
|
||||
position in a normalized parameter space, with parameter values in the
|
||||
latexmath:[$[0,1\]$], as illustrated in figure
|
||||
<<img-tessellation-topology>>.
|
||||
|
||||
[[img-tessellation-topology,Domain parameterization for tessellation primitive modes]]
|
||||
.Domain parameterization for tessellation primitive modes
|
||||
image:images/tessparam.{svgpdf}["Domain parameterization for tessellation primitive modes",{fullimagewidth}]
|
||||
|
||||
For triangles, the vertex's position is a barycentric coordinate (u,v,w),
|
||||
where u + v + w = 1.0, and indicates the relative influence of the three
|
||||
vertices of the triangle on the position of the vertex. For quads and
|
||||
isolines, the position is a (u,v) coordinate indicating the relative
|
||||
horizontal and vertical position of the vertex relative to the subdivided
|
||||
rectangle. The subdivision process is explained in more detail in subsequent
|
||||
sections.
|
||||
|
||||
|
||||
== Tessellator Patch Discard
|
||||
|
||||
A patch is discarded by the tessellator if any
|
||||
relevant outer tessellation level is less than or equal to zero.
|
||||
|
||||
Patches will also be discarded if any relevant outer tessellation level
|
||||
corresponds to a floating-point NaN (not a number) in implementations
|
||||
supporting NaN.
|
||||
|
||||
No new primitives are generated and the tessellation evaluation shader is
|
||||
not executed for patches that are discarded. For code:Quads, all four outer
|
||||
levels are relevant. For code:Triangles and code:IsoLines, only the first
|
||||
three or two outer levels, respectively, are relevant. Negative inner levels
|
||||
will not cause a patch to be discarded; they will be clamped as described
|
||||
below.
|
||||
|
||||
|
||||
[[tessellation-tessellator-spacing]]
|
||||
== Tessellator Spacing
|
||||
|
||||
Each of the tessellation levels is used to determine the number and
|
||||
spacing of segments used to subdivide a corresponding edge. The method
|
||||
used to derive the number and spacing of segments is specified by an
|
||||
code:OpExecutionMode in the tessellation control or tessellation evaluation
|
||||
shader using one of the identifiers code:SpacingEqual,
|
||||
code:SpacingFractionalEven, or code:SpacingFractionalOdd.
|
||||
|
||||
If code:SpacingEqual is used, the floating-point tessellation level is first
|
||||
clamped to latexmath:[$[1,\mathit{maxLevel}\]$], where
|
||||
latexmath:[$\mathit{maxLevel}$] is the implementation-dependent maximum
|
||||
tessellation level
|
||||
(sname:VkPhysicalDeviceLimits::pname:maxTessellationGenerationLevel). The
|
||||
result is rounded up to the nearest integer latexmath:[$n$], and the
|
||||
corresponding edge is divided into latexmath:[$n$] segments of equal length
|
||||
in (u,v) space.
|
||||
|
||||
If code:SpacingFractionalEven is used, the tessellation level is first
|
||||
clamped to latexmath:[$[2,\mathit{maxLevel}\]$] and then rounded up to the
|
||||
nearest even integer latexmath:[$n$]. If code:SpacingFractionalOdd is used,
|
||||
the tessellation level is clamped to latexmath:[$[1,\mathit{maxLevel}-1\]$]
|
||||
and then rounded up to the nearest odd integer latexmath:[$n$]. If
|
||||
latexmath:[$n$] is one, the edge will not be subdivided. Otherwise, the
|
||||
corresponding edge will be divided into latexmath:[$n-2$] segments of equal
|
||||
length, and two additional segments of equal length that are typically
|
||||
shorter than the other segments. The length of the two additional segments
|
||||
relative to the others will decrease monotonically with the value of
|
||||
latexmath:[$n-f$], where latexmath:[$f$] is the clamped floating-point
|
||||
tessellation level. When latexmath:[$n-f$] is zero, the additional segments
|
||||
will have equal length to the other segments. As latexmath:[$n-f$]
|
||||
approaches 2.0, the relative length of the additional segments approaches
|
||||
zero. The two additional segments should: be placed symmetrically on
|
||||
opposite sides of the subdivided edge. The relative location of these two
|
||||
segments is implementation-dependent, but must: be identical for any pair of
|
||||
subdivided edges with identical values of <f>.
|
||||
|
||||
When the tessellator produces triangles (in the code:Triangles or
|
||||
code:Quads modes), the orientation of all triangles is specified with
|
||||
an code:OpExecutionMode of code:VertexOrderCw or code:VertexOrderCcw in the
|
||||
tessellation control or tessellation evaluation shaders. If the order is
|
||||
code:VertexOrderCw, the vertices of all generated triangles will have a
|
||||
clockwise ordering in (u,v) or (u,v,w) space. If the order is
|
||||
code:VertexOrderCcw, the vertices will be generated with counter-clockwise
|
||||
order.
|
||||
|
||||
The vertices of a triangle are defined to be in counter-clockwise ordering
|
||||
of the value
|
||||
[latexmath]
|
||||
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
|
||||
\[
|
||||
a = u_0 v_1 - u_1 v_0 + u_1 v_2 - u_2 v_1 + u_2 v_0 - u_0 v_2
|
||||
\]
|
||||
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
|
||||
is positive, where latexmath:[$u_i$] and latexmath:[$v_i$] are the
|
||||
latexmath:[$u$] and latexmath:[$v$] coordinates in normalized parameter
|
||||
space of the latexmath:[$i$]th vertex of the triangle. If the value
|
||||
latexmath:[$a$] is negative, the vertices of the triangle are defined to be
|
||||
in clockwise ordering.
|
||||
|
||||
[NOTE]
|
||||
.Note
|
||||
====
|
||||
The value latexmath:[$a$] is proportional (with a positive factor) to the
|
||||
signed area of the triangle.
|
||||
|
||||
In code:Triangles mode, even though the vertex coordinates have a
|
||||
latexmath:[$w$] value, it does not participate directly in the computation
|
||||
of latexmath:[$a$], being an affine combination of latexmath:[$u$] and
|
||||
latexmath:[$v$].
|
||||
====
|
||||
|
||||
For all primitive modes, the tessellator is capable of generating points
|
||||
instead of lines or triangles. If the tessellation control or tessellation
|
||||
evaluation shader specifies the code:OpExecutionMode code:PointMode, the
|
||||
primitive generator will generate one point for each distinct vertex
|
||||
produced by tessellation. Otherwise, the tessellator will produce a
|
||||
collection of line segments or triangles according to the primitive mode.
|
||||
When tessellating triangles or quads in point mode with fractional odd
|
||||
spacing, the tessellator may: produce _interior vertices_ that are
|
||||
positioned on the edge of the patch if an inner tessellation level is less
|
||||
than or equal to one. Such vertices are considered distinct from vertices
|
||||
produced by subdividing the outer edge of the patch, even if there are pairs
|
||||
of vertices with identical coordinates.
|
||||
|
||||
The points, lines, or triangles produced by the tessellator
|
||||
are passed to subsequent pipeline stages in an
|
||||
implementation-dependent order.
|
||||
|
||||
|
||||
[[tessellation-triangle-tessellation]]
|
||||
== Triangle Tessellation
|
||||
|
||||
If the tessellation primitive mode is code:Triangles, an equilateral
|
||||
triangle is subdivided into a collection of triangles covering the area of
|
||||
the original triangle. First, the original triangle is subdivided into a
|
||||
collection of concentric equilateral triangles. The edges of each of these
|
||||
triangles are subdivided, and the area between each triangle pair is filled
|
||||
by triangles produced by joining the vertices on the subdivided edges. The
|
||||
number of concentric triangles and the number of subdivisions along each
|
||||
triangle except the outermost is derived from the first inner tessellation
|
||||
level. The edges of the outermost triangle are subdivided independently,
|
||||
using the first, second, and third outer tessellation levels to control the
|
||||
number of subdivisions of the latexmath:[$u=0$] (left), latexmath:[$v=0$]
|
||||
(bottom), and latexmath:[$w=0$] (right) edges, respectively. The second
|
||||
inner tessellation level and the fourth outer tessellation level have no
|
||||
effect in this mode.
|
||||
|
||||
If the first inner tessellation level and all three outer tessellation
|
||||
levels are exactly one after clamping and rounding, only a single triangle
|
||||
with (u,v,w) coordinates of (0,0,1), (1,0,0), and (0,1,0) is generated.
|
||||
If the inner tessellation level is one and any of the outer tessellation
|
||||
levels is greater than one, the inner tessellation level is treated as
|
||||
though it were originally specified as latexmath:[$1+\epsilon$] and will
|
||||
result in a two- or three-segment subdivision depending on the tessellation
|
||||
spacing. When used with fractional odd spacing, the three-segment
|
||||
subdivision may: produce _inner vertices_ positioned on the edge of the
|
||||
triangle.
|
||||
|
||||
If any tessellation level is greater than one, tessellation begins by
|
||||
producing a set of concentric inner triangles and subdividing their edges.
|
||||
First, the three outer edges are temporarily subdivided using the clamped
|
||||
and rounded first inner tessellation level and the specified tessellation
|
||||
spacing, generating latexmath:[$n$] segments. For the outermost inner
|
||||
triangle, the inner triangle is degenerate -- a single point at the center
|
||||
of the triangle -- if latexmath:[$n$] is two. Otherwise, for each corner of
|
||||
the outer triangle, an inner triangle corner is produced at the intersection
|
||||
of two lines extended perpendicular to the corner's two adjacent edges
|
||||
running through the vertex of the subdivided outer edge nearest that corner.
|
||||
If latexmath:[$n$] is three, the edges of the inner triangle are not
|
||||
subdivided and is the final triangle in the set of concentric triangles.
|
||||
Otherwise, each edge of the inner triangle is divided into latexmath:[$n-2$]
|
||||
segments, with the latexmath:[$n-1$] vertices of this subdivision produced
|
||||
by intersecting the inner edge with lines perpendicular to the edge running
|
||||
through the latexmath:[$n-1$] innermost vertices of the subdivision of the
|
||||
outer edge. Once the outermost inner triangle is subdivided, the previous
|
||||
subdivision process repeats itself, using the generated triangle as an outer
|
||||
triangle. This subdivision process is illustrated in <<img-innertri,Inner
|
||||
Triangle Tessellation>>.
|
||||
|
||||
[[img-innertri,Inner Triangle Tessellation]]
|
||||
.Inner Triangle Tessellation
|
||||
image:images/innertri.{svgpdf}["Inner Triangle Tessellation",{fullimagewidth}]
|
||||
|
||||
// TODO: Add caption:
|
||||
// Inner triangle tessellation with inner tessellation
|
||||
// levels of (a) five and (b) four, respectively (not to scale). Solid
|
||||
// black circles depict vertices along the edges of the concentric
|
||||
// triangles. The edges of inner triangles are subdivided by intersecting
|
||||
// the edge with segments perpendicular to the edge passing through each
|
||||
// inner vertex of the subdivided outer edge. Dotted lines depict edges
|
||||
// connecting corresponding vertices on the inner and outer triangle
|
||||
// edges.
|
||||
|
||||
Once all the concentric triangles are produced and their edges are
|
||||
subdivided, the area between each pair of adjacent inner triangles is
|
||||
filled completely with a set of non-overlapping triangles. In this
|
||||
subdivision, two of the three vertices of each triangle are taken from
|
||||
adjacent vertices on a subdivided edge of one triangle; the third is one
|
||||
of the vertices on the corresponding edge of the other triangle. If the
|
||||
innermost triangle is degenerate (i.e., a point), the triangle containing
|
||||
it is subdivided into six triangles by connecting each of the six vertices
|
||||
on that triangle with the center point. If the innermost triangle is not
|
||||
degenerate, that triangle is added to the set of generated triangles
|
||||
as-is.
|
||||
|
||||
After the area corresponding to any inner triangles is filled, the
|
||||
tessellator generates triangles to cover the area between the outermost
|
||||
triangle and the outermost inner triangle. To do this, the temporary
|
||||
subdivision of the outer triangle edge above is discarded. Instead, the
|
||||
latexmath:[$u=0$], latexmath:[$v=0$], and latexmath:[$w=0$] edges are
|
||||
subdivided according to the first, second, and third outer tessellation
|
||||
levels, respectively, and the tessellation spacing. The original subdivision
|
||||
of the first inner triangle is retained. The area between the outer and
|
||||
first inner triangles is completely filled by non-overlapping triangles as
|
||||
described above. If the first (and only) inner triangle is degenerate, a set
|
||||
of triangles is produced by connecting each vertex on the outer triangle
|
||||
edges with the center point.
|
||||
|
||||
After all triangles are generated, each vertex in the subdivided triangle
|
||||
is assigned a barycentric (u,v,w) coordinate based on its location
|
||||
relative to the three vertices of the outer triangle.
|
||||
|
||||
The algorithm used to subdivide the triangular domain in (u,v,w) space into
|
||||
individual triangles is implementation-dependent. However, the set of
|
||||
triangles produced will completely cover the domain, and no portion of the
|
||||
domain will be covered by multiple triangles. The order in which the
|
||||
generated triangles passed to subsequent pipeline stages and the order of
|
||||
the vertices in those triangles are both implementation-dependent. However,
|
||||
when depicted in a manner similar to <<img-innertri,Inner Triangle
|
||||
Tessellation>>, the order of the vertices in the generated triangles will be
|
||||
either all clockwise or all counter-clockwise, according to the vertex order
|
||||
layout declaration.
|
||||
|
||||
|
||||
[[tessellation-quad-tessellation]]
|
||||
== Quad Tessellation
|
||||
|
||||
If the tessellation primitive mode is code:Quads, a rectangle is subdivided
|
||||
into a collection of triangles covering the area of the original rectangle.
|
||||
First, the original rectangle is subdivided into a regular mesh of
|
||||
rectangles, where the number of rectangles along the latexmath:[$u=0$] and
|
||||
latexmath:[$u=1$] (vertical) and latexmath:[$v=0$] and latexmath:[$v=1$]
|
||||
(horizontal) edges are derived from the first and second inner tessellation
|
||||
levels, respectively. All rectangles, except those adjacent to one of the
|
||||
outer rectangle edges, are decomposed into triangle pairs. The outermost
|
||||
rectangle edges are subdivided independently, using the first, second,
|
||||
third, and fourth outer tessellation levels to control the number of
|
||||
subdivisions of the latexmath:[$u=0$] (left), latexmath:[$v=0$] (bottom),
|
||||
latexmath:[$u=1$] (right), and latexmath:[$v=1$] (top) edges, respectively.
|
||||
The area between the inner rectangles of the mesh and the outer rectangle
|
||||
edges are filled by triangles produced by joining the vertices on the
|
||||
subdivided outer edges to the vertices on the edge of the inner rectangle
|
||||
mesh.
|
||||
|
||||
If both clamped inner tessellation levels and all four clamped outer
|
||||
tessellation levels are exactly one, only a single triangle pair covering
|
||||
the outer rectangle is generated. Otherwise, if either clamped inner
|
||||
tessellation level is one, that tessellation level is treated as though it
|
||||
were originally specified as latexmath:[$1+\epsilon$] and will result in a
|
||||
two- or three-segment subdivision depending on the tessellation spacing.
|
||||
When used with fractional odd spacing, the three-segment subdivision may:
|
||||
produce _inner vertices_ positioned on the edge of the rectangle.
|
||||
|
||||
If any tessellation level is greater than one, tessellation begins by
|
||||
subdividing the latexmath:[$u=0$] and latexmath:[$u=1$] edges of the outer
|
||||
rectangle into latexmath:[$m$] segments using the clamped and rounded first
|
||||
inner tessellation level and the tessellation spacing. The latexmath:[$v=0$]
|
||||
and latexmath:[$v=1$] edges are subdivided into latexmath:[$n$] segments
|
||||
using the second inner tessellation level. Each vertex on the
|
||||
latexmath:[$u=0$] and latexmath:[$v=0$] edges are joined with the
|
||||
corresponding vertex on the latexmath:[$u=1$] and latexmath:[$v=1$] edges to
|
||||
produce a set of vertical and horizontal lines that divide the rectangle
|
||||
into a grid of smaller rectangles. The primitive generator emits a pair of
|
||||
non-overlapping triangles covering each such rectangle not adjacent to an
|
||||
edge of the outer rectangle. The boundary of the region covered by these
|
||||
triangles forms an inner rectangle, the edges of which are subdivided by the
|
||||
grid vertices that lie on the edge. If either latexmath:[$m$] or
|
||||
latexmath:[$n$] is two, the inner rectangle is degenerate, and one or both
|
||||
of the rectangle's _edges_ consist of a single point. This subdivision is
|
||||
illustrated in Figure <<img-innerquad,Inner Quad Tessellation>>.
|
||||
|
||||
[[img-innerquad,Inner Quad Tessellation]]
|
||||
.Inner Quad Tessellation
|
||||
image:images/innerquad.{svgpdf}["Inner Quad Tessellation",{fullimagewidth}]
|
||||
|
||||
// TODO: Add caption:
|
||||
// Inner quad tessellation with inner tessellation
|
||||
// levels of
|
||||
// (a) $(4,2)$ and (b) $(7,4)$, respectively. Gray regions on the
|
||||
// bottom figure
|
||||
// depict the 10 inner rectangles, each of which will be subdivided
|
||||
// into two triangles.
|
||||
// Solid black circles depict vertices on the boundary of the outer and
|
||||
// inner rectangles,
|
||||
// where the inner rectangle on the top figure
|
||||
// is degenerate (a single line segment). Dotted lines depict the
|
||||
// horizontal and vertical edges connecting corresponding
|
||||
// vertices on the inner and outer rectangle edges.
|
||||
|
||||
After the area corresponding to the inner rectangle is filled, the
|
||||
tessellator must: produce triangles to cover the area between the inner and
|
||||
outer rectangles. To do this, the subdivision of the outer rectangle edge
|
||||
above is discarded. Instead, the latexmath:[$u=0$], latexmath:[$v=0$],
|
||||
latexmath:[$u=1$], and latexmath:[$v=1$] edges are subdivided according to
|
||||
the first, second, third, and fourth outer tessellation levels,
|
||||
respectively, and the tessellation spacing. The original subdivision of the
|
||||
inner rectangle is retained. The area between the outer and inner rectangles
|
||||
is completely filled by non-overlapping triangles. Two of the three vertices
|
||||
of each triangle are adjacent vertices on a subdivided edge of one
|
||||
rectangle; the third is one of the vertices on the corresponding edge of the
|
||||
other triangle. If either edge of the innermost rectangle is degenerate, the
|
||||
area near the corresponding outer edges is filled by connecting each vertex
|
||||
on the outer edge with the single vertex making up the _inner edge_.
|
||||
|
||||
The algorithm used to subdivide the rectangular domain in (u,v) space into
|
||||
individual triangles is implementation-dependent. However, the set of
|
||||
triangles produced will completely cover the domain, and no portion of the
|
||||
domain will be covered by multiple triangles. The order in which the
|
||||
generated triangles passed to subsequent pipeline stages and the order of
|
||||
the vertices in those triangles are both implementation-dependent.
|
||||
However, when depicted in a manner similar to <<img-innerquad,Inner Quad
|
||||
Tessellation>>, the order of the vertices in the generated triangles will be
|
||||
either all clockwise or all counter-clockwise, according to the vertex order
|
||||
layout declaration.
|
||||
|
||||
|
||||
[[tessellation-isoline-tessellation]]
|
||||
== Isoline Tessellation
|
||||
|
||||
If the tessellation primitive mode is code:IsoLines, a set of independent
|
||||
horizontal line segments is drawn. The segments are arranged into
|
||||
connected strips called _isolines_, where the vertices of each isoline
|
||||
have a constant v coordinate and u coordinates covering the full range
|
||||
[0,1]. The number of isolines generated is derived from the first outer
|
||||
tessellation level; the number of segments in each isoline is derived from
|
||||
the second outer tessellation level. Both inner tessellation levels and
|
||||
the third and fourth outer tessellation levels have no effect in this
|
||||
mode.
|
||||
|
||||
As with quad tessellation above, isoline tessellation begins with a
|
||||
rectangle. The latexmath:[$u=0$] and latexmath:[$u=1$] edges of the
|
||||
rectangle are subdivided according to the first outer tessellation level.
|
||||
For the purposes of this subdivision, the tessellation spacing mode is
|
||||
ignored and treated as equal_spacing. An isoline is drawn connecting each
|
||||
vertex on the latexmath:[$u=0$] rectangle edge to the corresponding vertex
|
||||
on the latexmath:[$u=1$] rectangle edge, except that no line is drawn
|
||||
between (0,1) and (1,1). If the number of isolines on the subdivided
|
||||
latexmath:[$u=0$] and latexmath:[$u=1$] edges is latexmath:[$n$], this
|
||||
process will result in latexmath:[$n$] equally spaced lines with constant v
|
||||
coordinates of 0, latexmath:[$\frac{1}{n}, \frac{2}{n}, \ldots,
|
||||
\frac{n-1}{n}$].
|
||||
|
||||
Each of the latexmath:[$n$] isolines is then subdivided according to the
|
||||
second outer tessellation level and the tessellation spacing, resulting in
|
||||
latexmath:[$m$] line segments. Each segment of each line is emitted by the
|
||||
tessellator.
|
||||
|
||||
The order in which the generated line segments are passed to subsequent
|
||||
pipeline stages and the order of the vertices in each generated line
|
||||
segment are both implementation-dependent.
|
||||
|
||||
|
||||
== Tessellation Pipeline State
|
||||
|
||||
The pname:pTessellationState member of slink:VkGraphicsPipelineCreateInfo is
|
||||
of type sname:VkPipelineTessellationStateCreateInfo:
|
||||
|
||||
include::../structs/VkPipelineTessellationStateCreateInfo.txt[]
|
||||
|
||||
The members of the sname:VkPipelineTessellationStateCreateInfo structure are
|
||||
as follows:
|
||||
|
||||
* 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:patchControlPoints number of control points per patch.
|
||||
|
||||
include::../validity/structs/VkPipelineTessellationStateCreateInfo.txt[]
|
||||
File diff suppressed because it is too large
Load Diff
|
|
@ -0,0 +1,401 @@
|
|||
// Copyright (c) 2015-2016 The Khronos Group Inc.
|
||||
// Copyright notice at https://www.khronos.org/registry/speccopyright.html
|
||||
|
||||
[[vertexpostproc]]
|
||||
= Fixed-Function Vertex Post-Processing
|
||||
|
||||
After programmable vertex processing, the following fixed-function
|
||||
operations are applied to vertices of the resulting primitives:
|
||||
|
||||
* Flatshading (see <<vertexpostproc-flatshading,Flatshading>>).
|
||||
* Primitive clipping, including client-defined half-spaces (see
|
||||
<<vertexpostproc-clipping,Primitive Clipping>>).
|
||||
* Shader output attribute clipping (see
|
||||
<<vertexpostproc-clipping-shader-outputs,Clipping Shader Outputs>>).
|
||||
* Perspective division on clip coordinates (see
|
||||
<<vertexpostproc-coord-transform,Coordinate Transformations>>).
|
||||
* Viewport mapping, including depth range scaling (see
|
||||
<<vertexpostproc-viewport,Controlling the Viewport>>).
|
||||
* Front face determination for polygon primitives (see
|
||||
<<primsrast-triangles-basic,Basic Triangle Rasterization>>).
|
||||
|
||||
ifdef::editing-notes[]
|
||||
[NOTE]
|
||||
.editing-note
|
||||
====
|
||||
TODO:Odd that this one link to a different chapter is in this list.
|
||||
====
|
||||
endif::editing-notes[]
|
||||
|
||||
Next, rasterization is performed on primitives as described in chapter
|
||||
<<primsrast,Rasterization>>.
|
||||
|
||||
|
||||
[[vertexpostproc-flatshading]]
|
||||
== Flatshading
|
||||
|
||||
_Flatshading_ a vertex output attribute means to assign all vertices of the
|
||||
primitive the same value for that output.
|
||||
|
||||
The output values assigned are those of the _provoking vertex_ of the
|
||||
primitive. The provoking vertex depends on the primitive topology, and is
|
||||
generally the ``first'' vertex of the primitive. For primitives not
|
||||
processed by tessellation or geometry shaders, the provoking vertex is
|
||||
selected from the input vertices according to the following table.
|
||||
|
||||
<<<
|
||||
|
||||
.Provoking vertex selection
|
||||
[align="center",cols="75%,25%"]
|
||||
|========================================
|
||||
|Primitive type of primitive latexmath:[$i$] | Provoking vertex number
|
||||
|ename:VK_PRIMITIVE_TOPOLOGY_POINT_LIST | latexmath:[$i$]
|
||||
|ename:VK_PRIMITIVE_TOPOLOGY_LINE_LIST | latexmath:[$2 i$]
|
||||
|ename:VK_PRIMITIVE_TOPOLOGY_LINE_STRIP | latexmath:[$i$]
|
||||
|ename:VK_PRIMITIVE_TOPOLOGY_TRIANGLE_LIST | latexmath:[$3 i$]
|
||||
|ename:VK_PRIMITIVE_TOPOLOGY_TRIANGLE_STRIP | latexmath:[$i$]
|
||||
|ename:VK_PRIMITIVE_TOPOLOGY_TRIANGLE_FAN | latexmath:[$i + 1$]
|
||||
|ename:VK_PRIMITIVE_TOPOLOGY_LINE_LIST_WITH_ADJACENCY | latexmath:[$4 i + 1$]
|
||||
|ename:VK_PRIMITIVE_TOPOLOGY_LINE_STRIP_WITH_ADJACENCY | latexmath:[$i + 1$]
|
||||
|ename:VK_PRIMITIVE_TOPOLOGY_TRIANGLE_LIST_WITH_ADJACENCY | latexmath:[$6 i$]
|
||||
|ename:VK_PRIMITIVE_TOPOLOGY_TRIANGLE_STRIP_WITH_ADJACENCY | latexmath:[$2 i$]
|
||||
|========================================
|
||||
|
||||
ifdef::editing-notes[]
|
||||
[NOTE]
|
||||
.editing-note
|
||||
====
|
||||
TODO: Add full caption:
|
||||
|
||||
Provoking vertex selection. The output values used for flatshading the i^th^
|
||||
primitive generated by drawing commands with the indicated primitive type
|
||||
are derived from the corresponding values of the vertex whose index is shown
|
||||
in the table. Primitives and vertices are numbered starting from zero.
|
||||
====
|
||||
endif::editing-notes[]
|
||||
|
||||
Flatshading is applied to those vertex attributes that
|
||||
<<interfaces-iointerfaces-matching,match>> fragment input attributes
|
||||
which are decorated as code:Flat.
|
||||
|
||||
If a geometry shader is active, the output primitive topology is either
|
||||
points, line strips, or triangle strips, and the selection of the provoking
|
||||
vertex behaves according to the corresponding row of the table. If a
|
||||
tessellation evaluation shader is active and a geometry shader is not
|
||||
active, the provoking vertex is undefined but must: be one of the vertices
|
||||
of the primitive.
|
||||
|
||||
|
||||
[[vertexpostproc-clipping]]
|
||||
== Primitive Clipping
|
||||
|
||||
Primitives are culled against the _cull volume_ and then clipped to the
|
||||
_clip volume_. In clip coordinates, the _view volume_ is defined by:
|
||||
|
||||
latexmath:[$
|
||||
\begin{array}{c}
|
||||
-w_c \leq x_c \leq w_c \\
|
||||
-w_c \leq y_c \leq w_c \\
|
||||
0 \leq z_c \leq w_c \\
|
||||
\end{array}
|
||||
$]
|
||||
|
||||
This view volume can: be further restricted by as many as
|
||||
sname:VkPhysicalDeviceLimits::pname:maxClipDistances client-defined
|
||||
half-spaces.
|
||||
|
||||
The cull volume is the intersection of up to
|
||||
sname:VkPhysicalDeviceLimits::pname:maxCullDistances client-defined
|
||||
half-spaces (if no client-defined cull half-spaces are enabled, culling
|
||||
against the cull volume is skipped).
|
||||
|
||||
A shader must: write a single cull distance for each enabled cull half-space
|
||||
to elements of the code:CullDistance array. If the cull distance for any
|
||||
enabled cull half-space is negative for all of the vertices of the primitive
|
||||
under consideration, the primitive is discarded. Otherwise the primitive is
|
||||
clipped against the clip volume as defined below.
|
||||
|
||||
The clip volume is the intersection of up to the value of
|
||||
sname:VkPhysicalDeviceLimits::pname:maxClipDistances client-defined
|
||||
half-spaces with the view volume (if no client-defined clip half-spaces are
|
||||
enabled, the clip volume is the view volume).
|
||||
|
||||
A shader must: write a single clip distance for each enabled clip
|
||||
half-space to elements of the code:ClipDistance array. Clip half-space
|
||||
latexmath:[$i$] is then given by the set of points satisfying the inequality
|
||||
|
||||
latexmath:[$c_i(P) \geq 0$]
|
||||
|
||||
where latexmath:[$c_i(P)$] is the value of clip distance latexmath:[$i$] at
|
||||
point latexmath:[$P$]. For point primitives, latexmath:[$c_i(P)$] is simply
|
||||
the clip distance for the vertex in question. For line and triangle
|
||||
primitives, per-vertex clip distances are interpolated using a weighted
|
||||
mean, with weights derived according to the algorithms described in sections
|
||||
<<primsrast-lines-basic,Basic Line Segment Rasterization>> and
|
||||
<<primsrast-polygons-basic,Basic Polygon Rasterization>>, using the
|
||||
perspective interpolation equations.
|
||||
|
||||
The number of client-defined clip and cull half-spaces that are enabled is
|
||||
determined by the explicit size of the built-in arrays code:ClipDistance and
|
||||
code:CullDistance, respectively, declared as an output in the interface of
|
||||
the entry point of the final shader stage before clipping.
|
||||
|
||||
Depth clamping is enabled or disabled via the pname:depthClampEnable enable
|
||||
of the sname:VkPipelineRasterizationStateCreateInfo structure. If depth
|
||||
clamping is enabled, the plane equation
|
||||
|
||||
latexmath:[$0 \leq z_c \leq w_c$]
|
||||
|
||||
(see the clip volume definition above) is ignored by view
|
||||
volume clipping (effectively, there is no near or far plane clipping).
|
||||
|
||||
If the primitive under consideration is a point, then clipping passes it
|
||||
unchanged if it lies within the clip volume; otherwise, it is discarded.
|
||||
|
||||
If the primitive is a line segment, then clipping does nothing to it if it
|
||||
lies entirely within the clip volume, and discards it if it lies entirely
|
||||
outside the volume.
|
||||
|
||||
If part of the line segment lies in the volume and part lies outside, then
|
||||
the line segment is clipped and new vertex coordinates are computed for one
|
||||
or both vertices. A clipped line segment endpoint lies on both the original
|
||||
line segment and the boundary of the clip volume.
|
||||
|
||||
This clipping produces a value, latexmath:[$0 \leq t \leq 1$], for each
|
||||
clipped vertex. If the coordinates of a clipped vertex are
|
||||
latexmath:[${\textbf P}$] and the original vertices' coordinates are
|
||||
latexmath:[${\textbf P}_1$] and latexmath:[${\textbf P}_2$], then
|
||||
latexmath:[$t$] is given by
|
||||
|
||||
latexmath:[${\textbf P} = t{\textbf P}_1 + (1-t){\textbf P}_2.$]
|
||||
|
||||
The value of latexmath:[$t$] is used to clip vertex output attributes as
|
||||
described in <<vertexpostproc-clipping-shader-outputs,Clipping Shader
|
||||
Outputs>>.
|
||||
|
||||
If the primitive is a polygon, it passes unchanged if every one of its edges
|
||||
lie entirely inside the clip volume, and it is discarded if every one of its
|
||||
edges lie entirely outside the clip volume. If the edges of the polygon
|
||||
intersect the boundary of the clip volume, the intersecting edges are
|
||||
reconnected by new edges that lie along the boundary of the clip volume -
|
||||
in some cases requiring the introduction of new vertices into a polygon.
|
||||
|
||||
If a polygon intersects an edge of the clip volume's boundary, the clipped
|
||||
polygon must: include a point on this boundary edge.
|
||||
|
||||
Primitives rendered with user-defined half-spaces must: satisfy a
|
||||
complementarity criterion. Suppose a series of primitives is drawn where
|
||||
each vertex latexmath:[$i$] has a single specified clip distance
|
||||
latexmath:[$d_i$] (or a number of similarly specified clip distances, if
|
||||
multiple half-spaces are enabled). Next, suppose that the same series of
|
||||
primitives are drawn again with each such clip distance replaced by
|
||||
latexmath:[$-d_i$] (and the graphics pipeline is otherwise the same). In
|
||||
this case, primitives mustnot: be missing any pixels, and pixels mustnot: be
|
||||
drawn twice in regions where those primitives are cut by the clip planes.
|
||||
|
||||
|
||||
[[vertexpostproc-clipping-shader-outputs]]
|
||||
== Clipping Shader Outputs
|
||||
|
||||
Next, vertex output attributes are clipped. The output values associated
|
||||
with a vertex that lies within the clip volume are unaffected by clipping.
|
||||
If a primitive is clipped, however, the output values assigned to vertices
|
||||
produced by clipping are clipped.
|
||||
|
||||
Let the output values assigned to the two vertices latexmath:[${\textbf
|
||||
P}_1$] and latexmath:[${\textbf P}_2$] of an unclipped edge be
|
||||
latexmath:[${\textbf c}_1$] and latexmath:[${\textbf c}_2$]. The value of
|
||||
latexmath:[$t$] (see <<vertexpostproc-clipping,Primitive Clipping>>) for a
|
||||
clipped point latexmath:[${\textbf P}$] is used to obtain the output value
|
||||
associated with latexmath:[${\textbf P}$] as
|
||||
|
||||
latexmath:[${\textbf c} = t {\textbf c}_1 + (1-t){\textbf c}_2. $]
|
||||
|
||||
(Multiplying an output value by a scalar means multiplying each of _x_, _y_,
|
||||
_z_, and _w_ by the scalar.)
|
||||
|
||||
Since this computation is performed in clip space before division by
|
||||
latexmath:[$w_c$], clipped output values are perspective-correct.
|
||||
|
||||
Polygon clipping creates a clipped vertex along an edge of the clip
|
||||
volume's boundary. This situation is handled by noting that polygon clipping
|
||||
proceeds by clipping against one half-space at a time. Output value clipping
|
||||
is done in the same way, so that clipped points always occur at the
|
||||
intersection of polygon edges (possibly already clipped) with the clip
|
||||
volume's boundary.
|
||||
|
||||
For vertex output attributes whose matching fragment input attributes are
|
||||
decorated with code:NoPerspective, the value
|
||||
of latexmath:[$t$] used to obtain the output value associated with
|
||||
latexmath:[${\textbf P}$] will be adjusted to produce results that vary
|
||||
linearly in framebuffer space.
|
||||
|
||||
Output attributes of integer or unsigned integer type must: always be
|
||||
flatshaded. Flatshaded attributes are constant over the primitive being
|
||||
rasterized (see <<primsrast-lines-basic,Basic Line Segment Rasterization>>
|
||||
and <<primsrast-polygons-basic,Basic Polygon Rasterization>>), and no
|
||||
interpolation is performed. The output value latexmath:[${\textbf c}$] is
|
||||
taken from either latexmath:[${\textbf c}_1$] or latexmath:[${\textbf
|
||||
c}_2$], since flatshading has already occured and the two values are
|
||||
identical.
|
||||
|
||||
|
||||
[[vertexpostproc-coord-transform]]
|
||||
== Coordinate Transformations
|
||||
|
||||
_Clip coordinates_ for a vertex result from shader execution, which yields a
|
||||
vertex coordinate code:Position.
|
||||
|
||||
Perspective division on clip coordinates yields _normalized device
|
||||
coordinates_, followed by a _viewport_ transformation (see
|
||||
<<vertexpostproc-viewport,Controlling the Viewport>>) to convert these
|
||||
coordinates into _framebuffer coordinates_.
|
||||
|
||||
If a vertex in clip coordinates has a position given by
|
||||
|
||||
latexmath:[$\left(\begin{array}{c} x_c \\ y_c \\ z_c \\ w_c \end{array}\right)$]
|
||||
|
||||
then the vertex's normalized device coordinates are
|
||||
|
||||
latexmath:[$
|
||||
\left(\begin{array}{c} x_d \\ y_d \\ z_d \end{array}\right) =
|
||||
\left(\begin{array}{c} \frac{x_c}{w_c} \\ \frac{y_c}{w_c} \\ \frac{z_c}{w_c} \end{array}\right)
|
||||
$]
|
||||
|
||||
|
||||
[[vertexpostproc-viewport]]
|
||||
== Controlling the Viewport
|
||||
|
||||
The viewport transformation is determined by the selected viewport's width
|
||||
and height in pixels, latexmath:[$p_x$] and latexmath:[$p_y$], respectively,
|
||||
and its center latexmath:[$(o_x, o_y)$] (also in pixels), as well as its
|
||||
depth range min and max determining a depth range scale value
|
||||
latexmath:[$p_z$] and a depth range bias value latexmath:[$o_z$] (defined
|
||||
below). The vertex's framebuffer coordinates,
|
||||
latexmath:[$\left(\begin{array}{c} x_f \\ y_f \\ z_f \end{array}\right),$]
|
||||
are given by
|
||||
|
||||
latexmath:[$
|
||||
\left(\begin{array}{c} x_f \\ y_f \\ z_f \end{array}\right) =
|
||||
\left(\begin{array}{c}
|
||||
\frac{ p_x }{ 2 } x_d + o_x \\
|
||||
\frac{ p_y }{ 2 } y_d + o_y \\
|
||||
p_z \times z_d + o_z
|
||||
\end{array}\right).
|
||||
$]
|
||||
|
||||
Multiple viewports are available and are numbered zero up to the value of
|
||||
sname:VkPhysicalDeviceLimits::pname:maxViewports. The number of viewports
|
||||
used by a pipeline is controlled by the pname:viewportCount member of the
|
||||
sname:VkPipelineViewportStateCreateInfo structure used in pipeline creation:
|
||||
|
||||
include::../structs/VkPipelineViewportStateCreateInfo.txt[]
|
||||
|
||||
The members of the sname:VkPipelineViewportStateCreateInfo structure are as
|
||||
follows:
|
||||
|
||||
* 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:viewportCount is the number of viewports used by the pipeline.
|
||||
* pname:pViewports is a pointer to an array of slink:VkViewport structs,
|
||||
defining the viewport transforms. If the viewport state is dynamic, this
|
||||
member is ignored.
|
||||
* pname:scissorCount is the number of <<fragops-scissor,scissors>> and
|
||||
must: match the number of viewports.
|
||||
* pname:pScissors is a pointer to an array of sname:VkRect2D structs which
|
||||
define the rectangular bounds of the scissor for the corresponding
|
||||
viewport. If the scissor state is dynamic, this member is ignored.
|
||||
|
||||
include::../validity/structs/VkPipelineViewportStateCreateInfo.txt[]
|
||||
|
||||
If a geometry shader is active and has an output variable decorated with
|
||||
code:ViewportIndex, the viewport transformation uses the viewport
|
||||
corresponding to the value assigned to code:ViewportIndex taken from an
|
||||
implementation-dependent vertex of each primitive. If the value of
|
||||
code:ViewportIndex is outside the range zero to the value of
|
||||
pname:viewportCount minus one for a primitive, or if the geometry shader did
|
||||
not assign a value to code:ViewportIndex for all vertices of a primitive due
|
||||
to flow control, the results of the viewport transformation of the vertices
|
||||
of such primitives are undefined. If no geometry shader is active, or if the
|
||||
geometry shader does not have an output decorated with code:ViewportIndex,
|
||||
the viewport numbered zero is used by the viewport transformation.
|
||||
|
||||
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.
|
||||
|
||||
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
|
||||
member of sname:VkPipelineViewportStateCreateInfo in the pipeline state
|
||||
object. If the pipeline state object was created with the
|
||||
ename:VK_DYNAMIC_STATE_VIEWPORT dynamic state enabled, the viewport
|
||||
transformation parameters are dynamically set and changed with the command:
|
||||
|
||||
include::../protos/vkCmdSetViewport.txt[]
|
||||
|
||||
* pname:commandBuffer is the command buffer into which the command will be
|
||||
recorded.
|
||||
* pname:firstViewport is the index of the first viewport whose parameters
|
||||
are updated by the command.
|
||||
* pname:viewportCount is the number of viewports whose parameters are
|
||||
updated by the command.
|
||||
* pname:pViewports is a pointer to an array of slink:VkViewport structures
|
||||
specifying viewport parameters.
|
||||
|
||||
The viewport parameters taken from element latexmath:[$i$] of
|
||||
pname:pViewports replace the current state for the viewport index
|
||||
latexmath:[$\mathit{firstViewport}+i$], for latexmath:[$i$] in
|
||||
latexmath:[$[0, viewportCount)$].
|
||||
|
||||
include::../validity/protos/vkCmdSetViewport.txt[]
|
||||
|
||||
Either of these methods of setting the viewport transformation parameters
|
||||
use the sname:VkViewport struct:
|
||||
|
||||
include::../structs/VkViewport.txt[]
|
||||
|
||||
* pname:x and pname:y are the viewport's upper left corner
|
||||
latexmath:[$(x,y)$].
|
||||
* pname:width and pname:height are the viewport's width and height,
|
||||
respectively.
|
||||
* pname:minDepth and pname:maxDepth are the depth range for the viewport.
|
||||
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
|
||||
has a floating-point depth component. If an latexmath:[$m$]-bit fixed-point
|
||||
representation is used, we assume that it represents each value
|
||||
latexmath:[$\frac{k}{2^m - 1}$], where latexmath:[$k \in \{ 0,1, \ldots,
|
||||
2^m-1 \}$], as latexmath:[$k$] (e.g. 1.0 is represented in binary as a
|
||||
string of all ones).
|
||||
|
||||
The viewport parameters shown in the above equations are found from these
|
||||
values as
|
||||
|
||||
[latexmath]
|
||||
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
|
||||
\begin{align*}
|
||||
o_x & = x + \frac{width}{2} \\
|
||||
o_y & = y + \frac{height}{2} \\
|
||||
o_z & = minDepth \\
|
||||
p_x & = width \\
|
||||
p_y & = height \\
|
||||
p_z & = maxDepth - minDepth.
|
||||
\end{align*}
|
||||
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
|
||||
|
||||
The width and height of the <<features-limits-maxViewportDimensions,
|
||||
implementation-dependent maximum viewport dimensions>> must: be greater
|
||||
than or equal to the width and height of the largest image which can: be
|
||||
created and attached to a framebuffer.
|
||||
|
||||
The floating-point viewport bounds are represented with an
|
||||
<<features-limits-viewportSubPixelBits,implementation-dependent precision>>.
|
||||
|
||||
|
||||
|
|
@ -0,0 +1,312 @@
|
|||
#!/usr/bin/python3
|
||||
#
|
||||
# Copyright (c) 2015-2016 The Khronos Group Inc.
|
||||
#
|
||||
# Permission is hereby granted, free of charge, to any person obtaining a
|
||||
# copy of this software and/or associated documentation files (the
|
||||
# "Materials"), to deal in the Materials without restriction, including
|
||||
# without limitation the rights to use, copy, modify, merge, publish,
|
||||
# distribute, sublicense, and/or sell copies of the Materials, and to
|
||||
# permit persons to whom the Materials are furnished to do so, subject to
|
||||
# the following conditions:
|
||||
#
|
||||
# The above copyright notice and this permission notice shall be included
|
||||
# in all copies or substantial portions of the Materials.
|
||||
#
|
||||
# THE MATERIALS ARE PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
|
||||
# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
|
||||
# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
|
||||
# IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
|
||||
# CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
|
||||
# TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
|
||||
# MATERIALS OR THE USE OR OTHER DEALINGS IN THE MATERIALS.
|
||||
|
||||
# checkLinks.py - validate link/reference API constructs in files
|
||||
#
|
||||
# Usage: checkLinks.py files > logfile
|
||||
#
|
||||
# Uses vkapi.py, which is a Python representation of relevant parts
|
||||
# of the Vulkan API.
|
||||
|
||||
import copy, os, pdb, re, string, sys
|
||||
from vkapi import *
|
||||
|
||||
global curFile, curLine, sectionDepth
|
||||
global errCount, warnCount, emittedPrefix, printInfo
|
||||
|
||||
curFile = '???'
|
||||
curLine = -1
|
||||
sectionDepth = 0
|
||||
errCount = 0
|
||||
warnCount = 0
|
||||
emittedPrefix = {}
|
||||
printInfo = False
|
||||
|
||||
# Called before printing a warning or error. Only prints once prior
|
||||
# to output for a given file.
|
||||
def emitPrefix():
|
||||
global curFile, curLine, emittedPrefix
|
||||
if (curFile not in emittedPrefix.keys()):
|
||||
emittedPrefix[curFile] = None
|
||||
print('Checking file:', curFile)
|
||||
print('-------------------------------')
|
||||
|
||||
def info(*args, **kwargs):
|
||||
global curFile, curLine, printInfo
|
||||
if (printInfo):
|
||||
|
||||
emitPrefix()
|
||||
print('INFO: %s line %d:' % (curFile, curLine),
|
||||
' '.join([str(arg) for arg in args]))
|
||||
|
||||
# Print a validation warning found in a file
|
||||
def warning(*args, **kwargs):
|
||||
global curFile, curLine, warnCount
|
||||
|
||||
warnCount = warnCount + 1
|
||||
emitPrefix()
|
||||
print('WARNING: %s line %d:' % (curFile, curLine),
|
||||
' '.join([str(arg) for arg in args]))
|
||||
|
||||
# Print a validation error found in a file
|
||||
def error(*args, **kwargs):
|
||||
global curFile, curLine, errCount
|
||||
|
||||
errCount = errCount + 1
|
||||
emitPrefix()
|
||||
print('ERROR: %s line %d:' % (curFile, curLine),
|
||||
' '.join([str(arg) for arg in args]))
|
||||
|
||||
# See if a tag value exists in the specified dictionary and
|
||||
# suggest it as an alternative if so.
|
||||
def checkTag(tag, value, dict, dictName, tagName):
|
||||
if (value in dict.keys()):
|
||||
warning(value, 'exists in the API but not as a',
|
||||
tag + ': .', 'Try using the', tagName + ': tag.')
|
||||
|
||||
# Report an error due to an asciidoc tag which doesn't match
|
||||
# a corresponding API entity.
|
||||
def foundError(errType, tag, value):
|
||||
global curFile, curLine
|
||||
error('no such', errType, tag + ':' + value)
|
||||
# Try some heuristics to detect likely problems such as missing vk
|
||||
# prefixes or the wrong tag.
|
||||
|
||||
# Look in all the dictionaries in vkapi.py to see if the tag
|
||||
# is just wrong but the API entity actually exists.
|
||||
checkTag(tag, value, flags, 'flags', 'elink')
|
||||
checkTag(tag, value, enums, 'enums', 'elink')
|
||||
checkTag(tag, value, structs, 'structs', 'slink/sname')
|
||||
checkTag(tag, value, consts, 'consts', 'ename')
|
||||
checkTag(tag, value, protos, 'protos', 'flink/fname')
|
||||
checkTag(tag, value, funcpointers, 'funcpointers', 'tlink/tname')
|
||||
|
||||
# Look for missing vk prefixes (quirky since it's case-dependent)
|
||||
# NOT DONE YET
|
||||
|
||||
# Look for param in the list of all parameters of the specified functions
|
||||
# Returns True if found, False otherwise
|
||||
def findParam(param, funclist):
|
||||
for f in funclist:
|
||||
if (param in protos[f]):
|
||||
info('parameter:', param, 'found in function:', f)
|
||||
return True
|
||||
return False
|
||||
|
||||
# Initialize tracking state for checking links/includes
|
||||
def initChecks():
|
||||
global curFile, curLine, curFuncs, curStruct, accumFunc, sectionDepth
|
||||
global errCount, warnCount
|
||||
global incPat, linkPat, pathPat, sectionPat
|
||||
|
||||
# Matches asciidoc single-line section tags
|
||||
sectionPat = re.compile('^(=+) ')
|
||||
|
||||
# Matches any asciidoc include:: directive
|
||||
pathPat = re.compile('^include::([\w./_]+)\[\]')
|
||||
|
||||
# Matches asciidoc include:: directives used in spec/ref pages (and also
|
||||
# others such as validity)
|
||||
incPat = re.compile('^\.\./(\w+)/(\w+)\.txt')
|
||||
|
||||
# Lists of current /protos/ (functions) and /structs/ includes. There
|
||||
# can be several protos contiguously for different forms of a command
|
||||
curFuncs = []
|
||||
curStruct = None
|
||||
|
||||
# Tag if we should accumulate funcs or start a new list. Any intervening
|
||||
# pname: tags or struct includes will restart the list.
|
||||
accumFunc = False
|
||||
|
||||
# Matches all link names in the current spec/man pages. Assumes these
|
||||
# macro names are not trailing subsets of other macros. Used to
|
||||
# precede the regexp with [^A-Za-z], but this didn't catch macros
|
||||
# at start of line.
|
||||
linkPat = re.compile('([efpst](name|link)):(\w*)')
|
||||
|
||||
# Total error/warning counters
|
||||
errCount = 0
|
||||
warnCount = 0
|
||||
|
||||
# Validate asciidoc internal links in specified file.
|
||||
# infile - filename to validate
|
||||
# follow - if True, recursively follow include:: directives
|
||||
# included - if True, function was called recursively
|
||||
# Links checked are:
|
||||
# fname:vkBlah - Vulkan command name (generates internal link)
|
||||
# flink:vkBlah - Vulkan command name
|
||||
# sname:VkBlah - Vulkan struct name (generates internal link)
|
||||
# slink:VkBlah - Vulkan struct name
|
||||
# elink:VkEnumName - Vulkan enumeration ('enum') type name
|
||||
# ename:VK_BLAH - Vulkan enumerant token name
|
||||
# pname:name - parameter name to a command or a struct member
|
||||
# tlink:name - Other Vulkan type name (generates internal link)
|
||||
# tname:name - Other Vulkan type name
|
||||
def checkLinks(infile, follow = False, included = False):
|
||||
global curFile, curLine, curFuncs, curStruct, accumFunc, sectionDepth
|
||||
global errCount, warnCount
|
||||
global incPat, linkPat, pathPat, sectionPat
|
||||
|
||||
# Global state which gets saved and restored by this function
|
||||
oldCurFile = curFile
|
||||
oldCurLine = curLine
|
||||
curFile = infile
|
||||
curLine = 0
|
||||
|
||||
# N.b. dirname() returns an empty string for a path with no directories,
|
||||
# unlike the shell dirname(1).
|
||||
if (not os.path.exists(curFile)):
|
||||
error('No such file', curFile, '- skipping check')
|
||||
# Restore global state before exiting the function
|
||||
curFile = oldCurFile
|
||||
curLine = oldCurLine
|
||||
return
|
||||
|
||||
inPath = os.path.dirname(curFile)
|
||||
fp = open(curFile, 'r')
|
||||
|
||||
for line in fp:
|
||||
curLine = curLine + 1
|
||||
|
||||
# Track changes up and down section headers, and forget
|
||||
# the current functions/structure when popping up a level
|
||||
match = sectionPat.search(line)
|
||||
if (match):
|
||||
depth = len(match.group(1))
|
||||
if (depth < sectionDepth):
|
||||
info('Resetting current function/structure for section:', line)
|
||||
curFuncs = []
|
||||
curStruct = None
|
||||
sectionDepth = depth
|
||||
|
||||
match = pathPat.search(line)
|
||||
if (match):
|
||||
incpath = match.group(1)
|
||||
# An include:: directive. First check if it looks like a
|
||||
# function or struct include file, and modify the corresponding
|
||||
# current function or struct state accordingly.
|
||||
match = incPat.search(incpath)
|
||||
if (match):
|
||||
# For prototypes, if it is preceded by
|
||||
# another include:: directive with no intervening link: tags,
|
||||
# add to the current function list. Otherwise start a new list.
|
||||
# There is only one current structure.
|
||||
category = match.group(1)
|
||||
tag = match.group(2)
|
||||
# @ Validate tag!
|
||||
# @ Arguably, any intervening text should shift to accumFuncs = False,
|
||||
# e.g. only back-to-back includes separated by blank lines would be
|
||||
# accumulated.
|
||||
if (category == 'protos'):
|
||||
if (tag in protos.keys()):
|
||||
if (accumFunc):
|
||||
curFuncs.append(tag)
|
||||
else:
|
||||
curFuncs = [ tag ]
|
||||
# Restart accumulating functions
|
||||
accumFunc = True
|
||||
info('curFuncs =', curFuncs, 'accumFunc =', accumFunc)
|
||||
else:
|
||||
error('include of nonexistent function', tag)
|
||||
elif (category == 'structs'):
|
||||
if (tag in structs.keys()):
|
||||
curStruct = tag
|
||||
# Any /structs/ include means to stop accumulating /protos/
|
||||
accumFunc = False
|
||||
info('curStruct =', curStruct)
|
||||
else:
|
||||
error('include of nonexistent struct', tag)
|
||||
if (follow):
|
||||
# Actually process the included file now, recursively
|
||||
newpath = os.path.normpath(os.path.join(inPath, incpath))
|
||||
info(curFile, ': including file:', newpath)
|
||||
checkLinks(newpath, follow, included=True)
|
||||
|
||||
matches = linkPat.findall(line)
|
||||
for match in matches:
|
||||
# Start actual validation work. Depending on what the
|
||||
# asciidoc tag name is, look up the value in the corresponding
|
||||
# dictionary.
|
||||
tag = match[0]
|
||||
value = match[2]
|
||||
if (tag == 'fname' or tag == 'flink'):
|
||||
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)
|
||||
elif (tag == 'ename'):
|
||||
if (value not in consts.keys()):
|
||||
foundError('enumerant/constant', tag, value)
|
||||
elif (tag == 'elink'):
|
||||
if (value not in enums.keys() and value not in flags.keys()):
|
||||
foundError('enum/bitflag type', tag, value)
|
||||
elif (tag == 'tlink' or tag == 'tname'):
|
||||
if (value not in funcpointers.keys()):
|
||||
foundError('function pointer/other type', tag, value)
|
||||
elif (tag == 'pname'):
|
||||
# Any pname: tag means to stop accumulating /protos/
|
||||
accumFunc = False
|
||||
# See if this parameter is in the current proto(s) and struct
|
||||
foundParam = False
|
||||
if (curStruct and value in structs[curStruct]):
|
||||
info('parameter', value, 'found in struct', curStruct)
|
||||
elif (curFuncs and findParam(value, curFuncs)):
|
||||
True
|
||||
else:
|
||||
warning('parameter', value, 'not found. curStruct =',
|
||||
curStruct, 'curFuncs =', curFuncs)
|
||||
else:
|
||||
# This is a logic error
|
||||
error('unknown tag', tag + ':' + value)
|
||||
fp.close()
|
||||
|
||||
if (errCount > 0 or warnCount > 0):
|
||||
if (not included):
|
||||
print('Errors found:', errCount, 'Warnings found:', warnCount)
|
||||
print('')
|
||||
|
||||
if (included):
|
||||
info('----- returning from:', infile, 'to parent file', '-----')
|
||||
|
||||
# Don't generate any output for files without errors
|
||||
# else:
|
||||
# print(curFile + ': No errors found')
|
||||
|
||||
# Restore global state before exiting the function
|
||||
curFile = oldCurFile
|
||||
curLine = oldCurLine
|
||||
|
||||
if __name__ == '__main__':
|
||||
follow = False
|
||||
if (len(sys.argv) > 1):
|
||||
for file in sys.argv[1:]:
|
||||
if (file == '-follow'):
|
||||
follow = True
|
||||
elif (file == '-info'):
|
||||
printInfo = True
|
||||
else:
|
||||
initChecks()
|
||||
checkLinks(file, follow)
|
||||
else:
|
||||
print('Need arguments: [-follow] [-info] infile [infile...]', file=sys.stderr)
|
||||
|
|
@ -0,0 +1,76 @@
|
|||
There's apparently some sort of parsing issue with comments in vkspec.conf,
|
||||
so they are pulled out here for now.
|
||||
|
||||
// The [efs]link macros insert named xrefs to the specified target
|
||||
// enumerated type, function, or structure name, and are also used
|
||||
// for validation.
|
||||
// Could also use <xref linkend="{target}"/>
|
||||
|
||||
// The [efsp]text macros insert the specified target enumerant, function,
|
||||
// structure or parameter name, and are NOT used for validation. They are
|
||||
// otherwise identical to the [efsp]name macros above, and are intended
|
||||
// to get the proper formatting for terms that are *not* actually API
|
||||
// features, e.g. wildcards or partial names.
|
||||
|
||||
// The [efsp]name macros insert the specified target enumerant, function,
|
||||
// structure or parameter name, and are also used for validation.
|
||||
|
||||
// The basetype macro inserts text for the specified base (scalar) type. It
|
||||
// is not currently used for validation, but will be eventually
|
||||
|
||||
// The code macro inserts text for the specified shader code function or
|
||||
// variable.
|
||||
|
||||
// I have no idea what the old 'vkkeyword' macro does, but it appears
|
||||
// to be unused, so removed it and archived here for the moment.
|
||||
//
|
||||
// (?u)^(?P<name>):(?P<subslist>\S*?)(\[(?P<passtext>.*?)\])$=vkkeyword
|
||||
//
|
||||
// [vkkeyword-inlinemacro]
|
||||
// {passtext}
|
||||
|
||||
--------------- PDF Generation ----------------
|
||||
|
||||
vkspec-dblatex.xsl is XSL specific to a2x->dblatex->PDF spec generation.
|
||||
It is a very slightly modified version of
|
||||
/etc/asciidoc/dblatex/asciidoc-dblatex.xsl, as follows:
|
||||
|
||||
> <xsl:param name="latex.hyperparam">colorlinks,linkcolor=black,pdfstartview=FitH</xsl:param>
|
||||
> <xsl:param name="doc.publisher.show">0</xsl:param>
|
||||
> <xsl:param name="latex.output.revhistory">0</xsl:param>
|
||||
|
||||
and has been simplified to just those parameters. Additional templates
|
||||
replacing those under
|
||||
/usr/share/xml/docbook/stylesheet/dblatex/xsl/* can be added here.
|
||||
|
||||
--------------- XHTML Generation ----------------
|
||||
|
||||
vkspec-xhtml.css is CSS for the xhtml and chunked targets. It is pulled
|
||||
in from docbook-xsl/common.xsl. This gives us direct control over the
|
||||
CSS for the document, including support for markup styles.
|
||||
|
||||
--------------- Asciibook Stylesheets ----------------
|
||||
|
||||
docbook-xsl/chunked.xsl
|
||||
docbook-xsl/common.xsl
|
||||
docbook-xsl/xhtml.xsl
|
||||
replace parts of the asciibook stylesheets normally found under
|
||||
/etc/asciidoc/docbook-xsl
|
||||
in order to generate consistent IDs on sections and to insert
|
||||
MathJax <script> tags into HTML headers. More will be required for other
|
||||
HTML output types.
|
||||
|
||||
--------------- Support for Math ----------------
|
||||
|
||||
mathjax-asciidoc.conf
|
||||
mathjax-docbook.conf
|
||||
mathjax.js
|
||||
customize asciidoc macros for HTML and Docbook output to insert
|
||||
MathJax <script> tags from mathjax.js, and properly pass through
|
||||
math which has \begin{}\/end{} delimiters instead of $$\[\]\(\),
|
||||
using the <?texmath delimiters="user"?> processing instruction.
|
||||
|
||||
Note that mathjax-docbook.conf is heavily conditionalized depending
|
||||
on whether the final output format (which should be described in the
|
||||
a2x-format variable) is 'pdf' or not, since Docbook passes through
|
||||
math differently to dblatex vs. the HTML stylesheets.
|
||||
|
|
@ -0,0 +1,33 @@
|
|||
<!--
|
||||
Generates chunked XHTML documents from DocBook XML source using DocBook XSL
|
||||
stylesheets.
|
||||
|
||||
NOTE: The URL reference to the current DocBook XSL stylesheets is
|
||||
rewritten to point to the copy on the local disk drive by the XML catalog
|
||||
rewrite directives so it doesn't need to go out to the Internet for the
|
||||
stylesheets. This means you don't need to edit the <xsl:import> elements on
|
||||
a machine by machine basis.
|
||||
-->
|
||||
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
|
||||
<xsl:import href="http://docbook.sourceforge.net/release/xsl/current/xhtml/chunk.xsl"/>
|
||||
<xsl:import href="common.xsl"/>
|
||||
<xsl:param name="navig.graphics.path">images/icons/</xsl:param>
|
||||
<xsl:param name="admon.graphics.path">images/icons/</xsl:param>
|
||||
<xsl:param name="callout.graphics.path" select="'images/icons/callouts/'"/>
|
||||
|
||||
<!-- Generate consistent id attribute values if document is unchanged -->
|
||||
<xsl:param name="generate.consistent.ids" select="1"></xsl:param>
|
||||
|
||||
<!-- Add MathJax <script> tags to document <head> -->
|
||||
<xsl:template name="user.head.content">
|
||||
<script type="text/x-mathjax-config">
|
||||
MathJax.Hub.Config({
|
||||
MathML: { extensions: ["content-mathml.js"] },
|
||||
tex2jax: { inlineMath: [['$','$'], ['\\(','\\)']] }
|
||||
});
|
||||
</script>
|
||||
<script type="text/javascript"
|
||||
src="https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML">
|
||||
</script>
|
||||
</xsl:template>
|
||||
</xsl:stylesheet>
|
||||
|
|
@ -0,0 +1,110 @@
|
|||
<!--
|
||||
Included in xhtml.xsl, xhtml.chunked.xsl, htmlhelp.xsl.
|
||||
Contains common XSL stylesheets parameters.
|
||||
|
||||
This is branched from /etc/asciidoc/docbook-xsl/common.xsl in order to use
|
||||
Vulkan-specific CSS. There is probably a less drastic approach to doing
|
||||
this involving multiple stylesheets or some other way to override the
|
||||
"html.stylesheet" param.
|
||||
-->
|
||||
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
|
||||
<xsl:param name="html.stylesheet" select="'config/vkspec-xhtml.css'"/>
|
||||
|
||||
<xsl:param name="htmlhelp.chm" select="'htmlhelp.chm'"/>
|
||||
<xsl:param name="htmlhelp.hhc.section.depth" select="5"/>
|
||||
|
||||
<xsl:param name="section.autolabel">
|
||||
<xsl:choose>
|
||||
<xsl:when test="/processing-instruction('asciidoc-numbered')">1</xsl:when>
|
||||
<xsl:otherwise>0</xsl:otherwise>
|
||||
</xsl:choose>
|
||||
</xsl:param>
|
||||
|
||||
<xsl:param name="suppress.navigation" select="0"/>
|
||||
<xsl:param name="navig.graphics.extension" select="'.png'"/>
|
||||
<xsl:param name="navig.graphics" select="0"/>
|
||||
<xsl:param name="navig.graphics.path">images/icons/</xsl:param>
|
||||
<xsl:param name="navig.showtitles">0</xsl:param>
|
||||
|
||||
<xsl:param name="shade.verbatim" select="0"/>
|
||||
<xsl:attribute-set name="shade.verbatim.style">
|
||||
<xsl:attribute name="border">0</xsl:attribute>
|
||||
<xsl:attribute name="background-color">#E0E0E0</xsl:attribute>
|
||||
</xsl:attribute-set>
|
||||
|
||||
<xsl:param name="admon.graphics" select="1"/>
|
||||
<xsl:param name="admon.graphics.path">images/icons/</xsl:param>
|
||||
<xsl:param name="admon.graphics.extension" select="'.png'"/>
|
||||
<xsl:param name="admon.style">
|
||||
<xsl:text>margin-left: 0; margin-right: 10%;</xsl:text>
|
||||
</xsl:param>
|
||||
<xsl:param name="admon.textlabel" select="1"/>
|
||||
|
||||
<xsl:param name="callout.defaultcolumn" select="'60'"/>
|
||||
<xsl:param name="callout.graphics.extension" select="'.png'"/>
|
||||
<xsl:param name="callout.graphics" select="'1'"/>
|
||||
<xsl:param name="callout.graphics.number.limit" select="'10'"/>
|
||||
<xsl:param name="callout.graphics.path" select="'images/icons/callouts/'"/>
|
||||
<xsl:param name="callout.list.table" select="'1'"/>
|
||||
|
||||
<!-- This does not seem to work. -->
|
||||
<xsl:param name="section.autolabel.max.depth" select="2"/>
|
||||
|
||||
<xsl:param name="chunk.first.sections" select="1"/>
|
||||
<xsl:param name="chunk.section.depth" select="1"/>
|
||||
<xsl:param name="chunk.quietly" select="0"/>
|
||||
<xsl:param name="chunk.toc" select="''"/>
|
||||
<xsl:param name="chunk.tocs.and.lots" select="0"/>
|
||||
|
||||
<xsl:param name="html.cellpadding" select="'4px'"/>
|
||||
<xsl:param name="html.cellspacing" select="''"/>
|
||||
|
||||
<xsl:param name="table.borders.with.css" select="1"/>
|
||||
<xsl:param name="table.cell.border.color" select="'#527bbd'"/>
|
||||
|
||||
<xsl:param name="table.cell.border.style" select="'solid'"/>
|
||||
<xsl:param name="table.cell.border.thickness" select="'1px'"/>
|
||||
<xsl:param name="table.footnote.number.format" select="'a'"/>
|
||||
<xsl:param name="table.footnote.number.symbols" select="''"/>
|
||||
<xsl:param name="table.frame.border.color" select="'#527bbd'"/>
|
||||
<xsl:param name="table.frame.border.style" select="'solid'"/>
|
||||
<xsl:param name="table.frame.border.thickness" select="'3px'"/>
|
||||
<xsl:param name="tablecolumns.extension" select="'1'"/>
|
||||
|
||||
<xsl:param name="highlight.source" select="1"/>
|
||||
|
||||
<xsl:param name="section.label.includes.component.label" select="1"/>
|
||||
|
||||
<!--
|
||||
Table of contents inserted by <?asciidoc-toc?> processing instruction.
|
||||
-->
|
||||
<xsl:param name="generate.toc">
|
||||
<xsl:choose>
|
||||
<xsl:when test="/processing-instruction('asciidoc-toc')">
|
||||
article toc,title
|
||||
book toc,title,figure,table,example,equation
|
||||
<!-- The only way I could find that suppressed book chapter TOCs -->
|
||||
<xsl:if test="$generate.section.toc.level != 0">
|
||||
chapter toc,title
|
||||
part toc,title
|
||||
preface toc,title
|
||||
qandadiv toc
|
||||
qandaset toc
|
||||
reference toc,title
|
||||
sect1 toc
|
||||
sect2 toc
|
||||
sect3 toc
|
||||
sect4 toc
|
||||
sect5 toc
|
||||
section toc
|
||||
set toc,title
|
||||
</xsl:if>
|
||||
</xsl:when>
|
||||
<xsl:otherwise>
|
||||
article nop
|
||||
book nop
|
||||
</xsl:otherwise>
|
||||
</xsl:choose>
|
||||
</xsl:param>
|
||||
|
||||
</xsl:stylesheet>
|
||||
|
|
@ -0,0 +1,30 @@
|
|||
<!--
|
||||
Generates single XHTML document from DocBook XML source using DocBook XSL
|
||||
stylesheets.
|
||||
|
||||
NOTE: The URL reference to the current DocBook XSL stylesheets is
|
||||
rewritten to point to the copy on the local disk drive by the XML catalog
|
||||
rewrite directives so it doesn't need to go out to the Internet for the
|
||||
stylesheets. This means you don't need to edit the <xsl:import> elements on
|
||||
a machine by machine basis.
|
||||
-->
|
||||
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
|
||||
<xsl:import href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl"/>
|
||||
<xsl:import href="common.xsl"/>
|
||||
|
||||
<!-- Generate consistent id attribute values if document is unchanged -->
|
||||
<xsl:param name="generate.consistent.ids" select="1"></xsl:param>
|
||||
|
||||
<!-- Add MathJax <script> tags to document <head> -->
|
||||
<xsl:template name="user.head.content">
|
||||
<script type="text/x-mathjax-config">
|
||||
MathJax.Hub.Config({
|
||||
MathML: { extensions: ["content-mathml.js"] },
|
||||
tex2jax: { inlineMath: [['$','$'], ['\\(','\\)']] }
|
||||
});
|
||||
</script>
|
||||
<script type="text/javascript"
|
||||
src="https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML">
|
||||
</script>
|
||||
</xsl:template>
|
||||
</xsl:stylesheet>
|
||||
|
|
@ -0,0 +1,140 @@
|
|||
# Copyright (c) 2015-2016 The Khronos Group Inc.
|
||||
# Copyright notice at https://www.khronos.org/registry/speccopyright.html
|
||||
|
||||
[attributes]
|
||||
author="Khronos Group"
|
||||
max-width="1024px"
|
||||
|
||||
[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
|
||||
(?su)(?P<name>optionally):(?P<arg>\w*)=normative
|
||||
(?su)(?P<name>recommend):(?P<arg>\w*)=normative
|
||||
(?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+)=
|
||||
|
||||
[normative-inlinemacro]
|
||||
ifdef::basebackend-docbook[]
|
||||
<phrase role="normative">{name}</phrase>
|
||||
endif::basebackend-docbook[]
|
||||
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>
|
||||
endif::basebackend-docbook[]
|
||||
ifdef::basebackend-html[]
|
||||
<span role="normative">must not</span>
|
||||
endif::basebackend-html[]
|
||||
|
||||
[shouldnot-inlinemacro]
|
||||
ifdef::basebackend-docbook[]
|
||||
<phrase role="normative">should not</phrase>
|
||||
endif::basebackend-docbook[]
|
||||
ifdef::basebackend-html[]
|
||||
<span role="normative">should not</span>
|
||||
endif::basebackend-html[]
|
||||
|
||||
[flink-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>
|
||||
endif::basebackend-docbook[]
|
||||
ifdef::basebackend-html[]
|
||||
<code>{target}</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]
|
||||
<code>{target}</code>
|
||||
|
||||
[must-inlinemacro]
|
||||
must {target}
|
||||
|
|
@ -0,0 +1,10 @@
|
|||
# adoc.conf - add some asciidoc-specific (non-a2x) config stuff for html5.conf
|
||||
|
||||
# Override html5.conf definition
|
||||
[latexmath-inlinemacro]
|
||||
{passtext}
|
||||
|
||||
[docinfo]
|
||||
ifdef::mathjax[]
|
||||
include1::mathjax.js[]
|
||||
endif::[]
|
||||
|
|
@ -0,0 +1,56 @@
|
|||
# testdb.conf - override some Docbook-specific config stuff
|
||||
|
||||
# Override docbook45 definition to not encapsulate LaTeX math
|
||||
# This requires some cleverness in the latexmath macros to include
|
||||
# the equation source in the alt block for PDF output, and in
|
||||
# a Docbook block tag otherwise, using the a2x-format variable.
|
||||
|
||||
# a2x-format can be one of: chunked, docbook, dvi, epub, htmlhelp, manpage,
|
||||
# pdf (default), ps, tex, text, xhtml.
|
||||
|
||||
[blockdef-pass]
|
||||
ifeval::["{a2x-format}"=="pdf"]
|
||||
latexmath-style=template="latexmathblock",subs=()
|
||||
endif::[]
|
||||
ifeval::["{a2x-format}"!="pdf"]
|
||||
latexmath-style=template="latexmathblock"
|
||||
subs=specialcharacters
|
||||
endif::[]
|
||||
|
||||
[latexmath-inlinemacro]
|
||||
<inlineequation>
|
||||
ifeval::["{a2x-format}"=="pdf"]
|
||||
<alt><?texmath delimiters="user"?><![CDATA[{passtext}]]></alt>
|
||||
endif::[]
|
||||
<inlinemediaobject><textobject><phrase>
|
||||
ifeval::["{a2x-format}"!="pdf"]
|
||||
{passtext}
|
||||
endif::[]
|
||||
</phrase></textobject></inlinemediaobject>
|
||||
</inlineequation>
|
||||
|
||||
[latexmath-blockmacro]
|
||||
<informalequation>
|
||||
ifeval::["{a2x-format}"=="pdf"]
|
||||
<alt><?texmath delimiters="user"?><![CDATA[{passtext}]]></alt>
|
||||
endif::[]
|
||||
<inlinemediaobject><textobject><phrase>
|
||||
ifeval::["{a2x-format}"!="pdf"]
|
||||
{passtext}
|
||||
endif::[]
|
||||
</phrase></textobject></inlinemediaobject>
|
||||
</informalequation>
|
||||
|
||||
[latexmathblock]
|
||||
{title#}<equation{id? id="{id}"}{role? role="{role}"}{reftext? xreflabel="{reftext}"}><title>{title}</title>
|
||||
{title%}<informalequation{id? id="{id}"}{role? role="{role}"}{reftext? xreflabel="{reftext}"}>
|
||||
ifeval::["{a2x-format}"=="pdf"]
|
||||
<alt><?texmath delimiters="user"?><![CDATA[|]]></alt>
|
||||
endif::[]
|
||||
<mediaobject><textobject><phrase>
|
||||
ifeval::["{a2x-format}"!="pdf"]
|
||||
|
|
||||
endif::[]
|
||||
</phrase></textobject></mediaobject>
|
||||
{title#}</equation>
|
||||
{title%}</informalequation>
|
||||
|
|
@ -0,0 +1,8 @@
|
|||
<script type="text/x-mathjax-config">
|
||||
MathJax.Hub.Config({
|
||||
MathML: { extensions: ["content-mathml.js"] },
|
||||
tex2jax: { inlineMath: [['$','$'], ['\\(','\\)']] }
|
||||
});
|
||||
</script>
|
||||
<script type="text/javascript" src="https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML">
|
||||
</script>
|
||||
|
|
@ -0,0 +1,125 @@
|
|||
%%
|
||||
%% This style is derived from the docbook one.
|
||||
%%
|
||||
\NeedsTeXFormat{LaTeX2e}
|
||||
\ProvidesPackage{asciidoc}[2008/06/05 AsciiDoc DocBook Style]
|
||||
|
||||
\usepackage[english]{babel}
|
||||
\usepackage{framed}
|
||||
\def\lt{<}
|
||||
\def\gt{>}
|
||||
|
||||
% Set page geometry
|
||||
\usepackage[
|
||||
letterpaper,
|
||||
hmargin=0.9in,
|
||||
bmargin=1in,
|
||||
twoside
|
||||
]{geometry}
|
||||
\raggedbottom
|
||||
\raggedright
|
||||
|
||||
%% Just use the original package and pass the options.
|
||||
\RequirePackageWithOptions{docbook}
|
||||
|
||||
% Sidebar is a boxed minipage that can contain verbatim.
|
||||
% Changed shadow box to double box.
|
||||
\renewenvironment{sidebar}[1][0.95\textwidth]{
|
||||
\hspace{0mm}\newline%
|
||||
\noindent\begin{framed}%
|
||||
\setlength\parskip{\medskipamount}%
|
||||
}{
|
||||
\end{framed}%
|
||||
}
|
||||
|
||||
\renewcommand\_{\textunderscore\allowbreak}
|
||||
|
||||
\lstdefinelanguage{GLSL}
|
||||
{
|
||||
sensitive=true,
|
||||
morekeywords=[1]{
|
||||
attribute, const, uniform, varying,
|
||||
layout, centroid, flat, smooth,
|
||||
noperspective, break, continue, do,
|
||||
for, while, switch, case, default, if,
|
||||
else, in, out, inout, float, int, void,
|
||||
bool, true, false, invariant, discard,
|
||||
return, mat2, mat3, mat4, mat2x2, mat2x3,
|
||||
mat2x4, mat3x2, mat3x3, mat3x4, mat4x2,
|
||||
mat4x3, mat4x4, vec2, vec3, vec4, ivec2,
|
||||
ivec3, ivec4, bvec2, bvec3, bvec4, uint,
|
||||
uvec2, uvec3, uvec4, lowp, mediump, highp,
|
||||
precision, sampler1D, sampler2D, sampler3D,
|
||||
samplerCube, sampler1DShadow,
|
||||
sampler2DShadow, samplerCubeShadow,
|
||||
sampler1DArray, sampler2DArray,
|
||||
sampler1DArrayShadow, sampler2DArrayShadow,
|
||||
isampler1D, isampler2D, isampler3D,
|
||||
isamplerCube, isampler1DArray,
|
||||
isampler2DArray, usampler1D, usampler2D,
|
||||
usampler3D, usamplerCube, usampler1DArray,
|
||||
usampler2DArray, sampler2DRect,
|
||||
sampler2DRectShadow, isampler2DRect,
|
||||
usampler2DRect, samplerBuffer,
|
||||
isamplerBuffer, usamplerBuffer, sampler2DMS,
|
||||
isampler2DMS, usampler2DMS,
|
||||
sampler2DMSArray, isampler2DMSArray,
|
||||
usampler2DMSArray, struct},
|
||||
morekeywords=[2]{
|
||||
radians,degrees,sin,cos,tan,asin,acos,atan,
|
||||
atan,sinh,cosh,tanh,asinh,acosh,atanh,pow,
|
||||
exp,log,exp2,log2,sqrt,inversesqrt,abs,sign,
|
||||
floor,trunc,round,roundEven,ceil,fract,mod,modf,
|
||||
min,max,clamp,mix,step,smoothstep,isnan,isinf,
|
||||
floatBitsToInt,floatBitsToUint,intBitsToFloat,
|
||||
uintBitsToFloat,length,distance,dot,cross,
|
||||
normalize,faceforward,reflect,refract,
|
||||
matrixCompMult,outerProduct,transpose,
|
||||
determinant,inverse,lessThan,lessThanEqual,
|
||||
greaterThan,greaterThanEqual,equal,notEqual,
|
||||
any,all,not,textureSize,texture,textureProj,
|
||||
textureLod,textureOffset,texelFetch,
|
||||
texelFetchOffset,textureProjOffset,
|
||||
textureLodOffset,textureProjLod,
|
||||
textureProjLodOffset,textureGrad,
|
||||
textureGradOffset,textureProjGrad,
|
||||
textureProjGradOffset,texture1D,texture1DProj,
|
||||
texture1DProjLod,texture2D,texture2DProj,
|
||||
texture2DLod,texture2DProjLod,texture3D,
|
||||
texture3DProj,texture3DLod,texture3DProjLod,
|
||||
textureCube,textureCubeLod,shadow1D,shadow2D,
|
||||
shadow1DProj,shadow2DProj,shadow1DLod,
|
||||
shadow2DLod,shadow1DProjLod,shadow2DProjLod,
|
||||
dFdx,dFdy,fwidth,noise1,noise2,noise3,noise4,
|
||||
EmitVertex,EndPrimitive},
|
||||
morekeywords=[3]{
|
||||
gl_VertexID,gl_InstanceID,gl_Position,
|
||||
gl_PointSize,gl_ClipDistance,gl_PerVertex,
|
||||
gl_Layer,gl_ClipVertex,gl_FragCoord,
|
||||
gl_FrontFacing,gl_ClipDistance,gl_FragColor,
|
||||
gl_FragData,gl_MaxDrawBuffers,gl_FragDepth,
|
||||
gl_PointCoord,gl_PrimitiveID,
|
||||
gl_MaxVertexAttribs,gl_MaxVertexUniformComponents,
|
||||
gl_MaxVaryingFloats,gl_MaxVaryingComponents,
|
||||
gl_MaxVertexOutputComponents,
|
||||
gl_MaxGeometryInputComponents,
|
||||
gl_MaxGeometryOutputComponents,
|
||||
gl_MaxFragmentInputComponents,
|
||||
gl_MaxVertexTextureImageUnits,
|
||||
gl_MaxCombinedTextureImageUnits,
|
||||
gl_MaxTextureImageUnits,
|
||||
gl_MaxFragmentUniformComponents,
|
||||
gl_MaxDrawBuffers,gl_MaxClipDistances,
|
||||
gl_MaxGeometryTextureImageUnits,
|
||||
gl_MaxGeometryOutputVertices,
|
||||
gl_MaxGeometryOutputVertices,
|
||||
gl_MaxGeometryTotalOutputComponents,
|
||||
gl_MaxGeometryUniformComponents,
|
||||
gl_MaxGeometryVaryingComponents,gl_DepthRange},
|
||||
morecomment=[l]{//},
|
||||
morecomment=[s]{/*}{*/},
|
||||
morecomment=[l][keywordstyle4]{\#},
|
||||
}
|
||||
|
||||
% For DocBook literallayout elements, see `./dblatex/dblatex-readme.txt`.
|
||||
\usepackage{alltt}
|
||||
|
|
@ -0,0 +1,14 @@
|
|||
<?xml version="1.0" encoding="iso-8859-1"?>
|
||||
<!--
|
||||
dblatex(1) XSL user stylesheet for asciidoc(1).
|
||||
See dblatex(1) -p option.
|
||||
-->
|
||||
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
|
||||
<!-- Override parameters in /etc/asciidoc/dblatex/asciidoc-dblatex.xsl -->
|
||||
<xsl:param name="latex.hyperparam">colorlinks,linkcolor=black,pdfstartview=FitH</xsl:param>
|
||||
<xsl:param name="doc.publisher.show">0</xsl:param>
|
||||
<xsl:param name="latex.output.revhistory">0</xsl:param>
|
||||
|
||||
<!-- Modified dblatex templates etc. can go here -->
|
||||
</xsl:stylesheet>
|
||||
|
||||
|
|
@ -0,0 +1,358 @@
|
|||
/*
|
||||
CSS stylesheet for XHTML produced by DocBook XSL stylesheets.
|
||||
|
||||
This is branched from /etc/asciidoc/stylesheets/docbook-xsl.css with a few
|
||||
tweaks from the asciidoc.css modified for the SPIR-V specification - see
|
||||
/repos/util/trunk/SpecificationTemplates/Asciidoc/specStyle/asciidoc.css
|
||||
*/
|
||||
|
||||
/* Vulkan modifications and additions */
|
||||
|
||||
/* For showing added material in a document */
|
||||
div.added { color: red; }
|
||||
p.added { color: red; }
|
||||
span.added { color: red; }
|
||||
|
||||
/* For showing removed material in a document */
|
||||
div.removed { color: red; text-decoration: line-through; }
|
||||
p.removed { color: red; text-decoration: line-through; }
|
||||
span.removed { color: red; text-decoration: line-through; }
|
||||
|
||||
/* For showing changed material in a document */
|
||||
div.change { color: red; }
|
||||
p.change { color: red; }
|
||||
span.change { color: red; }
|
||||
|
||||
/* For marking the "normative" terms like must:, can:, etc. */
|
||||
div.normative { color: purple; }
|
||||
p.normative { color: purple; }
|
||||
span.normative { color: purple; }
|
||||
|
||||
/* Use a sans-serif font. This needs to be in a smaller point size. */
|
||||
body {
|
||||
font-family: Arial,sans-serif;
|
||||
}
|
||||
|
||||
/* End Vulkan modifications and additions */
|
||||
|
||||
code, pre {
|
||||
font-family: "Courier New", Courier, monospace;
|
||||
}
|
||||
|
||||
span.strong {
|
||||
font-weight: bold;
|
||||
}
|
||||
|
||||
body blockquote {
|
||||
margin-top: .75em;
|
||||
line-height: 1.5;
|
||||
margin-bottom: .75em;
|
||||
}
|
||||
|
||||
html body {
|
||||
margin: 1em 5% 1em 5%;
|
||||
line-height: 1.2;
|
||||
}
|
||||
|
||||
body div {
|
||||
margin: 0;
|
||||
}
|
||||
|
||||
h1, h2, h3, h4, h5, h6
|
||||
{
|
||||
color: #527bbd;
|
||||
font-family: Arial,Helvetica,sans-serif;
|
||||
}
|
||||
|
||||
div.toc p:first-child,
|
||||
div.list-of-figures p:first-child,
|
||||
div.list-of-tables p:first-child,
|
||||
div.list-of-examples p:first-child,
|
||||
div.example p.title,
|
||||
div.sidebar p.title
|
||||
{
|
||||
font-weight: bold;
|
||||
color: #527bbd;
|
||||
font-family: Arial,Helvetica,sans-serif;
|
||||
margin-bottom: 0.2em;
|
||||
}
|
||||
|
||||
body h1 {
|
||||
margin: .0em 0 0 -4%;
|
||||
line-height: 1.3;
|
||||
border-bottom: 2px solid silver;
|
||||
}
|
||||
|
||||
body h2 {
|
||||
margin: 0.5em 0 0 -4%;
|
||||
line-height: 1.3;
|
||||
border-bottom: 2px solid silver;
|
||||
}
|
||||
|
||||
body h3 {
|
||||
margin: .8em 0 0 -3%;
|
||||
line-height: 1.3;
|
||||
}
|
||||
|
||||
body h4 {
|
||||
margin: .8em 0 0 -3%;
|
||||
line-height: 1.3;
|
||||
}
|
||||
|
||||
body h5 {
|
||||
margin: .8em 0 0 -2%;
|
||||
line-height: 1.3;
|
||||
}
|
||||
|
||||
body h6 {
|
||||
margin: .8em 0 0 -1%;
|
||||
line-height: 1.3;
|
||||
}
|
||||
|
||||
body hr {
|
||||
border: none; /* Broken on IE6 */
|
||||
}
|
||||
div.footnotes hr {
|
||||
border: 1px solid silver;
|
||||
}
|
||||
|
||||
div.navheader th, div.navheader td, div.navfooter td {
|
||||
font-family: Arial,Helvetica,sans-serif;
|
||||
font-size: 0.9em;
|
||||
font-weight: bold;
|
||||
color: #527bbd;
|
||||
}
|
||||
div.navheader img, div.navfooter img {
|
||||
border-style: none;
|
||||
}
|
||||
div.navheader a, div.navfooter a {
|
||||
font-weight: normal;
|
||||
}
|
||||
div.navfooter hr {
|
||||
border: 1px solid silver;
|
||||
}
|
||||
|
||||
body td {
|
||||
line-height: 1.2
|
||||
}
|
||||
|
||||
body th {
|
||||
line-height: 1.2;
|
||||
}
|
||||
|
||||
ol {
|
||||
line-height: 1.2;
|
||||
}
|
||||
|
||||
ul, body dir, body menu {
|
||||
line-height: 1.2;
|
||||
}
|
||||
|
||||
html {
|
||||
margin: 0;
|
||||
padding: 0;
|
||||
}
|
||||
|
||||
body h1, body h2, body h3, body h4, body h5, body h6 {
|
||||
margin-left: 0
|
||||
}
|
||||
|
||||
body pre {
|
||||
margin: 0.5em 10% 0.5em 1em;
|
||||
line-height: 1.0;
|
||||
color: navy;
|
||||
}
|
||||
|
||||
tt.literal, code.literal {
|
||||
color: navy;
|
||||
}
|
||||
|
||||
.programlisting, .screen {
|
||||
border: 1px solid silver;
|
||||
background: #f4f4f4;
|
||||
margin: 0.5em 10% 0.5em 0;
|
||||
padding: 0.5em 1em;
|
||||
}
|
||||
|
||||
div.sidebar {
|
||||
background: #ffffee;
|
||||
margin: 1.0em 10% 0.5em 0;
|
||||
padding: 0.5em 1em;
|
||||
border: 1px solid silver;
|
||||
}
|
||||
div.sidebar * { padding: 0; }
|
||||
div.sidebar div { margin: 0; }
|
||||
div.sidebar p.title {
|
||||
margin-top: 0.5em;
|
||||
margin-bottom: 0.2em;
|
||||
}
|
||||
|
||||
div.bibliomixed {
|
||||
margin: 0.5em 5% 0.5em 1em;
|
||||
}
|
||||
|
||||
div.glossary dt {
|
||||
font-weight: bold;
|
||||
}
|
||||
div.glossary dd p {
|
||||
margin-top: 0.2em;
|
||||
}
|
||||
|
||||
dl {
|
||||
margin: .8em 0;
|
||||
line-height: 1.2;
|
||||
}
|
||||
|
||||
dt {
|
||||
margin-top: 0.5em;
|
||||
}
|
||||
|
||||
dt span.term {
|
||||
font-style: normal;
|
||||
color: navy;
|
||||
}
|
||||
|
||||
div.variablelist dd p {
|
||||
margin-top: 0;
|
||||
}
|
||||
|
||||
div.itemizedlist li, div.orderedlist li {
|
||||
margin-left: -0.8em;
|
||||
margin-top: 0.5em;
|
||||
}
|
||||
|
||||
ul, ol {
|
||||
list-style-position: outside;
|
||||
}
|
||||
|
||||
div.sidebar ul, div.sidebar ol {
|
||||
margin-left: 2.8em;
|
||||
}
|
||||
|
||||
div.itemizedlist p.title,
|
||||
div.orderedlist p.title,
|
||||
div.variablelist p.title
|
||||
{
|
||||
margin-bottom: -0.8em;
|
||||
}
|
||||
|
||||
div.revhistory table {
|
||||
border-collapse: collapse;
|
||||
border: none;
|
||||
}
|
||||
div.revhistory th {
|
||||
border: none;
|
||||
color: #527bbd;
|
||||
font-family: Arial,Helvetica,sans-serif;
|
||||
}
|
||||
div.revhistory td {
|
||||
border: 1px solid silver;
|
||||
}
|
||||
|
||||
/* Keep TOC and index lines close together. */
|
||||
div.toc dl, div.toc dt,
|
||||
div.list-of-figures dl, div.list-of-figures dt,
|
||||
div.list-of-tables dl, div.list-of-tables dt,
|
||||
div.indexdiv dl, div.indexdiv dt
|
||||
{
|
||||
line-height: normal;
|
||||
margin-top: 0;
|
||||
margin-bottom: 0;
|
||||
}
|
||||
|
||||
/*
|
||||
Table styling does not work because of overriding attributes in
|
||||
generated HTML.
|
||||
*/
|
||||
div.table table,
|
||||
div.informaltable table
|
||||
{
|
||||
margin-left: 0;
|
||||
margin-right: 5%;
|
||||
margin-bottom: 0.8em;
|
||||
}
|
||||
div.informaltable table
|
||||
{
|
||||
margin-top: 0.4em
|
||||
}
|
||||
div.table thead,
|
||||
div.table tfoot,
|
||||
div.table tbody,
|
||||
div.informaltable thead,
|
||||
div.informaltable tfoot,
|
||||
div.informaltable tbody
|
||||
{
|
||||
/* No effect in IE6. */
|
||||
border-top: 3px solid #527bbd;
|
||||
border-bottom: 3px solid #527bbd;
|
||||
}
|
||||
div.table thead, div.table tfoot,
|
||||
div.informaltable thead, div.informaltable tfoot
|
||||
{
|
||||
font-weight: bold;
|
||||
}
|
||||
|
||||
div.mediaobject img {
|
||||
margin-bottom: 0.8em;
|
||||
}
|
||||
div.figure p.title,
|
||||
div.table p.title
|
||||
{
|
||||
margin-top: 1em;
|
||||
margin-bottom: 0.4em;
|
||||
}
|
||||
|
||||
div.calloutlist p
|
||||
{
|
||||
margin-top: 0em;
|
||||
margin-bottom: 0.4em;
|
||||
}
|
||||
|
||||
a img {
|
||||
border-style: none;
|
||||
}
|
||||
|
||||
@media print {
|
||||
div.navheader, div.navfooter { display: none; }
|
||||
}
|
||||
|
||||
span.aqua { color: aqua; }
|
||||
span.black { color: black; }
|
||||
span.blue { color: blue; }
|
||||
span.fuchsia { color: fuchsia; }
|
||||
span.gray { color: gray; }
|
||||
span.green { color: green; }
|
||||
span.lime { color: lime; }
|
||||
span.maroon { color: maroon; }
|
||||
span.navy { color: navy; }
|
||||
span.olive { color: olive; }
|
||||
span.purple { color: purple; }
|
||||
span.red { color: red; }
|
||||
span.silver { color: silver; }
|
||||
span.teal { color: teal; }
|
||||
span.white { color: white; }
|
||||
span.yellow { color: yellow; }
|
||||
|
||||
span.aqua-background { background: aqua; }
|
||||
span.black-background { background: black; }
|
||||
span.blue-background { background: blue; }
|
||||
span.fuchsia-background { background: fuchsia; }
|
||||
span.gray-background { background: gray; }
|
||||
span.green-background { background: green; }
|
||||
span.lime-background { background: lime; }
|
||||
span.maroon-background { background: maroon; }
|
||||
span.navy-background { background: navy; }
|
||||
span.olive-background { background: olive; }
|
||||
span.purple-background { background: purple; }
|
||||
span.red-background { background: red; }
|
||||
span.silver-background { background: silver; }
|
||||
span.teal-background { background: teal; }
|
||||
span.white-background { background: white; }
|
||||
span.yellow-background { background: yellow; }
|
||||
|
||||
span.big { font-size: 2em; }
|
||||
span.small { font-size: 0.6em; }
|
||||
|
||||
span.underline { text-decoration: underline; }
|
||||
span.overline { text-decoration: overline; }
|
||||
span.line-through { text-decoration: line-through; }
|
||||
|
|
@ -0,0 +1,109 @@
|
|||
# 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 (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:
|
||||
#
|
||||
# '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
|
||||
(?su)(?P<name>optionally):(?P<arg>\w*)=normative
|
||||
(?su)(?P<name>recommend):(?P<arg>\w*)=normative
|
||||
(?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+)=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>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[]
|
||||
<phrase role="normative">{name}</phrase>
|
||||
endif::basebackend-docbook[]
|
||||
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>
|
||||
endif::basebackend-docbook[]
|
||||
ifdef::basebackend-html[]
|
||||
<span role="normative">must not</span>
|
||||
endif::basebackend-html[]
|
||||
|
||||
[shouldnot-inlinemacro]
|
||||
ifdef::basebackend-docbook[]
|
||||
<phrase role="normative">should not</phrase>
|
||||
endif::basebackend-docbook[]
|
||||
ifdef::basebackend-html[]
|
||||
<span role="normative">should not</span>
|
||||
endif::basebackend-html[]
|
||||
|
||||
[link-inlinemacro]
|
||||
ifdef::basebackend-docbook[]
|
||||
<code><link linkend="{target}">{target}</link></code>
|
||||
endif::basebackend-docbook[]
|
||||
ifdef::basebackend-html[]
|
||||
<code><a href="#{target}">{target}</a></code>
|
||||
endif::basebackend-html[]
|
||||
|
||||
[code-inlinemacro]
|
||||
ifdef::basebackend-docbook[]
|
||||
<code>{target}</code>
|
||||
endif::basebackend-docbook[]
|
||||
ifdef::basebackend-html[]
|
||||
<code>{target}</code>
|
||||
endif::basebackend-html[]
|
||||
|
||||
[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[]
|
||||
|
|
@ -0,0 +1,67 @@
|
|||
Copyright (C) 2014-2016 The Khronos Group Inc. All Rights Reserved.
|
||||
|
||||
This specification is protected by copyright laws and contains material proprietary
|
||||
to the Khronos Group, Inc. It or any components may not be reproduced, republished,
|
||||
distributed, transmitted, displayed, broadcast or otherwise exploited in any
|
||||
manner without the express prior written permission of Khronos Group. You may
|
||||
use this specification for implementing the functionality therein, without altering or
|
||||
removing any trademark, copyright or other notice from the specification, but the
|
||||
receipt or possession of this specification does not convey any rights to reproduce,
|
||||
disclose, or distribute its contents, or to manufacture, use, or sell anything that it
|
||||
may describe, in whole or in part.
|
||||
|
||||
Khronos Group grants express permission to any current Promoter, Contributor
|
||||
or Adopter member of Khronos to copy and redistribute UNMODIFIED versions
|
||||
of this specification in any fashion, provided that NO CHARGE is made for the
|
||||
specification and the latest available update of the specification for any version
|
||||
of the API is used whenever possible. Such distributed specification may be reformatted
|
||||
AS LONG AS the contents of the specification are not changed in any
|
||||
way. The specification may be incorporated into a product that is sold as long as
|
||||
such product includes significant independent work developed by the seller. A link
|
||||
to the current version of this specification on the Khronos Group web-site should
|
||||
be included whenever possible with specification distributions.
|
||||
|
||||
This specification has been created under the Khronos Intellectual Property Rights Policy,
|
||||
which is Attachment A of the Khronos Group Membership Agreement available at
|
||||
www.khronos.org/files/member_agreement.pdf. This specification contains substantially
|
||||
unmodified functionality from, and is a successor to, Khronos specifications including
|
||||
OpenGL, OpenGL ES and OpenCL.
|
||||
|
||||
Some parts of this Specification are purely informative and do not define requirements
|
||||
necessary for compliance and so are outside the Scope of this Specification. These
|
||||
parts of the Specification are marked by the “Note” icon or designated “Informative”.
|
||||
|
||||
Where this Specification uses terms, defined in the Glossary or otherwise, that refer to
|
||||
enabling technologies that are not expressly set forth as being required for compliance,
|
||||
those enabling technologies are outside the Scope of this Specification.
|
||||
|
||||
Where this Specification uses the terms “may”, or “optional”, such features or
|
||||
behaviors do not define requirements necessary for compliance and so are outside the
|
||||
Scope of this Specification.
|
||||
|
||||
Where this Specification uses the terms “not required”, such features or
|
||||
behaviors may be omitted from certain implementations, but when they are included, they
|
||||
define requirements necessary for compliance and so are INCLUDED in the Scope of this
|
||||
Specification.
|
||||
|
||||
Where this Specification includes normative references to external documents, the
|
||||
specifically identified sections and functionality of those external documents are in
|
||||
Scope. Requirements defined by external documents not created by Khronos may contain
|
||||
contributions from non-members of Khronos not covered by the Khronos Intellectual
|
||||
Property Rights Policy.
|
||||
|
||||
Khronos Group makes no, and expressly disclaims any, representations or warranties,
|
||||
express or implied, regarding this specification, including, without limitation,
|
||||
any implied warranties of merchantability or fitness for a particular purpose
|
||||
or non-infringement of any intellectual property. Khronos Group makes no, and
|
||||
expressly disclaims any, warranties, express or implied, regarding the correctness,
|
||||
accuracy, completeness, timeliness, and reliability of the specification. Under no
|
||||
circumstances will the Khronos Group, or any of its Promoters, Contributors or
|
||||
Members or their respective partners, officers, directors, employees, agents or
|
||||
representatives be liable for any damages, whether direct, indirect, special or
|
||||
consequential damages for lost revenues, lost profits, or otherwise, arising from or in
|
||||
connection with these materials.
|
||||
|
||||
Khronos and {apiname} are trademarks of The Khronos Group Inc. OpenCL is a trademark of
|
||||
Apple Inc. and OpenGL is a registered trademark of Silicon Graphics International, both
|
||||
used under license by Khronos.
|
||||
|
|
@ -0,0 +1,29 @@
|
|||
// WARNING: DO NOT MODIFY! This file is automatically generated from the vk.xml registry
|
||||
ifndef::doctype-manpage[]
|
||||
[[VkAccessFlagBits,VkAccessFlagBits]]
|
||||
["source","{basebackend@docbook:c++:cpp}",title=""]
|
||||
endif::doctype-manpage[]
|
||||
ifdef::doctype-manpage[]
|
||||
["source","{basebackend@docbook:c++:cpp}"]
|
||||
endif::doctype-manpage[]
|
||||
------------------------------------------------------------------------------
|
||||
typedef enum VkAccessFlagBits {
|
||||
VK_ACCESS_INDIRECT_COMMAND_READ_BIT = 0x00000001,
|
||||
VK_ACCESS_INDEX_READ_BIT = 0x00000002,
|
||||
VK_ACCESS_VERTEX_ATTRIBUTE_READ_BIT = 0x00000004,
|
||||
VK_ACCESS_UNIFORM_READ_BIT = 0x00000008,
|
||||
VK_ACCESS_INPUT_ATTACHMENT_READ_BIT = 0x00000010,
|
||||
VK_ACCESS_SHADER_READ_BIT = 0x00000020,
|
||||
VK_ACCESS_SHADER_WRITE_BIT = 0x00000040,
|
||||
VK_ACCESS_COLOR_ATTACHMENT_READ_BIT = 0x00000080,
|
||||
VK_ACCESS_COLOR_ATTACHMENT_WRITE_BIT = 0x00000100,
|
||||
VK_ACCESS_DEPTH_STENCIL_ATTACHMENT_READ_BIT = 0x00000200,
|
||||
VK_ACCESS_DEPTH_STENCIL_ATTACHMENT_WRITE_BIT = 0x00000400,
|
||||
VK_ACCESS_TRANSFER_READ_BIT = 0x00000800,
|
||||
VK_ACCESS_TRANSFER_WRITE_BIT = 0x00001000,
|
||||
VK_ACCESS_HOST_READ_BIT = 0x00002000,
|
||||
VK_ACCESS_HOST_WRITE_BIT = 0x00004000,
|
||||
VK_ACCESS_MEMORY_READ_BIT = 0x00008000,
|
||||
VK_ACCESS_MEMORY_WRITE_BIT = 0x00010000,
|
||||
} VkAccessFlagBits;
|
||||
------------------------------------------------------------------------------
|
||||
|
|
@ -0,0 +1,13 @@
|
|||
// WARNING: DO NOT MODIFY! This file is automatically generated from the vk.xml registry
|
||||
ifndef::doctype-manpage[]
|
||||
[[VkAttachmentDescriptionFlagBits,VkAttachmentDescriptionFlagBits]]
|
||||
["source","{basebackend@docbook:c++:cpp}",title=""]
|
||||
endif::doctype-manpage[]
|
||||
ifdef::doctype-manpage[]
|
||||
["source","{basebackend@docbook:c++:cpp}"]
|
||||
endif::doctype-manpage[]
|
||||
------------------------------------------------------------------------------
|
||||
typedef enum VkAttachmentDescriptionFlagBits {
|
||||
VK_ATTACHMENT_DESCRIPTION_MAY_ALIAS_BIT = 0x00000001,
|
||||
} VkAttachmentDescriptionFlagBits;
|
||||
------------------------------------------------------------------------------
|
||||
|
|
@ -0,0 +1,15 @@
|
|||
// WARNING: DO NOT MODIFY! This file is automatically generated from the vk.xml registry
|
||||
ifndef::doctype-manpage[]
|
||||
[[VkAttachmentLoadOp,VkAttachmentLoadOp]]
|
||||
["source","{basebackend@docbook:c++:cpp}",title=""]
|
||||
endif::doctype-manpage[]
|
||||
ifdef::doctype-manpage[]
|
||||
["source","{basebackend@docbook:c++:cpp}"]
|
||||
endif::doctype-manpage[]
|
||||
------------------------------------------------------------------------------
|
||||
typedef enum VkAttachmentLoadOp {
|
||||
VK_ATTACHMENT_LOAD_OP_LOAD = 0,
|
||||
VK_ATTACHMENT_LOAD_OP_CLEAR = 1,
|
||||
VK_ATTACHMENT_LOAD_OP_DONT_CARE = 2,
|
||||
} VkAttachmentLoadOp;
|
||||
------------------------------------------------------------------------------
|
||||
|
|
@ -0,0 +1,14 @@
|
|||
// WARNING: DO NOT MODIFY! This file is automatically generated from the vk.xml registry
|
||||
ifndef::doctype-manpage[]
|
||||
[[VkAttachmentStoreOp,VkAttachmentStoreOp]]
|
||||
["source","{basebackend@docbook:c++:cpp}",title=""]
|
||||
endif::doctype-manpage[]
|
||||
ifdef::doctype-manpage[]
|
||||
["source","{basebackend@docbook:c++:cpp}"]
|
||||
endif::doctype-manpage[]
|
||||
------------------------------------------------------------------------------
|
||||
typedef enum VkAttachmentStoreOp {
|
||||
VK_ATTACHMENT_STORE_OP_STORE = 0,
|
||||
VK_ATTACHMENT_STORE_OP_DONT_CARE = 1,
|
||||
} VkAttachmentStoreOp;
|
||||
------------------------------------------------------------------------------
|
||||
|
|
@ -0,0 +1,31 @@
|
|||
// WARNING: DO NOT MODIFY! This file is automatically generated from the vk.xml registry
|
||||
ifndef::doctype-manpage[]
|
||||
[[VkBlendFactor,VkBlendFactor]]
|
||||
["source","{basebackend@docbook:c++:cpp}",title=""]
|
||||
endif::doctype-manpage[]
|
||||
ifdef::doctype-manpage[]
|
||||
["source","{basebackend@docbook:c++:cpp}"]
|
||||
endif::doctype-manpage[]
|
||||
------------------------------------------------------------------------------
|
||||
typedef enum VkBlendFactor {
|
||||
VK_BLEND_FACTOR_ZERO = 0,
|
||||
VK_BLEND_FACTOR_ONE = 1,
|
||||
VK_BLEND_FACTOR_SRC_COLOR = 2,
|
||||
VK_BLEND_FACTOR_ONE_MINUS_SRC_COLOR = 3,
|
||||
VK_BLEND_FACTOR_DST_COLOR = 4,
|
||||
VK_BLEND_FACTOR_ONE_MINUS_DST_COLOR = 5,
|
||||
VK_BLEND_FACTOR_SRC_ALPHA = 6,
|
||||
VK_BLEND_FACTOR_ONE_MINUS_SRC_ALPHA = 7,
|
||||
VK_BLEND_FACTOR_DST_ALPHA = 8,
|
||||
VK_BLEND_FACTOR_ONE_MINUS_DST_ALPHA = 9,
|
||||
VK_BLEND_FACTOR_CONSTANT_COLOR = 10,
|
||||
VK_BLEND_FACTOR_ONE_MINUS_CONSTANT_COLOR = 11,
|
||||
VK_BLEND_FACTOR_CONSTANT_ALPHA = 12,
|
||||
VK_BLEND_FACTOR_ONE_MINUS_CONSTANT_ALPHA = 13,
|
||||
VK_BLEND_FACTOR_SRC_ALPHA_SATURATE = 14,
|
||||
VK_BLEND_FACTOR_SRC1_COLOR = 15,
|
||||
VK_BLEND_FACTOR_ONE_MINUS_SRC1_COLOR = 16,
|
||||
VK_BLEND_FACTOR_SRC1_ALPHA = 17,
|
||||
VK_BLEND_FACTOR_ONE_MINUS_SRC1_ALPHA = 18,
|
||||
} VkBlendFactor;
|
||||
------------------------------------------------------------------------------
|
||||
|
|
@ -0,0 +1,17 @@
|
|||
// WARNING: DO NOT MODIFY! This file is automatically generated from the vk.xml registry
|
||||
ifndef::doctype-manpage[]
|
||||
[[VkBlendOp,VkBlendOp]]
|
||||
["source","{basebackend@docbook:c++:cpp}",title=""]
|
||||
endif::doctype-manpage[]
|
||||
ifdef::doctype-manpage[]
|
||||
["source","{basebackend@docbook:c++:cpp}"]
|
||||
endif::doctype-manpage[]
|
||||
------------------------------------------------------------------------------
|
||||
typedef enum VkBlendOp {
|
||||
VK_BLEND_OP_ADD = 0,
|
||||
VK_BLEND_OP_SUBTRACT = 1,
|
||||
VK_BLEND_OP_REVERSE_SUBTRACT = 2,
|
||||
VK_BLEND_OP_MIN = 3,
|
||||
VK_BLEND_OP_MAX = 4,
|
||||
} VkBlendOp;
|
||||
------------------------------------------------------------------------------
|
||||
|
|
@ -0,0 +1,18 @@
|
|||
// WARNING: DO NOT MODIFY! This file is automatically generated from the vk.xml registry
|
||||
ifndef::doctype-manpage[]
|
||||
[[VkBorderColor,VkBorderColor]]
|
||||
["source","{basebackend@docbook:c++:cpp}",title=""]
|
||||
endif::doctype-manpage[]
|
||||
ifdef::doctype-manpage[]
|
||||
["source","{basebackend@docbook:c++:cpp}"]
|
||||
endif::doctype-manpage[]
|
||||
------------------------------------------------------------------------------
|
||||
typedef enum VkBorderColor {
|
||||
VK_BORDER_COLOR_FLOAT_TRANSPARENT_BLACK = 0,
|
||||
VK_BORDER_COLOR_INT_TRANSPARENT_BLACK = 1,
|
||||
VK_BORDER_COLOR_FLOAT_OPAQUE_BLACK = 2,
|
||||
VK_BORDER_COLOR_INT_OPAQUE_BLACK = 3,
|
||||
VK_BORDER_COLOR_FLOAT_OPAQUE_WHITE = 4,
|
||||
VK_BORDER_COLOR_INT_OPAQUE_WHITE = 5,
|
||||
} VkBorderColor;
|
||||
------------------------------------------------------------------------------
|
||||
|
|
@ -0,0 +1,15 @@
|
|||
// WARNING: DO NOT MODIFY! This file is automatically generated from the vk.xml registry
|
||||
ifndef::doctype-manpage[]
|
||||
[[VkBufferCreateFlagBits,VkBufferCreateFlagBits]]
|
||||
["source","{basebackend@docbook:c++:cpp}",title=""]
|
||||
endif::doctype-manpage[]
|
||||
ifdef::doctype-manpage[]
|
||||
["source","{basebackend@docbook:c++:cpp}"]
|
||||
endif::doctype-manpage[]
|
||||
------------------------------------------------------------------------------
|
||||
typedef enum VkBufferCreateFlagBits {
|
||||
VK_BUFFER_CREATE_SPARSE_BINDING_BIT = 0x00000001,
|
||||
VK_BUFFER_CREATE_SPARSE_RESIDENCY_BIT = 0x00000002,
|
||||
VK_BUFFER_CREATE_SPARSE_ALIASED_BIT = 0x00000004,
|
||||
} VkBufferCreateFlagBits;
|
||||
------------------------------------------------------------------------------
|
||||
|
|
@ -0,0 +1,21 @@
|
|||
// WARNING: DO NOT MODIFY! This file is automatically generated from the vk.xml registry
|
||||
ifndef::doctype-manpage[]
|
||||
[[VkBufferUsageFlagBits,VkBufferUsageFlagBits]]
|
||||
["source","{basebackend@docbook:c++:cpp}",title=""]
|
||||
endif::doctype-manpage[]
|
||||
ifdef::doctype-manpage[]
|
||||
["source","{basebackend@docbook:c++:cpp}"]
|
||||
endif::doctype-manpage[]
|
||||
------------------------------------------------------------------------------
|
||||
typedef enum VkBufferUsageFlagBits {
|
||||
VK_BUFFER_USAGE_TRANSFER_SRC_BIT = 0x00000001,
|
||||
VK_BUFFER_USAGE_TRANSFER_DST_BIT = 0x00000002,
|
||||
VK_BUFFER_USAGE_UNIFORM_TEXEL_BUFFER_BIT = 0x00000004,
|
||||
VK_BUFFER_USAGE_STORAGE_TEXEL_BUFFER_BIT = 0x00000008,
|
||||
VK_BUFFER_USAGE_UNIFORM_BUFFER_BIT = 0x00000010,
|
||||
VK_BUFFER_USAGE_STORAGE_BUFFER_BIT = 0x00000020,
|
||||
VK_BUFFER_USAGE_INDEX_BUFFER_BIT = 0x00000040,
|
||||
VK_BUFFER_USAGE_VERTEX_BUFFER_BIT = 0x00000080,
|
||||
VK_BUFFER_USAGE_INDIRECT_BUFFER_BIT = 0x00000100,
|
||||
} VkBufferUsageFlagBits;
|
||||
------------------------------------------------------------------------------
|
||||
|
|
@ -0,0 +1,16 @@
|
|||
// WARNING: DO NOT MODIFY! This file is automatically generated from the vk.xml registry
|
||||
ifndef::doctype-manpage[]
|
||||
[[VkColorComponentFlagBits,VkColorComponentFlagBits]]
|
||||
["source","{basebackend@docbook:c++:cpp}",title=""]
|
||||
endif::doctype-manpage[]
|
||||
ifdef::doctype-manpage[]
|
||||
["source","{basebackend@docbook:c++:cpp}"]
|
||||
endif::doctype-manpage[]
|
||||
------------------------------------------------------------------------------
|
||||
typedef enum VkColorComponentFlagBits {
|
||||
VK_COLOR_COMPONENT_R_BIT = 0x00000001,
|
||||
VK_COLOR_COMPONENT_G_BIT = 0x00000002,
|
||||
VK_COLOR_COMPONENT_B_BIT = 0x00000004,
|
||||
VK_COLOR_COMPONENT_A_BIT = 0x00000008,
|
||||
} VkColorComponentFlagBits;
|
||||
------------------------------------------------------------------------------
|
||||
|
|
@ -0,0 +1,14 @@
|
|||
// WARNING: DO NOT MODIFY! This file is automatically generated from the vk.xml registry
|
||||
ifndef::doctype-manpage[]
|
||||
[[VkCommandBufferLevel,VkCommandBufferLevel]]
|
||||
["source","{basebackend@docbook:c++:cpp}",title=""]
|
||||
endif::doctype-manpage[]
|
||||
ifdef::doctype-manpage[]
|
||||
["source","{basebackend@docbook:c++:cpp}"]
|
||||
endif::doctype-manpage[]
|
||||
------------------------------------------------------------------------------
|
||||
typedef enum VkCommandBufferLevel {
|
||||
VK_COMMAND_BUFFER_LEVEL_PRIMARY = 0,
|
||||
VK_COMMAND_BUFFER_LEVEL_SECONDARY = 1,
|
||||
} VkCommandBufferLevel;
|
||||
------------------------------------------------------------------------------
|
||||
|
|
@ -0,0 +1,13 @@
|
|||
// WARNING: DO NOT MODIFY! This file is automatically generated from the vk.xml registry
|
||||
ifndef::doctype-manpage[]
|
||||
[[VkCommandBufferResetFlagBits,VkCommandBufferResetFlagBits]]
|
||||
["source","{basebackend@docbook:c++:cpp}",title=""]
|
||||
endif::doctype-manpage[]
|
||||
ifdef::doctype-manpage[]
|
||||
["source","{basebackend@docbook:c++:cpp}"]
|
||||
endif::doctype-manpage[]
|
||||
------------------------------------------------------------------------------
|
||||
typedef enum VkCommandBufferResetFlagBits {
|
||||
VK_COMMAND_BUFFER_RESET_RELEASE_RESOURCES_BIT = 0x00000001,
|
||||
} VkCommandBufferResetFlagBits;
|
||||
------------------------------------------------------------------------------
|
||||
|
|
@ -0,0 +1,15 @@
|
|||
// WARNING: DO NOT MODIFY! This file is automatically generated from the vk.xml registry
|
||||
ifndef::doctype-manpage[]
|
||||
[[VkCommandBufferUsageFlagBits,VkCommandBufferUsageFlagBits]]
|
||||
["source","{basebackend@docbook:c++:cpp}",title=""]
|
||||
endif::doctype-manpage[]
|
||||
ifdef::doctype-manpage[]
|
||||
["source","{basebackend@docbook:c++:cpp}"]
|
||||
endif::doctype-manpage[]
|
||||
------------------------------------------------------------------------------
|
||||
typedef enum VkCommandBufferUsageFlagBits {
|
||||
VK_COMMAND_BUFFER_USAGE_ONE_TIME_SUBMIT_BIT = 0x00000001,
|
||||
VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT = 0x00000002,
|
||||
VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT = 0x00000004,
|
||||
} VkCommandBufferUsageFlagBits;
|
||||
------------------------------------------------------------------------------
|
||||
|
|
@ -0,0 +1,14 @@
|
|||
// WARNING: DO NOT MODIFY! This file is automatically generated from the vk.xml registry
|
||||
ifndef::doctype-manpage[]
|
||||
[[VkCommandPoolCreateFlagBits,VkCommandPoolCreateFlagBits]]
|
||||
["source","{basebackend@docbook:c++:cpp}",title=""]
|
||||
endif::doctype-manpage[]
|
||||
ifdef::doctype-manpage[]
|
||||
["source","{basebackend@docbook:c++:cpp}"]
|
||||
endif::doctype-manpage[]
|
||||
------------------------------------------------------------------------------
|
||||
typedef enum VkCommandPoolCreateFlagBits {
|
||||
VK_COMMAND_POOL_CREATE_TRANSIENT_BIT = 0x00000001,
|
||||
VK_COMMAND_POOL_CREATE_RESET_COMMAND_BUFFER_BIT = 0x00000002,
|
||||
} VkCommandPoolCreateFlagBits;
|
||||
------------------------------------------------------------------------------
|
||||
|
|
@ -0,0 +1,13 @@
|
|||
// WARNING: DO NOT MODIFY! This file is automatically generated from the vk.xml registry
|
||||
ifndef::doctype-manpage[]
|
||||
[[VkCommandPoolResetFlagBits,VkCommandPoolResetFlagBits]]
|
||||
["source","{basebackend@docbook:c++:cpp}",title=""]
|
||||
endif::doctype-manpage[]
|
||||
ifdef::doctype-manpage[]
|
||||
["source","{basebackend@docbook:c++:cpp}"]
|
||||
endif::doctype-manpage[]
|
||||
------------------------------------------------------------------------------
|
||||
typedef enum VkCommandPoolResetFlagBits {
|
||||
VK_COMMAND_POOL_RESET_RELEASE_RESOURCES_BIT = 0x00000001,
|
||||
} VkCommandPoolResetFlagBits;
|
||||
------------------------------------------------------------------------------
|
||||
|
|
@ -0,0 +1,20 @@
|
|||
// WARNING: DO NOT MODIFY! This file is automatically generated from the vk.xml registry
|
||||
ifndef::doctype-manpage[]
|
||||
[[VkCompareOp,VkCompareOp]]
|
||||
["source","{basebackend@docbook:c++:cpp}",title=""]
|
||||
endif::doctype-manpage[]
|
||||
ifdef::doctype-manpage[]
|
||||
["source","{basebackend@docbook:c++:cpp}"]
|
||||
endif::doctype-manpage[]
|
||||
------------------------------------------------------------------------------
|
||||
typedef enum VkCompareOp {
|
||||
VK_COMPARE_OP_NEVER = 0,
|
||||
VK_COMPARE_OP_LESS = 1,
|
||||
VK_COMPARE_OP_EQUAL = 2,
|
||||
VK_COMPARE_OP_LESS_OR_EQUAL = 3,
|
||||
VK_COMPARE_OP_GREATER = 4,
|
||||
VK_COMPARE_OP_NOT_EQUAL = 5,
|
||||
VK_COMPARE_OP_GREATER_OR_EQUAL = 6,
|
||||
VK_COMPARE_OP_ALWAYS = 7,
|
||||
} VkCompareOp;
|
||||
------------------------------------------------------------------------------
|
||||
|
|
@ -0,0 +1,19 @@
|
|||
// WARNING: DO NOT MODIFY! This file is automatically generated from the vk.xml registry
|
||||
ifndef::doctype-manpage[]
|
||||
[[VkComponentSwizzle,VkComponentSwizzle]]
|
||||
["source","{basebackend@docbook:c++:cpp}",title=""]
|
||||
endif::doctype-manpage[]
|
||||
ifdef::doctype-manpage[]
|
||||
["source","{basebackend@docbook:c++:cpp}"]
|
||||
endif::doctype-manpage[]
|
||||
------------------------------------------------------------------------------
|
||||
typedef enum VkComponentSwizzle {
|
||||
VK_COMPONENT_SWIZZLE_IDENTITY = 0,
|
||||
VK_COMPONENT_SWIZZLE_ZERO = 1,
|
||||
VK_COMPONENT_SWIZZLE_ONE = 2,
|
||||
VK_COMPONENT_SWIZZLE_R = 3,
|
||||
VK_COMPONENT_SWIZZLE_G = 4,
|
||||
VK_COMPONENT_SWIZZLE_B = 5,
|
||||
VK_COMPONENT_SWIZZLE_A = 6,
|
||||
} VkComponentSwizzle;
|
||||
------------------------------------------------------------------------------
|
||||
|
|
@ -0,0 +1,16 @@
|
|||
// WARNING: DO NOT MODIFY! This file is automatically generated from the vk.xml registry
|
||||
ifndef::doctype-manpage[]
|
||||
[[VkCullModeFlagBits,VkCullModeFlagBits]]
|
||||
["source","{basebackend@docbook:c++:cpp}",title=""]
|
||||
endif::doctype-manpage[]
|
||||
ifdef::doctype-manpage[]
|
||||
["source","{basebackend@docbook:c++:cpp}"]
|
||||
endif::doctype-manpage[]
|
||||
------------------------------------------------------------------------------
|
||||
typedef enum VkCullModeFlagBits {
|
||||
VK_CULL_MODE_NONE = 0,
|
||||
VK_CULL_MODE_FRONT_BIT = 0x00000001,
|
||||
VK_CULL_MODE_BACK_BIT = 0x00000002,
|
||||
VK_CULL_MODE_FRONT_AND_BACK = 0x3,
|
||||
} VkCullModeFlagBits;
|
||||
------------------------------------------------------------------------------
|
||||
|
|
@ -0,0 +1,13 @@
|
|||
// WARNING: DO NOT MODIFY! This file is automatically generated from the vk.xml registry
|
||||
ifndef::doctype-manpage[]
|
||||
[[VkDependencyFlagBits,VkDependencyFlagBits]]
|
||||
["source","{basebackend@docbook:c++:cpp}",title=""]
|
||||
endif::doctype-manpage[]
|
||||
ifdef::doctype-manpage[]
|
||||
["source","{basebackend@docbook:c++:cpp}"]
|
||||
endif::doctype-manpage[]
|
||||
------------------------------------------------------------------------------
|
||||
typedef enum VkDependencyFlagBits {
|
||||
VK_DEPENDENCY_BY_REGION_BIT = 0x00000001,
|
||||
} VkDependencyFlagBits;
|
||||
------------------------------------------------------------------------------
|
||||
|
|
@ -0,0 +1,13 @@
|
|||
// WARNING: DO NOT MODIFY! This file is automatically generated from the vk.xml registry
|
||||
ifndef::doctype-manpage[]
|
||||
[[VkDescriptorPoolCreateFlagBits,VkDescriptorPoolCreateFlagBits]]
|
||||
["source","{basebackend@docbook:c++:cpp}",title=""]
|
||||
endif::doctype-manpage[]
|
||||
ifdef::doctype-manpage[]
|
||||
["source","{basebackend@docbook:c++:cpp}"]
|
||||
endif::doctype-manpage[]
|
||||
------------------------------------------------------------------------------
|
||||
typedef enum VkDescriptorPoolCreateFlagBits {
|
||||
VK_DESCRIPTOR_POOL_CREATE_FREE_DESCRIPTOR_SET_BIT = 0x00000001,
|
||||
} VkDescriptorPoolCreateFlagBits;
|
||||
------------------------------------------------------------------------------
|
||||
|
|
@ -0,0 +1,23 @@
|
|||
// WARNING: DO NOT MODIFY! This file is automatically generated from the vk.xml registry
|
||||
ifndef::doctype-manpage[]
|
||||
[[VkDescriptorType,VkDescriptorType]]
|
||||
["source","{basebackend@docbook:c++:cpp}",title=""]
|
||||
endif::doctype-manpage[]
|
||||
ifdef::doctype-manpage[]
|
||||
["source","{basebackend@docbook:c++:cpp}"]
|
||||
endif::doctype-manpage[]
|
||||
------------------------------------------------------------------------------
|
||||
typedef enum VkDescriptorType {
|
||||
VK_DESCRIPTOR_TYPE_SAMPLER = 0,
|
||||
VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER = 1,
|
||||
VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE = 2,
|
||||
VK_DESCRIPTOR_TYPE_STORAGE_IMAGE = 3,
|
||||
VK_DESCRIPTOR_TYPE_UNIFORM_TEXEL_BUFFER = 4,
|
||||
VK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFER = 5,
|
||||
VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER = 6,
|
||||
VK_DESCRIPTOR_TYPE_STORAGE_BUFFER = 7,
|
||||
VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC = 8,
|
||||
VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC = 9,
|
||||
VK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT = 10,
|
||||
} VkDescriptorType;
|
||||
------------------------------------------------------------------------------
|
||||
|
|
@ -0,0 +1,21 @@
|
|||
// WARNING: DO NOT MODIFY! This file is automatically generated from the vk.xml registry
|
||||
ifndef::doctype-manpage[]
|
||||
[[VkDynamicState,VkDynamicState]]
|
||||
["source","{basebackend@docbook:c++:cpp}",title=""]
|
||||
endif::doctype-manpage[]
|
||||
ifdef::doctype-manpage[]
|
||||
["source","{basebackend@docbook:c++:cpp}"]
|
||||
endif::doctype-manpage[]
|
||||
------------------------------------------------------------------------------
|
||||
typedef enum VkDynamicState {
|
||||
VK_DYNAMIC_STATE_VIEWPORT = 0,
|
||||
VK_DYNAMIC_STATE_SCISSOR = 1,
|
||||
VK_DYNAMIC_STATE_LINE_WIDTH = 2,
|
||||
VK_DYNAMIC_STATE_DEPTH_BIAS = 3,
|
||||
VK_DYNAMIC_STATE_BLEND_CONSTANTS = 4,
|
||||
VK_DYNAMIC_STATE_DEPTH_BOUNDS = 5,
|
||||
VK_DYNAMIC_STATE_STENCIL_COMPARE_MASK = 6,
|
||||
VK_DYNAMIC_STATE_STENCIL_WRITE_MASK = 7,
|
||||
VK_DYNAMIC_STATE_STENCIL_REFERENCE = 8,
|
||||
} VkDynamicState;
|
||||
------------------------------------------------------------------------------
|
||||
|
|
@ -0,0 +1,13 @@
|
|||
// WARNING: DO NOT MODIFY! This file is automatically generated from the vk.xml registry
|
||||
ifndef::doctype-manpage[]
|
||||
[[VkFenceCreateFlagBits,VkFenceCreateFlagBits]]
|
||||
["source","{basebackend@docbook:c++:cpp}",title=""]
|
||||
endif::doctype-manpage[]
|
||||
ifdef::doctype-manpage[]
|
||||
["source","{basebackend@docbook:c++:cpp}"]
|
||||
endif::doctype-manpage[]
|
||||
------------------------------------------------------------------------------
|
||||
typedef enum VkFenceCreateFlagBits {
|
||||
VK_FENCE_CREATE_SIGNALED_BIT = 0x00000001,
|
||||
} VkFenceCreateFlagBits;
|
||||
------------------------------------------------------------------------------
|
||||
|
|
@ -0,0 +1,14 @@
|
|||
// WARNING: DO NOT MODIFY! This file is automatically generated from the vk.xml registry
|
||||
ifndef::doctype-manpage[]
|
||||
[[VkFilter,VkFilter]]
|
||||
["source","{basebackend@docbook:c++:cpp}",title=""]
|
||||
endif::doctype-manpage[]
|
||||
ifdef::doctype-manpage[]
|
||||
["source","{basebackend@docbook:c++:cpp}"]
|
||||
endif::doctype-manpage[]
|
||||
------------------------------------------------------------------------------
|
||||
typedef enum VkFilter {
|
||||
VK_FILTER_NEAREST = 0,
|
||||
VK_FILTER_LINEAR = 1,
|
||||
} VkFilter;
|
||||
------------------------------------------------------------------------------
|
||||
|
|
@ -0,0 +1,197 @@
|
|||
// WARNING: DO NOT MODIFY! This file is automatically generated from the vk.xml registry
|
||||
ifndef::doctype-manpage[]
|
||||
[[VkFormat,VkFormat]]
|
||||
["source","{basebackend@docbook:c++:cpp}",title=""]
|
||||
endif::doctype-manpage[]
|
||||
ifdef::doctype-manpage[]
|
||||
["source","{basebackend@docbook:c++:cpp}"]
|
||||
endif::doctype-manpage[]
|
||||
------------------------------------------------------------------------------
|
||||
typedef enum VkFormat {
|
||||
VK_FORMAT_UNDEFINED = 0,
|
||||
VK_FORMAT_R4G4_UNORM_PACK8 = 1,
|
||||
VK_FORMAT_R4G4B4A4_UNORM_PACK16 = 2,
|
||||
VK_FORMAT_B4G4R4A4_UNORM_PACK16 = 3,
|
||||
VK_FORMAT_R5G6B5_UNORM_PACK16 = 4,
|
||||
VK_FORMAT_B5G6R5_UNORM_PACK16 = 5,
|
||||
VK_FORMAT_R5G5B5A1_UNORM_PACK16 = 6,
|
||||
VK_FORMAT_B5G5R5A1_UNORM_PACK16 = 7,
|
||||
VK_FORMAT_A1R5G5B5_UNORM_PACK16 = 8,
|
||||
VK_FORMAT_R8_UNORM = 9,
|
||||
VK_FORMAT_R8_SNORM = 10,
|
||||
VK_FORMAT_R8_USCALED = 11,
|
||||
VK_FORMAT_R8_SSCALED = 12,
|
||||
VK_FORMAT_R8_UINT = 13,
|
||||
VK_FORMAT_R8_SINT = 14,
|
||||
VK_FORMAT_R8_SRGB = 15,
|
||||
VK_FORMAT_R8G8_UNORM = 16,
|
||||
VK_FORMAT_R8G8_SNORM = 17,
|
||||
VK_FORMAT_R8G8_USCALED = 18,
|
||||
VK_FORMAT_R8G8_SSCALED = 19,
|
||||
VK_FORMAT_R8G8_UINT = 20,
|
||||
VK_FORMAT_R8G8_SINT = 21,
|
||||
VK_FORMAT_R8G8_SRGB = 22,
|
||||
VK_FORMAT_R8G8B8_UNORM = 23,
|
||||
VK_FORMAT_R8G8B8_SNORM = 24,
|
||||
VK_FORMAT_R8G8B8_USCALED = 25,
|
||||
VK_FORMAT_R8G8B8_SSCALED = 26,
|
||||
VK_FORMAT_R8G8B8_UINT = 27,
|
||||
VK_FORMAT_R8G8B8_SINT = 28,
|
||||
VK_FORMAT_R8G8B8_SRGB = 29,
|
||||
VK_FORMAT_B8G8R8_UNORM = 30,
|
||||
VK_FORMAT_B8G8R8_SNORM = 31,
|
||||
VK_FORMAT_B8G8R8_USCALED = 32,
|
||||
VK_FORMAT_B8G8R8_SSCALED = 33,
|
||||
VK_FORMAT_B8G8R8_UINT = 34,
|
||||
VK_FORMAT_B8G8R8_SINT = 35,
|
||||
VK_FORMAT_B8G8R8_SRGB = 36,
|
||||
VK_FORMAT_R8G8B8A8_UNORM = 37,
|
||||
VK_FORMAT_R8G8B8A8_SNORM = 38,
|
||||
VK_FORMAT_R8G8B8A8_USCALED = 39,
|
||||
VK_FORMAT_R8G8B8A8_SSCALED = 40,
|
||||
VK_FORMAT_R8G8B8A8_UINT = 41,
|
||||
VK_FORMAT_R8G8B8A8_SINT = 42,
|
||||
VK_FORMAT_R8G8B8A8_SRGB = 43,
|
||||
VK_FORMAT_B8G8R8A8_UNORM = 44,
|
||||
VK_FORMAT_B8G8R8A8_SNORM = 45,
|
||||
VK_FORMAT_B8G8R8A8_USCALED = 46,
|
||||
VK_FORMAT_B8G8R8A8_SSCALED = 47,
|
||||
VK_FORMAT_B8G8R8A8_UINT = 48,
|
||||
VK_FORMAT_B8G8R8A8_SINT = 49,
|
||||
VK_FORMAT_B8G8R8A8_SRGB = 50,
|
||||
VK_FORMAT_A8B8G8R8_UNORM_PACK32 = 51,
|
||||
VK_FORMAT_A8B8G8R8_SNORM_PACK32 = 52,
|
||||
VK_FORMAT_A8B8G8R8_USCALED_PACK32 = 53,
|
||||
VK_FORMAT_A8B8G8R8_SSCALED_PACK32 = 54,
|
||||
VK_FORMAT_A8B8G8R8_UINT_PACK32 = 55,
|
||||
VK_FORMAT_A8B8G8R8_SINT_PACK32 = 56,
|
||||
VK_FORMAT_A8B8G8R8_SRGB_PACK32 = 57,
|
||||
VK_FORMAT_A2R10G10B10_UNORM_PACK32 = 58,
|
||||
VK_FORMAT_A2R10G10B10_SNORM_PACK32 = 59,
|
||||
VK_FORMAT_A2R10G10B10_USCALED_PACK32 = 60,
|
||||
VK_FORMAT_A2R10G10B10_SSCALED_PACK32 = 61,
|
||||
VK_FORMAT_A2R10G10B10_UINT_PACK32 = 62,
|
||||
VK_FORMAT_A2R10G10B10_SINT_PACK32 = 63,
|
||||
VK_FORMAT_A2B10G10R10_UNORM_PACK32 = 64,
|
||||
VK_FORMAT_A2B10G10R10_SNORM_PACK32 = 65,
|
||||
VK_FORMAT_A2B10G10R10_USCALED_PACK32 = 66,
|
||||
VK_FORMAT_A2B10G10R10_SSCALED_PACK32 = 67,
|
||||
VK_FORMAT_A2B10G10R10_UINT_PACK32 = 68,
|
||||
VK_FORMAT_A2B10G10R10_SINT_PACK32 = 69,
|
||||
VK_FORMAT_R16_UNORM = 70,
|
||||
VK_FORMAT_R16_SNORM = 71,
|
||||
VK_FORMAT_R16_USCALED = 72,
|
||||
VK_FORMAT_R16_SSCALED = 73,
|
||||
VK_FORMAT_R16_UINT = 74,
|
||||
VK_FORMAT_R16_SINT = 75,
|
||||
VK_FORMAT_R16_SFLOAT = 76,
|
||||
VK_FORMAT_R16G16_UNORM = 77,
|
||||
VK_FORMAT_R16G16_SNORM = 78,
|
||||
VK_FORMAT_R16G16_USCALED = 79,
|
||||
VK_FORMAT_R16G16_SSCALED = 80,
|
||||
VK_FORMAT_R16G16_UINT = 81,
|
||||
VK_FORMAT_R16G16_SINT = 82,
|
||||
VK_FORMAT_R16G16_SFLOAT = 83,
|
||||
VK_FORMAT_R16G16B16_UNORM = 84,
|
||||
VK_FORMAT_R16G16B16_SNORM = 85,
|
||||
VK_FORMAT_R16G16B16_USCALED = 86,
|
||||
VK_FORMAT_R16G16B16_SSCALED = 87,
|
||||
VK_FORMAT_R16G16B16_UINT = 88,
|
||||
VK_FORMAT_R16G16B16_SINT = 89,
|
||||
VK_FORMAT_R16G16B16_SFLOAT = 90,
|
||||
VK_FORMAT_R16G16B16A16_UNORM = 91,
|
||||
VK_FORMAT_R16G16B16A16_SNORM = 92,
|
||||
VK_FORMAT_R16G16B16A16_USCALED = 93,
|
||||
VK_FORMAT_R16G16B16A16_SSCALED = 94,
|
||||
VK_FORMAT_R16G16B16A16_UINT = 95,
|
||||
VK_FORMAT_R16G16B16A16_SINT = 96,
|
||||
VK_FORMAT_R16G16B16A16_SFLOAT = 97,
|
||||
VK_FORMAT_R32_UINT = 98,
|
||||
VK_FORMAT_R32_SINT = 99,
|
||||
VK_FORMAT_R32_SFLOAT = 100,
|
||||
VK_FORMAT_R32G32_UINT = 101,
|
||||
VK_FORMAT_R32G32_SINT = 102,
|
||||
VK_FORMAT_R32G32_SFLOAT = 103,
|
||||
VK_FORMAT_R32G32B32_UINT = 104,
|
||||
VK_FORMAT_R32G32B32_SINT = 105,
|
||||
VK_FORMAT_R32G32B32_SFLOAT = 106,
|
||||
VK_FORMAT_R32G32B32A32_UINT = 107,
|
||||
VK_FORMAT_R32G32B32A32_SINT = 108,
|
||||
VK_FORMAT_R32G32B32A32_SFLOAT = 109,
|
||||
VK_FORMAT_R64_UINT = 110,
|
||||
VK_FORMAT_R64_SINT = 111,
|
||||
VK_FORMAT_R64_SFLOAT = 112,
|
||||
VK_FORMAT_R64G64_UINT = 113,
|
||||
VK_FORMAT_R64G64_SINT = 114,
|
||||
VK_FORMAT_R64G64_SFLOAT = 115,
|
||||
VK_FORMAT_R64G64B64_UINT = 116,
|
||||
VK_FORMAT_R64G64B64_SINT = 117,
|
||||
VK_FORMAT_R64G64B64_SFLOAT = 118,
|
||||
VK_FORMAT_R64G64B64A64_UINT = 119,
|
||||
VK_FORMAT_R64G64B64A64_SINT = 120,
|
||||
VK_FORMAT_R64G64B64A64_SFLOAT = 121,
|
||||
VK_FORMAT_B10G11R11_UFLOAT_PACK32 = 122,
|
||||
VK_FORMAT_E5B9G9R9_UFLOAT_PACK32 = 123,
|
||||
VK_FORMAT_D16_UNORM = 124,
|
||||
VK_FORMAT_X8_D24_UNORM_PACK32 = 125,
|
||||
VK_FORMAT_D32_SFLOAT = 126,
|
||||
VK_FORMAT_S8_UINT = 127,
|
||||
VK_FORMAT_D16_UNORM_S8_UINT = 128,
|
||||
VK_FORMAT_D24_UNORM_S8_UINT = 129,
|
||||
VK_FORMAT_D32_SFLOAT_S8_UINT = 130,
|
||||
VK_FORMAT_BC1_RGB_UNORM_BLOCK = 131,
|
||||
VK_FORMAT_BC1_RGB_SRGB_BLOCK = 132,
|
||||
VK_FORMAT_BC1_RGBA_UNORM_BLOCK = 133,
|
||||
VK_FORMAT_BC1_RGBA_SRGB_BLOCK = 134,
|
||||
VK_FORMAT_BC2_UNORM_BLOCK = 135,
|
||||
VK_FORMAT_BC2_SRGB_BLOCK = 136,
|
||||
VK_FORMAT_BC3_UNORM_BLOCK = 137,
|
||||
VK_FORMAT_BC3_SRGB_BLOCK = 138,
|
||||
VK_FORMAT_BC4_UNORM_BLOCK = 139,
|
||||
VK_FORMAT_BC4_SNORM_BLOCK = 140,
|
||||
VK_FORMAT_BC5_UNORM_BLOCK = 141,
|
||||
VK_FORMAT_BC5_SNORM_BLOCK = 142,
|
||||
VK_FORMAT_BC6H_UFLOAT_BLOCK = 143,
|
||||
VK_FORMAT_BC6H_SFLOAT_BLOCK = 144,
|
||||
VK_FORMAT_BC7_UNORM_BLOCK = 145,
|
||||
VK_FORMAT_BC7_SRGB_BLOCK = 146,
|
||||
VK_FORMAT_ETC2_R8G8B8_UNORM_BLOCK = 147,
|
||||
VK_FORMAT_ETC2_R8G8B8_SRGB_BLOCK = 148,
|
||||
VK_FORMAT_ETC2_R8G8B8A1_UNORM_BLOCK = 149,
|
||||
VK_FORMAT_ETC2_R8G8B8A1_SRGB_BLOCK = 150,
|
||||
VK_FORMAT_ETC2_R8G8B8A8_UNORM_BLOCK = 151,
|
||||
VK_FORMAT_ETC2_R8G8B8A8_SRGB_BLOCK = 152,
|
||||
VK_FORMAT_EAC_R11_UNORM_BLOCK = 153,
|
||||
VK_FORMAT_EAC_R11_SNORM_BLOCK = 154,
|
||||
VK_FORMAT_EAC_R11G11_UNORM_BLOCK = 155,
|
||||
VK_FORMAT_EAC_R11G11_SNORM_BLOCK = 156,
|
||||
VK_FORMAT_ASTC_4x4_UNORM_BLOCK = 157,
|
||||
VK_FORMAT_ASTC_4x4_SRGB_BLOCK = 158,
|
||||
VK_FORMAT_ASTC_5x4_UNORM_BLOCK = 159,
|
||||
VK_FORMAT_ASTC_5x4_SRGB_BLOCK = 160,
|
||||
VK_FORMAT_ASTC_5x5_UNORM_BLOCK = 161,
|
||||
VK_FORMAT_ASTC_5x5_SRGB_BLOCK = 162,
|
||||
VK_FORMAT_ASTC_6x5_UNORM_BLOCK = 163,
|
||||
VK_FORMAT_ASTC_6x5_SRGB_BLOCK = 164,
|
||||
VK_FORMAT_ASTC_6x6_UNORM_BLOCK = 165,
|
||||
VK_FORMAT_ASTC_6x6_SRGB_BLOCK = 166,
|
||||
VK_FORMAT_ASTC_8x5_UNORM_BLOCK = 167,
|
||||
VK_FORMAT_ASTC_8x5_SRGB_BLOCK = 168,
|
||||
VK_FORMAT_ASTC_8x6_UNORM_BLOCK = 169,
|
||||
VK_FORMAT_ASTC_8x6_SRGB_BLOCK = 170,
|
||||
VK_FORMAT_ASTC_8x8_UNORM_BLOCK = 171,
|
||||
VK_FORMAT_ASTC_8x8_SRGB_BLOCK = 172,
|
||||
VK_FORMAT_ASTC_10x5_UNORM_BLOCK = 173,
|
||||
VK_FORMAT_ASTC_10x5_SRGB_BLOCK = 174,
|
||||
VK_FORMAT_ASTC_10x6_UNORM_BLOCK = 175,
|
||||
VK_FORMAT_ASTC_10x6_SRGB_BLOCK = 176,
|
||||
VK_FORMAT_ASTC_10x8_UNORM_BLOCK = 177,
|
||||
VK_FORMAT_ASTC_10x8_SRGB_BLOCK = 178,
|
||||
VK_FORMAT_ASTC_10x10_UNORM_BLOCK = 179,
|
||||
VK_FORMAT_ASTC_10x10_SRGB_BLOCK = 180,
|
||||
VK_FORMAT_ASTC_12x10_UNORM_BLOCK = 181,
|
||||
VK_FORMAT_ASTC_12x10_SRGB_BLOCK = 182,
|
||||
VK_FORMAT_ASTC_12x12_UNORM_BLOCK = 183,
|
||||
VK_FORMAT_ASTC_12x12_SRGB_BLOCK = 184,
|
||||
} VkFormat;
|
||||
------------------------------------------------------------------------------
|
||||
|
|
@ -0,0 +1,25 @@
|
|||
// WARNING: DO NOT MODIFY! This file is automatically generated from the vk.xml registry
|
||||
ifndef::doctype-manpage[]
|
||||
[[VkFormatFeatureFlagBits,VkFormatFeatureFlagBits]]
|
||||
["source","{basebackend@docbook:c++:cpp}",title=""]
|
||||
endif::doctype-manpage[]
|
||||
ifdef::doctype-manpage[]
|
||||
["source","{basebackend@docbook:c++:cpp}"]
|
||||
endif::doctype-manpage[]
|
||||
------------------------------------------------------------------------------
|
||||
typedef enum VkFormatFeatureFlagBits {
|
||||
VK_FORMAT_FEATURE_SAMPLED_IMAGE_BIT = 0x00000001,
|
||||
VK_FORMAT_FEATURE_STORAGE_IMAGE_BIT = 0x00000002,
|
||||
VK_FORMAT_FEATURE_STORAGE_IMAGE_ATOMIC_BIT = 0x00000004,
|
||||
VK_FORMAT_FEATURE_UNIFORM_TEXEL_BUFFER_BIT = 0x00000008,
|
||||
VK_FORMAT_FEATURE_STORAGE_TEXEL_BUFFER_BIT = 0x00000010,
|
||||
VK_FORMAT_FEATURE_STORAGE_TEXEL_BUFFER_ATOMIC_BIT = 0x00000020,
|
||||
VK_FORMAT_FEATURE_VERTEX_BUFFER_BIT = 0x00000040,
|
||||
VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT = 0x00000080,
|
||||
VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BLEND_BIT = 0x00000100,
|
||||
VK_FORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BIT = 0x00000200,
|
||||
VK_FORMAT_FEATURE_BLIT_SRC_BIT = 0x00000400,
|
||||
VK_FORMAT_FEATURE_BLIT_DST_BIT = 0x00000800,
|
||||
VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BIT = 0x00001000,
|
||||
} VkFormatFeatureFlagBits;
|
||||
------------------------------------------------------------------------------
|
||||
|
|
@ -0,0 +1,14 @@
|
|||
// WARNING: DO NOT MODIFY! This file is automatically generated from the vk.xml registry
|
||||
ifndef::doctype-manpage[]
|
||||
[[VkFrontFace,VkFrontFace]]
|
||||
["source","{basebackend@docbook:c++:cpp}",title=""]
|
||||
endif::doctype-manpage[]
|
||||
ifdef::doctype-manpage[]
|
||||
["source","{basebackend@docbook:c++:cpp}"]
|
||||
endif::doctype-manpage[]
|
||||
------------------------------------------------------------------------------
|
||||
typedef enum VkFrontFace {
|
||||
VK_FRONT_FACE_COUNTER_CLOCKWISE = 0,
|
||||
VK_FRONT_FACE_CLOCKWISE = 1,
|
||||
} VkFrontFace;
|
||||
------------------------------------------------------------------------------
|
||||
|
|
@ -0,0 +1,16 @@
|
|||
// WARNING: DO NOT MODIFY! This file is automatically generated from the vk.xml registry
|
||||
ifndef::doctype-manpage[]
|
||||
[[VkImageAspectFlagBits,VkImageAspectFlagBits]]
|
||||
["source","{basebackend@docbook:c++:cpp}",title=""]
|
||||
endif::doctype-manpage[]
|
||||
ifdef::doctype-manpage[]
|
||||
["source","{basebackend@docbook:c++:cpp}"]
|
||||
endif::doctype-manpage[]
|
||||
------------------------------------------------------------------------------
|
||||
typedef enum VkImageAspectFlagBits {
|
||||
VK_IMAGE_ASPECT_COLOR_BIT = 0x00000001,
|
||||
VK_IMAGE_ASPECT_DEPTH_BIT = 0x00000002,
|
||||
VK_IMAGE_ASPECT_STENCIL_BIT = 0x00000004,
|
||||
VK_IMAGE_ASPECT_METADATA_BIT = 0x00000008,
|
||||
} VkImageAspectFlagBits;
|
||||
------------------------------------------------------------------------------
|
||||
|
|
@ -0,0 +1,17 @@
|
|||
// WARNING: DO NOT MODIFY! This file is automatically generated from the vk.xml registry
|
||||
ifndef::doctype-manpage[]
|
||||
[[VkImageCreateFlagBits,VkImageCreateFlagBits]]
|
||||
["source","{basebackend@docbook:c++:cpp}",title=""]
|
||||
endif::doctype-manpage[]
|
||||
ifdef::doctype-manpage[]
|
||||
["source","{basebackend@docbook:c++:cpp}"]
|
||||
endif::doctype-manpage[]
|
||||
------------------------------------------------------------------------------
|
||||
typedef enum VkImageCreateFlagBits {
|
||||
VK_IMAGE_CREATE_SPARSE_BINDING_BIT = 0x00000001,
|
||||
VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT = 0x00000002,
|
||||
VK_IMAGE_CREATE_SPARSE_ALIASED_BIT = 0x00000004,
|
||||
VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT = 0x00000008,
|
||||
VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT = 0x00000010,
|
||||
} VkImageCreateFlagBits;
|
||||
------------------------------------------------------------------------------
|
||||
|
|
@ -0,0 +1,21 @@
|
|||
// WARNING: DO NOT MODIFY! This file is automatically generated from the vk.xml registry
|
||||
ifndef::doctype-manpage[]
|
||||
[[VkImageLayout,VkImageLayout]]
|
||||
["source","{basebackend@docbook:c++:cpp}",title=""]
|
||||
endif::doctype-manpage[]
|
||||
ifdef::doctype-manpage[]
|
||||
["source","{basebackend@docbook:c++:cpp}"]
|
||||
endif::doctype-manpage[]
|
||||
------------------------------------------------------------------------------
|
||||
typedef enum VkImageLayout {
|
||||
VK_IMAGE_LAYOUT_UNDEFINED = 0,
|
||||
VK_IMAGE_LAYOUT_GENERAL = 1,
|
||||
VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL = 2,
|
||||
VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL = 3,
|
||||
VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL = 4,
|
||||
VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL = 5,
|
||||
VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL = 6,
|
||||
VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL = 7,
|
||||
VK_IMAGE_LAYOUT_PREINITIALIZED = 8,
|
||||
} VkImageLayout;
|
||||
------------------------------------------------------------------------------
|
||||
|
|
@ -0,0 +1,14 @@
|
|||
// WARNING: DO NOT MODIFY! This file is automatically generated from the vk.xml registry
|
||||
ifndef::doctype-manpage[]
|
||||
[[VkImageTiling,VkImageTiling]]
|
||||
["source","{basebackend@docbook:c++:cpp}",title=""]
|
||||
endif::doctype-manpage[]
|
||||
ifdef::doctype-manpage[]
|
||||
["source","{basebackend@docbook:c++:cpp}"]
|
||||
endif::doctype-manpage[]
|
||||
------------------------------------------------------------------------------
|
||||
typedef enum VkImageTiling {
|
||||
VK_IMAGE_TILING_OPTIMAL = 0,
|
||||
VK_IMAGE_TILING_LINEAR = 1,
|
||||
} VkImageTiling;
|
||||
------------------------------------------------------------------------------
|
||||
|
|
@ -0,0 +1,15 @@
|
|||
// WARNING: DO NOT MODIFY! This file is automatically generated from the vk.xml registry
|
||||
ifndef::doctype-manpage[]
|
||||
[[VkImageType,VkImageType]]
|
||||
["source","{basebackend@docbook:c++:cpp}",title=""]
|
||||
endif::doctype-manpage[]
|
||||
ifdef::doctype-manpage[]
|
||||
["source","{basebackend@docbook:c++:cpp}"]
|
||||
endif::doctype-manpage[]
|
||||
------------------------------------------------------------------------------
|
||||
typedef enum VkImageType {
|
||||
VK_IMAGE_TYPE_1D = 0,
|
||||
VK_IMAGE_TYPE_2D = 1,
|
||||
VK_IMAGE_TYPE_3D = 2,
|
||||
} VkImageType;
|
||||
------------------------------------------------------------------------------
|
||||
|
|
@ -0,0 +1,20 @@
|
|||
// WARNING: DO NOT MODIFY! This file is automatically generated from the vk.xml registry
|
||||
ifndef::doctype-manpage[]
|
||||
[[VkImageUsageFlagBits,VkImageUsageFlagBits]]
|
||||
["source","{basebackend@docbook:c++:cpp}",title=""]
|
||||
endif::doctype-manpage[]
|
||||
ifdef::doctype-manpage[]
|
||||
["source","{basebackend@docbook:c++:cpp}"]
|
||||
endif::doctype-manpage[]
|
||||
------------------------------------------------------------------------------
|
||||
typedef enum VkImageUsageFlagBits {
|
||||
VK_IMAGE_USAGE_TRANSFER_SRC_BIT = 0x00000001,
|
||||
VK_IMAGE_USAGE_TRANSFER_DST_BIT = 0x00000002,
|
||||
VK_IMAGE_USAGE_SAMPLED_BIT = 0x00000004,
|
||||
VK_IMAGE_USAGE_STORAGE_BIT = 0x00000008,
|
||||
VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT = 0x00000010,
|
||||
VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT = 0x00000020,
|
||||
VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT = 0x00000040,
|
||||
VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT = 0x00000080,
|
||||
} VkImageUsageFlagBits;
|
||||
------------------------------------------------------------------------------
|
||||
|
|
@ -0,0 +1,19 @@
|
|||
// WARNING: DO NOT MODIFY! This file is automatically generated from the vk.xml registry
|
||||
ifndef::doctype-manpage[]
|
||||
[[VkImageViewType,VkImageViewType]]
|
||||
["source","{basebackend@docbook:c++:cpp}",title=""]
|
||||
endif::doctype-manpage[]
|
||||
ifdef::doctype-manpage[]
|
||||
["source","{basebackend@docbook:c++:cpp}"]
|
||||
endif::doctype-manpage[]
|
||||
------------------------------------------------------------------------------
|
||||
typedef enum VkImageViewType {
|
||||
VK_IMAGE_VIEW_TYPE_1D = 0,
|
||||
VK_IMAGE_VIEW_TYPE_2D = 1,
|
||||
VK_IMAGE_VIEW_TYPE_3D = 2,
|
||||
VK_IMAGE_VIEW_TYPE_CUBE = 3,
|
||||
VK_IMAGE_VIEW_TYPE_1D_ARRAY = 4,
|
||||
VK_IMAGE_VIEW_TYPE_2D_ARRAY = 5,
|
||||
VK_IMAGE_VIEW_TYPE_CUBE_ARRAY = 6,
|
||||
} VkImageViewType;
|
||||
------------------------------------------------------------------------------
|
||||
|
|
@ -0,0 +1,14 @@
|
|||
// WARNING: DO NOT MODIFY! This file is automatically generated from the vk.xml registry
|
||||
ifndef::doctype-manpage[]
|
||||
[[VkIndexType,VkIndexType]]
|
||||
["source","{basebackend@docbook:c++:cpp}",title=""]
|
||||
endif::doctype-manpage[]
|
||||
ifdef::doctype-manpage[]
|
||||
["source","{basebackend@docbook:c++:cpp}"]
|
||||
endif::doctype-manpage[]
|
||||
------------------------------------------------------------------------------
|
||||
typedef enum VkIndexType {
|
||||
VK_INDEX_TYPE_UINT16 = 0,
|
||||
VK_INDEX_TYPE_UINT32 = 1,
|
||||
} VkIndexType;
|
||||
------------------------------------------------------------------------------
|
||||
|
|
@ -0,0 +1,13 @@
|
|||
// WARNING: DO NOT MODIFY! This file is automatically generated from the vk.xml registry
|
||||
ifndef::doctype-manpage[]
|
||||
[[VkInternalAllocationType,VkInternalAllocationType]]
|
||||
["source","{basebackend@docbook:c++:cpp}",title=""]
|
||||
endif::doctype-manpage[]
|
||||
ifdef::doctype-manpage[]
|
||||
["source","{basebackend@docbook:c++:cpp}"]
|
||||
endif::doctype-manpage[]
|
||||
------------------------------------------------------------------------------
|
||||
typedef enum VkInternalAllocationType {
|
||||
VK_INTERNAL_ALLOCATION_TYPE_EXECUTABLE = 0,
|
||||
} VkInternalAllocationType;
|
||||
------------------------------------------------------------------------------
|
||||
|
|
@ -0,0 +1,28 @@
|
|||
// WARNING: DO NOT MODIFY! This file is automatically generated from the vk.xml registry
|
||||
ifndef::doctype-manpage[]
|
||||
[[VkLogicOp,VkLogicOp]]
|
||||
["source","{basebackend@docbook:c++:cpp}",title=""]
|
||||
endif::doctype-manpage[]
|
||||
ifdef::doctype-manpage[]
|
||||
["source","{basebackend@docbook:c++:cpp}"]
|
||||
endif::doctype-manpage[]
|
||||
------------------------------------------------------------------------------
|
||||
typedef enum VkLogicOp {
|
||||
VK_LOGIC_OP_CLEAR = 0,
|
||||
VK_LOGIC_OP_AND = 1,
|
||||
VK_LOGIC_OP_AND_REVERSE = 2,
|
||||
VK_LOGIC_OP_COPY = 3,
|
||||
VK_LOGIC_OP_AND_INVERTED = 4,
|
||||
VK_LOGIC_OP_NO_OP = 5,
|
||||
VK_LOGIC_OP_XOR = 6,
|
||||
VK_LOGIC_OP_OR = 7,
|
||||
VK_LOGIC_OP_NOR = 8,
|
||||
VK_LOGIC_OP_EQUIVALENT = 9,
|
||||
VK_LOGIC_OP_INVERT = 10,
|
||||
VK_LOGIC_OP_OR_REVERSE = 11,
|
||||
VK_LOGIC_OP_COPY_INVERTED = 12,
|
||||
VK_LOGIC_OP_OR_INVERTED = 13,
|
||||
VK_LOGIC_OP_NAND = 14,
|
||||
VK_LOGIC_OP_SET = 15,
|
||||
} VkLogicOp;
|
||||
------------------------------------------------------------------------------
|
||||
|
|
@ -0,0 +1,13 @@
|
|||
// WARNING: DO NOT MODIFY! This file is automatically generated from the vk.xml registry
|
||||
ifndef::doctype-manpage[]
|
||||
[[VkMemoryHeapFlagBits,VkMemoryHeapFlagBits]]
|
||||
["source","{basebackend@docbook:c++:cpp}",title=""]
|
||||
endif::doctype-manpage[]
|
||||
ifdef::doctype-manpage[]
|
||||
["source","{basebackend@docbook:c++:cpp}"]
|
||||
endif::doctype-manpage[]
|
||||
------------------------------------------------------------------------------
|
||||
typedef enum VkMemoryHeapFlagBits {
|
||||
VK_MEMORY_HEAP_DEVICE_LOCAL_BIT = 0x00000001,
|
||||
} VkMemoryHeapFlagBits;
|
||||
------------------------------------------------------------------------------
|
||||
|
|
@ -0,0 +1,17 @@
|
|||
// WARNING: DO NOT MODIFY! This file is automatically generated from the vk.xml registry
|
||||
ifndef::doctype-manpage[]
|
||||
[[VkMemoryPropertyFlagBits,VkMemoryPropertyFlagBits]]
|
||||
["source","{basebackend@docbook:c++:cpp}",title=""]
|
||||
endif::doctype-manpage[]
|
||||
ifdef::doctype-manpage[]
|
||||
["source","{basebackend@docbook:c++:cpp}"]
|
||||
endif::doctype-manpage[]
|
||||
------------------------------------------------------------------------------
|
||||
typedef enum VkMemoryPropertyFlagBits {
|
||||
VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT = 0x00000001,
|
||||
VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT = 0x00000002,
|
||||
VK_MEMORY_PROPERTY_HOST_COHERENT_BIT = 0x00000004,
|
||||
VK_MEMORY_PROPERTY_HOST_CACHED_BIT = 0x00000008,
|
||||
VK_MEMORY_PROPERTY_LAZILY_ALLOCATED_BIT = 0x00000010,
|
||||
} VkMemoryPropertyFlagBits;
|
||||
------------------------------------------------------------------------------
|
||||
|
|
@ -0,0 +1,17 @@
|
|||
// WARNING: DO NOT MODIFY! This file is automatically generated from the vk.xml registry
|
||||
ifndef::doctype-manpage[]
|
||||
[[VkPhysicalDeviceType,VkPhysicalDeviceType]]
|
||||
["source","{basebackend@docbook:c++:cpp}",title=""]
|
||||
endif::doctype-manpage[]
|
||||
ifdef::doctype-manpage[]
|
||||
["source","{basebackend@docbook:c++:cpp}"]
|
||||
endif::doctype-manpage[]
|
||||
------------------------------------------------------------------------------
|
||||
typedef enum VkPhysicalDeviceType {
|
||||
VK_PHYSICAL_DEVICE_TYPE_OTHER = 0,
|
||||
VK_PHYSICAL_DEVICE_TYPE_INTEGRATED_GPU = 1,
|
||||
VK_PHYSICAL_DEVICE_TYPE_DISCRETE_GPU = 2,
|
||||
VK_PHYSICAL_DEVICE_TYPE_VIRTUAL_GPU = 3,
|
||||
VK_PHYSICAL_DEVICE_TYPE_CPU = 4,
|
||||
} VkPhysicalDeviceType;
|
||||
------------------------------------------------------------------------------
|
||||
|
|
@ -0,0 +1,14 @@
|
|||
// WARNING: DO NOT MODIFY! This file is automatically generated from the vk.xml registry
|
||||
ifndef::doctype-manpage[]
|
||||
[[VkPipelineBindPoint,VkPipelineBindPoint]]
|
||||
["source","{basebackend@docbook:c++:cpp}",title=""]
|
||||
endif::doctype-manpage[]
|
||||
ifdef::doctype-manpage[]
|
||||
["source","{basebackend@docbook:c++:cpp}"]
|
||||
endif::doctype-manpage[]
|
||||
------------------------------------------------------------------------------
|
||||
typedef enum VkPipelineBindPoint {
|
||||
VK_PIPELINE_BIND_POINT_GRAPHICS = 0,
|
||||
VK_PIPELINE_BIND_POINT_COMPUTE = 1,
|
||||
} VkPipelineBindPoint;
|
||||
------------------------------------------------------------------------------
|
||||
|
|
@ -0,0 +1,13 @@
|
|||
// WARNING: DO NOT MODIFY! This file is automatically generated from the vk.xml registry
|
||||
ifndef::doctype-manpage[]
|
||||
[[VkPipelineCacheHeaderVersion,VkPipelineCacheHeaderVersion]]
|
||||
["source","{basebackend@docbook:c++:cpp}",title=""]
|
||||
endif::doctype-manpage[]
|
||||
ifdef::doctype-manpage[]
|
||||
["source","{basebackend@docbook:c++:cpp}"]
|
||||
endif::doctype-manpage[]
|
||||
------------------------------------------------------------------------------
|
||||
typedef enum VkPipelineCacheHeaderVersion {
|
||||
VK_PIPELINE_CACHE_HEADER_VERSION_ONE = 1,
|
||||
} VkPipelineCacheHeaderVersion;
|
||||
------------------------------------------------------------------------------
|
||||
Some files were not shown because too many files have changed in this diff Show More
Loading…
Reference in New Issue