diff --git a/.gitlab/issue_templates/Release checklist.md b/.gitlab/issue_templates/Release checklist.md index 3a7e885c..17cce83c 100644 --- a/.gitlab/issue_templates/Release checklist.md +++ b/.gitlab/issue_templates/Release checklist.md @@ -13,11 +13,9 @@ relevant; for example, an extension that has no language dependencies will not need SPIR-V / GLSL / HLSL items, and an EXT GLSL extension will not require Promoter ratification._ -_Requirements may be waived by vote of of the working group, provided +_Requirements may be waived by vote of the working group, provided that a 2/3 majority of non-abstaining vote are in favor._ -# Release checklist for _VK_KHR_extension_name_here_ - ## Preconditions for Call for Votes (CfV) _A formal CfV is issued following agreement at a Tuesday meeting that a @@ -30,7 +28,7 @@ the extension in question_ - [ ] VAP consulted to the extent the WG considers appropriate - [ ] CTS tests approved with three passing implementations - - [ ] Vulkan specification merged and stable in devel + - [ ] Vulkan API specification merged and stable in devel - [ ] SPIR-V specification merged and stable - [ ] GLSL specification merged and stable @@ -42,27 +40,29 @@ the extension in question_ ## Preconditions for creating public release issue on GitHub _Delete any of the following preconditions that are not relevant to -the extension in question_ +the extension in question. Enter target dates for software artifacts +where indicated. Note that these are targets and may slip._ - [ ] Vulkan specification ratified by Promoters - [ ] SPIR-V specification ratified by Promoters - [ ] GLSL specification ratified by Promoters - - [ ] GLSLang implementation approved to merge + - [ ] GLSLang implementation release schedule agreed: target _target-date_ - [ ] Marketing summary written and approved by Vulkan WG and PR team - [ ] Validation layer implementation approved to merge + - [ ] Loader support approved to merge (for instance extensions) - [ ] HLSL mapping defined - [ ] HLSL mapping supported in GLSLang - [ ] HLSL mapping supported in DXC - - [ ] CTS tests approved to merge - - [ ] SPIR-V tools implementation approved to merge - - [ ] Loader support approved to merge (for instance extensions) - - [ ] Public release approved by Vulkan WG + - [ ] CTS release schedule agreed: target _target-date_ + - [ ] SDK release schedule agreed: target _target-date_ + - [ ] SPIR-V tools implementation schedule agreed: target _target-date_ + - [ ] Public release schedule agreed: target _target-date_ ## Preconditions for closing this issue - [ ] Public release issue items checked off and issue closed -## Additional (Optional) Items +## Additional (Optional) Items _These additional items are recommended for creation at some point during or after the release, but are not required at any point._ diff --git a/BUILD.adoc b/BUILD.adoc index c364e734..0bd5bef7 100644 --- a/BUILD.adoc +++ b/BUILD.adoc @@ -2,74 +2,82 @@ :toc2: :toclevels: 2 +ifdef::env-github[] +:note-caption: :information_source: +endif::[] [[intro]] == Introduction -This README describes important stuff for getting the Vulkan API -specification and reference pages building properly. +This README describes how to build the Vulkan API specification, +reference pages, and\or other related targets. +It documents how to set up your build environment, build steps and +targets, and contains some troubleshooting advice. [[building]] == Building The Spec First, clone the Khronos Github repository containing the Vulkan -specification to your local Linux, Windows, or Mac PC. The repository is -located at https://github.com/KhronosGroup/Vulkan-Docs/ . +specification to your local Linux, Windows, or Mac PC. +The repository is located at https://github.com/KhronosGroup/Vulkan-Docs/. Next, install all the necessary build tools (see <> below). -Finally, go to the root directory of your local repository clone, and +Finally, go to the root directory of your local repository clone, and do $ make html -builds an HTML5 specification output. +which builds an HTML5 specification output. $ make all -builds the spec targets `html`, `pdf`, `styleguide`, `manhtml`, `manpdf`, -`manhtmlpages`, `checkinc`, and `checklinks`. +builds the spec targets `html`, `pdf`, `styleguide`, `registry`, `manhtml`, +`manpdf`, `manhtmlpages`, `checkinc`, and `checklinks`. [NOTE] -.Notes +.Note ==== * `make all` takes a long time to run, and generates outputs that are irrelevant for most users. Usually `make html` is used to update the HTML target, which is all - that's needed for quick verification and viewing of changes. + that's needed for quick review of changes made. * The default `make` options build a Vulkan 1.1 specification with no optional extensions. * The `validusage` target is not built as part of `make all`, due to it - needing to be built with all extensions enabled. Building this target - will fail otherwise. + needing to be built with all extensions enabled. + Building this target will fail otherwise. ==== These targets generate a variety of output documents in the directory -specified by the Makefile variable `$(OUTDIR)` (by default, `out`). +specified by the Makefile variable `$(OUTDIR)` (by default, `out/`). The checked-in file `out/index.html` links to all these targets, or they can individually be found as follows: - * API spec: - ** `html` - HTML5 in `$(OUTDIR)/html/vkspec.html` - ** `pdf` - PDF in `$(OUTDIR)/pdf/vkspec.pdf` - * "`Vulkan Documentation and Extensions`" guide: - ** `styleguide` - Single-file HTML5 in `$(OUTDIR)/styleguide.html` - * Diff spec: - ** `diff_html` - Single-file HTML5 in `$(OUTDIR)/html/diff.html` - * Reference pages: - ** `manhtml` - Single-file HTML in `$(OUTDIR)/apispec.html` - ** `manpdf` - Single-file PDF in `$(OUTDIR)/apispec.html` - ** `manhtmlpages` - File-per-entry-point HTML in `$(OUTDIR)/man/html/*` - * Validator output: - ** `checkinc` - List of commands, structs, etc. +Vulkan^(R)^ Specification:: + * `html` -- Single-file HTML5 in `$(OUTDIR)/html/vkspec.html`, and KaTeX + dependency in $(OUTDIR)/katex + * `pdf` -- PDF in `$(OUTDIR)/pdf/vkspec.pdf` +"`styleguide`" (Vulkan^(R)^ Documentation and Extensions: Procedures and Conventions):: + * `styleguide` -- Single-file HTML5 in `$(OUTDIR)/styleguide.html` +XML Registry schema document:: + * `registry` -- Single-file HTML5 in `$(OUTDIR)/registry.html` +<>:: + * `diff_html` -- Single-file HTML5 in `$(OUTDIR)/html/diff.html` +<>:: + * `manhtml` -- Single-file HTML in `$(OUTDIR)/apispec.html` + * `manpdf` -- Single-file PDF in `$(OUTDIR)/apispec.pdf` + * `manhtmlpages` -- File-per-entry-point HTML in `$(OUTDIR)/man/html/*` +<>:: + * `checkinc` -- List of commands, structs, etc. missing from the API spec in `$(OUTDIR)/checks/notInSpec.txt` - ** `checklinks` - Validator script output for API spec in - `$(OUTDIR)/checks/specErrs.txt` and for reference pages in - `$(OUTDIR)/checks/manErrs.txt` - * Valid usage database: - ** `validusage` - json database of all valid usage statements in the - specification. Must be built with ./makeAllExts (for now). + * `checklinks` -- Validator script output for API spec in + `$(OUTDIR)/checks/specErrs.txt` and for reference pages in + `$(OUTDIR)/checks/manErrs.txt` +Valid usage database:: + * `validusage` - json database of all valid usage statements in the + specification. Must be built with `./makeAllExts` (for now). Output in `$(OUTDIR)/validation/validusage.json`. A validated schema for the output of this is stored in `$(CURDIR)/config/vu-to-json/vu_schema.json` @@ -83,23 +91,13 @@ make -j 8 may significantly speed up the reference page builds. - -[[build-bugs]] -=== Asciidoctor Build Errors - -If you see an error like this from the `pdf` target: - - /home/jon/.rbenv/versions/2.3.3/lib/ruby/gems/2.3.0/gems/ruby-enum-0.7.1/lib/ruby-enum/enum.rb:34:in `const_set': asciidoctor: FAILED: /home/tree/git/vulkan/vkspec.txt: Failed to load AsciiDoc document - wrong constant name default (NameError) - -then try <> -as described below - +If you encounter problems refer to the <> section. [[building-versions]] === Building Specifications For Different API Versions The `Makefile` defaults to building a Vulkan 1.1 specification. -This is controlled by asciidoc attributes passed in the Makefile variable +This is controlled by Asciidoctor attributes passed in the Makefile variable `$(VERSIONS)` To instead build a Vulkan 1.0 specification, pass @@ -115,39 +113,45 @@ on the `make` command line. Extensions are defined in the same source as the core Specification, but are only conditionally included in the output. -Asciidoctor http://asciidoctor.org/docs/user-manual/#attributes[attributes] +http://asciidoctor.org/docs/user-manual/#attributes[Asciidoctor attributes] of the same name as the extension are used to define whether the extension -is included or not - defining such an attribute will cause the output to +is included or not -- defining such an attribute will cause the output to include the text for that extension. When building the specification, the extensions included are those specified as a space-separated list of extension names (e.g. `VK_KHR_surface`) in the -Makefile variable `$(EXTENSIONS)`, normally set on the make command line. +Makefile variable `$(EXTENSIONS)`, usually set on the make command line. When changing the list of extensions, it is critical to remove all generated files using the `clean_generated` Makefile target, as the contents of generated files depends on `$(EXTENSIONS)`. There are several helper scripts which clean these files and then build one or more specified targets for specified extensions: - * `makeExt` - generate outputs with one or more extensions enabled. + * `makeExt` -- generate outputs with one or more extensions enabled. Usage is `makeExt extension-names target(s)`, where `extension-names` is a space-separated list of extension names, such as `VK_EXT_debug_report`. If more than one extension is specified, `extension-names` must be quoted on the command line. - * `makeKHR` - generate outputs with all Khronos (`VK_KHR_*`) extensions + * `makeKHR` -- generate outputs with all Khronos (`VK_KHR_*`) extensions enabled. Usage is `makeKHR target(s)`. + * `makeAllExts` -- generate outputs with all Vulkan extensions enabled. + Usage is `makeAllExts target(s)`. The `target(s)` passed to these scripts are arbitrary `make` options, and can be used to set Makefile variables and options, as well as specify actual -build targets. +build targets; you can, for example, do: + +---- +$ ./makeAllExts -j 8 VERSIONS="VK_VERSION_1_0" html +---- The Makefile variable `$(APITITLE)` defines an additional string which is appended to the specification title. When building with extensions enabled, this should be set to something like `(with extension VK_extension_name)`. -The `makeExt` and `makeKHR` scripts already do this. +The `makeExt`, `makeKHR`, and `makeAllExts` scripts already do this. [[building-diff]] @@ -171,29 +175,37 @@ above. In the resulting HTML document, content that has been added by one of the extensions will be highlighted with a lime background, and content that was removed will be highlighted with a pink background. -Each section has an anchor of `"#differenceN"`, with an arrow (=>) at the end +Each section has an anchor of `#differenceN`, with an arrow (=>) at the end of each section which links to the next difference section. -The first diff section is "difference1". +The first diff section is `#difference1`. +[NOTE] +.Note +==== +This output is not without errors. +It may instead result in visible `+++[.added]##content##+++` and +`+++[.removed]##content##+++`, and so also highlights not being rendered. +But such visible markup still correctly encapsulates the modified content. +==== [[building-test]] === Alternate and Test Builds -If you are just testing asciidoc formatting, macros, stylesheets, etc., you -may want to edit `vkspec.txt` to just include your test code. +If you are just testing Asciidoctor formatting, macros, stylesheets, etc., +you may want to edit `vkspec.txt` to just include your test code. The asciidoctor HTML build is very fast, even for the whole Specification, but PDF builds take several minutes. === Images Used In The Specification -All images used in the specification are in the `images/` directory in SVG -format, and were created with Inkscape. +All images used in the specification are in the `images/` directory in the +SVG format, and were created with Inkscape. We recommend using Inkscape to modify or create new images, as we've had -problems using SVG files created by some other tools, especially in the PDF +problems using SVG files created by some other tools; especially in the PDF builds. - +[[validation-scripts]] === Validation Scripts [NOTE] @@ -204,7 +216,7 @@ work properly at present due to numerous changes in the macro and conditional markup used in the specification sources. ==== -There are a several Makefile targets which look for inconsistencies and +There are several Makefile targets which look for inconsistencies and missing material between the specification and ref pages, and the canonical description of the API in `vk.xml` : @@ -214,16 +226,13 @@ description of the API in `vk.xml` : 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. +It generates `notInSpec.txt` report. +This contains 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.) @@ -234,10 +243,10 @@ found. [[macros]] -== Our Asciidoc Macros +== Our Asciidoctor Macros -We use a bunch of custom macros in the reference pages and API spec asciidoc -sources. +We use a bunch of custom macros in the reference pages and API spec +Asciidoctor 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 @@ -246,12 +255,14 @@ easily verifiable. The supported macros are defined in the `config/vulkan-macros/extension.rb` asciidoctor extension script. -The tags used are described in the style guide (`styleguide.txt`). +The tags used are described in the +link:https://www.khronos.org/registry/vulkan/specs/1.1/styleguide.html[style +guide] (generated from `styleguide.txt`). We (may) eventually tool up the spec and ref pages to the point that anywhere there's a type or token referred to, clicking on (or perhaps -hovering over) it in the HTML view and be taken to the definition of that -type/token. +hovering over) it in the HTML view will take reader 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). @@ -300,11 +311,13 @@ font family]. === Marking Normative Language +// editing-note: Chapter should probably be merged with styleguide to reduce size + Normative language is marked as *bold*, and also with the [purple]#purple# role for HTML output. It can be used to mark entire paragraphs or spans of words. -In addition, the normative terminology macros, such as must: and may: and -cannot:, always use this role. +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. @@ -314,6 +327,8 @@ We may add a way to disable this formatting at build time. [[equations]] == Imbedding Equations +// editing-note: Chapter should probably be merged with styleguide to reduce size + Where possible, equations should be written using straight asciidoc markup with the _eq_ role. This covers many common equations and is faster than the alternatives. @@ -323,9 +338,9 @@ These symbols are defined using attribute names the same as the comparable LaTeX macro names, where possible. For more complex equations, such as multi-case statements, matrices, and -complex fractions, equations should be written using the latexmath: inline +complex fractions, equations should be written using the `latexmath:` inline and block macros. -The contents of the latexmath: blocks should be LaTeX math notation. +The contents of the `latexmath:` blocks should be LaTeX math notation. LaTeX math markup delimiters are now inserted by the asciidoctor toolchain. LaTeX math is passed through unmodified to all HTML output forms, which is @@ -342,26 +357,31 @@ The following caveats apply: `>=` respectively. `&` 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.) cannot be used in KaTeX at present, and have been replaced with - constructs supported by KaTeX such as pass:[{aligned}]. + * AMSmath environments (e.g. `pass:[\begin{equation*}]`, + `pass:[{align*}]`, etc.) cannot be used in KaTeX at present, and have + been replaced with constructs supported by KaTeX such as + `pass:[{aligned}]`. * Arbitrary LaTeX constructs cannot be used. KaTeX and asciidoctor-mathematical are only equation renderers, not full LaTeX engines. - Imbedding LaTeX like \Large or pass:[\hbox{\tt\small VK\_FOO}] may not - work in any of the backends, and should be avoided. + Imbedding LaTeX like `\Large` or `pass:[\hbox{\tt\small VK\_FOO}]` may + not work in any of the backends, and should be avoided. -See the "`Vulkan Documentation and Extensions`" document for more details of -supported LaTeX math constructs. +See the +link:https://www.khronos.org/registry/vulkan/specs/1.1/styleguide.html#writing-latexmath["`style guide`"] +(Vulkan Documentation and Extensions) document for more details of supported +LaTeX math constructs. [[anchors]] == Asciidoc Anchors And Xrefs +// editing-note: Chapter should probably be merged with styleguide to reduce size + 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]]+++'. +title and should use the form `pass:[[[chapter-section-label]]]`. For example, For example, in chapter `synchronization.txt`: @@ -392,6 +412,7 @@ Therefore you can say something like: Fences are used with the +++<>+++ command... ---- +// editing-note: why would I though. There are xlink: macros for that. [[depends]] == Software Dependencies @@ -403,21 +424,21 @@ Before building the Vulkan spec, you must install the following tools. Minimum versions known to be working are shown. Later versions will probably work at least as well. - * GNU make (make version: 4.0.8-1; older versions probably OK) - * Python 3 (python, version: 3.4.2) - * Ruby (ruby, version: 2.3.3) - ** The Ruby development package (ruby-dev) may also be required in some + * GNU make (`make` version: 4.0.8-1; older versions probably OK) + * Python 3 (`python`, version: 3.4.2) + * Ruby (`ruby`, version: 2.3.3) + ** The Ruby development package (`ruby-dev`) may also be required in some environments. - * Git command-line client (git, version: 2.1.4). + * Git command-line client (`git`, version: 2.1.4). The build can progress without a git client, but branch/commit information will be omitted from the build. Any version supporting the following operations should work: ** `git symbolic-ref --short HEAD` ** `git log -1 --format="%H"` - * Ghostscript (ghostscript, version: 9.10). + * Ghostscript (`ghostscript`, version: 9.10). This is for the PDF build, and it can still progress without it. - Ghostscript is used to optimize the size of the PDF, so will be a lot - smaller if it is included. + Ghostscript is used to optimize the size of the PDF, so it will be order + of magnitude smaller if it is included. The following Ruby Gems and platform package dependencies must also be installed. @@ -426,28 +447,28 @@ environment managers below. Please read the remainder of this document (other than platform-specific parts you don't use) completely before trying to install. - * Asciidoctor (asciidoctor, version: 1.5.6.1) - * Coderay (coderay, version 1.1.2) - * JSON Schema (json-schema, version 2.8.0) - * Asciidoctor PDF (asciidoctor-pdf, version: 1.5.0.alpha16) - * Asciidoctor Mathematical (asciidoctor-mathematical, version 0.2.2) + * Asciidoctor (`asciidoctor`, version: 1.5.6.1) + * Coderay (`coderay`, version 1.1.2) + * JSON Schema (`json-schema`, version 2.8.0) + * Asciidoctor PDF (`asciidoctor-pdf`, version: 1.5.0.alpha16) + * Asciidoctor Mathematical (`asciidoctor-mathematical`, version 0.2.2) * https://github.com/asciidoctor/asciidoctor-mathematical#dependencies[Dependencies - for asciidoctor-mathematical] (There are a lot of these!) - * KaTeX distribution (version 0.7.0 from https://github.com/Khan/KaTeX . - This is cached under `katex/`, and need not be - installed from github. + for `asciidoctor-mathematical`] (There are a lot of these!) + * KaTeX distribution (version 0.7.0 from https://github.com/Khan/KaTeX. + This is cached under `katex/`, and need not be installed from github. .Note [NOTE] ==== Older versions of these packages may work, but are not recommended. -In particular, the latest versions of asciidoctor-pdf and -asciidoctor-mathematical contain important patches working around issues +In particular, the latest versions of `asciidoctor-pdf` and +`asciidoctor-mathematical` contain important patches working around issues we've discovered, and those patches may not be present in earlier versions. ==== -Only the `asciidoctor` and `coderay` gems are needed if you don't intend to -build PDF versions of the spec and supporting documents. +Only the `asciidoctor` and `coderay` gems are needed for the HTML `make` +targets. +Rest is needed for the PDF builds. `json-schema` is only required in order to validate the output of the valid usage extraction scripts to a JSON file. @@ -465,9 +486,9 @@ targets. Platform-specific toolchain instructions follow: * Microsoft Windows - ** <> + ** <> ** <> (PDF builds not tested) - ** <> + ** <> * <> * <> @@ -478,166 +499,32 @@ Platform-specific toolchain instructions follow: Most of the dependencies on Linux packages are light enough that it's possible to build the spec natively in Windows, but it means bypassing the makefile and calling functions directly. -This might be solved in future. -For now, there are three options for Windows users: Ubuntu / Windows 10, -MinGW, or Cygwin. +Considering how easy it is to get an Unix subsystem or VM on Windows, this +is not recommended. +It is unlikely a direct path will become supported in the future. + +Three options for Windows users are described below: Ubuntu / Windows 10 +(best, as long as you're running Windows 10), MinGW, and Cygwin. [[depends-ubuntu]] ==== Ubuntu / Windows 10 -When using the "`Ubuntu Subsystem`" for Windows 10, most dependencies can be -installed via apt-get: +At the time of writing Ubuntu Subsystem is provided in 18.04 LTS and +16.04 LTS versions. +These versions are perfectly suitable for building this repo. + +You can install Ubuntu Subsystem as described in the official documentation: +https://docs.microsoft.com/en-us/windows/wsl/install-win10 + +The distro image is not kept up-to-date, so it is recommended to run: ---- -sudo apt-get -qq -y install build-essential python3 git cmake bison flex \ - libffi-dev libxml2-dev libgdk-pixbuf2.0-dev libcairo2-dev \ - libpango1.0-dev ttf-lyx gtk-doc-tools ghostscript +sudo apt update +sudo apt full-upgrade ---- -The default ruby packages on Ubuntu are fairly out of date. -Ubuntu only provides `ruby` and `ruby2.0` - the latter is multiple revisions -behind the current stable branch, and would require wrangling to get the -makefile working with it. - -Luckily, there are better options; either https://rvm.io[rvm] or -https://github.com/rbenv/rbenv[rbenv] is recommended to install a more -recent version. - -[NOTE] -.Note -==== - - * If you are new to Ruby, you should *completely remove* (through the - package manager, e.g. `sudo apt-get remove *packagename*`) all existing - Ruby and asciidoctor infrastructure on your machine before trying to use - rvm or rbenv for the first time. - `dpkg -l | egrep 'asciidoctor|ruby|rbenv|rvm'` will give you a list of - candidate package names to remove. - ** If you already have a favorite Ruby package manager, ignore this - advice, and just install the required OS packages and gems. - * In addition, `rvm` and `rbenv` are *mutually incompatible*. - They both rely on inserting shims and `$PATH` modifications in your bash - shell. - If you already have one of these installed and are familiar with it, - it's probably best to stay with that one. - One of the editors, who is new to Ruby, found `rbenv` far more - comprehensible than `rvm`. - The other editor likes `rvm` better. - ** Neither `rvm` nor `rbenv` work, out of the box, when invoked from - non-Bash shells like tcsh. - This can be hacked up by setting the right environment variables and - PATH additions based on a bash environment. - * Most of the tools on Bash for Windows are quite happy with Windows line - endings (CR LF), but bash scripts expect Unix line endings (LF). - The file `.gitattributes` at the top of the vulkan tree in the 1.0 - branch forces such scripts to be checked out with the proper line - endings on non-Linux platforms. - If you add new scripts whose names don't end in `.sh`, they should be - included in .gitattributes as well. -==== - - -[[depends-ubuntu-rbenv]] -===== Ubuntu/Windows 10 Using Rbenv - -Rbenv is a lighter-weight Ruby environment manager with less functionality -than rvm. -Its primary task is to manage different Ruby versions, while rvm has -additional functionality such as managing "`gemsets`" that is irrelevant to -our needs. - -A complete installation script for the toolchain on Ubuntu for Windows, -developed on an essentially out-of-the-box environment, follows. -If you try this, don't try to execute the entire thing at once. -Do each step separately in case of errors we didn't encounter. - ----- -# Install packages needed by `ruby_build` and by toolchain components. -# See https://github.com/rbenv/ruby-build/wiki and -# https://github.com/asciidoctor/asciidoctor-mathematical#dependencies - -sudo apt-get install autoconf bison build-essential libssl-dev \ - libyaml-dev libreadline6-dev zlib1g-dev libncurses5-dev \ - libffi-dev libgdbm3 libgdbm-dev cmake libxml2 \ - libxml2-dev flex pkg-config libglib2.0-dev \ - libcairo-dev libpango1.0-dev libgdk-pixbuf2.0-dev \ - libpangocairo-1.0 - -# Install rbenv from https://github.com/rbenv/rbenv -git clone https://github.com/rbenv/rbenv.git ~/.rbenv - -# Set path to shim layers in .bashrc -echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> .bashrc - -~/.rbenv/bin/rbenv init - -# Set .rbenv environment variables in .bashrc -echo 'eval "$(rbenv init -)"' >> .bashrc - -# Restart your shell (e.g. open a new terminal window). Note that -# you do not need to use the `-l` option, since the modifications -# were made to .bashrc rather than .bash_profile. If successful, -# `type rbenv` should print 'rbenv is a function' followed by code. - -# Install `ruby_build` plugin from https://github.com/rbenv/ruby-build - -git clone https://github.com/rbenv/ruby-build.git ~/.rbenv/plugins/ruby-build - -# Install Ruby 2.3.3 -# This takes in excess of 20 min. to build! -# https://github.com/rbenv/ruby-build/issues/1054#issuecomment-276934761 -# suggests: -# "You can speed up Ruby installs by avoiding generating ri/RDoc -# documentation for them: -# RUBY_CONFIGURE_OPTS=--disable-install-doc rbenv install 2.3.3 -# We have not tried this. - -rbenv install 2.3.3 - -# Configure rbenv globally to always use Ruby 2.3.3. -echo "2.3.3" > ~/.rbenv/version - -# Finally, install toolchain components. -# asciidoctor-mathematical also takes in excess of 20 min. to build! -# The same RUBY_CONFIGURE_OPTS advice above may apply here as well. - -gem install asciidoctor coderay json-schema -gem install --pre asciidoctor-pdf -MATHEMATICAL_SKIP_STRDUP=1 gem install asciidoctor-mathematical ----- - - -[[depends-ubuntu-rvm]] -===== Ubuntu/Windows 10 Using RVM - -Here are (sparser) instructions for using rvm to setup version 2.3.x: - ----- -gpg --keyserver hkp://keys.gnupg.net --recv-keys 409B6B1796C275462A1703113804BB82D39DC0E3 -\curl -sSL https://get.rvm.io | bash -s stable --ruby -source ~/.rvm/scripts/rvm -rvm install ruby-2.3 -rvm use ruby-2.3 ----- - -NOTE: Windows 10 Bash will need to be launched with the "-l" option -appended, so that it runs a login shell; otherwise RVM won't function -correctly on future launches. - - -[[depends-ubuntu-sys]] -===== Ubuntu 16.04 using system Ruby - -The Ubuntu 16.04.1 default Ruby install (version 2.3.1) seems to be -up-to-date enough to run all the required gems, but also needs the -`ruby-dev` package installed through the package manager. - -In addition, the library -`/var/lib/gems/2.3.0/gems/mathematical-1.6.7/ext/mathematical/lib/liblasem.so` -has to be copied or linked into a directory where the loader can find it. -This requirement appears to be due to a problem with the -asciidoctor-mathematical build process. +Rest is identical to <>. [[depends-mingw]] @@ -768,11 +655,46 @@ curl -LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/cmex10.ttf \ -LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/msbm10.ttf ---- +[[depends-linux]] +=== Linux (Debian, Ubuntu, etc.) + +System dependencies can be installed via apt: + +---- +sudo apt install build-essential python3 git cmake bison flex \ + libffi-dev libxml2-dev libgdk-pixbuf2.0-dev libcairo2-dev \ + libpango1.0-dev fonts-lyx ghostscript +---- + +[NOTE] +.Note +==== +On Ubuntu versions prior to 18.04 LTS, you will probably need to use the +`ttf-lyx` package instead of `fonts-lyx`. +==== + +These instructions are for the Ubuntu installation and are generally +applicable to native Linux environments that use Debian packages, although +the exact list of packages to install may differ. +Other distributions using different package managers, such as RPM (Fedora) +and Yum (SuSE) will have different requirements. + +Ruby can also be installed as a system package: + +---- +sudo apt install ruby ruby-dev +---- + +Ruby packages are often well out of date, so using <> such as `rbenv` or `rvm` might be preferable. + +Once the Ruby environment is set up, install the required +<>. [[depends-osx]] === Mac OS X -Mac OS X should work in the same way as for ubuntu by using the Homebrew +Mac OS X should work in the same way as for Ubuntu by using the Homebrew package manager, with the exception that you can simply install the ruby package via `brew` rather than using a ruby-specific version manager. @@ -794,23 +716,6 @@ curl -LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/cmex10.ttf \ Then install the required <>. -[[depends-linux]] -=== Linux (Debian, Ubuntu, etc.) - -The instructions for the <> installation -are generally applicable to native Linux environments using Debian packages, -such as Debian and Ubuntu, although the exact list of packages to install -may differ. -Other distributions using different package managers, such as RPM (Fedora) -and Yum (SuSE) will have different requirements. - -Using `rbenv` or `rvm` is necessary, since the system Ruby packages are -often well out of date. - -Once the environment manager, Ruby, and `ruby_build` have been installed, -install the required <>. - - [[depends-gems]] === Ruby Gems @@ -818,35 +723,271 @@ The following ruby gems can be installed directly via the `gem install` command, once the platform is set up: ---- -gem install rake asciidoctor coderay json-schema +gem install asciidoctor coderay json-schema # Required only for pdf builds -MATHEMATICAL_SKIP_STRDUP=1 gem install asciidoctor-mathematical +gem install asciidoctor-mathematical gem install --pre asciidoctor-pdf ---- -[[ruby-enum-downgrade]] -==== Ruby Gem Versioning Errors +Depending on Ruby environment `gem` may require `sudo`. + +It may significantly speed up installation if you skip documentation build +by passing `--no-rdoc --no-ri` arguments. + +It may be beneficial to use updated packages via: + +---- +gem update +gem clean +---- + +[[troubleshooting]] +== Troubleshooting + +This section goes over known problems and solutions for toolchain +installation or for build. + +If you get arbitrary build errors it can't hurt to first try resolve it by +cleaning the tree: + +---- +make clean +git clean -dxf +---- + + +=== STEM SVG Errors + +If you happen to have `_` or other Asciidoctor formating characters in your +path, then PDF build using `asciidoctor-mathematical` may fail with: + +---- +asciidoctor: WARNING: image to embed not found or not readable: whatever/stuff/Vulkan-Docs/out/equations_temp/stem-d3355033150173c1d397e342237db405.svg +---- + +See https://github.com/asciidoctor/asciidoctor-mathematical/issues/43. + +You simply need to have the repository cloned in a simpler path. + + +=== Ghostscript Errors + +Ghostscript optimization of the PDF may produce: + +---- + **** Error reading a content stream. The page may be incomplete. + Output may be incorrect. + **** Error: File did not complete the page properly and may be damaged. + Output may be incorrect. +---- + +Usually, it is just a problem with the Asciidoc sources (e.g. silent failure +to render content that does not fit in the page; such as SVG equations where +there is no line break opportunity). + + +=== Ruby Gem Versioning Errors + +Sometimes, when updating ruby gem packages incompatibilities arise. +It is resoleved by identifying the offending packages and downgrading them: + +---- +$ gem uninstall package_name +$ gem install package_name --version good_version_number +---- + +If you already have the gem dependencies previously installed, if there are +new versions, then updating to them instead might help: + +---- +$ gem update +---- *ruby-enum* -Make sure you are using ruby-enum 0.7.1 or later, and mathematical 1.6.8 or -later. If you are forced to use earlier versions, see +We have seen this PDF build error: +---- +Failed to load AsciiDoc document - wrong constant name default (NameError) +---- + +It should not be occuring with updated packages. +Make sure you are using `ruby-enum 0.7.1` or later, and `mathematical 1.6.8` +or later. +If you are forced to use earlier versions, see https://github.com/gjtorikian/mathematical/issues/69 for a report of a related versioning problem. - *prawn* Make sure you are using prawn 2.2.1 or later, and prawn-templates 0.0.5 or -later. Incompatibilities between asciidoctor-pdf and earlier versions of +later. Incompatibilities between `asciidoctor-pdf` and earlier versions of these gems affects the PDF build. See https://github.com/KhronosGroup/Vulkan-Docs/issues/476 +=== asciidoctor-mathematical gem native extension errors + +Installing `mathematical` gem builds `lasem` and `mtex2MML` native binaries. +The <> we list should be sufficient for the install to +build those native extensions successfully. + +If you encounter problems, it is possible to use those binaries from +preinstalled locations. +See https://github.com/gjtorikian/mathematical#troubleshooting. + + +=== Asciidoctor include errors + +If you get errors like: + +---- +asciidoctor: ERROR: chapters/???.txt: line 189: include file not found: ???/Vulkan-Docs/api/protos/???.txt +---- + +you probably forgot to call `make clean_generated` as stated in the +<> chapter. + + +[[ruby-env]] +== Alternative Ruby environments + +The default `ruby` packages on Linux distro may be out of date. +Through the default `ruby` package, Ubuntu 18.04 provides ruby 2.5, and +Ubuntu 16.10 provides ruby 2.3. +Those system packages seem to be sufficient to build this repo. + +But there are better options; either https://rvm.io[rvm] or +https://github.com/rbenv/rbenv[rbenv] is recommended to install an updated +version of Ruby environment. + +[NOTE] +.Note +==== + + * If you are new to Ruby, you should *completely remove* (through the + package manager, e.g. `sudo apt purge *packagename*`) all existing + Ruby and asciidoctor infrastructure on your machine before trying to use + rvm or rbenv for the first time. + `dpkg -l | egrep 'asciidoctor|ruby|rbenv|rvm'` will give you a list of + candidate package names to remove. + ** If you already have a favorite Ruby package manager, ignore this + advice, and just install the required OS packages and gems. + * In addition, `rvm` and `rbenv` are *mutually incompatible*. + They both rely on inserting shims and `$PATH` modifications in your bash + shell. + If you already have one of these installed and are familiar with it, + it's probably best to stay with that one. + One of the editors, who is new to Ruby, found `rbenv` far more + comprehensible than `rvm`. + The other editor likes `rvm` better. + ** Neither `rvm` nor `rbenv` work, out of the box, when invoked from + non-Bash shells like `tcsh`. + This can be hacked up by setting the right environment variables and + `PATH` additions based on a bash environment. + * Most of the tools on Bash for Windows are quite happy with Windows line + endings (`CR LF`), but bash scripts expect Unix line endings (`LF`). + The file `.gitattributes` at the top of the vulkan tree forces such + scripts to be checked out with the proper line endings on non-Linux + platforms. + If you add new scripts whose names don't end in `.sh`, they should be + included in `.gitattributes` as well. +==== + + +[[depends-ubuntu-rbenv]] +===== Ubuntu/Windows 10 Using Rbenv + +Rbenv is a lighter-weight Ruby environment manager with less functionality +than rvm. +Its primary task is to manage different Ruby versions, while rvm has +additional functionality such as managing "`gemsets`" that is irrelevant to +our needs. + +A complete installation script for the toolchain on Ubuntu for Windows, +developed on an essentially out-of-the-box environment, follows. +If you try this, don't try to execute the entire thing at once. +Do each step separately in case of errors we didn't encounter. + +---- +# Install packages needed by `ruby_build` and by toolchain components. +# See https://github.com/rbenv/ruby-build/wiki and +# https://github.com/asciidoctor/asciidoctor-mathematical#dependencies + +sudo apt-get install autoconf bison build-essential libssl-dev \ + libyaml-dev libreadline6-dev zlib1g-dev libncurses5-dev \ + libffi-dev libgdbm3 libgdbm-dev cmake libxml2 \ + libxml2-dev flex pkg-config libglib2.0-dev \ + libcairo-dev libpango1.0-dev libgdk-pixbuf2.0-dev \ + libpangocairo-1.0 + +# Install rbenv from https://github.com/rbenv/rbenv +git clone https://github.com/rbenv/rbenv.git ~/.rbenv + +# Set path to shim layers in .bashrc +echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> .bashrc + +~/.rbenv/bin/rbenv init + +# Set .rbenv environment variables in .bashrc +echo 'eval "$(rbenv init -)"' >> .bashrc + +# Restart your shell (e.g. open a new terminal window). Note that +# you do not need to use the `-l` option, since the modifications +# were made to .bashrc rather than .bash_profile. If successful, +# `type rbenv` should print 'rbenv is a function' followed by code. + +# Install `ruby_build` plugin from https://github.com/rbenv/ruby-build + +git clone https://github.com/rbenv/ruby-build.git ~/.rbenv/plugins/ruby-build + +# Install Ruby 2.3.3 +# This takes in excess of 20 min. to build! +# https://github.com/rbenv/ruby-build/issues/1054#issuecomment-276934761 +# suggests: +# "You can speed up Ruby installs by avoiding generating ri/RDoc +# documentation for them: +# RUBY_CONFIGURE_OPTS=--disable-install-doc rbenv install 2.3.3 +# We have not tried this. + +rbenv install 2.3.3 + +# Configure rbenv globally to always use Ruby 2.3.3. +echo "2.3.3" > ~/.rbenv/version + +# Finally, install toolchain components. +# asciidoctor-mathematical also takes in excess of 20 min. to build! +# The same RUBY_CONFIGURE_OPTS advice above may apply here as well. + +gem install asciidoctor coderay json-schema +gem install --pre asciidoctor-pdf +MATHEMATICAL_SKIP_STRDUP=1 gem install asciidoctor-mathematical +---- + + +[[depends-ubuntu-rvm]] +===== Ubuntu/Windows 10 Using RVM + +Here are (sparser) instructions for using rvm to setup version 2.3.x: + +---- +gpg --keyserver hkp://keys.gnupg.net --recv-keys 409B6B1796C275462A1703113804BB82D39DC0E3 +\curl -sSL https://get.rvm.io | bash -s stable --ruby +source ~/.rvm/scripts/rvm +rvm install ruby-2.3 +rvm use ruby-2.3 +---- + +NOTE: Windows 10 Bash will need to be launched with the "-l" option +appended, so that it runs a login shell; otherwise RVM won't function +correctly on future launches. + + [[history]] == Revision History + * 2018-10-25 - Update Troubleshooting, and Windows and Linux build. Plus + random editing. * 2018-03-13 - Rename to BUILD.adoc and update for new directory structure. * 2018-03-05 - Update README for Vulkan 1.1 release. diff --git a/COPYING.md b/COPYING.md index 61a87299..a542522c 100644 --- a/COPYING.md +++ b/COPYING.md @@ -71,4 +71,4 @@ accommodate new needs of external projects; but working with the different Khronos member company IP lawyers to make license changes is a very slow process, constrained by the Khronos Member Agreement and IP Policy as well as by individual company concerns about their IP. Do not expect rapid -changes in anything having to to with copyrights and licensing. +changes in anything having to do with copyrights and licensing. diff --git a/ChangeLog.txt b/ChangeLog.txt index dbeb5011..563a69a9 100644 --- a/ChangeLog.txt +++ b/ChangeLog.txt @@ -593,7 +593,7 @@ Other Issues: usage block instead of the body text, and give it a VUID. * Use the full name of the "`style guide`" in a reference in the description of slink:vkGetPhysicalDeviceProperties, update the - <>, and use the the full name + <>, and use the full name in the registry index page. ----------------------------------------------------- @@ -1074,7 +1074,7 @@ Other Issues: ** Clarified a number of definitions in the Glossary. ** Updated the document writing guide to match new terminology changes. * Explicitly state in the <> language that that for objects other than + application memory lifetime>> language that for objects other than descriptor sets, a slink:VkDescriptorSetLayout object used in the creation of another object (such as slink:VkPipelineLayout or slink:VkDescriptorUpdateTemplateKHR) is only in use during the creation diff --git a/Makefile b/Makefile index f30b9869..0a3eb16f 100644 --- a/Makefile +++ b/Makefile @@ -112,7 +112,7 @@ VERBOSE = # EXTRAATTRIBS sets additional attributes, if passed to make # ADOCOPTS options for asciidoc->HTML5 output NOTEOPTS = -a editing-notes -a implementation-guide -PATCHVERSION = 90 +PATCHVERSION = 91 ifneq (,$(findstring VK_VERSION_1_1,$(VERSIONS))) SPECREVISION = 1.1.$(PATCHVERSION) else diff --git a/appendices/VK_AMD_memory_overallocation_behavior.txt b/appendices/VK_AMD_memory_overallocation_behavior.txt new file mode 100644 index 00000000..028f9383 --- /dev/null +++ b/appendices/VK_AMD_memory_overallocation_behavior.txt @@ -0,0 +1,47 @@ +include::meta/VK_AMD_memory_overallocation_behavior.txt[] + +*Last Modified Date*:: + 2018-09-19 +*IP Status*:: + No known IP claims. +*Contributors*:: + - Martin Dinkov, AMD + - Matthaeus Chajdas, AMD + - Daniel Rakos, AMD + - Jon Campbell, AMD + +This extension allows controlling whether explicit overallocation beyond the +device memory heap sizes (reported by +slink:VkPhysicalDeviceMemoryProperties) is allowed or not. +Overallocation may lead to performance loss and is not supported for all +platforms. + +=== New Object Types + +None. + +=== New Enum Constants + + * Extending ename:VkStructureType: + ** ename:VK_STRUCTURE_TYPE_DEVICE_MEMORY_OVERALLOCATION_CREATE_INFO_AMD + +=== New Enums + + * elink:VkMemoryOverallocationBehaviorAMD + +=== New Structures + + * slink:VkDeviceMemoryOverallocationCreateInfoAMD + +=== New Functions + +None. + +=== Examples + +None. + +=== Version History + + * Revision 1, 2018-09-19 (Martin Dinkov) + - Initial draft. diff --git a/appendices/VK_EXT_conditional_rendering.txt b/appendices/VK_EXT_conditional_rendering.txt index 92de8016..2708d842 100644 --- a/appendices/VK_EXT_conditional_rendering.txt +++ b/appendices/VK_EXT_conditional_rendering.txt @@ -25,6 +25,10 @@ None. === New Enum Constants + * Extending elink:VkStructureType: + ** ename:VK_STRUCTURE_TYPE_COMMAND_BUFFER_INHERITANCE_CONDITIONAL_RENDERING_INFO_EXT + ** ename:VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_CONDITIONAL_RENDERING_FEATURES_EXT + ** ename:VK_STRUCTURE_TYPE_CONDITIONAL_RENDERING_BEGIN_INFO_EXT * Extending elink:VkAccessFlagBits: ** ename:VK_ACCESS_CONDITIONAL_RENDERING_READ_BIT_EXT * Extending elink:VkBufferUsageFlagBits: diff --git a/appendices/VK_EXT_vertex_attribute_divisor.txt b/appendices/VK_EXT_vertex_attribute_divisor.txt index dc0d236a..ab476038 100644 --- a/appendices/VK_EXT_vertex_attribute_divisor.txt +++ b/appendices/VK_EXT_vertex_attribute_divisor.txt @@ -22,6 +22,7 @@ Extending elink:VkStructureType: ** ename:VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VERTEX_ATTRIBUTE_DIVISOR_PROPERTIES_EXT ** ename:VK_STRUCTURE_TYPE_PIPELINE_VERTEX_INPUT_DIVISOR_STATE_CREATE_INFO_EXT + ** ename:VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VERTEX_ATTRIBUTE_DIVISOR_FEATURES_EXT === New Enums diff --git a/appendices/VK_KHR_device_group_creation.txt b/appendices/VK_KHR_device_group_creation.txt index 7d33a31f..7e973fb5 100644 --- a/appendices/VK_KHR_device_group_creation.txt +++ b/appendices/VK_KHR_device_group_creation.txt @@ -27,6 +27,7 @@ None. * Extending elink:VkStructureType: ** ename:VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_GROUP_PROPERTIES_KHR + ** ename:VK_STRUCTURE_TYPE_DEVICE_GROUP_DEVICE_CREATE_INFO_KHR * Extending elink:VkMemoryHeapFlagBits ** ename:VK_MEMORY_HEAP_MULTI_INSTANCE_BIT_KHR diff --git a/appendices/VK_KHR_maintenance2.txt b/appendices/VK_KHR_maintenance2.txt index efcec91e..b5832d64 100644 --- a/appendices/VK_KHR_maintenance2.txt +++ b/appendices/VK_KHR_maintenance2.txt @@ -44,7 +44,7 @@ accessed via a code:subpassLoad operation. On some implementations there may: be a performance penalty if the implementation does not know (at flink:vkCreateRenderPass time) which -aspect(s) of multi-aspect images can: be be accessed as input attachments. +aspect(s) of multi-aspect images can: be accessed as input attachments. diff --git a/appendices/VK_KHR_mir_surface.txt b/appendices/VK_KHR_mir_surface.txt deleted file mode 100644 index 97de2bca..00000000 --- a/appendices/VK_KHR_mir_surface.txt +++ /dev/null @@ -1,79 +0,0 @@ -// Copyright (c) 2014-2018 Khronos Group. This work is licensed under a -// Creative Commons Attribution 4.0 International License; see -// http://creativecommons.org/licenses/by/4.0/ - -include::meta/VK_KHR_mir_surface.txt[] - -*Last Modified Date*:: - 2015-11-28 -*IP Status*:: - No known IP claims. -*Contributors*:: - - Patrick Doane, Blizzard - - Jason Ekstrand, Intel - - Ian Elliott, LunarG - - Courtney Goeltzenleuchter, LunarG - - Jesse Hall, Google - - James Jones, NVIDIA - - Antoine Labour, Google - - Jon Leech, Khronos - - David Mao, AMD - - Norbert Nopper, Freescale - - Alon Or-bach, Samsung - - Daniel Rakos, AMD - - Graham Sellers, AMD - - Ray Smith, ARM - - Jeff Vigil, Qualcomm - - Chia-I Wu, LunarG - - -The `VK_KHR_mir_surface` extension is an instance extension. -It provides a mechanism to create a slink:VkSurfaceKHR object (defined by -the `<>` extension) that refers to a Mir surface, as well as -a query to determine support for rendering to the windows desktop. - -=== New Object Types - -None - -=== New Enum Constants - - * Extending elink:VkStructureType: - ** ename:VK_STRUCTURE_TYPE_MIR_SURFACE_CREATE_INFO_KHR - -=== New Enums - -None - -=== New Structures - - * slink:VkMirSurfaceCreateInfoKHR - -=== New Functions - - * flink:vkCreateMirSurfaceKHR - * flink:vkGetPhysicalDeviceMirPresentationSupportKHR - -=== Issues - -1) Does Mir need a way to query for compatibility between a particular -physical device (and queue family?) and a specific Mir connection, screen, -window, etc.? - -*RESOLVED*: Yes, flink:vkGetPhysicalDeviceMirPresentationSupportKHR was -added to address this. - -=== Version History - - * Revision 1, 2015-09-23 (Jesse Hall) - - Initial draft, based on the previous contents of VK_EXT_KHR_swapchain - (later renamed VK_EXT_KHR_surface). - - * Revision 2, 2015-10-02 (James Jones) - - Added vkGetPhysicalDeviceMirPresentationSupportKHR to resolve issue #1. - - * Revision 3, 2015-10-26 (Ian Elliott) - - Renamed from VK_EXT_KHR_mir_surface to VK_KHR_mir_surface. - - * Revision 4, 2015-11-28 (Daniel Rakos) - - Updated the surface create function to take a pCreateInfo structure. diff --git a/appendices/VK_NVX_raytracing.txt b/appendices/VK_NVX_raytracing.txt deleted file mode 100644 index 3503305a..00000000 --- a/appendices/VK_NVX_raytracing.txt +++ /dev/null @@ -1,179 +0,0 @@ -include::meta/VK_NVX_raytracing.txt[] - -*Last Modified Date*:: - 2018-09-11 - -*Interactions and External Dependencies*:: - - This extension requires the - https://htmlpreview.github.io/?https://github.com/KhronosGroup/SPIRV-Registry/blob/master/extensions/NV/SPV_NVX_raytracing.html[+SPV_NVX_raytracing+] - SPIR-V extension. - - This extension requires the - https://github.com/KhronosGroup/GLSL/blob/master/extensions/nvx/GLSL_NVX_raytracing.txt[+GL_NVX_raytracing+] - extension for GLSL source languages. - -*Contributors*:: - - Eric Werness, NVIDIA - - Ashwin Lele, NVIDIA - - Robert Stepinski, NVIDIA - - Nuno Subtil, NVIDIA - - Christoph Kubisch, NVIDIA - - Martin Stich, NVIDIA - - Daniel Koch, NVIDIA - -Rasterization has been the dominant method to produce interactive graphics, -but increasing performance of graphics hardware has made raytracing a viable -option for interactive rendering. -Being able to integrate raytracing with traditional rasterization makes it -easier for applications to incrementally add raytraced effects to existing -applications or to do hybrid approaches with rasterization for primary -visibility and raytracing for secondary queries. - -To enable raytracing, this extension adds a few different categories of new -functionality: - - * Acceleration structure objects and build commands - * A new pipeline type with new shader domains - * An indirection table to link shader groups with acceleration structure - items - -This extension adds support for the following SPIR-V extension in Vulkan: - - * +SPV_NVX_raytracing+ - -=== New Object Types - - * slink:VkAccelerationStructureNVX - -=== New Enum Constants - - * Extending elink:VkStructureType: - ** ename:VK_STRUCTURE_TYPE_RAYTRACING_PIPELINE_CREATE_INFO_NVX - ** ename:VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_CREATE_INFO_NVX - ** ename:VK_STRUCTURE_TYPE_GEOMETRY_INSTANCE_NVX - ** ename:VK_STRUCTURE_TYPE_GEOMETRY_NVX - ** ename:VK_STRUCTURE_TYPE_GEOMETRY_TRIANGLES_NVX - ** ename:VK_STRUCTURE_TYPE_GEOMETRY_AABB_NVX - ** ename:VK_STRUCTURE_TYPE_BIND_ACCELERATION_STRUCTURE_MEMORY_INFO_NVX - ** ename:VK_STRUCTURE_TYPE_DESCRIPTOR_ACCELERATION_STRUCTURE_INFO_NVX - ** ename:VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_INFO_NVX - ** ename:VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_RAYTRACING_PROPERTIES_NVX - * Extending elink:VkShaderStageFlagBits: - ** ename:VK_SHADER_STAGE_RAYGEN_BIT_NVX - ** ename:VK_SHADER_STAGE_ANY_HIT_BIT_NVX - ** ename:VK_SHADER_STAGE_CLOSEST_HIT_BIT_NVX - ** ename:VK_SHADER_STAGE_MISS_BIT_NVX - ** ename:VK_SHADER_STAGE_INTERSECTION_BIT_NVX - ** ename:VK_SHADER_STAGE_CALLABLE_BIT_NVX - * Extending elink:VkPipelineStageFlagBits: - ** ename:VK_PIPELINE_STAGE_RAYTRACING_BIT_NVX - * Extending elink:VkBufferUsageFlagBits: - ** ename:VK_BUFFER_USAGE_RAYTRACING_BIT_NVX - * Extending elink:VkPipelineBindPoint: - ** ename:VK_PIPELINE_BIND_POINT_RAYTRACING_NVX - * Extending elink:VkDescriptorType - ** ename:VK_DESCRIPTOR_TYPE_ACCELERATION_STRUCTURE_NVX - * Extending elink:VkAccessFlagBits - ** ename:VK_ACCESS_ACCELERATION_STRUCTURE_READ_BIT_NVX - ** ename:VK_ACCESS_ACCELERATION_STRUCTURE_WRITE_BIT_NVX - * Extending elink:VkQueryType - ** ename:VK_QUERY_TYPE_COMPACTED_SIZE_NVX - * Extending elink:VkPipelineCreateFlagBits - ** ename:VK_PIPELINE_CREATE_DEFER_COMPILE_BIT_NVX - - -=== New Enums - - ** elink:VkGeometryFlagBitsNVX - ** elink:VkGeometryInstanceFlagBitsNVX (TBD) - ** elink:VkBuildAccelerationStructureFlagBitsNVX - ** elink:VkCopyAccelerationStructureModeNVX - ** elink:VkGeometryTypeNVX - -=== New Structures - - ** slink:VkRaytracingPipelineCreateInfoNVX - ** slink:VkGeometryTrianglesNVX - ** slink:VkGeometryAABBNVX - ** slink:VkGeometryDataNVX - ** slink:VkGeometryNVX - ** slink:VkAccelerationStructureCreateInfoNVX - ** slink:VkBindAccelerationStructureMemoryInfoNVX - ** slink:VkDescriptorAccelerationStructureInfoNVX - ** slink:VkAccelerationStructureMemoryRequirementsInfoNVX - ** slink:VkPhysicalDeviceRaytracingPropertiesNVX - -=== New Functions - - * flink:vkCreateAccelerationStructureNVX - * flink:vkDestroyAccelerationStructureNVX - * flink:vkGetAccelerationStructureMemoryRequirementsNVX - * flink:vkGetAccelerationStructureScratchMemoryRequirementsNVX - * flink:vkBindAccelerationStructureMemoryNVX - * flink:vkCmdBuildAccelerationStructureNVX - * flink:vkCmdCopyAccelerationStructureNVX - * flink:vkCmdTraceRaysNVX - * flink:vkCreateRaytracingPipelinesNVX - * flink:vkGetRaytracingShaderHandlesNVX - * flink:vkGetAccelerationStructureHandleNVX - * flink:vkCmdWriteAccelerationStructurePropertiesNVX - * flink:vkCompileDeferredNVX - -=== New or Modified Built-In Variables - - * <> - * <> - * <> - * <> - * <> - * <> - * <> - * <> - * <> - * <> - * <> - * <> - * <> - * (modified)code:InstanceIndex - * (modified)code:PrimitiveId - -=== New SPIR-V Capabilities - - * <> - -=== Issues - -1) Are there issues? - -*RESOLVED*: Yes. - -=== Sample Code - -Example ray generation GLSL shader - -[source,c] ---------------------------------------------------- -#version 450 core -#extension GL_NVX_raytracing : require -layout(set = 0, binding = 0, rgba8) uniform image2D image; -layout(set = 0, binding = 1) uniform accelerationStructureNVX as; -layout(location = 0) rayPayloadNVX float payload; - -void main() -{ - vec4 col = vec4(0, 0, 0, 1); - - vec3 origin = vec3(float(gl_LaunchIDNVX.x)/float(gl_LaunchSizeNVX.x), float(gl_LaunchIDNVX.y)/float(gl_LaunchSizeNVX.y), 1.0); - vec3 dir = vec3(0.0, 0.0, -1.0); - - traceNVX(as, 0, 0xff, 0, 1, 0, origin, 0.0, dir, 1000.0, 0); - - col.y = payload; - - imageStore(image, ivec2(gl_LaunchIDNVX.xy), col); -} ---------------------------------------------------- - -=== Version History - - * Revision 1, 2018-09-11 (Robert Stepinski, Nuno Subtil, Eric Werness) - - Internal revisions diff --git a/appendices/VK_NV_corner_sampled_image.txt b/appendices/VK_NV_corner_sampled_image.txt index 8cadb639..febfe791 100644 --- a/appendices/VK_NV_corner_sampled_image.txt +++ b/appendices/VK_NV_corner_sampled_image.txt @@ -44,6 +44,8 @@ None. === New Enum Constants + * Extending elink:VkStructureType + ** ename:VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_CORNER_SAMPLED_IMAGE_FEATURES_NV * Extending elink:VkImageCreateFlagBits ** ename:VK_IMAGE_CREATE_CORNER_SAMPLED_BIT_NV diff --git a/appendices/VK_NV_fragment_shader_barycentric.txt b/appendices/VK_NV_fragment_shader_barycentric.txt index cfe9a786..18c78e7e 100644 --- a/appendices/VK_NV_fragment_shader_barycentric.txt +++ b/appendices/VK_NV_fragment_shader_barycentric.txt @@ -46,7 +46,8 @@ None. === New Enum Constants -None. + * Extending elink:VkStructureType + ** ename:VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FRAGMENT_SHADER_BARYCENTRIC_FEATURES_NV === New Enums diff --git a/appendices/VK_NV_framebuffer_mixed_samples.txt b/appendices/VK_NV_framebuffer_mixed_samples.txt index 1c0229c0..abd3e7d0 100644 --- a/appendices/VK_NV_framebuffer_mixed_samples.txt +++ b/appendices/VK_NV_framebuffer_mixed_samples.txt @@ -51,7 +51,8 @@ None. === New Enum Constants -None. + * Extending elink:VkStructureType + ** ename:VK_STRUCTURE_TYPE_PIPELINE_COVERAGE_MODULATION_STATE_CREATE_INFO_NV === New Enums diff --git a/appendices/VK_NV_ray_tracing.txt b/appendices/VK_NV_ray_tracing.txt new file mode 100644 index 00000000..b28a0d1e --- /dev/null +++ b/appendices/VK_NV_ray_tracing.txt @@ -0,0 +1,190 @@ +include::meta/VK_NV_ray_tracing.txt[] + +*Last Modified Date*:: + 2018-09-11 + +*Interactions and External Dependencies*:: + - This extension requires the + https://htmlpreview.github.io/?https://github.com/KhronosGroup/SPIRV-Registry/blob/master/extensions/NV/SPV_NV_ray_tracing.html[+SPV_NV_ray_tracing+] + SPIR-V extension. + - This extension requires the + https://github.com/KhronosGroup/GLSL/blob/master/extensions/nv/GLSL_NV_ray_tracing.txt[+GL_NV_ray_tracing+] + extension for GLSL source languages. + +*Contributors*:: + - Eric Werness, NVIDIA + - Ashwin Lele, NVIDIA + - Robert Stepinski, NVIDIA + - Nuno Subtil, NVIDIA + - Christoph Kubisch, NVIDIA + - Martin Stich, NVIDIA + - Daniel Koch, NVIDIA + - Jeff Bolz, NVIDIA + - Joshua Barczak, Intel + - Tobias Hector, AMD + - Henrik Rydgard, NVIDIA + - Pascal Gautron, NVIDIA + +Rasterization has been the dominant method to produce interactive graphics, +but increasing performance of graphics hardware has made ray tracing a +viable option for interactive rendering. +Being able to integrate ray tracing with traditional rasterization makes it +easier for applications to incrementally add ray traced effects to existing +applications or to do hybrid approaches with rasterization for primary +visibility and ray tracing for secondary queries. + +To enable ray tracing, this extension adds a few different categories of new +functionality: + + * Acceleration structure objects and build commands + * A new pipeline type with new shader domains + * An indirection table to link shader groups with acceleration structure + items + +This extension adds support for the following SPIR-V extension in Vulkan: + + * +SPV_NV_ray_tracing+ + +=== New Object Types + + * slink:VkAccelerationStructureNV + +=== New Enum Constants + + * Extending elink:VkStructureType: + ** ename:VK_STRUCTURE_TYPE_RAY_TRACING_PIPELINE_CREATE_INFO_NV + ** ename:VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_CREATE_INFO_NV + ** ename:VK_STRUCTURE_TYPE_GEOMETRY_NV + ** ename:VK_STRUCTURE_TYPE_GEOMETRY_TRIANGLES_NV + ** ename:VK_STRUCTURE_TYPE_GEOMETRY_AABB_NV + ** ename:VK_STRUCTURE_TYPE_BIND_ACCELERATION_STRUCTURE_MEMORY_INFO_NV + ** ename:VK_STRUCTURE_TYPE_WRITE_DESCRIPTOR_SET_ACCELERATION_STRUCTURE_NV + ** ename:VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_INFO_NV + ** ename:VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_RAY_TRACING_PROPERTIES_NV + ** ename:VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_INFO_NV + ** ename:VK_STRUCTURE_TYPE_RAY_TRACING_SHADER_GROUP_CREATE_INFO_NV + * Extending elink:VkShaderStageFlagBits: + ** ename:VK_SHADER_STAGE_RAYGEN_BIT_NV + ** ename:VK_SHADER_STAGE_ANY_HIT_BIT_NV + ** ename:VK_SHADER_STAGE_CLOSEST_HIT_BIT_NV + ** ename:VK_SHADER_STAGE_MISS_BIT_NV + ** ename:VK_SHADER_STAGE_INTERSECTION_BIT_NV + ** ename:VK_SHADER_STAGE_CALLABLE_BIT_NV + * Extending elink:VkPipelineStageFlagBits: + ** ename:VK_PIPELINE_STAGE_RAY_TRACING_SHADER_BIT_NV + ** ename:VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_NV + * Extending elink:VkBufferUsageFlagBits: + ** ename:VK_BUFFER_USAGE_RAY_TRACING_BIT_NV + * Extending elink:VkPipelineBindPoint: + ** ename:VK_PIPELINE_BIND_POINT_RAY_TRACING_NV + * Extending elink:VkDescriptorType + ** ename:VK_DESCRIPTOR_TYPE_ACCELERATION_STRUCTURE_NV + * Extending elink:VkAccessFlagBits + ** ename:VK_ACCESS_ACCELERATION_STRUCTURE_READ_BIT_NV + ** ename:VK_ACCESS_ACCELERATION_STRUCTURE_WRITE_BIT_NV + * Extending elink:VkQueryType + ** ename:VK_QUERY_TYPE_ACCELERATION_STRUCTURE_COMPACTED_SIZE_NV + * Extending elink:VkPipelineCreateFlagBits + ** ename:VK_PIPELINE_CREATE_DEFER_COMPILE_BIT_NV + + +=== New Enums + + ** elink:VkGeometryFlagBitsNV + ** elink:VkGeometryInstanceFlagBitsNV + ** elink:VkBuildAccelerationStructureFlagBitsNV + ** elink:VkCopyAccelerationStructureModeNV + ** elink:VkGeometryTypeNV + ** elink:VkRayTracingShaderGroupTypeNV + ** elink:VkAccelerationStructureMemoryRequirementsTypeNV + +=== New Structures + + ** slink:VkRayTracingPipelineCreateInfoNV + ** slink:VkGeometryTrianglesNV + ** slink:VkGeometryAABBNV + ** slink:VkGeometryDataNV + ** slink:VkGeometryNV + ** slink:VkAccelerationStructureCreateInfoNV + ** slink:VkBindAccelerationStructureMemoryInfoNV + ** slink:VkWriteDescriptorSetAccelerationStructureNV + ** slink:VkAccelerationStructureMemoryRequirementsInfoNV + ** slink:VkPhysicalDeviceRayTracingPropertiesNV + ** slink:VkRayTracingShaderGroupCreateInfoNV + ** slink:VkAccelerationStructureInfoNV + +=== New Functions + + * flink:vkCreateAccelerationStructureNV + * flink:vkDestroyAccelerationStructureNV + * flink:vkGetAccelerationStructureMemoryRequirementsNV + * flink:vkBindAccelerationStructureMemoryNV + * flink:vkCmdBuildAccelerationStructureNV + * flink:vkCmdCopyAccelerationStructureNV + * flink:vkCmdTraceRaysNV + * flink:vkCreateRayTracingPipelinesNV + * flink:vkGetRayTracingShaderGroupHandlesNV + * flink:vkGetAccelerationStructureHandleNV + * flink:vkCmdWriteAccelerationStructuresPropertiesNV + * flink:vkCompileDeferredNV + +=== New or Modified Built-In Variables + + * <> + * <> + * <> + * <> + * <> + * <> + * <> + * <> + * <> + * <> + * <> + * <> + * <> + * <> + * (modified)code:InstanceIndex + * (modified)code:PrimitiveId + +=== New SPIR-V Capabilities + + * <> + +=== Issues + +1) Are there issues? + +*RESOLVED*: Yes. + +=== Sample Code + +Example ray generation GLSL shader + +[source,c] +--------------------------------------------------- +#version 450 core +#extension GL_NV_ray_tracing : require +layout(set = 0, binding = 0, rgba8) uniform image2D image; +layout(set = 0, binding = 1) uniform accelerationStructureNV as; +layout(location = 0) rayPayloadNV float payload; + +void main() +{ + vec4 col = vec4(0, 0, 0, 1); + + vec3 origin = vec3(float(gl_LaunchIDNV.x)/float(gl_LaunchSizeNV.x), float(gl_LaunchIDNV.y)/float(gl_LaunchSizeNV.y), 1.0); + vec3 dir = vec3(0.0, 0.0, -1.0); + + traceNV(as, 0, 0xff, 0, 1, 0, origin, 0.0, dir, 1000.0, 0); + + col.y = payload; + + imageStore(image, ivec2(gl_LaunchIDNV.xy), col); +} +--------------------------------------------------- + +=== Version History + + * Revision 1, 2018-09-11 (Robert Stepinski, Nuno Subtil, Eric Werness) + - Internal revisions diff --git a/appendices/VK_NV_scissor_exclusive.txt b/appendices/VK_NV_scissor_exclusive.txt index c622d1b7..6fe99942 100644 --- a/appendices/VK_NV_scissor_exclusive.txt +++ b/appendices/VK_NV_scissor_exclusive.txt @@ -27,7 +27,7 @@ None. === New Enum Constants * Extending elink:VkStructureType - ** ename:VK_STRUCTURE_TYPE_PIPELINE_EXCLUSIVE_SCISSOR_STATE_CREATE_INFO_NV + ** ename:VK_STRUCTURE_TYPE_PIPELINE_VIEWPORT_EXCLUSIVE_SCISSOR_STATE_CREATE_INFO_NV ** ename:VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_EXCLUSIVE_SCISSOR_FEATURES_NV * Extending elink:VkDynamicState ** ename:VK_DYNAMIC_STATE_EXCLUSIVE_SCISSOR_NV diff --git a/appendices/VK_NV_shading_rate_image.txt b/appendices/VK_NV_shading_rate_image.txt index 407cf654..4ab69e8f 100644 --- a/appendices/VK_NV_shading_rate_image.txt +++ b/appendices/VK_NV_shading_rate_image.txt @@ -61,6 +61,7 @@ None. ** ename:VK_STRUCTURE_TYPE_PIPELINE_VIEWPORT_SHADING_RATE_IMAGE_STATE_CREATE_INFO_NV ** ename:VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADING_RATE_IMAGE_FEATURES_NV ** ename:VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADING_RATE_IMAGE_PROPERTIES_NV + ** ename:VK_STRUCTURE_TYPE_PIPELINE_VIEWPORT_COARSE_SAMPLE_ORDER_STATE_CREATE_INFO_NV * Extending elink:VkImageLayout: diff --git a/appendices/boilerplate.txt b/appendices/boilerplate.txt index 01353520..aacd6f7a 100644 --- a/appendices/boilerplate.txt +++ b/appendices/boilerplate.txt @@ -336,7 +336,6 @@ preprocessor macros which enable inclusion by `vulkan.h` are shown in the |==== | Extension Name | Window System Name | Platform-specific Header | Required External Headers | Controlling `vulkan.h` Macro | `<>` | Android | `vulkan_android.h` | None | dname:VK_USE_PLATFORM_ANDROID_KHR -| `<>` | Mir | `vulkan_mir.h` | `` | dname:VK_USE_PLATFORM_MIR_KHR | `<>` | Wayland | `vulkan_wayland.h` | `` | dname:VK_USE_PLATFORM_WAYLAND_KHR | `<>`, `<>`, diff --git a/appendices/glossary.txt b/appendices/glossary.txt index b3ce31e3..0332fe78 100644 --- a/appendices/glossary.txt +++ b/appendices/glossary.txt @@ -80,12 +80,12 @@ Availability Operation:: Available:: A state of values written to memory that allows them to be made visible. -ifdef::VK_NVX_raytracing[] +ifdef::VK_NV_ray_tracing[] Axis-aligned Bounding Box:: A box bounding a region in space defined by extents along each axis and thus representing a box where each edge is aligned to one of the major axes. -endif::VK_NVX_raytracing[] +endif::VK_NV_ray_tracing[] Back-Facing:: See Facingness. diff --git a/appendices/spirvenv.txt b/appendices/spirvenv.txt index a0b763c0..6816a70b 100644 --- a/appendices/spirvenv.txt +++ b/appendices/spirvenv.txt @@ -236,10 +236,10 @@ ifdef::VK_NV_mesh_shader[] [[spirvenv-capabilities-table-meshshading]] | code:MeshShadingNV | `<>` endif::VK_NV_mesh_shader[] -ifdef::VK_NVX_raytracing[] +ifdef::VK_NV_ray_tracing[] [[spirvenv-capabilities-table-raytracing]] -| code:RaytracingNVX | `<>` -endif::VK_NVX_raytracing[] +| code:RayTracingNV | `<>` +endif::VK_NV_ray_tracing[] ifdef::VK_EXT_transform_feedback[] | code:TransformFeedback | <> | code:GeometryStreams | <> @@ -400,10 +400,10 @@ The application can: pass a SPIR-V module to flink:vkCreateShaderModule that uses the `SPV_NV_shading_rate` SPIR-V extension. endif::VK_NV_shading_rate_image[] -ifdef::VK_NVX_raytracing[] +ifdef::VK_NV_ray_tracing[] The application can: pass a SPIR-V module to flink:vkCreateShaderModule that -uses the `SPV_NVX_raytracing` SPIR-V extension. -endif::VK_NVX_raytracing[] +uses the `SPV_NV_ray_tracing` SPIR-V extension. +endif::VK_NV_ray_tracing[] ifdef::VK_GOOGLE_hlsl_functionality1[] The application can: pass a SPIR-V module to flink:vkCreateShaderModule that @@ -478,6 +478,14 @@ endif::VK_VERSION_1_1[] ifdef::VK_VERSION_1_1,VK_KHR_storage_buffer_storage_class[] ** *StorageBuffer* endif::VK_VERSION_1_1,VK_KHR_storage_buffer_storage_class[] +ifdef::VK_NV_ray_tracing[] + ** *RayPayloadNV* + ** *IncomingRayPayloadNV* + ** *HitAttributeNV* + ** *CallableDataNV* + ** *IncomingCallableDataNV* + ** *ShaderRecordBufferNV* +endif::VK_NV_ray_tracing[] * Memory semantics must: obey the following rules: ** *Acquire* must: not be used with code:OpAtomicStore. ** *Release* must: not be used with code:OpAtomicLoad. @@ -654,8 +662,8 @@ ifdef::VK_EXT_transform_feedback[] * Output variables or block members decorated with code:Offset that have a 64-bit type, or a composite type containing a 64-bit type, must: specify an code:Offset value aligned to a 8 byte boundary - * Any output block or block member decorated with code:XfbOffset - containing a 64-bit type consumes a multiple of 8 bytes + * Any output block or block member decorated with code:Offset containing a + 64-bit type consumes a multiple of 8 bytes * The size of any output block, that contains any member decorated with code:Offset that is a 64-bit type, must: be a multiple of 8 * The first member of an output block that specifies a code:Offset @@ -697,6 +705,18 @@ ifdef::VK_EXT_transform_feedback[] * The XFB Stride value to code:XfbStride must be less than or equal to sname:VkPhysicalDeviceTransformFeedbackPropertiesEXT::pname:maxTransformFeedbackBufferDataStride endif::VK_EXT_transform_feedback[] +ifdef::VK_NV_ray_tracing[] + * code:RayPayloadNV storage class must: only be used in ray generation, + any hit, closest hit or miss shaders. + * code:IncomingRayPayloadNV storage class must: only be used in closest + hit, any hit, or miss shaders. + * code:HitAttributeNV storage class must: only be used in intersection, + any hit, or closest hit shaders. + * code:CallableDataNV storage class must: only be used in ray generation, + closest hit, mis, and callable shaders. + * code:IncomingCallableDataNV storage class must only be used in callable + shaders. +endif::VK_NV_ray_tracing[] [[spirvenv-precision-operation]] == Precision and Operation of SPIR-V Instructions diff --git a/chapters/VK_KHR_surface/wsi.txt b/chapters/VK_KHR_surface/wsi.txt index af8170d5..53319ed3 100644 --- a/chapters/VK_KHR_surface/wsi.txt +++ b/chapters/VK_KHR_surface/wsi.txt @@ -94,10 +94,6 @@ ifdef::VK_KHR_android_surface[] include::../VK_KHR_android_surface/platformCreateSurface_android.txt[] endif::VK_KHR_android_surface[] -ifdef::VK_KHR_mir_surface[] -include::../VK_KHR_mir_surface/platformCreateSurface_mir.txt[] -endif::VK_KHR_mir_surface[] - ifdef::VK_KHR_wayland_surface[] include::../VK_KHR_wayland_surface/platformCreateSurface_wayland.txt[] endif::VK_KHR_wayland_surface[] @@ -227,10 +223,6 @@ ifdef::VK_KHR_android_surface[] include::../VK_KHR_android_surface/platformQuerySupport_android.txt[] endif::VK_KHR_android_surface[] -ifdef::VK_KHR_mir_surface[] -include::../VK_KHR_mir_surface/platformQuerySupport_mir.txt[] -endif::VK_KHR_mir_surface[] - ifdef::VK_KHR_wayland_surface[] include::../VK_KHR_wayland_surface/platformQuerySupport_wayland.txt[] endif::VK_KHR_wayland_surface[] diff --git a/chapters/VK_NVX_raytracing/raytracing-pipelines.txt b/chapters/VK_NVX_raytracing/raytracing-pipelines.txt deleted file mode 100644 index 88f6c8bc..00000000 --- a/chapters/VK_NVX_raytracing/raytracing-pipelines.txt +++ /dev/null @@ -1,130 +0,0 @@ -// This section is included inside the Pipelines chapter (pipelines.txt) - -[[pipelines-raytracing]] -== Raytracing Pipeline - -Raytracing pipelines consist of multiple shader stages, fixed-function -traversal stages, and a pipeline layout. - -[open,refpage='vkCreateRaytracingPipelinesNVX',desc='Creates a new raytracing pipeline object',type='protos'] --- - -To create raytracing pipelines, call: - -include::../../api/protos/vkCreateRaytracingPipelinesNVX.txt[] - - * pname:device is the logical device that creates the raytracing - pipelines. - * pname:pipelineCache is either dlink:VK_NULL_HANDLE, indicating that - pipeline caching is disabled; or the handle of a valid - <> 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:pPipelines arrays. - * pname:pCreateInfos is an array of - sname:VkRaytracingPipelineCreateInfoNVX structures. - * pname:pAllocator controls host memory allocation as described in the - <> chapter. - * pname:pPipelines is a pointer to an array in which the resulting compute - pipeline objects are returned. - -.Valid Usage -**** -**** - -include::../../validity/protos/vkCreateRaytracingPipelinesNVX.txt[] --- - -[open,refpage='VkRaytracingPipelineCreateInfoNVX',desc='Structure specifying parameters of a newly created raytracing pipeline',type='structs'] --- - -The sname:VkRaytracingPipelineCreateInfoNVX structure is defined as: - -include::../../api/structs/VkRaytracingPipelineCreateInfoNVX.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 bitmask of elink:VkPipelineCreateFlagBits specifying - how the pipeline will be generated. - * pname:stageCount is the number of entries in the pname:pStages and - pname:pGroupNumbers arrays. - * 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 raytracing pipeline. - * pname:pGroupNumbers is an array of size pname:stageCount integers, where - each integer indicates the hit group that the corresponding shader - belongs to. - * pname:maxRecursionDepth is the maximum recursion that will be called - from this pipeline. - * 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. - -The parameters pname:basePipelineHandle and pname:basePipelineIndex are -described in more detail in <>. - -.Valid Usage -**** -**** - -include::../../validity/structs/VkRaytracingPipelineCreateInfoNVX.txt[] --- - -[open,refpage='vkGetRaytracingShaderHandlesNVX',desc='Query raytracing pipeline shader handles',type='protos'] --- - -To query the opaque handles of shaders in the raytracing pipeline, call: - -include::../../api/protos/vkGetRaytracingShaderHandlesNVX.txt[] - - * pname:device is the logical device that contains the raytracing - pipeline. - * pname:pipeline is the raytracing pipeline object that contains the - shaders. - * pname:firstShader is the index of the first shader to retrieve a handle - for from the pname:pStages array of - sname:VkPipelineShaderStageCreateInfo entries. - * pname:shaderCount is the number of shader handles to retrieve. - * pname:dataSize is the size in bytes of the buffer pointed to by pData. - * pname:pData is a pointer to a user-allocated buffer where the results - will be written. - -.Valid Usage -**** -**** - -include::../../validity/protos/vkGetRaytracingShaderHandlesNVX.txt[] --- - -Raytracing pipelines can contain more shaders than a graphics or compute -pipeline, so to allow parallel compilation of shaders within a pipeline, an -application may: choose to defer compilation until a later point in time. - -[open,refpage='vkCompileDeferredNVX',desc='Deferred compilation of shaders',type='protos'] --- - -To compile a deferred shader in a pipeline call: - -include::../../api/protos/vkCompileDeferredNVX.txt[] - - * pname:device is the logical device that contains the raytracing - pipeline. - * pname:pipeline is the raytracing pipeline object that contains the - shaders. - * pname:shader is the index of the shader to compile. - -.Valid Usage -**** - * [[VUID-vkCompileDeferredNVX-pipeline-02237]] - pname:pipeline must: have been created with - VK_PIPELINE_CREATE_DEFER_COMPILE_BIT_NVX. - * [[VUID-vkCompileDeferredNVX-shader-02238]] - pname:shader must: not have been called as a deferred compile before. -**** - -include::../../validity/protos/vkCompileDeferredNVX.txt[] --- - diff --git a/chapters/VK_NVX_raytracing/raytracing-resources.txt b/chapters/VK_NVX_raytracing/raytracing-resources.txt deleted file mode 100644 index 3b7b8f6a..00000000 --- a/chapters/VK_NVX_raytracing/raytracing-resources.txt +++ /dev/null @@ -1,358 +0,0 @@ -// This section is included inside the Resources chapter (resources.txt) - -[[resources-acceleration-structures]] -== Acceleration Structures - -[open,refpage='VkAccelerationStructureNVX',desc='Opaque handle to an acceleration structure object',type='handles'] --- - -Acceleration structures are an opaque structure that can be built by the -implementation to more efficiently perform spatial queries on the provided -geometric data. -For this extension, an acceleration structure is either a top-level -acceleration structure containing a set of bottom-level acceleration -structures or a bottom-level acceleration structure containing either a set -of axis-aligned bounding boxes for custom geometry or a set of triangles. - -Each instance in the top-level acceleration structure contains a reference -to a bottom-level acceleration structure as well as an instance transform -plus information required to index into the shader bindings. -The top-level acceleration structure is what is bound to the acceleration -descriptor to trace inside the shader in the raytracing pipeline. - -Acceleration structures are represented by sname:VkAccelerationStructureNVX -handles: - -include::../../api/handles/VkAccelerationStructureNVX.txt[] - --- - -[open,refpage='vkCreateAccelerationStructureNVX',desc='Create a new acceleration structure object',type='protos'] --- - -To create acceleration structures, call: - -include::../../api/protos/vkCreateAccelerationStructureNVX.txt[] - - * pname:device is the logical device that creates the buffer object. - * pname:pCreateInfo is a pointer to an instance of the - sname:VkAccelerationStructureCreateInfoNVX structure containing - parameters affecting creation of the acceleration structure. - * pname:pAllocator controls host memory allocation as described in the - <> chapter. - * pname:pAccelerationStructure points to a - sname:VkAccelerationStructureNVX handle in which the resulting - acceleration structure object is returned. - -.Valid Usage -**** -**** - -include::../../validity/protos/vkCreateAccelerationStructureNVX.txt[] --- - -[open,refpage='VkAccelerationStructureCreateInfoNVX',desc='Structure specifying the parameters of a newly created acceleration structure object',type='structs'] --- - -The sname:VkAccelerationStructureCreateInfoNVX structure is defined as: - -include::../../api/structs/VkAccelerationStructureCreateInfoNVX.txt[] - - * pname:sType is the type of this structure. - * pname:pNext is `NULL` or a pointer to an extension-specific structure. - * pname:type is a ename:VkAccelerationStructureTypeBitsNVX value that - specifies the type of acceleration structure that will be created. - * pname:flags is a set of ename:VkBuildAccelerationStructureFlagBitsNVX - values that specify additional parameters of the acceleration structure. - * pname:compactedSize is the size from the result of - flink:vkCmdWriteAccelerationStructurePropertiesNVX, if this acceleration - structure is going to be the target of compacting copy. - * pname:instanceCount specifies the number of instances that will be in - the new acceleration structure - * pname:geometryCount specifies the number of geometries that will be in - the new acceleration structure - * pname:pGeometries is an array of ename:VkGeometryNVX structures which - contain the scene data being passed into the acceleration structure. - -.Valid Usage -**** - * [[VUID-VkAccelerationStructureCreateInfoNVX-geometryCount-02239]] - pname:geometryCount must: be less than or equal to - sname:VkPhysicalDeviceRaytracingPropertiesNVX::pname:maxGeometryCount -**** - -include::../../validity/structs/VkAccelerationStructureCreateInfoNVX.txt[] --- - -[open,refpage='VkGeometryNVX',desc='Structure specifying a geometry in a bottom-level acceleration structure',type='structs'] --- - -The sname:VkGeometryNVX structure is defined as: - -include::../../api/structs/VkGeometryNVX.txt[] - - * pname:sType is the type of this structure. - * pname:pNext is `NULL` or a pointer to an extension-specific structure. - * pname:geometryType describes which type of geometry this VkGeometryNVX - refers to. - * pname:geometry contains the geometry data. - * pname:flags has flags describing options for this geometry. - -.Valid Usage -**** -**** - -include::../../validity/structs/VkGeometryNVX.txt[] --- - -[open,refpage='VkGeometryTypeNVX',desc='Enum specifying which type of geometry is provided',type='enums'] --- - -Geometry types are specified by elink:VkGeometryTypeNVX, which takes values: - -include::../../api/enums/VkGeometryTypeNVX.txt[] --- - -[open,refpage='VkGeometryFlagBitsNVX',desc='Bitmask specifying additional parameters for a geometry',type='enums'] --- - -Bits which can: be set in slink:VkGeometryNVX::pname:flags, specifying -additional parameters for acceleration structure builds, are: - -include::../../api/enums/VkGeometryFlagBitsNVX.txt[] - --- - - -[open,refpage='VkGeometryDataNVX',desc='Structure specifying geometry in a bottom-level acceleration structure',type='structs'] --- - -The sname:VkGeometryDataNVX structure is defined as: - -include::../../api/structs/VkGeometryDataNVX.txt[] - - * pname:triangles contains triangle data if pname:geometryType is - ename:VK_GEOMETRY_TYPE_TRIANGLES_NVX. - * pname:aabbs contains axis-aligned bounding box data if - pname:geometryType is ename:VK_GEOMETRY_TYPE_AABBS_NVX. - -.Valid Usage -**** -**** - -include::../../validity/structs/VkGeometryDataNVX.txt[] --- - -[open,refpage='VkGeometryTrianglesNVX',desc='Structure specifying a triangle geometry in a bottom-level acceleration structure',type='structs'] --- - -The sname:VkGeometryTrianglesNVX structure is defined as: - -include::../../api/structs/VkGeometryTrianglesNVX.txt[] - - * pname:sType is the type of this structure. - * pname:pNext is `NULL` or a pointer to an extension-specific structure. - * pname:vertexData is the buffer containing vertex data. - * pname:vertexOffset is the offset within pname:vertexData containing - vertex data. - * pname:vertexCount is the number of valid vertices. - * pname:vertexStride is the stride in bytes between each vertex. - * pname:vertexFormat is the format of each vertex element. - * pname:indexData is the buffer containing index data. - * pname:indexOffset is the offset within pname:indexData containing index - data. - * pname:indexCount is the number of indices to include in this geometry. - * pname:indexType is the format of each index. - * pname:transformData is a buffer containing optional reference to an - array of floats representing a 3x4 row major affine transformation - matrix. - * pname:transformOffset is the offset in pname:transformData - -.Valid Usage -**** -**** - -include::../../validity/structs/VkGeometryTrianglesNVX.txt[] --- - -[open,refpage='VkGeometryAABBNVX',desc='Structure specifying axis-aligned bounding box geometry in a bottom-level acceleration structure',type='structs'] --- - -The sname:VkGeometryAABBNVX structure is defined as: - -include::../../api/structs/VkGeometryAABBNVX.txt[] - - * pname:sType is the type of this structure. - * pname:pNext is `NULL` or a pointer to an extension-specific structure. - * pname:aabbData is the buffer containing axis-aligned bounding box data - * pname:numAABBs is the number of AABBs in this geometry. - * pname:stride is the stride in bytes between AABBs in pname:aabbData. - * pname:offset is the offset in bytes of the first AABB in pname:aabbData. - -.Valid Usage -**** -**** - -include::../../validity/structs/VkGeometryAABBNVX.txt[] --- - - -[open,refpage='vkDestroyAccelerationStructureNVX',desc='Destroy an acceleration structure object',type='protos'] --- - -To destroy an acceleration structure, call: - -include::../../api/protos/vkDestroyAccelerationStructureNVX.txt[] - - * pname:device is the logical device that destroys the buffer. - * pname:accelerationStructure is the acceleration structure to destroy. - * pname:pAllocator controls host memory allocation as described in the - <> chapter. - -.Valid Usage -**** -**** - -include::../../validity/protos/vkDestroyAccelerationStructureNVX.txt[] --- - -[open,refpage='vkGetAccelerationStructureMemoryRequirementsNVX',desc='Get acceleration structure memory requirements',type='protos'] --- - -An acceleration structure has both its own memory use and the scratch memory -use required when building it. - -To query the basic memory requirements call: - -include::../../api/protos/vkGetAccelerationStructureMemoryRequirementsNVX.txt[] - - * pname:device is the logical device on which the acceleration structure - was created. - * pname:pInfo specifies the acceleration structure to get memory - requirements for. - * pname:pMemoryRequirements returns the memory requirements. - -.Valid Usage -**** -**** - -include::../../validity/protos/vkGetAccelerationStructureMemoryRequirementsNVX.txt[] --- - -[open,refpage='vkGetAccelerationStructureScratchMemoryRequirementsNVX',desc='Get acceleration structure scratch memory requirements',type='protos'] --- - -To query the scratch memory requirements call: - -include::../../api/protos/vkGetAccelerationStructureScratchMemoryRequirementsNVX.txt[] - - * pname:device is the logical device on which the acceleration structure - was created. - * pname:pInfo specifies the acceleration structure to get scratch memory - requirements for. - * pname:pMemoryRequirements returns the memory requirements. - -.Valid Usage -**** -**** - -include::../../validity/protos/vkGetAccelerationStructureScratchMemoryRequirementsNVX.txt[] --- - -[open,refpage='VkAccelerationStructureMemoryRequirementsInfoNVX',desc='Structure specifying acceleration to query for memory requirements',type='structs'] --- -The sname:VkAccelerationStructureMemoryRequirementsInfoNVX structure is -defined as: - -include::../../api/structs/VkAccelerationStructureMemoryRequirementsInfoNVX.txt[] - - * pname:sType is the type of this structure. - * pname:pNext is `NULL` or a pointer to an extension-specific structure. - * pname:accelerationStructure is the acceleration structure to be queried - for memory requirements. - -.Valid Usage -**** -**** - -include::../../validity/structs/VkAccelerationStructureMemoryRequirementsInfoNVX.txt[] --- - - -[open,refpage='vkBindAccelerationStructureMemoryNVX',desc='Bind acceleration structure memory',type='protos'] --- - -To attach memory to one or more acceleration structures at a time, call: - -include::../../api/protos/vkBindAccelerationStructureMemoryNVX.txt[] - - * pname:device is the logical device that owns the acceleration structures - and memory. - * pname:bindInfoCount is the number of elements in pBindInfos. - * pname:pBindInfos is a pointer to an array of structures of type - slink:VkBindAccelerationStructureMemoryInfoNVX, describing images and - memory to bind. - -.Valid Usage -**** -**** - -include::../../validity/protos/vkBindAccelerationStructureMemoryNVX.txt[] --- - -[open,refpage='VkBindAccelerationStructureMemoryInfoNVX',desc='Structure specifying acceleration structure memory binding',type='structs'] --- -The sname:VkBindAccelerationStructureMemoryInfoNVX structure is defined as: - -include::../../api/structs/VkBindAccelerationStructureMemoryInfoNVX.txt[] - - * pname:sType is the type of this structure. - * pname:pNext is `NULL` or a pointer to an extension-specific structure. - * pname:accelerationStructure is the acceleration structure to be attached - to memory. - * pname:memory is a VkDeviceMemory object describing the device memory to - attach. - * pname:memoryOffset is the start offset of the region of memory which is - to be bound to the acceleration structure. - The number of bytes returned in the slink:VkMemoryRequirements::size - member in memory, starting from pname:memoryOffset bytes, will be bound - to the specified acceleration structure. - * pname:deviceIndexCount is the number of elements in - pname:pDeviceIndices. - * pname:pDeviceIndices is a pointer to an array of device indices. - -.Valid Usage -**** -**** - -include::../../validity/structs/VkBindAccelerationStructureMemoryInfoNVX.txt[] --- - - -[open,refpage='vkGetAccelerationStructureHandleNVX',desc='Get opaque acceleration structure handle',type='protos'] --- - -To allow constructing geometry instances with device code if desired, we -need to be able to query a opaque handle for an acceleration structure. -This handle is a value of 8 bytes. -To get this handle, call: - -include::../../api/protos/vkGetAccelerationStructureHandleNVX.txt[] - - * pname:device is the logical device that owns the acceleration - structures. - * pname:accelerationStructure is the acceleration structur. - * 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 - -.Valid Usage -**** - * [[VUID-vkGetAccelerationStructureHandleNVX-dataSize-02240]] - pname:dataSize must: be large enough to contain the result of the query, - as described above -**** - -include::../../validity/protos/vkGetAccelerationStructureHandleNVX.txt[] --- diff --git a/chapters/VK_NVX_raytracing/raytracing.txt b/chapters/VK_NVX_raytracing/raytracing.txt deleted file mode 100644 index 270c42bd..00000000 --- a/chapters/VK_NVX_raytracing/raytracing.txt +++ /dev/null @@ -1,391 +0,0 @@ -[[raytracing]] -= Raytracing - -Unlike draw commands which use rasterization, ray tracing is a rendering -method which generates an image by tracing the path of rays which have a -single origin and using shaders to determine the final colour of an image -plane. - -Raytracing uses a separate rendering pipeline from both the graphics and -compute pipelines (see <>). -It has a unique set of programmable and fixed function stages. - -[[fig-raypipe]] -image::images/raypipe.svg[align="center",title="Raytracing Pipeline",{fullimagewidth}] - -.Caption -**** -Interaction between the different shader stages in the raytracing pipeline -**** - -[[raytracing-properties]] -== Raytracing Properties - -[open,refpage='VkPhysicalDeviceRaytracingPropertiesNVX',desc='Properties of the physical device for raytracing',type='structs'] --- -The sname:VkPhysicalDeviceRaytracingPropertiesNVX structure is defined as: - -include::../../api/structs/VkPhysicalDeviceRaytracingPropertiesNVX.txt[] - - * pname:sType is the type of this structure. - * pname:pNext is `NULL` or a pointer to an extension-specific structure. - * pname:shaderHeaderSize size in bytes of the shader header. - * pname:maxRecursionDepth is the maximum number of levels of recursion - allowed in a trace command. - * pname:maxGeometryCount is the maximum number of geometries in the bottom - level acceleration structure. - -.Valid Usage -**** -**** - -include::../../validity/structs/VkPhysicalDeviceRaytracingPropertiesNVX.txt[] --- - - -[[raytracing-commands]] -== Raytracing Commands -_Raytracing commands_ provoke work in the raytacing pipeline. -Raytracing commands are recorded into a command buffer and when executed by -a queue will produce work which executes according to the currently bound -raytracing pipeline. -A raytracing pipeline must: be bound to a command buffer before any -raytracing commands are recorded in that command buffer. - -Each raytracing call operates on a set of shader stages that are specific to -the raytracing pipeline as well as a set of sname:VkAccelerationStructure -objects which describe the scene geometry in an implementation-specific way. -The relationship between the raytracing pipeline object and the acceleration -structures is passed into the raytacing command in a sname:VkBuffer object -known as a _shader binding table_. - -During execution, control alternates between scheduling and other -operations. -The scheduling functionality is implementation-specific and is responsible -for workload execution. -The shader stages are programmable. -_Traversal_, which refers to the process of traversing acceleration -structures to find potential intersections of rays with geometry, is fixed -function. - -The programmable portions of the pipeline are exposed in a single-ray -programming model. -Each GPU thread handles one ray at a time. -Memory operations can be synchronized using standard memory barriers. -However, communication and synchronization between threads is not allowed. -In particular, the use of compute pipeline synchronization functions is not -supported in the raytracing pipeline. - -[open,refpage='vkCmdTraceRaysNVX',desc='Initialize a raytracing dispatch',type='protos'] --- - -To dispatch a raytracing call use: - -include::../../api/protos/vkCmdTraceRaysNVX.txt[] - - * pname:cmdBuf is the command buffer into which the command will be - recorded. - * pname:raygenShaderBindingTableBuffer is the buffer object that holds the - shader binding table data for the ray generation shader stage. - * pname:raygenShaderBindingOffset is the offset (relative to - pname:raygenShaderBindingTableBuffer) of the ray generation shader being - used for the trace. - * pname:missShaderBindingTableBuffer is the buffer object that holds the - shader binding table data for the miss shader stage. - * pname:missShaderBindingOffset is the offset (relative to - pname:missShaderBindingTableBuffer) of the miss shader being used for - the trace. - * pname:missShaderBindingStride is the size of each shader binding table - record in pname:missShaderBindingTableBuffer - * pname:hitShaderBindingTableBuffer is the buffer object that holds the - shader binding table data for the hit shader stages. - * pname:hitShaderBindingOffset is the offset (relative to - pname:hitShaderBindingTableBuffer) of the hit shader group being used - for the trace. - * pname:hitShaderBindingStride is the size of each shader binding table - record in pname:hitShaderBindingTableBuffer - * pname:width is the width of the ray trace query dimensions. - * pname:height is height of the ray trace query dimensions. - -When the command is executed, a ray query of [eq]#pname:width {times} -pname:height# rays is assembled. - -.Valid Usage -**** -**** - -include::../../validity/protos/vkCmdTraceRaysNVX.txt[] --- - -[[shader-binding-table]] -== Shader Binding Table - -A _shader binding table_ is a resource which establishes the relationship -between the raytracing pipeline and the acceleration structures that were -built for the ray tracing query. -It indicates the shaders that operate on each geometry in an acceleration -structure. -In addition, it contains the resources accessed by each shader, including -textures and constants. -The application allocates and manages _shader binding tables_ as -elink:VkBuffer objects. - -The shader binding tables to use in a ray tracing query are passed to -fname:VkCmdTraceRaysNVX. -Shader binding tables are read-only in shaders that are executing on the ray -tracing pipeline. - -[[shader-binding-table-indexing-rules]] -=== Indexing Rules - -In order to execute the correct shaders and access the correct resources -during a ray tracing dispatch, the implementation must be able to locate -shader binding table entries at various stages of execution. -This is accomplished by defining a set of indexing rules that compute shader -binding table record positions relative to the buffer's base address in -memory. -The application must: organize the contents of the shader binding table's -memory in a way that application of the indexing rules will lead to correct -records. - -==== Ray Generation Shaders -Only one ray generation shader is executed per ray tracing dispatch. -Its location is passed into fname:vkCmdTraceRaysNVX using the -pname:raygenShaderBindingTableBuffer and -pname:raygenShaderBindingTableOffset parameters. - -The rule to compute a ray generation shader binding table record index is: - - :: [eq]#pname:raygenShaderBindingTableIndex# - -==== Hit Shaders -The base for the computation of intersection, any hit and closest hit shader -locations is the pname:instanceShaderBindingTableRecordOffset value stored -with each instance of a top-level acceleration structure (see -elink:VkInstanceNVX). -This value determines the beginning of the shader binding table records for -a given instance. -Each geometry in the instance must: have at least one hit program record. - -In the following rule, _geometryIndex_ refers to the location of the -geometry within the instance. - -The pname:sbtRecordStride and pname:sbtRecordOffset values are passed in as -parameters to fname:traceNVX() calls made in the shaders. -See Section 8.19 (Raytracing Functions) of the OpenGL Shading Language -Specification for more details. - -The result of this computation is then added to -pname:hitProgramShaderBindingTableBaseIndex, a base index passed to -fname:vkCmdTraceRaysNVX. - -The complete rule to compute a hit shader binding table record index is: - - :: [eq]#instanceShaderBindingTableRecordOffset {plus} - hitProgramShaderBindingTableBaseIndex {plus} geometryIndex {times} - sbtRecordStride {plus} sbtRecordOffset# - -==== Miss Shaders -A Miss shader is executed whenever a ray query fails to find an intersection -for the given scene geometry. -Multiple miss shaders can be executed throughout a ray tracing dispatch. - -The base for the computation of miss shader locations is -pname:missProgramShaderBindingTableBaseIndex, a base index passed into -fname:vkCmdTraceRaysNVX. - -The pname:sbtRecordOffset value is passed in as parameters to -fname:traceNVX() calls made in the shaders. -See Section 8.19 (Raytracing Functions) of the OpenGL Shading Language -Specification for more details. - -The complete rule to compute a miss shader binding table record index is: - - :: [eq]#missProgramShaderBindingTableBaseIndex {plus} sbtRecordOffset# - -[[acceleration-structure]] -== Acceleration Structures -_Acceleration structures_ are data structures used by the implementation to -efficiently manage the scene geometry as it is traversed during a ray -tracing query. -The application is responsible for managing acceleration structure objects -(see <>, -including allocation, destruction, executing builds or updates, and -synchronizing resources used uring ray tracing queries. - -There are two types of acceleration structures, _top level acceleration -structures_ and _bottom level acceleration structures_. - -[[fig-accelstruct]] -image::images/accelstruct.svg[align="center",title="Acceleration Structure",{fullimagewidth}] - -.Caption -**** -The diagram shows the relationship between top and bottom level acceleration -structures. -**** - -[[acceleration-structure-instance]] -=== Instances -_Instances_ are found in top level acceleration structures and contain data -that refer to a single bottom-level acceleration structure, a transform -matrix, and shading information. -Multiple instances may point to a single bottom level acceleration -structure. - -[[acceleration-structure-geometry]] -=== Geometry -_Geometries_ refer to a triangle or axis-aligned bounding box. - -[[acceleration-structure-top-level]] -=== Top Level Acceleration Structures -Opaque acceleration structure for an array of instances. -The descriptor referencing this is the starting point for tracing - -[[acceleration-structure-bottom-level]] -=== Bottom Level Acceleration Structures -Opaque acceleration structure for an array of geometries. - -[[acceleration-structure-building]] -=== Building Acceleration Structures -[open,refpage='vkCmdBuildAccelerationStructureNVX',desc='Build an acceleration structure',type='protos'] --- - -To build an acceleration structure call: - -include::../../api/protos/vkCmdBuildAccelerationStructureNVX.txt[] - - * pname:cmdBuf is the command buffer into which the command will be - recorded - * pname:type is the type of acceleration structure that is being built - * pname:instanceCount is the number of instances in the acceleration - structure. - This parameter must: be 0 for bottom level acceleration structures. - * pname:instanceData is the buffer containing instance data that will be - used to build the acceleration structure. - This parameter must: be NULL for bottom level acceleration structures. - * pname:instanceOffset is the offset (relative to the start of - pname:instanceData) at which the instance data is located. - * pname:geometryCount is the number of geometries in the acceleration - structure. - This parameter must: be 0 for top level acceleration structures. - * pname:pGeometries is a pointer to an array of geometries used by bottom - level acceleration structures. - This parameter must: be NULL for top level acceleration structures. - * pname:flags is a ename:vkBuildAccelerationStructureFlagBitsNVX value - that specifies additional parameters for the acceleration structure - build. - * pname:update specifies whether to update the pname:dst acceleration - structure with the data in pname:src. - * pname:dst points to the target acceleration structure for the build. - * pname:src points to an existing acceleration structure that can be used - to update the pname:dst acceleration structure. - * pname:scratch is the sname:VkBuffer that will be used as scratch memory - for the build. - * pname:scratchOffset is the offset relative to the start of pname:scratch - that will be used as scratch memory - -.Valid Usage -**** - * [[VUID-vkCmdBuildAccelerationStructureNVX-geometryCount-02241]] - pname:geometryCount must: be less than or equal to - sname:VkPhysicalDeviceRaytracingPropertiesNVX::pname:maxGeometryCount -**** - -include::../../validity/protos/vkCmdBuildAccelerationStructureNVX.txt[] --- - -[open,refpage='VkBuildAccelerationStructureFlagBitsNVX',desc='Bitmask specifying additional parameters for acceleration structure builds',type='enums'] --- - -Bits which can: be set in -slink:vkBuildAccelerationStructureFlagBitsNVX::pname:flags, specifying -additional parameters for acceleration structure builds, are: - -include::../../api/enums/VkBuildAccelerationStructureFlagBitsNVX.txt[] - --- - -[[acceleration-structure-copying]] -=== Copying Acceleration Structures - -An additional command exists for copying acceleration structures without -updating their contents. -The acceleration structure object may: be compacted in order to improve -performance. -Before copying, an application must: query the size of the resulting -acceleration structure. - -[open,refpage='vkCmdWriteAccelerationStructurePropertiesNVX',desc='Write acceleration structure result parameters to query results.',type='protos'] --- - -To query acceleration structure size parameters call: - -include::../../api/protos/vkCmdWriteAccelerationStructurePropertiesNVX.txt[] - - * pname:cmdBuf is the command buffer into which the command will be - recorded. - * pname:accelerationStructure points to an existing acceleration structure - which has been built. - * pname:queryType is a elink:VkQueryType value specifying the type of - queries managed by the pool. - * 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. - -.Valid Usage -**** - * [[VUID-vkCmdWriteAccelerationStructurePropertiesNVX-queryType-02242]] - pname:queryType must: be VK_QUERY_TYPE_COMPACTED_SIZE_NVX -**** - -include::../../validity/protos/vkCmdWriteAccelerationStructurePropertiesNVX.txt[] - --- - - -[open,refpage='vkCmdCopyAccelerationStructureNVX',desc='Copy an acceleration structure',type='protos'] --- - -To copy an acceleration structure call: - -include::../../api/protos/vkCmdCopyAccelerationStructureNVX.txt[] - - * pname:cmdBuf is the command buffer into which the command will be - recorded. - * pname:dst points to the target acceleration structure for the build - * pname:src points to an existing acceleration structure that can be used - to update the pname:dst acceleration structure - * pname:mode is a ename:VkCopyAccelerationStructureModeNVX value that - specifies additional operations to perform during the copy. - -.Valid Usage -**** -**** - -include::../../validity/protos/vkCmdCopyAccelerationStructureNVX.txt[] - --- - -[open,refpage='VkCopyAccelerationStructureModeNVX',desc='Acceleration structure copy mode',type='enums'] --- - -Possible values of slink:vkCmdCopyAccelerationStructureNVX::pname:mode, -specifying additional operations to perform during the copy, are: - -include::../../api/enums/VkCopyAccelerationStructureModeNVX.txt[] - - * ename:VK_COPY_ACCELERATION_STRUCTURE_MODE_CLONE_NVX creates a direct - copy of the acceleration structure specified in pname:src into the one - specified by pname:dst. - The pname:dst acceleration structure must: have been created with the - same parameters as pname:src. - * ename:VK_COPY_ACCELERATION_STRUCTURE_MODE_COMPACT_NVX creates a more - compact version of an acceleration structure pname:src into pname:dst. - The acceleration structure pname:dst must: have been created with a - pname:compactedSize corresponding to the one returned by - slink:vkCmdWriteAccelerationStructurePropertiesNVX after the build of - the acceleration structure specified by pname:src. - --- diff --git a/chapters/VK_NVX_raytracing/raytracing-descriptors.txt b/chapters/VK_NV_ray_tracing/raytracing-descriptors.txt similarity index 55% rename from chapters/VK_NVX_raytracing/raytracing-descriptors.txt rename to chapters/VK_NV_ray_tracing/raytracing-descriptors.txt index b84f63c4..9a6fa43f 100644 --- a/chapters/VK_NVX_raytracing/raytracing-descriptors.txt +++ b/chapters/VK_NV_ray_tracing/raytracing-descriptors.txt @@ -4,16 +4,17 @@ === Acceleration Structure An _acceleration structure_ -(ename:VK_DESCRIPTOR_TYPE_ACCELERATION_STRUCTURE_NVX) is a descriptor type -that is used to retrieve scene geometry from within shaders bound to -raytracing pipelines. +(ename:VK_DESCRIPTOR_TYPE_ACCELERATION_STRUCTURE_NV) is a descriptor type +that is used to retrieve scene geometry from within shaders bound to ray +tracing pipelines. Shaders have read-only access to the memory. -[open,refpage='VkDescriptorAccelerationStructureInfoNVX',desc='Structure specifying acceleration to query for memory requirements',type='structs'] +[open,refpage='VkWriteDescriptorSetAccelerationStructureNV',desc='Structure specifying acceleration to query for memory requirements',type='structs'] -- -The sname:VkDescriptorAccelerationStructureInfoNVX structure is defined as: +The sname:VkWriteDescriptorSetAccelerationStructureNV structure is defined +as: -include::../../api/structs/VkDescriptorAccelerationStructureInfoNVX.txt[] +include::../../api/structs/VkWriteDescriptorSetAccelerationStructureNV.txt[] * pname:sType is the type of this structure. * pname:pNext is `NULL` or a pointer to an extension-specific structure. @@ -23,10 +24,10 @@ include::../../api/structs/VkDescriptorAccelerationStructureInfoNVX.txt[] .Valid Usage **** - * [[VUID-VkDescriptorAccelerationStructureInfoNVX-accelerationStructureCount-02236]] + * [[VUID-VkWriteDescriptorSetAccelerationStructureNV-accelerationStructureCount-02236]] pname:accelerationStructureCount must: be equal to descriptorCount in the extended structure. **** -include::../../validity/structs/VkDescriptorAccelerationStructureInfoNVX.txt[] +include::../../validity/structs/VkWriteDescriptorSetAccelerationStructureNV.txt[] -- diff --git a/chapters/VK_NV_ray_tracing/raytracing-pipelines.txt b/chapters/VK_NV_ray_tracing/raytracing-pipelines.txt new file mode 100644 index 00000000..66842846 --- /dev/null +++ b/chapters/VK_NV_ray_tracing/raytracing-pipelines.txt @@ -0,0 +1,283 @@ +// This section is included inside the Pipelines chapter (pipelines.txt) + +[[pipelines-raytracing]] +== Ray Tracing Pipeline + +Ray tracing pipelines consist of multiple shader stages, fixed-function +traversal stages, and a pipeline layout. + +[open,refpage='vkCreateRayTracingPipelinesNV',desc='Creates a new ray tracing pipeline object',type='protos'] +-- + +To create ray tracing pipelines, call: + +include::../../api/protos/vkCreateRayTracingPipelinesNV.txt[] + + * pname:device is the logical device that creates the ray tracing + pipelines. + * pname:pipelineCache is either dlink:VK_NULL_HANDLE, indicating that + pipeline caching is disabled; or the handle of a valid + <> 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:pPipelines arrays. + * pname:pCreateInfos is an array of sname:VkRayTracingPipelineCreateInfoNV + structures. + * pname:pAllocator controls host memory allocation as described in the + <> chapter. + * pname:pPipelines is a pointer to an array in which the resulting compute + pipeline objects are returned. + +.Valid Usage +**** + * [[VUID-vkCreateRayTracingPipelinesNV-flags-02402]] + If the pname:flags member of any element of pname:pCreateInfos contains + the ename:VK_PIPELINE_CREATE_DERIVATIVE_BIT flag, and the + pname:basePipelineIndex member of that same element is not `-1`, + pname:basePipelineIndex must: be less than the index into + pname:pCreateInfos that corresponds to that element + * [[VUID-vkCreateRayTracingPipelinesNV-flags-02403]] + If the pname:flags member of any element of pname:pCreateInfos contains + the ename:VK_PIPELINE_CREATE_DERIVATIVE_BIT flag, the base pipeline + must: have been created with the + ename:VK_PIPELINE_CREATE_ALLOW_DERIVATIVES_BIT flag set +**** + +include::../../validity/protos/vkCreateRayTracingPipelinesNV.txt[] +-- + +[open,refpage='VkRayTracingPipelineCreateInfoNV',desc='Structure specifying parameters of a newly created ray tracing pipeline',type='structs'] +-- + +The sname:VkRayTracingPipelineCreateInfoNV structure is defined as: + +include::../../api/structs/VkRayTracingPipelineCreateInfoNV.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 bitmask of elink:VkPipelineCreateFlagBits specifying + how the pipeline will be generated. + * 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 ray tracing pipeline. + * pname:groupCount is the number of entries in the pname:pGroups array. + * pname:pGroups is an array of size pname:groupCount structures of type + slink:VkRayTracingShaderGroupCreateInfoNV describing the set of the + shader stages to be included in each shader group in the ray tracing + pipeline. + * pname:maxRecursionDepth is the maximum recursion that will be called + from this pipeline. + * 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. + +The parameters pname:basePipelineHandle and pname:basePipelineIndex are +described in more detail in <>. + +.Valid Usage +**** + * [[VUID-VkRayTracingPipelineCreateInfoNV-flags-02404]] + If pname:flags contains the ename:VK_PIPELINE_CREATE_DERIVATIVE_BIT + flag, and pname:basePipelineIndex is -1, pname:basePipelineHandle must: + be a valid handle to a ray tracing sname:VkPipeline + * [[VUID-VkRayTracingPipelineCreateInfoNV-flags-02405]] + If pname:flags contains the ename:VK_PIPELINE_CREATE_DERIVATIVE_BIT + flag, and pname:basePipelineHandle is dlink:VK_NULL_HANDLE, + pname:basePipelineIndex must: be a valid index into the calling + command's pname:pCreateInfos parameter + * [[VUID-VkRayTracingPipelineCreateInfoNV-flags-02406]] + If pname:flags contains the ename:VK_PIPELINE_CREATE_DERIVATIVE_BIT + flag, and pname:basePipelineIndex is not -1, pname:basePipelineHandle + must: be dlink:VK_NULL_HANDLE + * [[VUID-VkRayTracingPipelineCreateInfoNV-flags-02407]] + If pname:flags contains the ename:VK_PIPELINE_CREATE_DERIVATIVE_BIT + flag, and pname:basePipelineHandle is not dlink:VK_NULL_HANDLE, + pname:basePipelineIndex must: be -1 + * [[VUID-VkRayTracingPipelineCreateInfoNV-stage-02408]] + The pname:stage member of one element of pname:pStages must: be + ename:VK_SHADER_STAGE_RAYGEN_BIT_NV + * [[VUID-VkRayTracingPipelineCreateInfoNV-pStages-02409]] + The shader code for the entry points identified by pname:pStages, and + the rest of the state identified by this structure must: adhere to the + pipeline linking rules described in the <> + chapter + * [[VUID-VkRayTracingPipelineCreateInfoNV-layout-02410]] + pname:layout must: be + <> with all + shaders specified in pname:pStages + * [[VUID-VkRayTracingPipelineCreateInfoNV-layout-02411]] + The number of resources in pname:layout accessible to each shader stage + that is used by the pipeline must: be less than or equal to + sname:VkPhysicalDeviceLimits::pname:maxPerStageResources + * [[VUID-VkRayTracingPipelineCreateInfoNV-maxRecursionDepth-02412]] + pname:maxRecursionDepth must: be less than or equal to + VkPhysicalDeviceRayTracingPropertiesNV::pname:maxRecursionDepth +**** + +include::../../validity/structs/VkRayTracingPipelineCreateInfoNV.txt[] +-- + +[open,refpage='VkRayTracingShaderGroupCreateInfoNV',desc='Structure specifying shaders in a shader group',type='structs'] +-- + +The sname:VkRayTracingShaderGroupCreateInfoNV structure is defined as: + +include::../../api/structs/VkRayTracingShaderGroupCreateInfoNV.txt[] + + * pname:sType is the type of this structure. + * pname:pNext is `NULL` or a pointer to an extension-specific structure. + * pname:type is the type of hit group specified in this structure. + * pname:generalShader is the index of the ray generation, miss, or + callable shader from + sname:VkRayTracingPipelineCreateInfoNV::pname:pStages in the group if + the shader group has pname:type of + ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_GENERAL_NV and + ename:VK_SHADER_UNUSED_NV otherwise. + * pname:closestHitShader is the optional index of the closest hit shader + from sname:VkRayTracingPipelineCreateInfoNV::pname:pStages in the group + if the shader group has pname:type of + ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_TRIANGLES_HIT_GROUP_NV or + ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_NV and + ename:VK_SHADER_UNUSED_NV otherwise. + * pname:anyHitShader is the optional index of the any hit shader from + sname:VkRayTracingPipelineCreateInfoNV::pname:pStages in the group if + the shader group has pname:type of + ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_TRIANGLES_HIT_GROUP_NV or + ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_NV and + ename:VK_SHADER_UNUSED_NV otherwise. + * pname:intersectionShader is the index of the intersection shader from + sname:VkRayTracingPipelineCreateInfoNV::pname:pStages in the group if + the shader group has pname:type of + ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_NV and + ename:VK_SHADER_UNUSED_NV otherwise. + +.Valid Usage +**** + * [[VUID-VkRayTracingShaderGroupCreateInfoNV-type-02413]] + If pname:type is ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_GENERAL_NV then + pname:generalShader must: be a valid index into pname:pStages referring + to a shader of ename:VK_SHADER_STAGE_RAYGEN_BIT_NV, + ename:VK_SHADER_STAGE_MISS_BIT_NV, or + ename:VK_SHADER_STAGE_CALLABLE_BIT_NV. + * [[VUID-VkRayTracingShaderGroupCreateInfoNV-type-02414]] + If pname:type is ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_GENERAL_NV then + pname:closestHitShader, pname:anyHitShader, and pname:intersectionShader + must: be ename:VK_SHADER_UNUSED_NV. + * [[VUID-VkRayTracingShaderGroupCreateInfoNV-type-02415]] + If pname:type is + ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_NV then + pname:intersectionShader must: be a valid index into pname:pStages + referring to a shader of ename:VK_SHADER_STAGE_INTERSECTION_BIT_NV. + * [[VUID-VkRayTracingShaderGroupCreateInfoNV-type-02416]] + If pname:type is + ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_TRIANGLES_HIT_GROUP_NV then + pname:intersectionShader must: be ename:VK_SHADER_UNUSED_NV. + * [[VUID-VkRayTracingShaderGroupCreateInfoNV-closestHitShader-02417]] + pname:closestHitShader must: be either ename:VK_SHADER_UNUSED_NV or a + valid index into pname:pStages referring to a shader of + ename:VK_SHADER_STAGE_CLOSEST_HIT_BIT_NV. + * [[VUID-VkRayTracingShaderGroupCreateInfoNV-anyHitShader-02418]] + pname:anyHitShader must: be either ename:VK_SHADER_UNUSED_NV or a valid + index into pname:pStages referring to a shader of + ename:VK_SHADER_STAGE_ANY_HIT_BIT_NV. +**** + +include::../../validity/structs/VkRayTracingShaderGroupCreateInfoNV.txt[] +-- + + +[open,refpage='VkRayTracingShaderGroupTypeNV',desc='Shader group types',type='enums'] +-- + +Possible values of pname:type in sname:VkRayTracingShaderGroupCreateInfoNV +are:, + +include::../../api/enums/VkRayTracingShaderGroupTypeNV.txt[] + + * ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_GENERAL_NV indicates a shader + group with a single ename:VK_SHADER_STAGE_RAYGEN_BIT_NV, + ename:VK_SHADER_STAGE_MISS_BIT_NV, or + ename:VK_SHADER_STAGE_CALLABLE_BIT_NV shader in it + * ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_TRIANGLES_HIT_GROUP_NV specifies + a shader group that only hits triangles and must: not contain an + intersection shader, only closest hit and any hit. + * ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_NV specifies + a shader group that only intersects with custom geometry and must: + contain an intersection shader and may: contain closest hit and any hit + shaders. + +[NOTE] +.Note +==== +For current group types, the hit group type could be inferred from the +presence or absence of the intersection shader, but we provide the type +explicitly for future hit groups that don't have that property. +==== + +-- + +[open,refpage='vkGetRayTracingShaderGroupHandlesNV',desc='Query ray tracing pipeline shader group handles',type='protos'] +-- + +To query the opaque handles of shaders in the ray tracing pipeline, call: + +include::../../api/protos/vkGetRayTracingShaderGroupHandlesNV.txt[] + + * pname:device is the logical device that contains the ray tracing + pipeline. + * pname:pipeline is the ray tracing pipeline object that contains the + shaders. + * pname:firstGroup is the index of the first group to retrieve a handle + for from the sname:VkPipelineShaderStageCreateInfo::pname:pGroups array. + * pname:groupCount is the number of shader handles to retrieve. + * pname:dataSize is the size in bytes of the buffer pointed to by pData. + * pname:pData is a pointer to a user-allocated buffer where the results + will be written. + +.Valid Usage +**** + * [[VUID-vkGetRayTracingShaderGroupHandlesNV-firstGroup-02419]] + The sum of pname:firstGroup and pname:groupCount must: be less than the + number of shader groups in pname:pipeline. + * [[VUID-vkGetRayTracingShaderGroupHandlesNV-dataSize-02420]] + pname:dataSize must: be at least + [eq]#sname:VkPhysicalDeviceRayTracingPropertiesNV::pname:shaderGroupHandleSize + {times} pname:groupCount# +**** + +include::../../validity/protos/vkGetRayTracingShaderGroupHandlesNV.txt[] +-- + +Ray tracing pipelines can contain more shaders than a graphics or compute +pipeline, so to allow parallel compilation of shaders within a pipeline, an +application may: choose to defer compilation until a later point in time. + +[open,refpage='vkCompileDeferredNV',desc='Deferred compilation of shaders',type='protos'] +-- + +To compile a deferred shader in a pipeline call: + +include::../../api/protos/vkCompileDeferredNV.txt[] + + * pname:device is the logical device that contains the ray tracing + pipeline. + * pname:pipeline is the ray tracing pipeline object that contains the + shaders. + * pname:shader is the index of the shader to compile. + +.Valid Usage +**** + * [[VUID-vkCompileDeferredNV-pipeline-02237]] + pname:pipeline must: have been created with + ename:VK_PIPELINE_CREATE_DEFER_COMPILE_BIT_NV. + * [[VUID-vkCompileDeferredNV-shader-02238]] + pname:shader must: not have been called as a deferred compile before. +**** + +include::../../validity/protos/vkCompileDeferredNV.txt[] +-- + diff --git a/chapters/VK_NV_ray_tracing/raytracing-resources.txt b/chapters/VK_NV_ray_tracing/raytracing-resources.txt new file mode 100644 index 00000000..26054c1d --- /dev/null +++ b/chapters/VK_NV_ray_tracing/raytracing-resources.txt @@ -0,0 +1,567 @@ +// This section is included inside the Resources chapter (resources.txt) + +[[resources-acceleration-structures]] +== Acceleration Structures + +[open,refpage='VkAccelerationStructureNV',desc='Opaque handle to an acceleration structure object',type='handles'] +-- + +Acceleration structures are an opaque structure that can be built by the +implementation to more efficiently perform spatial queries on the provided +geometric data. +For this extension, an acceleration structure is either a top-level +acceleration structure containing a set of bottom-level acceleration +structures or a bottom-level acceleration structure containing either a set +of axis-aligned bounding boxes for custom geometry or a set of triangles. + +Each instance in the top-level acceleration structure contains a reference +to a bottom-level acceleration structure as well as an instance transform +plus information required to index into the shader bindings. +The top-level acceleration structure is what is bound to the acceleration +descriptor to trace inside the shader in the ray tracing pipeline. + +Acceleration structures are represented by sname:VkAccelerationStructureNV +handles: + +include::../../api/handles/VkAccelerationStructureNV.txt[] + +-- + +[open,refpage='vkCreateAccelerationStructureNV',desc='Create a new acceleration structure object',type='protos'] +-- + +To create acceleration structures, call: + +include::../../api/protos/vkCreateAccelerationStructureNV.txt[] + + * pname:device is the logical device that creates the buffer object. + * pname:pCreateInfo is a pointer to an instance of the + sname:VkAccelerationStructureCreateInfoNV structure containing + parameters affecting creation of the acceleration structure. + * pname:pAllocator controls host memory allocation as described in the + <> chapter. + * pname:pAccelerationStructure points to a sname:VkAccelerationStructureNV + handle in which the resulting acceleration structure object is returned. + +Similar to other objects in Vulkan, the acceleration structure creation +merely creates an object with a specific "shape" as specified by the +information in sname:VkAccelerationStructureInfoNV and pname:compactedSize +in pname:pCreateInfo. +Populating the data in the object after allocating and binding memory is +done with fname:vkCmdBuildAccelerationStructureNV and +fname:vkCmdCopyAccelerationStructureNV. + +Acceleration structure creation uses the count and type information from the +geometries, but does not use the data references in the structures. + +include::../../validity/protos/vkCreateAccelerationStructureNV.txt[] +-- + +[open,refpage='VkAccelerationStructureCreateInfoNV',desc='Structure specifying the parameters of a newly created acceleration structure object',type='structs'] +-- + +The sname:VkAccelerationStructureCreateInfoNV structure is defined as: + +include::../../api/structs/VkAccelerationStructureCreateInfoNV.txt[] + + * pname:sType is the type of this structure. + * pname:pNext is `NULL` or a pointer to an extension-specific structure. + * pname:compactedSize is the size from the result of + flink:vkCmdWriteAccelerationStructurePropertiesNV, if this acceleration + structure is going to be the target of a compacting copy. + * pname:info contains the elink:VkAccelerationStructureInfoNV information + for the acceleration structure's parameters + +.Valid Usage +**** + * [[VUID-VkAccelerationStructureCreateInfoNV-compactedSize-02421]] + If pname:compactedSize is not `0` then both + sname:info::pname:geometryCount and sname:info::pname:instanceCount + must: be `0` +**** + +include::../../validity/structs/VkAccelerationStructureCreateInfoNV.txt[] +-- + +[open,refpage='VkAccelerationStructureInfoNV',desc='Structure specifying the parameters of acceleration structure object',type='structs'] +-- + +The sname:VkAccelerationStructureInfoNV structure is defined as: + +include::../../api/structs/VkAccelerationStructureInfoNV.txt[] + + * pname:sType is the type of this structure. + * pname:pNext is `NULL` or a pointer to an extension-specific structure. + * pname:type is a ename:VkAccelerationStructureTypeBitsNV value that + specifies the type of acceleration structure that will be created. + * pname:flags is a set of ename:VkBuildAccelerationStructureFlagBitsNV + values that specify additional parameters of the acceleration structure. + * pname:instanceCount specifies the number of instances that will be in + the new acceleration structure + * pname:geometryCount specifies the number of geometries that will be in + the new acceleration structure + * pname:pGeometries is an array of ename:VkGeometryNV structures which + contain the scene data being passed into the acceleration structure. + + +sname:VkAccelerationStructureInfoNV contains information that's used both +for acceleration structure creation with +fname:vkCreateAccelerationStructureNV and in combination with the actual +geometric data to build the acceleration structure with +fname:vkCmdBuildAccelerationStructureNV. + +.Valid Usage +**** + * [[VUID-VkAccelerationStructureInfoNV-geometryCount-02422]] + pname:geometryCount must: be less than or equal to + sname:VkPhysicalDeviceRayTracingPropertiesNV::pname:maxGeometryCount + * [[VUID-VkAccelerationStructureInfoNV-instanceCount-02423]] + pname:instanceCount must: be less than or equal to + sname:VkPhysicalDeviceRayTracingPropertiesNV::pname:maxInstanceCount + * [[VUID-VkAccelerationStructureInfoNV-maxTriangleCount-02424]] + The total number of triangles in all geometries must: be less than or + equal to + sname:VkPhysicalDeviceRayTracingPropertiesNV::pname:maxTriangleCount + * [[VUID-VkAccelerationStructureInfoNV-type-02425]] + If pname:type is ename:VK_ACCELERATION_STRUCTURE_TYPE_TOP_LEVEL_NV then + pname:geometryCount must: be `0`. + * [[VUID-VkAccelerationStructureInfoNV-type-02426]] + If pname:type is ename:VK_ACCELERATION_STRUCTURE_TYPE_BOTTOM_LEVEL_NV + then pname:instanceCount must: be `0`. + * [[VUID-VkAccelerationStructureInfoNV-compactedSize-02427]] + If pname:compactedSize is not `0` then both pname:geometryCount and + pname:instanceCount must: be `0` + +**** + +include::../../validity/structs/VkAccelerationStructureInfoNV.txt[] + +-- +[open,refpage='VkBuildAccelerationStructureFlagBitsNV',desc='Bitmask specifying additional parameters for acceleration structure builds',type='enums'] +-- + +Bits which can: be set in slink:VkAccelerationStructureInfoNV::pname:flags, +specifying additional parameters for acceleration structure builds, are: + +include::../../api/enums/VkBuildAccelerationStructureFlagBitsNV.txt[] + + * ename:VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_UPDATE_BIT_NV indicates that + the specified acceleration structure may: be updated with pname:update + of true in flink:vkCmdBuildAccelerationStructureNV. + This flag must: only be set on a build that is not an update or is an + update with a source that also had this flag set. + * ename:VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_COMPACTION_BIT_NV indicates + that the specified acceleration structure may: act as the source for + flink:vkCmdCopyAccelerationStructureNN with pname:mode of + ename:VK_COPY_ACCELERATION_STRUCTURE_MODE_COMPACT_NV to produce a + compacted acceleration structure. + * ename:VK_BUILD_ACCELERATION_STRUCTURE_PREFER_FAST_TRACE_BIT_NV indicates + that the given acceleration structure build should prioritize trace + performance over build time. + * ename:VK_BUILD_ACCELERATION_STRUCTURE_PREFER_FAST_BUILD_BIT_NV indicates + that the given acceleration structure build should prioritize build time + over trace performance. + * ename:VK_BUILD_ACCELERATION_STRUCTURE_LOW_MEMORY_BIT_NV indicates that + this acceleration structure should minimize the size of scratch memory + and final result build, potentially at the expense of build time or + trace performance. + +ename:VK_BUILD_ACCELERATION_STRUCTURE_PREFER_FAST_TRACE_BIT_NV and +ename:VK_BUILD_ACCELERATION_STRUCTURE_PREFER_FAST_BUILD_BIT_NV must: not be +used in the same flags. + +[NOTE] +.Note +==== +ename:VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_UPDATE_BIT_NV and +ename:VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_COMPACTION_BIT_NV may: take more +time and memory than a normal build, so should only be used when those +features are used. +==== + +-- + + +[open,refpage='VkGeometryNV',desc='Structure specifying a geometry in a bottom-level acceleration structure',type='structs'] +-- + +The sname:VkGeometryNV structure is defined as: + +include::../../api/structs/VkGeometryNV.txt[] + + * pname:sType is the type of this structure. + * pname:pNext is `NULL` or a pointer to an extension-specific structure. + * pname:geometryType describes which type of geometry this VkGeometryNV + refers to. + * pname:geometry contains the geometry data as described in + slink:VkGeometryDataNV. + * pname:flags has flags describing options for this geometry. + +include::../../validity/structs/VkGeometryNV.txt[] +-- + +[open,refpage='VkGeometryTypeNV',desc='Enum specifying which type of geometry is provided',type='enums'] +-- + +Geometry types are specified by elink:VkGeometryTypeNV, which takes values: + +include::../../api/enums/VkGeometryTypeNV.txt[] + + * ename:VK_GEOMETRY_TYPE_TRIANGLES_NV indicates that the pname:triangles + of sname:VkGeometryDataNV contains valid data. + * ename:VK_GEOMETRY_TYPE_AABBS_NV indicates that the pname:aabbs of + sname:VkGeometryDataNV contains valid data. +-- + +[open,refpage='VkGeometryFlagBitsNV',desc='Bitmask specifying additional parameters for a geometry',type='enums'] +-- + +Bits which can: be set in slink:VkGeometryNV::pname:flags, specifying +additional parameters for acceleration structure builds, are: + +include::../../api/enums/VkGeometryFlagBitsNV.txt[] + + * ename:VK_GEOMETRY_OPAQUE_BIT_NV indicates that this geometry does not + use any hit shaders. + * ename:VK_GEOMETRY_NO_DUPLICATE_ANY_HIT_INVOCATION_BIT_NV indicates that + the implementation must: only call any hit a single time for each + primitive in this geometry. + If this bit is absent an implementation may: invoke an any hit shader + more than once for this geometry. + +-- + + +[open,refpage='VkGeometryDataNV',desc='Structure specifying geometry in a bottom-level acceleration structure',type='structs'] +-- + +The sname:VkGeometryDataNV structure is defined as: + +include::../../api/structs/VkGeometryDataNV.txt[] + + * pname:triangles contains triangle data if pname:geometryType is + ename:VK_GEOMETRY_TYPE_TRIANGLES_NV. + * pname:aabbs contains axis-aligned bounding box data if + pname:geometryType is ename:VK_GEOMETRY_TYPE_AABBS_NV. + +include::../../validity/structs/VkGeometryDataNV.txt[] +-- + +[open,refpage='VkGeometryTrianglesNV',desc='Structure specifying a triangle geometry in a bottom-level acceleration structure',type='structs'] +-- + +The sname:VkGeometryTrianglesNV structure is defined as: + +include::../../api/structs/VkGeometryTrianglesNV.txt[] + + * pname:sType is the type of this structure. + * pname:pNext is `NULL` or a pointer to an extension-specific structure. + * pname:vertexData is the buffer containing vertex data for this geometry. + * pname:vertexOffset is the offset in bytes within pname:vertexData + containing vertex data for this geometry. + * pname:vertexCount is the number of valid vertices. + * pname:vertexStride is the stride in bytes between each vertex. + * pname:vertexFormat is the format of each vertex element. + * pname:indexData is the buffer containing index data for this geometry. + * pname:indexOffset is the offset in bytes within pname:indexData + containing index data for this geometry. + * pname:indexCount is the number of indices to include in this geometry. + * pname:indexType is the format of each index. + * pname:transformData is a buffer containing optional reference to an + array of 32-bit floats representing a 3x4 row major affine + transformation matrix for this geometry. + * pname:transformOffset is the offset in bytes in pname:transformData of + the transform information described above. + +If pname:indexType is ename:VK_INDEX_TYPE_NONE_NV, then this structure +describes a set of triangles determined by pname:vertexCount. +Otherwise, this structure describes a set of indexed triangles determined by +pname:indexCount. + +.Valid Usage +**** + * [[VUID-VkGeometryTrianglesNV-vertexOffset-02428]] + pname:vertexOffset must: be less than the size of pname:vertexData + * [[VUID-VkGeometryTrianglesNV-vertexOffset-02429]] + pname:vertexOffset must: be a multiple of the component size of + pname:vertexFormat. + * [[VUID-VkGeometryTrianglesNV-vertexFormat-02430]] + pname:vertexFormat must: be one of ename:VK_FORMAT_R32G32B32_SFLOAT, + ename:VK_FORMAT_R32G32_SFLOAT, ename:VK_FORMAT_R16G16B16_SFLOAT, + ename:VK_FORMAT_R16G16_SFLOAT, ename:VK_FORMAT_R16G16_SNORM, or + ename:VK_FORMAT_R16G16B16_SNORM + * [[VUID-VkGeometryTrianglesNV-indexOffset-02431]] + pname:indexOffset must: be less than the size of pname:indexData + * [[VUID-VkGeometryTrianglesNV-indexOffset-02432]] + pname:indexOffset must: be a multiple of the element size of + pname:indexType + * [[VUID-VkGeometryTrianglesNV-indexType-02433]] + pname:indexType must: be ename:VK_INDEX_TYPE_UINT16, + ename:VK_INDEX_TYPE_UINT32, or ename:VK_INDEX_TYPE_NONE_NV + * [[VUID-VkGeometryTrianglesNV-indexData-02434]] + pname:indexData must: be ename:VK_NULL_HANDLE if pname:indexType is + ename:VK_INDEX_TYPE_NONE_NV + * [[VUID-VkGeometryTrianglesNV-indexData-02435]] + pname:indexData must: be a valid handle if pname:indexType is not + ename:VK_INDEX_TYPE_NONE_NV + * [[VUID-VkGeometryTrianglesNV-indexCount-02436]] + pname:indexCount must: be 0 if pname:indexType is + ename:VK_INDEX_TYPE_NONE_NV + * [[VUID-VkGeometryTrianglesNV-transformOffset-02437]] + pname:transformOffset must: be less than the size of pname:transformData + * [[VUID-VkGeometryTrianglesNV-transformOffset-02438]] + pname:transformOffset must: be a multiple of 16 +**** + +include::../../validity/structs/VkGeometryTrianglesNV.txt[] +-- + +[open,refpage='VkGeometryAABBNV',desc='Structure specifying axis-aligned bounding box geometry in a bottom-level acceleration structure',type='structs'] +-- + +The sname:VkGeometryAABBNV structure is defined as: + +include::../../api/structs/VkGeometryAABBNV.txt[] + + * pname:sType is the type of this structure. + * pname:pNext is `NULL` or a pointer to an extension-specific structure. + * pname:aabbData is the buffer containing axis-aligned bounding box data + * pname:numAABBs is the number of AABBs in this geometry. + * pname:stride is the stride in bytes between AABBs in pname:aabbData. + * pname:offset is the offset in bytes of the first AABB in pname:aabbData. + +.Valid Usage +**** + * [[VUID-VkGeometryAABBNV-offset-02439]] + pname:offset must: be less than the size of pname:aabbData + * [[VUID-VkGeometryAABBNV-offset-02440]] + pname:offset must: be a multiple of 8. + * [[VUID-VkGeometryAABBNV-stride-02441]] + pname:stride must: be a multiple of 8. +**** + +The AABB data in memory is 6 32-bit floats consisting of the minimum x, y, +and z values followed by the maximum x, y, and x values. + +include::../../validity/structs/VkGeometryAABBNV.txt[] +-- + + +[open,refpage='vkDestroyAccelerationStructureNV',desc='Destroy an acceleration structure object',type='protos'] +-- + +To destroy an acceleration structure, call: + +include::../../api/protos/vkDestroyAccelerationStructureNV.txt[] + + * pname:device is the logical device that destroys the buffer. + * pname:accelerationStructure is the acceleration structure to destroy. + * pname:pAllocator controls host memory allocation as described in the + <> chapter. + +.Valid Usage +**** + * [[VUID-vkDestroyAccelerationStructureNV-accelerationStructure-02442]] + All submitted commands that refer to pname:accelerationStructure must: + have completed execution + * [[VUID-vkDestroyAccelerationStructureNV-accelerationStructure-02443]] + If sname:VkAllocationCallbacks were provided when + pname:accelerationStructure was created, a compatible set of callbacks + must: be provided here + * [[VUID-vkDestroyAccelerationStructureNV-accelerationStructure-02444]] + If no sname:VkAllocationCallbacks were provided when + pname:accelerationStructure was created, pname:pAllocator must: be + `NULL` +**** + +include::../../validity/protos/vkDestroyAccelerationStructureNV.txt[] +-- + +[open,refpage='vkGetAccelerationStructureMemoryRequirementsNV',desc='Get acceleration structure memory requirements',type='protos'] +-- + +An acceleration structure has memory requirements for the structure object +itself, scratch space for the build, and scratch space for the update. + +To query the memory requirements call: + +include::../../api/protos/vkGetAccelerationStructureMemoryRequirementsNV.txt[] + + * pname:device is the logical device on which the acceleration structure + was created. + * pname:pInfo specifies the acceleration structure to get memory + requirements for. + * pname:pMemoryRequirements returns the requested acceleration structure + memory requirements. + +include::../../validity/protos/vkGetAccelerationStructureMemoryRequirementsNV.txt[] +-- + +[open,refpage='VkAccelerationStructureMemoryRequirementsInfoNV',desc='Structure specifying acceleration to query for memory requirements',type='structs'] +-- +The sname:VkAccelerationStructureMemoryRequirementsInfoNV structure is +defined as: + +include::../../api/structs/VkAccelerationStructureMemoryRequirementsInfoNV.txt[] + + * pname:sType is the type of this structure. + * pname:pNext is `NULL` or a pointer to an extension-specific structure. + * pname:type selects the type of memory requirement being queried. + ename:VK_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_OBJECT_NV + returns the memory requirements for the object itself. + ename:VK_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_BUILD_SCRATCH_NV + returns the memory requirements for the scratch memory when doing a + build. + ename:VK_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_UPDATE_SCRATCH_NV + returns the memory requirements for the scratch memory when doing an + update. + * pname:accelerationStructure is the acceleration structure to be queried + for memory requirements. + +include::../../validity/structs/VkAccelerationStructureMemoryRequirementsInfoNV.txt[] +-- + +[open,refpage='VkAccelerationStructureMemoryRequirementsTypeNV',desc='Acceleration structure memory requirement type',type='enums'] +-- + +Possible values of pname:type in +sname:VkAccelerationStructureMemoryRequirementsInfoNV are:, + +include::../../api/enums/VkAccelerationStructureMemoryRequirementsTypeNV.txt[] + + * ename:VK_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_OBJECT_NV + requests the memory requirement for the sname:VkAccelerationStructureNV + backing store. + * ename:VK_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_BUILD_SCRATCH_NV + requests the memory requirement for scratch space during the initial + build. + * ename:VK_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_UPDATE_SCRATCH_NV + requests the memory requirement for scratch space during an update. + +-- + + +[open,refpage='vkBindAccelerationStructureMemoryNV',desc='Bind acceleration structure memory',type='protos'] +-- + +To attach memory to one or more acceleration structures at a time, call: + +include::../../api/protos/vkBindAccelerationStructureMemoryNV.txt[] + + * pname:device is the logical device that owns the acceleration structures + and memory. + * pname:bindInfoCount is the number of elements in pBindInfos. + * pname:pBindInfos is a pointer to an array of structures of type + slink:VkBindAccelerationStructureMemoryInfoNV, describing images and + memory to bind. + +.Valid Usage +**** + * [[VUID-vkBindAccelerationStructureMemoryNV-accelerationStructure-02445]] + pname:accelerationStructure must: not already be backed by a memory + object + * [[VUID-vkBindAccelerationStructureMemoryNV-memoryOffset-02446]] + pname:memoryOffset must: be less than the size of pname:memory + * [[VUID-vkBindAccelerationStructureMemoryNV-memory-02447]] + pname:memory must: have been allocated using one of the memory types + allowed in the pname:memoryTypeBits member of the + sname:VkMemoryRequirements structure returned from a call to + fname:vkGetAccelerationStructureMemoryRequirementsNV with + pname:accelerationStructure and pname:type of + ename:VK_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_OBJECT_NV + * [[VUID-vkBindAccelerationStructureMemoryNV-memoryOffset-02448]] + pname:memoryOffset must: be an integer multiple of the pname:alignment + member of the sname:VkMemoryRequirements structure returned from a call + to fname:vkGetAccelerationStructureMemoryRequirementsNV with + pname:accelerationStructure and pname:type of + ename:VK_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_OBJECT_NV + * [[VUID-vkBindAccelerationStructureMemoryNV-size-02449]] + The pname:size member of the sname:VkMemoryRequirements structure + returned from a call to fname:vkGetImageMemoryRequirements with + pname:accelerationStructure and pname:type of + ename:VK_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_OBJECT_NV must: + be less than or equal to the size of pname:memory minus + pname:memoryOffset +**** + +include::../../validity/protos/vkBindAccelerationStructureMemoryNV.txt[] +-- + +[open,refpage='VkBindAccelerationStructureMemoryInfoNV',desc='Structure specifying acceleration structure memory binding',type='structs'] +-- +The sname:VkBindAccelerationStructureMemoryInfoNV structure is defined as: + +include::../../api/structs/VkBindAccelerationStructureMemoryInfoNV.txt[] + + * pname:sType is the type of this structure. + * pname:pNext is `NULL` or a pointer to an extension-specific structure. + * pname:accelerationStructure is the acceleration structure to be attached + to memory. + * pname:memory is a VkDeviceMemory object describing the device memory to + attach. + * pname:memoryOffset is the start offset of the region of memory which is + to be bound to the acceleration structure. + The number of bytes returned in the slink:VkMemoryRequirements::size + member in memory, starting from pname:memoryOffset bytes, will be bound + to the specified acceleration structure. + * pname:deviceIndexCount is the number of elements in + pname:pDeviceIndices. + * pname:pDeviceIndices is a pointer to an array of device indices. + +.Valid Usage +**** + * [[VUID-VkBindAccelerationStructureMemoryInfoNV-accelerationStructure-02450]] + pname:accelerationStructure must: not already be backed by a memory + object + * [[VUID-VkBindAccelerationStructureMemoryInfoNV-memoryOffset-02451]] + pname:memoryOffset must: be less than the size of pname:memory + * [[VUID-VkBindAccelerationStructureMemoryInfoNV-memory-02452]] + pname:memory must: have been allocated using one of the memory types + allowed in the pname:memoryTypeBits member of the + sname:VkMemoryRequirements structure returned from a call to + fname:vkGetAccelerationStructureMemoryRequirementsNV with + pname:accelerationStructure + * [[VUID-VkBindAccelerationStructureMemoryInfoNV-memoryOffset-02453]] + pname:memoryOffset must: be an integer multiple of the pname:alignment + member of the sname:VkMemoryRequirements structure returned from a call + to fname:vkGetAccelerationStructureMemoryRequirementsNV with + pname:accelerationStructure + * [[VUID-VkBindAccelerationStructureMemoryInfoNV-size-02454]] + The pname:size member of the sname:VkMemoryRequirements structure + returned from a call to + fname:vkGetAccelerationStructureMemoryRequirementsNV with + pname:accelerationStructure must: be less than or equal to the size of + pname:memory minus pname:memoryOffset +**** + +include::../../validity/structs/VkBindAccelerationStructureMemoryInfoNV.txt[] +-- + + +[open,refpage='vkGetAccelerationStructureHandleNV',desc='Get opaque acceleration structure handle',type='protos'] +-- + +To allow constructing geometry instances with device code if desired, we +need to be able to query a opaque handle for an acceleration structure. +This handle is a value of 8 bytes. +To get this handle, call: + +include::../../api/protos/vkGetAccelerationStructureHandleNV.txt[] + + * pname:device is the logical device that owns the acceleration + structures. + * pname:accelerationStructure is the acceleration structure. + * 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 + +.Valid Usage +**** + * [[VUID-vkGetAccelerationStructureHandleNV-dataSize-02240]] + pname:dataSize must: be large enough to contain the result of the query, + as described above +**** + +include::../../validity/protos/vkGetAccelerationStructureHandleNV.txt[] +-- diff --git a/chapters/VK_NVX_raytracing/raytracing-shaders.txt b/chapters/VK_NV_ray_tracing/raytracing-shaders.txt similarity index 83% rename from chapters/VK_NVX_raytracing/raytracing-shaders.txt rename to chapters/VK_NV_ray_tracing/raytracing-shaders.txt index d9c8f1ef..e6e02ad9 100644 --- a/chapters/VK_NVX_raytracing/raytracing-shaders.txt +++ b/chapters/VK_NV_ray_tracing/raytracing-shaders.txt @@ -5,7 +5,7 @@ == Ray Generation Shaders A ray generation shader is similar to a compute shader. -Its main purpose is to execute ray tracing queries using code:OpTraceNVX +Its main purpose is to execute ray tracing queries using code:OpTraceNV instructions and process the results. [[shaders-ray-generation-execution]] @@ -13,7 +13,7 @@ instructions and process the results. One ray generation shader is executed per ray tracing dispatch. Its location in the shader binding table (see <> for details) is passed directly into fname:vkCmdTraceRaysNVX +Binding Table>> for details) is passed directly into fname:vkCmdTraceRaysNV using the pname:raygenShaderBindingTableBuffer and pname:raygenShaderBindingOffset parameters. @@ -26,15 +26,15 @@ An intersection shader for a primitive is executed whenever its axis-aligned bounding box is hit by a ray. A built-in intersection shader for triangle primitives that is used -automatically whenever geometry of type ename:VK_GEOMETRY_TYPE_TRIANGLES_NVX +automatically whenever geometry of type ename:VK_GEOMETRY_TYPE_TRIANGLES_NV is specified. -Like other raytracing shader domains, an intersection shader operates on a +Like other ray tracing shader domains, an intersection shader operates on a single ray at a time. It also operates on a single primitive at a time. It is therefore the purpose of an intersection shader to compute the ray-primitive intersections and report them. -To report an intersection, the shader calls the code:OpReportIntersectionNVX +To report an intersection, the shader calls the code:OpReportIntersectionNV instruction. An intersection shader communicates with any hit and closest shaders by @@ -52,7 +52,7 @@ intersection that lies within the current [tmin,tmax] of the ray. The main use of any hit shaders is to programmatically decide whether or not an intersection should be accepted. The intersection will be accepted unless the shader calls the -code:OpIgnoreIntersectionNVX instruction. +code:OpIgnoreIntersectionNV instruction. [[shaders-any-hit-execution]] === Any Hit Shader Execution @@ -69,7 +69,7 @@ point during traversal, unless the ray is forcibly terminated. Closest hit shaders have read-only access to the attributes generated by the corresponding intersection shader, and may: read or modify the ray payload. They also have access to a number of system-generated values. -Closest hit shaders may call code:OpTraceNVX to recursively trace rays. +Closest hit shaders may call code:OpTraceNV to recursively trace rays. [[shaders-closest-hit-execution]] === Closest Hit Shader Execution @@ -81,7 +81,7 @@ intersection has been found and accepted. == Miss Shaders Miss shaders can access the ray payload and can trace new rays through the -code:OpTraceNVX instruction, but cannot access attributes since they are not +code:OpTraceNV instruction, but cannot access attributes since they are not associated with an intersection. [[shaders-miss-execution]] @@ -89,3 +89,15 @@ associated with an intersection. A miss shader is executed instead of a closest hit shader if no intersection was found during traversal. + +[[shaders-callable]] +== Callable Shaders + +Callable shaders may: access a callable payload that works similarly to ray +payloads to do subroutine work. + +[[shaders-callable-execution]] +=== Callable Shader Execution + +A callable shader is executed by calling code:OpExecuteCallableNV from an +allowed shader stage. diff --git a/chapters/VK_NV_ray_tracing/raytracing.txt b/chapters/VK_NV_ray_tracing/raytracing.txt new file mode 100644 index 00000000..e75ad48b --- /dev/null +++ b/chapters/VK_NV_ray_tracing/raytracing.txt @@ -0,0 +1,636 @@ +[[raytracing]] += Ray Tracing + +Unlike draw commands which use rasterization, ray tracing is a rendering +method which generates an image by tracing the path of rays which have a +single origin and using shaders to determine the final colour of an image +plane. + +Ray tracing uses a separate rendering pipeline from both the graphics and +compute pipelines (see <>). +It has a unique set of programmable and fixed function stages. + +[[fig-raypipe]] +image::images/raypipe.svg[align="center",title="Ray tracing Pipeline",opts="{imageopts}"] + +.Caption +**** +Interaction between the different shader stages in the ray tracing pipeline +**** + +[[raytracing-commands]] +== Ray Tracing Commands +_Ray tracing commands_ provoke work in the raytacing pipeline. +Ray tracing commands are recorded into a command buffer and when executed by +a queue will produce work which executes according to the currently bound +ray tracing pipeline. +A ray tracing pipeline must: be bound to a command buffer before any ray +tracing commands are recorded in that command buffer. + +Each ray tracing call operates on a set of shader stages that are specific +to the ray tracing pipeline as well as a set of +sname:VkAccelerationStructure objects which describe the scene geometry in +an implementation-specific way. +The relationship between the ray tracing pipeline object and the +acceleration structures is passed into the raytacing command in a +sname:VkBuffer object known as a _shader binding table_. + +During execution, control alternates between scheduling and other +operations. +The scheduling functionality is implementation-specific and is responsible +for workload execution. +The shader stages are programmable. +_Traversal_, which refers to the process of traversing acceleration +structures to find potential intersections of rays with geometry, is fixed +function. + +The programmable portions of the pipeline are exposed in a single-ray +programming model. +Each GPU thread handles one ray at a time. +Memory operations can be synchronized using standard memory barriers. +However, communication and synchronization between threads is not allowed. +In particular, the use of compute pipeline synchronization functions is not +supported in the ray tracing pipeline. + +[open,refpage='vkCmdTraceRaysNV',desc='Initialize a ray tracing dispatch',type='protos'] +-- + +To dispatch a ray tracing call use: + +include::../../api/protos/vkCmdTraceRaysNV.txt[] + + * pname:commandBuffer is the command buffer into which the command will be + recorded. + * pname:raygenShaderBindingTableBuffer is the buffer object that holds the + shader binding table data for the ray generation shader stage. + * pname:raygenShaderBindingOffset is the offset in bytes (relative to + pname:raygenShaderBindingTableBuffer) of the ray generation shader being + used for the trace. + * pname:missShaderBindingTableBuffer is the buffer object that holds the + shader binding table data for the miss shader stage. + * pname:missShaderBindingOffset is the offset in bytes (relative to + pname:missShaderBindingTableBuffer) of the miss shader being used for + the trace. + * pname:missShaderBindingStride is the size in bytes of each shader + binding table record in pname:missShaderBindingTableBuffer + * pname:hitShaderBindingTableBuffer is the buffer object that holds the + shader binding table data for the hit shader stages. + * pname:hitShaderBindingOffset is the offset in bytes (relative to + pname:hitShaderBindingTableBuffer) of the hit shader group being used + for the trace. + * pname:hitShaderBindingStride is the size in bytes of each shader binding + table record in pname:hitShaderBindingTableBuffer + * pname:callableShaderBindingTableBuffer is the buffer object that holds + the shader binding table data for the callable shader stage. + * pname:callableShaderBindingOffset is the offset in bytes (relative to + pname:callableShaderBindingTableBuffer) of the callable shader being + used for the trace. + * pname:callableShaderBindingStride is the size in bytes of each shader + binding table record in pname:callableShaderBindingTableBuffer + * pname:width is the width of the ray trace query dimensions. + * pname:height is height of the ray trace query dimensions. + * pname:depth is depth of the ray trace query dimensions. + +When the command is executed, a ray generation group of [eq]#pname:width +{times} pname:height {times} pname:depth# rays is assembled. + +.Valid Usage +**** + * [[VUID-vkCmdTraceRaysNV-raygenShaderBindingOffset-02455]] + pname:raygenShaderBindingOffset must: be less than the size of + pname:raygenShaderBindingTableBuffer + * [[VUID-vkCmdTraceRaysNV-raygenShaderBindingOffset-02456]] + pname:raygenShaderBindingOffset must: be a multiple of + sname:VkPhysicalDeviceRayTracingPropertiesNV::pname:shaderGroupBaseAlignment. + * [[VUID-vkCmdTraceRaysNV-missShaderBindingOffset-02457]] + pname:missShaderBindingOffset must: be less than the size of + pname:missShaderBindingTableBuffer + * [[VUID-vkCmdTraceRaysNV-missShaderBindingOffset-02458]] + pname:missShaderBindingOffset must: be a multiple of + sname:VkPhysicalDeviceRayTracingPropertiesNV::pname:shaderGroupBaseAlignment. + * [[VUID-vkCmdTraceRaysNV-hitShaderBindingOffset-02459]] + pname:hitShaderBindingOffset must: be less than the size of + pname:hitShaderBindingTableBuffer + * [[VUID-vkCmdTraceRaysNV-hitShaderBindingOffset-02460]] + pname:hitShaderBindingOffset must: be a multiple of + sname:VkPhysicalDeviceRayTracingPropertiesNV::pname:shaderGroupBaseAlignment. + * [[VUID-vkCmdTraceRaysNV-callableShaderBindingOffset-02461]] + pname:callableShaderBindingOffset must: be less than the size of + pname:callableShaderBindingTableBuffer + * [[VUID-vkCmdTraceRaysNV-callableShaderBindingOffset-02462]] + pname:callableShaderBindingOffset must: be a multiple of + sname:VkPhysicalDeviceRayTracingPropertiesNV::pname:shaderGroupBaseAlignment. + * [[VUID-vkCmdTraceRaysNV-missShaderBindingStride-02463]] + pname:missShaderBindingStride must: be a multiple of + sname:VkPhysicalDeviceRayTracingPropertiesNV::pname:shaderGroupHandleSize + * [[VUID-vkCmdTraceRaysNV-hitShaderBindingStride-02464]] + pname:hitShaderBindingStride must: be a multiple of + sname:VkPhysicalDeviceRayTracingPropertiesNV::pname:shaderGroupHandleSize + * [[VUID-vkCmdTraceRaysNV-callableShaderBindingStride-02465]] + pname:callableShaderBindingStride must: be a multiple of + sname:VkPhysicalDeviceRayTracingPropertiesNV::pname:shaderGroupHandleSize + * [[VUID-vkCmdTraceRaysNV-missShaderBindingStride-02466]] + pname:missShaderBindingStride must: be a less than or equal to + sname:VkPhysicalDeviceRayTracingPropertiesNV::pname:maxShaderGroupStride + * [[VUID-vkCmdTraceRaysNV-hitShaderBindingStride-02467]] + pname:hitShaderBindingStride must: be a less than or equal to + sname:VkPhysicalDeviceRayTracingPropertiesNV::pname:maxShaderGroupStride + * [[VUID-vkCmdTraceRaysNV-callableShaderBindingStride-02468]] + pname:callableShaderBindingStride must: be a less than or equal to + sname:VkPhysicalDeviceRayTracingPropertiesNV::pname:maxShaderGroupStride + * [[VUID-vkCmdTraceRaysNV-width-02469]] + pname:width must: be less than or equal to + sname:VkPhysicalDeviceLimits::pname:maxComputeWorkGroupCount[0] + * [[VUID-vkCmdTraceRaysNV-height-02470]] + pname:height must: be less than or equal to + sname:VkPhysicalDeviceLimits::pname:maxComputeWorkGroupCount[1] + * [[VUID-vkCmdTraceRaysNV-depth-02471]] + pname:depth must: be less than or equal to + sname:VkPhysicalDeviceLimits::pname:maxComputeWorkGroupCount[2] + * [[VUID-vkCmdTraceRaysNV-None-02472]] + For each set _n_ that is statically used by the sname:VkPipeline bound + to ename:VK_PIPELINE_BIND_POINT_RAY_TRACING_NV, a descriptor set must: + have been bound to _n_ at ename:VK_PIPELINE_BIND_POINT_RAY_TRACING_NV, + with a sname:VkPipelineLayout that is compatible for set _n_, with the + sname:VkPipelineLayout used to create the current sname:VkPipeline, as + described in <> + * [[VUID-vkCmdTraceRaysNV-None-02473]] + Descriptors in each bound descriptor set, specified via + fname:vkCmdBindDescriptorSets, must: be valid if they are statically + used by the bound sname:VkPipeline object, specified via + fname:vkCmdBindPipeline + * [[VUID-vkCmdTraceRaysNV-None-02474]] + A valid ray tracing pipeline must: be bound to the current command + buffer with ename:VK_PIPELINE_BIND_POINT_RAY_TRACING_NV + * [[VUID-vkCmdTraceRaysNV-None-02475]] + For each push constant that is statically used by the sname:VkPipeline + bound to ename:VK_PIPELINE_BIND_POINT_RAY_TRACING_NV, a push constant + value must: have been set for + ename:VK_PIPELINE_BIND_POINT_RAY_TRACING_NV, with a + sname:VkPipelineLayout that is compatible for push constants with the + one used to create the current sname:VkPipeline, as described in + <> + * [[VUID-vkCmdTraceRaysNV-None-02476]] + If any sname:VkSampler object that is accessed from a shader by the + sname:VkPipeline bound to ename:VK_PIPELINE_BIND_POINT_RAY_TRACING_NV + uses unnormalized coordinates, it must: not be used to sample from any + sname:VkImage with a sname:VkImageView of the type + ename:VK_IMAGE_VIEW_TYPE_3D, ename:VK_IMAGE_VIEW_TYPE_CUBE, + ename:VK_IMAGE_VIEW_TYPE_1D_ARRAY, ename:VK_IMAGE_VIEW_TYPE_2D_ARRAY or + ename:VK_IMAGE_VIEW_TYPE_CUBE_ARRAY, in any shader stage + * [[VUID-vkCmdTraceRaysNV-None-02477]] + If any sname:VkSampler object that is accessed from a shader by the + sname:VkPipeline bound to ename:VK_PIPELINE_BIND_POINT_RAY_TRACING_NV + uses unnormalized coordinates, it must: not be used with any of the + SPIR-V `OpImageSample*` or `OpImageSparseSample*` instructions with + code:ImplicitLod, code:Dref or code:Proj in their name, in any shader + stage + * [[VUID-vkCmdTraceRaysNV-None-02478]] + If any sname:VkSampler object that is accessed from a shader by the + sname:VkPipeline bound to ename:VK_PIPELINE_BIND_POINT_RAY_TRACING_NV + uses unnormalized coordinates, it must: not be used with any of the + SPIR-V `OpImageSample*` or `OpImageSparseSample*` instructions that + includes a LOD bias or any offset values, in any shader stage + * [[VUID-vkCmdTraceRaysNV-None-02479]] + If the <> + feature is not enabled, and any shader stage in the sname:VkPipeline + object bound to ename:VK_PIPELINE_BIND_POINT_RAY_TRACING_NV accesses a + uniform buffer, it must: not access values outside of the range of that + buffer specified in the bound descriptor set + * [[VUID-vkCmdTraceRaysNV-None-02480]] + If the <> + feature is not enabled, and any shader stage in the sname:VkPipeline + object bound to ename:VK_PIPELINE_BIND_POINT_RAY_TRACING_NV accesses a + storage buffer, it must: not access values outside of the range of that + buffer specified in the bound descriptor set + * [[VUID-vkCmdTraceRaysNV-None-02481]] + If a sname:VkImageView is sampled with with ename:VK_FILTER_LINEAR as a + result of this command, then the image view's + <> must: contain + ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BIT. +ifdef::VK_IMG_filter_cubic[] + * [[VUID-vkCmdTraceRaysNV-None-02482]] + If a sname:VkImageView is sampled with with ename:VK_FILTER_CUBIC_IMG as + a result of this command, then the image view's + <> must: contain + ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_CUBIC_BIT_IMG. + * [[VUID-vkCmdTraceRaysNV-None-02483]] + Any slink:VkImageView being sampled with ename:VK_FILTER_CUBIC_IMG as a + result of this command must: not have a elink:VkImageViewType of + ename:VK_IMAGE_VIEW_TYPE_3D, ename:VK_IMAGE_VIEW_TYPE_CUBE, or + ename:VK_IMAGE_VIEW_TYPE_CUBE_ARRAY +endif::VK_IMG_filter_cubic[] +ifdef::VK_VERSION_1_1[] + * [[VUID-vkCmdTraceRaysNV-commandBuffer-02484]] + If pname:commandBuffer is an unprotected command buffer, and any + pipeline stage in the sname:VkPipeline object bound to + ename:VK_PIPELINE_BIND_POINT_RAY_TRACING_NV reads from or writes to any + image or buffer, that image or buffer must: not be a protected image or + protected buffer. + * [[VUID-vkCmdTraceRaysNV-commandBuffer-02485]] + If pname:commandBuffer is a protected command buffer, and any pipeline + stage in the sname:VkPipeline object bound to + ename:VK_PIPELINE_BIND_POINT_RAY_TRACING_NV writes to any image or + buffer, that image or buffer must: not be an unprotected image or + unprotected buffer. + * [[VUID-vkCmdTraceRaysNV-commandBuffer-02486]] + If pname:commandBuffer is a protected command buffer, and any pipeline + stage other than the ray tracing pipeline stage in the sname:VkPipeline + object bound to ename:VK_PIPELINE_BIND_POINT_RAY_TRACING_NV reads from + any image or buffer, the image or buffer must: not be a protected image + or protected buffer. +endif::VK_VERSION_1_1[] +ifdef::VK_NV_corner_sampled_image[] + * [[VUID-vkCmdTraceRaysNV-flags-02487]] + Any slink:VkImage created with a slink:VkImageCreateInfo::pname:flags + containing ename:VK_IMAGE_CREATE_CORNER_SAMPLED_BIT_NV sampled as a + result of this command must: only be sampled using a + slink:VkSamplerAddressMode of + ename:VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_EDGE. +endif::VK_NV_corner_sampled_image[] +**** + +include::../../validity/protos/vkCmdTraceRaysNV.txt[] +-- + +[[shader-binding-table]] +== Shader Binding Table + +A _shader binding table_ is a resource which establishes the relationship +between the ray tracing pipeline and the acceleration structures that were +built for the ray tracing query. +It indicates the shaders that operate on each geometry in an acceleration +structure. +In addition, it contains the resources accessed by each shader, including +indices of textures and constants. +The application allocates and manages _shader binding tables_ as +elink:VkBuffer objects. + +Each entry in the shader binding table consists of pname:shaderHeaderSize +bytes of data as queried by vkGetRayTracingShaderHandlesNV to refer to the +shader that it invokes. +The remainder of the data specified by the stride is application-visible +data that can be referenced by a shaderRecordNV block in the shader. + +The shader binding tables to use in a ray tracing query are passed to +fname:vkCmdTraceRaysNV. +Shader binding tables are read-only in shaders that are executing on the ray +tracing pipeline. + +[[shader-binding-table-indexing-rules]] +=== Indexing Rules + +In order to execute the correct shaders and access the correct resources +during a ray tracing dispatch, the implementation must be able to locate +shader binding table entries at various stages of execution. +This is accomplished by defining a set of indexing rules that compute shader +binding table record positions relative to the buffer's base address in +memory. +The application must: organize the contents of the shader binding table's +memory in a way that application of the indexing rules will lead to correct +records. + +==== Ray Generation Shaders +Only one ray generation shader is executed per ray tracing dispatch. +Its location is passed into fname:vkCmdTraceRaysNV using the +pname:raygenShaderBindingTableBuffer and +pname:raygenShaderBindingTableOffset parameters - there is no indexing. + +==== Hit Shaders +The base for the computation of intersection, any hit and closest hit shader +locations is the pname:instanceShaderBindingTableRecordOffset value stored +with each instance of a top-level acceleration structure. +This value determines the beginning of the shader binding table records for +a given instance. +Each geometry in the instance must: have at least one hit program record. + +In the following rule, _geometryIndex_ refers to the location of the +geometry within the instance. + +The pname:sbtRecordStride and pname:sbtRecordOffset values are passed in as +parameters to fname:traceNV() calls made in the shaders. +See Section 8.19 (Ray Tracing Functions) of the OpenGL Shading Language +Specification for more details. + +The result of this computation is then added to +pname:hitProgramShaderBindingTableBaseIndex, a base index passed to +fname:vkCmdTraceRaysNV. + +The complete rule to compute a hit shader binding table record index is: + + :: [eq]#instanceShaderBindingTableRecordOffset {plus} + hitProgramShaderBindingTableBaseIndex {plus} geometryIndex {times} + sbtRecordStride {plus} sbtRecordOffset# + +==== Miss Shaders +A Miss shader is executed whenever a ray query fails to find an intersection +for the given scene geometry. +Multiple miss shaders can be executed throughout a ray tracing dispatch. + +The base for the computation of miss shader locations is +pname:missProgramShaderBindingTableBaseIndex, a base index passed into +fname:vkCmdTraceRaysNV. + +The pname:sbtRecordOffset value is passed in as parameters to +fname:traceNV() calls made in the shaders. +See Section 8.19 (Ray Tracing Functions) of the OpenGL Shading Language +Specification for more details. + +The complete rule to compute a miss shader binding table record address is: + + :: [eq]#missIndex {times} missShaderBindingStride {plus} sbtRecordOffset# + +[[acceleration-structure]] +== Acceleration Structures +_Acceleration structures_ are data structures used by the implementation to +efficiently manage the scene geometry as it is traversed during a ray +tracing query. +The application is responsible for managing acceleration structure objects +(see <>, +including allocation, destruction, executing builds or updates, and +synchronizing resources used uring ray tracing queries. + +There are two types of acceleration structures, _top level acceleration +structures_ and _bottom level acceleration structures_. + +[[fig-accelstruct]] +image::images/accelstruct.svg[align="center",title="Acceleration Structure",opts="{imageopts}"] + +.Caption +**** +The diagram shows the relationship between top and bottom level acceleration +structures. +**** + +[[acceleration-structure-instance]] +=== Instances +_Instances_ are found in top level acceleration structures and contain data +that refer to a single bottom-level acceleration structure, a transform +matrix, and shading information. +Multiple instances may point to a single bottom level acceleration +structure. + +An instance is defined in a VkBuffer by a structure consisting of 64 bytes +of data. + + * pname:transform is 12 floats representing a 4x3 transform matrix in + row-major order + * pname:instanceCustomIndex The low 24 bits of a 32-bit integer after the + transform. + This value appears in the builtin gl_InstanceCustomIndexNV + * pname:mask The high 8 bits of the same integer as instanceCustomIndex. + This is the visibility mask. + The instance can only be hit if rayMask & instance.mask != 0 + * pname:instanceOffset The low 24 bits of the next 32-bit integer. + The value contributed by this instance to the hit shader binding table + index computation as instanceShaderBindingTableRecordOffset. + * pname:flags The high 8 bits of the same integer as instanceOffset. + VkGeometryInstanceFlagBitsNV values that apply to this instance. + * pname:accelerationStructure. + The 8 byte value returned by vkGetAccelerationStructureHandleNV for the + bottom level acceleration structure referred to by this instance. + +[NOTE] +.Note +==== +The C language spec doesn't define the ordering of bit-fields, but in +practice, this struct produces the layout described above: + +[source,c] +--------------------------------------------------- +struct VkGeometryInstanceNV { + float transform[12]; + uint32_t instanceId : 24; + uint32_t mask : 8; + uint32_t instanceOffset : 24; + uint32_t flags : 8; + uint64_t accelerationStructureHandle; +}; +--------------------------------------------------- + +==== + +[open,refpage='VkGeometryInstanceFlagBitsNV',desc='Instance flag bits',type='enums'] +-- + +Possible values of pname:flags in the instance modifying the behavior of +that instance are:, + +include::../../api/enums/VkGeometryInstanceFlagBitsNV.txt[] + + * ename:VK_GEOMETRY_INSTANCE_TRIANGLE_CULL_DISABLE_BIT_NV disables face + culling for this instance. + * ename:VK_GEOMETRY_INSTANCE_TRIANGLE_FRONT_COUNTERCLOCKWISE_BIT_NV + indicates that the front face of the triangle for culling purposes + should be the face that's counter clockwise in object space relative to + the ray origin. + Because the facing is determined in object space, an instance transform + matrix does not changing winding, but a geometry transform does. + * ename:VK_GEOMETRY_INSTANCE_FORCE_OPAQUE_BIT_NV causes this instance to + act as though ename:VK_GEOMETRY_OPAQUE_BIT_NV were specified on all + geometries referenced by this instance. + This behavior can be overridden by the ray flag gl_RayFlagsNoOpaqueNV. + * ename:VK_GEOMETRY_INSTANCE_FORCE_NO_OPAQUE_BIT_NV causes this instance + to act as though ename:VK_GEOMETRY_NO_OPAQUE_BIT_NV were specified on + all geometries referenced by this instance. + This behavior can be overridden by the ray flag gl_RayFlagsOpaqueNV. + +ename:VK_GEOMETRY_INSTANCE_FORCE_NO_OPAQUE_BIT_NV and +ename:VK_GEOMETRY_INSTANCE_FORCE_OPAQUE_BIT_NV must: not be used in the same +flag. + +-- + +[[acceleration-structure-geometry]] +=== Geometry +_Geometries_ refer to a triangle or axis-aligned bounding box. + +[[acceleration-structure-top-level]] +=== Top Level Acceleration Structures +Opaque acceleration structure for an array of instances. +The descriptor referencing this is the starting point for tracing + +[[acceleration-structure-bottom-level]] +=== Bottom Level Acceleration Structures +Opaque acceleration structure for an array of geometries. + +[[acceleration-structure-building]] +=== Building Acceleration Structures +[open,refpage='vkCmdBuildAccelerationStructureNV',desc='Build an acceleration structure',type='protos'] +-- + +To build an acceleration structure call: + +include::../../api/protos/vkCmdBuildAccelerationStructureNV.txt[] + + * pname:commandBuffer is the command buffer into which the command will be + recorded + * pname:info contains the shared information for the acceleration + structure's structure + * pname:instanceData is the buffer containing instance data that will be + used to build the acceleration structure as described in + <> + This parameter must: be NULL for bottom level acceleration structures. + * pname:instanceOffset is the offset in bytes (relative to the start of + pname:instanceData) at which the instance data is located. + * pname:update specifies whether to update the pname:dst acceleration + structure with the data in pname:src. + * pname:dst points to the target acceleration structure for the build. + * pname:src points to an existing acceleration structure that can be used + to update the pname:dst acceleration structure. + * pname:scratch is the sname:VkBuffer that will be used as scratch memory + for the build. + * pname:scratchOffset is the offset in bytes relative to the start of + pname:scratch that will be used as scratch memory. + +.Valid Usage +**** + * [[VUID-vkCmdBuildAccelerationStructureNV-geometryCount-02241]] + pname:geometryCount must: be less than or equal to + sname:VkPhysicalDeviceRayTracingPropertiesNV::pname:maxGeometryCount + * [[VUID-vkCmdBuildAccelerationStructureNV-dst-02488]] + pname:dst must: have been created with compatible + sname:VkAccelerationStructureInfoNV where + sname:VkAccelerationStructureInfoNV:::pname:type and + sname:VkAccelerationStructureInfoNV::pname:flags are identical, + sname:VkAccelerationStructureInfoNV::pname:instanceCount and + sname:VkAccelerationStructureInfoNV::pname:geometryCount for pname:dst + are greater than or equal to the build size and each geometry in + sname:VkAccelerationStructureInfoNV::pname:pGeometries for pname:dst has + greater than or equal to the number of vertices, indices, and AABBs. + * [[VUID-vkCmdBuildAccelerationStructureNV-update-02489]] + If pname:update is true, pname:src must: not be ename:VK_NULL_HANDLE + * [[VUID-vkCmdBuildAccelerationStructureNV-update-02490]] + If pname:update is true, pname:src must: have been built last with + ename:VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_UPDATE_BIT_NV set in + sname:VkAccelerationStructureInfoNV::pname:flags + * [[VUID-vkCmdBuildAccelerationStructureNV-update-02491]] + If pname:update is false, The pname:size member of the + sname:VkMemoryRequirements structure returned from a call to + fname:vkGetAccelerationStructureMemoryRequirementsNV with + sname:VkAccelerationStructureMemoryRequirementsInfoNV::pname:accelerationStructure + set to pname:dst and + sname:VkAccelerationStructureMemoryRequirementsInfoNV::pname:type set to + ename:VK_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_BUILD_SCRATCH_NV + must: be less than or equal to the size of pname:scratch minus + pname:scratchOffset + * [[VUID-vkCmdBuildAccelerationStructureNV-update-02492]] + If pname:update is true, The pname:size member of the + sname:VkMemoryRequirements structure returned from a call to + fname:vkGetAccelerationStructureMemoryRequirementsNV with + sname:VkAccelerationStructureMemoryRequirementsInfoNV::pname:accelerationStructure + set to pname:dst and + sname:VkAccelerationStructureMemoryRequirementsInfoNV::pname:type set to + ename:VK_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_UPDATE_SCRATCH_NV + must: be less than or equal to the size of pname:scratch minus + pname:scratchOffset +**** + +include::../../validity/protos/vkCmdBuildAccelerationStructureNV.txt[] +-- + +[[acceleration-structure-copying]] +=== Copying Acceleration Structures + +An additional command exists for copying acceleration structures without +updating their contents. +The acceleration structure object may: be compacted in order to improve +performance. +Before copying, an application must: query the size of the resulting +acceleration structure. + +[open,refpage='vkCmdWriteAccelerationStructuresPropertiesNV',desc='Write acceleration structure result parameters to query results.',type='protos'] +-- + + +To query acceleration structure size parameters call: + +include::../../api/protos/vkCmdWriteAccelerationStructuresPropertiesNV.txt[] + + * pname:commandBuffer is the command buffer into which the command will be + recorded. + * pname:accelerationStructureCount is the count of acceleration structures + for which to query the property. + * pname:accelerationStructures points to an array of existing acceleration + structures which have been built. + * pname:queryType is a elink:VkQueryType value specifying the type of + queries managed by the pool. + * pname:queryPool is the query pool that will manage the results of the + query. + * pname:firstQuery is the first query index within the query pool that + will contain the pname:accelerationStructureCount number of results + +.Valid Usage +**** + * [[VUID-vkCmdWriteAccelerationStructuresPropertiesNV-queryType-02242]] + pname:queryType must: be + ename:VK_QUERY_TYPE_ACCELERATION_STRUCTURE_COMPACTED_SIZE_NV + * [[VUID-vkCmdWriteAccelerationStructuresPropertiesNV-queryPool-02493]] + pname:queryPool must: have been created with a pname:queryType matching + pname:queryType + * [[VUID-vkCmdWriteAccelerationStructuresPropertiesNV-queryPool-02494]] + The queries identified by pname:queryPool and pname:firstQuery must: be + _unavailable_ + * [[VUID-vkCmdWriteAccelerationStructuresPropertiesNV-accelerationStructures-02495]] + All acceleration structures in pname:accelerationStructures must: have + been built with + ename:VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_COMPACTION_BIT_NV if + pname:queryType is + ename:VK_QUERY_TYPE_ACCELERATION_STRUCTURE_COMPACTED_SIZE_NV +**** + +include::../../validity/protos/vkCmdWriteAccelerationStructuresPropertiesNV.txt[] + +-- + + +[open,refpage='vkCmdCopyAccelerationStructureNV',desc='Copy an acceleration structure',type='protos'] +-- + +To copy an acceleration structure call: + +include::../../api/protos/vkCmdCopyAccelerationStructureNV.txt[] + + * pname:commandBuffer is the command buffer into which the command will be + recorded. + * pname:dst points to the target acceleration structure for the copy + * pname:src points to the source acceleration structure for the copy + * pname:mode is a ename:VkCopyAccelerationStructureModeNV value that + specifies additional operations to perform during the copy. + +.Valid Usage +**** + * [[VUID-vkCmdCopyAccelerationStructureNV-mode-02496]] + pname:mode must: be ename:VK_COPY_ACCELERATION_STRUCTURE_MODE_COMPACT_NV + or ename:VK_COPY_ACCELERATION_STRUCTURE_MODE_CLONE_NV + * [[VUID-vkCmdCopyAccelerationStructureNV-src-02497]] + pname:src must: have been built with + ename:VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_COMPACTION_BIT_NV if + pname:mode is ename:VK_COPY_ACCELERATION_STRUCTURE_MODE_COMPACT_NV +**** + +include::../../validity/protos/vkCmdCopyAccelerationStructureNV.txt[] + +-- + +[open,refpage='VkCopyAccelerationStructureModeNV',desc='Acceleration structure copy mode',type='enums'] +-- + +Possible values of slink:vkCmdCopyAccelerationStructureNV::pname:mode, +specifying additional operations to perform during the copy, are: + +include::../../api/enums/VkCopyAccelerationStructureModeNV.txt[] + + * ename:VK_COPY_ACCELERATION_STRUCTURE_MODE_CLONE_NV creates a direct copy + of the acceleration structure specified in pname:src into the one + specified by pname:dst. + The pname:dst acceleration structure must: have been created with the + same parameters as pname:src. + * ename:VK_COPY_ACCELERATION_STRUCTURE_MODE_COMPACT_NV creates a more + compact version of an acceleration structure pname:src into pname:dst. + The acceleration structure pname:dst must: have been created with a + pname:compactedSize corresponding to the one returned by + slink:vkCmdWriteAccelerationStructurePropertiesNV after the build of the + acceleration structure specified by pname:src. + +-- diff --git a/chapters/copies.txt b/chapters/copies.txt index 594d0651..8d59c6fe 100644 --- a/chapters/copies.txt +++ b/chapters/copies.txt @@ -1118,7 +1118,7 @@ do not support graphics. ifndef::VK_EXT_depth_range_unrestricted[] When copying to a depth aspect, the data in buffer memory must: be in the -the range [eq]#[0,1]#, or the resulting values are undefined:. +range [eq]#[0,1]#, or the resulting values are undefined:. endif::VK_EXT_depth_range_unrestricted[] Copies are done layer by layer starting with image layer diff --git a/chapters/descriptorsets.txt b/chapters/descriptorsets.txt index 1359bd83..613fe9a9 100644 --- a/chapters/descriptorsets.txt +++ b/chapters/descriptorsets.txt @@ -318,7 +318,6 @@ ename:VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL, or ename:VK_IMAGE_LAYOUT_GENERAL layout in order to access its data in a shader. - [[descriptorsets-sets]] == Descriptor Sets @@ -1548,6 +1547,14 @@ ifdef::VK_KHR_push_descriptor[] that was created with ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_PUSH_DESCRIPTOR_BIT_KHR set endif::VK_KHR_push_descriptor[] +ifdef::VK_NV_ray_tracing[] + * [[VUID-VkPipelineLayoutCreateInfo-descriptorType-02381]] + The total number of bindings with a pname:descriptorType of + ename:VK_DESCRIPTOR_TYPE_ACCELERATION_STRUCTURE_NV accessible across all + shader stages and across all elements of pname:pSetLayouts must: be less + than or equal to + sname:VkPhysicalDeviceRayTracingPropertiesNV::pname:maxDescriptorSetAccelerationStructures +endif::VK_NV_ray_tracing[] **** include::../validity/structs/VkPipelineLayoutCreateInfo.txt[] @@ -1696,6 +1703,10 @@ or pname:maxDescriptorSetUpdateAfterBindInlineUniformBlocks endif::VK_EXT_descriptor_indexing[] | inline uniform block endif::VK_EXT_inline_uniform_block[] +ifdef::VK_NV_ray_tracing[] +| pname:maxDescriptorSetAccelerationStructures + | acceleration structure +endif::VK_NV_ray_tracing[] |==== @@ -2455,6 +2466,11 @@ ifdef::VK_EXT_inline_uniform_block[] , or a value matching the pname:dataSize member of an instance of slink:VkWriteDescriptorSetInlineUniformBlockEXT in the pname:pNext chain endif::VK_EXT_inline_uniform_block[] +ifdef::VK_NV_ray_tracing[] + , or a value matching the pname:accelerationStructureCount of an + instance of slink:VkWriteDescriptorSetAccelerationStructureNV in the + pname:pNext chain +endif::VK_NV_ray_tracing[] ). ifdef::VK_EXT_inline_uniform_block[] If the descriptor binding identified by pname:dstSet and @@ -2488,6 +2504,13 @@ data for the descriptor writes is taken from the instance of slink:VkWriteDescriptorSetInlineUniformBlockEXT in the pname:pNext chain of sname:VkWriteDescriptorSet, endif::VK_EXT_inline_uniform_block[] +ifdef::VK_NV_ray_tracing[] +or if pname:descriptorType is +ename:VK_DESCRIPTOR_TYPE_ACCELERATION_STRUCTURE_NV, in which case the source +data for the descriptor writes is taken from the instance of +slink:VkWriteDescriptorSetAccelerationStructureNV in the pname:pNext chain +of sname:VkWriteDescriptorSet, +endif::VK_NV_ray_tracing[] as specified below. [[descriptorsets-updates-consecutive, consecutive binding updates]] @@ -2593,6 +2616,14 @@ ifdef::VK_EXT_inline_uniform_block[] must: include a slink:VkWriteDescriptorSetInlineUniformBlockEXT structure whose pname:dataSize member equals pname:descriptorCount endif::VK_EXT_inline_uniform_block[] +ifdef::VK_NV_ray_tracing[] + * [[VUID-VkWriteDescriptorSet-descriptorType-02382]] + If pname:descriptorType is + ename:VK_DESCRIPTOR_TYPE_ACCELERATION_STRUCTURE_NV, the pname:pNext + chain must: include a slink:VkWriteDescriptorSetAccelerationStructureNV + structure whose pname:accelerationStructureCount member equals + pname:descriptorCount +endif::VK_NV_ray_tracing[] ifdef::VULKAN_1_1,VK_KHR_sampler_ycbcr_conversion[] * [[VUID-VkWriteDescriptorSet-descriptorType-01946]] If pname:descriptorType is ename:VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE, then @@ -2781,6 +2812,14 @@ accessed, instead the source data of the descriptor update operation is taken from the instance of slink:VkWriteDescriptorSetInlineUniformBlockEXT in the pname:pNext chain of sname:VkWriteDescriptorSet. endif::VK_EXT_inline_uniform_block[] +ifdef::VK_NV_ray_tracing[] +When updating descriptors with a pname:descriptorType of +ename:VK_DESCRIPTOR_TYPE_ACCELERATION_STRUCTURE_NV, none of the +pname:pImageInfo, pname:pBufferInfo, or pname:pTexelBufferView members are +accessed, instead the source data of the descriptor update operation is +taken from the instance of slink:VkWriteDescriptorSetAccelerationStructureNV +in the pname:pNext chain of sname:VkWriteDescriptorSet. +endif::VK_NV_ray_tracing[] -- [open,refpage='VkDescriptorBufferInfo',desc='Structure specifying descriptor buffer info',type='structs'] @@ -2921,6 +2960,10 @@ include::../validity/structs/VkWriteDescriptorSetInlineUniformBlockEXT.txt[] -- endif::VK_EXT_inline_uniform_block[] +ifdef::VK_NV_ray_tracing[] +include::VK_NV_ray_tracing/raytracing-descriptors.txt[] +endif::VK_NV_ray_tracing[] + [open,refpage='VkCopyDescriptorSet',desc='Structure specifying a copy descriptor set operation',type='structs'] -- @@ -3911,7 +3954,3 @@ created on are ignored. include::../validity/protos/vkCmdPushConstants.txt[] -- - -ifdef::VK_NVX_raytracing[] -include::VK_NVX_raytracing/raytracing-descriptors.txt[] -endif::VK_NVX_raytracing[] \ No newline at end of file diff --git a/chapters/devsandqueues.txt b/chapters/devsandqueues.txt index e65270e1..d386bd3a 100644 --- a/chapters/devsandqueues.txt +++ b/chapters/devsandqueues.txt @@ -1042,6 +1042,52 @@ include::../validity/structs/VkDeviceGroupDeviceCreateInfo.txt[] endif::VK_VERSION_1_1,VK_KHR_device_group_creation[] +ifdef::VK_AMD_memory_overallocation_behavior[] + +[open,refpage='VkDeviceMemoryOverallocationCreateInfoAMD',desc='Specify memory overallocation behavior for a Vulkan device',type='structs'] +-- + +To specify whether device memory allocation is allowed beyond the size +reported by slink:VkPhysicalDeviceMemoryProperties, add a +slink:VkDeviceMemoryOverallocationCreateInfoAMD structure to the pname:pNext +chain of the slink:VkDeviceCreateInfo structure. +If this structure is not specified, it is as if the +VK_MEMORY_OVERALLOCATION_BEHAVIOR_DEFAULT_AMD value is used. + +include::../api/structs/VkDeviceMemoryOverallocationCreateInfoAMD.txt[] + + * pname:sType is the type of this structure. + * pname:pNext is `NULL` or a pointer to an extension-specific structure. + * pname:overallocationBehavior is the desired overallocation behavior. + +include::../validity/structs/VkDeviceMemoryOverallocationCreateInfoAMD.txt[] +-- + +[open,refpage='VkMemoryOverallocationBehaviorAMD',desc='Specify memory overallocation behavior',type='enums'] +-- + +Possible values for +slink:VkDeviceMemoryOverallocationCreateInfoAMD::overallocationBehavior +include: + +include::../api/enums/VkMemoryOverallocationBehaviorAMD.txt[] + + * ename:VK_MEMORY_OVERALLOCATION_BEHAVIOR_DEFAULT_AMD lets the + implementation decide if overallocation should be allowed. + * ename:VK_MEMORY_OVERALLOCATION_BEHAVIOR_ALLOWED_AMD specifies + overallocation is allowed if platform permits. + * ename:VK_MEMORY_OVERALLOCATION_BEHAVIOR_DISALLOWED_AMD specifies the + application is not allowed to allocate device memory beyond the heap + sizes reported by slink:VkPhysicalDeviceMemoryProperties. + Allocations that are not explicitly made by the application within the + scope of the Vulkan instance are not accounted for. + +-- + +endif::VK_AMD_memory_overallocation_behavior[] + + + [[devsandqueues-use]] === Device Use diff --git a/chapters/dispatch.txt b/chapters/dispatch.txt index dd808818..63b08301 100644 --- a/chapters/dispatch.txt +++ b/chapters/dispatch.txt @@ -100,14 +100,14 @@ is assembled. buffer, it must: not access values outside of the range of that buffer specified in the bound descriptor set * [[VUID-vkCmdDispatch-None-02005]] - If a sname:VkImageView is sampled with with ename:VK_FILTER_LINEAR as a + If a sname:VkImageView is sampled with ename:VK_FILTER_LINEAR as a result of this command, then the image view's <> must: contain ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BIT. ifdef::VK_IMG_filter_cubic[] * [[VUID-vkCmdDispatch-None-02006]] - If a sname:VkImageView is sampled with with ename:VK_FILTER_CUBIC_IMG as - a result of this command, then the image view's + If a sname:VkImageView is sampled with ename:VK_FILTER_CUBIC_IMG as a + result of this command, then the image view's <> must: contain ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_CUBIC_BIT_IMG. * [[VUID-vkCmdDispatch-None-00400]] @@ -236,14 +236,14 @@ at pname:offset. buffer, it must: not access values outside of the range of that buffer specified in the bound descriptor set * [[VUID-vkCmdDispatchIndirect-None-02007]] - If a sname:VkImageView is sampled with with ename:VK_FILTER_LINEAR as a + If a sname:VkImageView is sampled with ename:VK_FILTER_LINEAR as a result of this command, then the image view's <> must: contain ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BIT. ifdef::VK_IMG_filter_cubic[] * [[VUID-vkCmdDispatchIndirect-None-02008]] - If a sname:VkImageView is sampled with with ename:VK_FILTER_CUBIC_IMG as - a result of this command, then the image view's + If a sname:VkImageView is sampled with ename:VK_FILTER_CUBIC_IMG as a + result of this command, then the image view's <> must: contain ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_CUBIC_BIT_IMG. * [[VUID-vkCmdDispatchIndirect-None-00416]] diff --git a/chapters/drawing.txt b/chapters/drawing.txt index a2e5596e..456296ef 100644 --- a/chapters/drawing.txt +++ b/chapters/drawing.txt @@ -2362,14 +2362,14 @@ The effective pname:firstVertex is zero. Image subresources used as attachments in the current render pass must: not be accessed in any way other than as an attachment by this command * [[VUID-vkCmdDrawIndirectByteCountEXT-None-02305]] - If a sname:VkImageView is sampled with with ename:VK_FILTER_LINEAR as a + If a sname:VkImageView is sampled with ename:VK_FILTER_LINEAR as a result of this command, then the image view's <> must: contain ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BIT ifdef::VK_IMG_filter_cubic[] * [[VUID-vkCmdDrawIndirectByteCountEXT-None-02306]] - If a sname:VkImageView is sampled with with ename:VK_FILTER_CUBIC_IMG as - a result of this command, then the image view's + If a sname:VkImageView is sampled with ename:VK_FILTER_CUBIC_IMG as a + result of this command, then the image view's <> must: contain ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_CUBIC_BIT_IMG * [[VUID-vkCmdDrawIndirectByteCountEXT-None-02307]] diff --git a/chapters/features.txt b/chapters/features.txt index fc62ff08..08c8d842 100644 --- a/chapters/features.txt +++ b/chapters/features.txt @@ -3798,6 +3798,37 @@ it is filled with the implementation-dependent limits and properties. endif::VK_EXT_transform_feedback[] + +ifdef::VK_NV_ray_tracing[] + +[open,refpage='VkPhysicalDeviceRayTracingPropertiesNV',desc='Properties of the physical device for ray tracing',type='structs'] +-- +The sname:VkPhysicalDeviceRayTracingPropertiesNV structure is defined as: + +include::../api/structs/VkPhysicalDeviceRayTracingPropertiesNV.txt[] + + * pname:sType is the type of this structure. + * pname:pNext is `NULL` or a pointer to an extension-specific structure. + * pname:shaderHeaderSize size in bytes of the shader header. + * pname:maxRecursionDepth is the maximum number of levels of recursion + allowed in a trace command. + * pname:maxShaderGroupStride is the maximum stride in bytes allowed + between shader groups in the SBT. + * pname:shaderGroupBaseAlignment is the required alignment in bytes for + the base of the SBTs. + * pname:maxGeometryCount is the maximum number of geometries in the bottom + level acceleration structure. + * pname:maxInstanceCount is the maximum number of instances in the top + level acceleration structure. + * pname:maxTriangleCount is the maximum number of triangles in all + geometries in the bottom level acceleration structure. + * pname:maxDescriptorSetAccelerationStructures is the maximum number of + acceleration structure descriptors that are allowed in a descriptor set. + +include::../validity/structs/VkPhysicalDeviceRayTracingPropertiesNV.txt[] +-- +endif::VK_NV_ray_tracing[] + [[features-limits-minmax]] === Limit Requirements diff --git a/chapters/interfaces.txt b/chapters/interfaces.txt index a04c5b68..c2a4453b 100755 --- a/chapters/interfaces.txt +++ b/chapters/interfaces.txt @@ -691,6 +691,9 @@ endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] ifdef::VK_EXT_inline_uniform_block[] | inline uniform block | ename:VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK_EXT endif::VK_EXT_inline_uniform_block[] +ifdef::VK_NV_ray_tracing[] +| acceleration structure | ename:VK_DESCRIPTOR_TYPE_ACCELERATION_STRUCTURE +endif::VK_NV_ray_tracing[] |==== [[interfaces-resources-storage-class-correspondence]] @@ -734,6 +737,10 @@ ifdef::VK_EXT_inline_uniform_block[] | code:Uniform | code:OpTypeStruct | code:Block, code:Offset, (code:ArrayStride), (code:MatrixStride) endif::VK_EXT_inline_uniform_block[] +ifdef::VK_NV_ray_tracing[] +| acceleration structure + | code:UniformConstant | code:OpTypeAccelerationStructureNV +endif::VK_NV_ray_tracing[] |==== 1:: in addition to code:DescriptorSet and code:Binding @@ -1549,49 +1556,65 @@ It is very likely that a helper invocation will have a value of code:SampleMask fragment shader input value that is zero. ==== -ifdef::VK_NVX_raytracing[] +ifdef::VK_NV_ray_tracing[] [[interfaces-builtin-variables-hitkind]] -code:HitKindNVX:: +code:HitKindNV:: -A variable decorated with the code:HitKindNVX decoration will describe the +A variable decorated with the code:HitKindNV decoration will describe the intersection that triggered the execution of the current shader. The values are determined by the intersection shader. + -The code:HitKindNVX decoration must: only be used in any hit and closest hit +The code:HitKindNV decoration must: only be used in any hit and closest hit shaders. + -Any variable decorated with code:HitKindNVX must: be declared using the +Any variable decorated with code:HitKindNV must: be declared using the code:Input storage class. + -Any variable decorated with code:HitKindNVX must: be declared as a scalar +Any variable decorated with code:HitKindNV must: be declared as a scalar 32-bit integer. [[interfaces-builtin-variables-hitt]] -code:HitTNVX:: +code:HitTNV:: -A variable decorated with the code:HitTNVX decoration is equivalent to a -variable decorated with the code:RayTmaxNVX decoration. +A variable decorated with the code:HitTNV decoration is equivalent to a +variable decorated with the code:RayTmaxNV decoration. + -The code:HitTNVX decoration must: only be used in any hit and closest hit +The code:HitTNV decoration must: only be used in any hit and closest hit shaders. [[interfaces-builtin-variables-instancecustomindex]] -code:InstanceCustomIndexNVX:: +code:InstanceCustomIndexNV:: -A variable decorated with the code:InstanceCustomIndexNVX decoration will +A variable decorated with the code:InstanceCustomIndexNV decoration will contain the application-defined value of the instance that intersects the current ray. Only the lower 24 bits are valid, the upper 8 bits will be ignored. + -The code:InstanceCustomIndexNVX decoration must: only be used in the +The code:InstanceCustomIndexNV decoration must: only be used in the intersection, any hit, and closest hit shaders. + -Any variable decorated with code:InstanceCustomIndexNVX must: be declared +Any variable decorated with code:InstanceCustomIndexNV must: be declared using the code:Input storage class. + -Any variable decorated with code:InstanceCustomIndexNVX must: be declared as +Any variable decorated with code:InstanceCustomIndexNV must: be declared as a scalar 32-bit integer. -endif::VK_NVX_raytracing[] + +[[interfaces-builtin-variables-incomingrayflags]] +code:IncomingRayFlagsNV:: + +A variable with the code:IncomingRayFlagsNV decoration will contain the ray +flags passed in to the trace call that invoked this particular shader. ++ +The code:InstanceCustomIndexNV decoration must: only be used in the +intersection, any hit, closest hit and miss shaders. ++ +Any variable decorated with code:InstanceCustomIndexNV must: be declared +using the code:Input storage class. ++ +Any variable decorated with code:InstanceCustomIndexNV must: be declared as +a scalar 32-bit integer. + +endif::VK_NV_ray_tracing[] code:InvocationId:: @@ -1650,17 +1673,17 @@ flink:vkCmdDraw or flink:vkCmdDrawIndexed or at the pname:firstInstance member of a structure consumed by flink:vkCmdDrawIndirect or flink:vkCmdDrawIndexedIndirect. -ifdef::VK_NVX_raytracing[] +ifdef::VK_NV_ray_tracing[] + Decorating a variable in an intersection, any hit, or closest hit shader with the code:InstanceIndex decoration will make that variable contain the index of the instance that intersects the current ray. -endif::VK_NVX_raytracing[] +endif::VK_NV_ray_tracing[] + The code:InstanceIndex decoration must: be used only within -ifdef::VK_NVX_raytracing[] +ifdef::VK_NV_ray_tracing[] intersection, any hit, closest hit, or -endif::VK_NVX_raytracing[] +endif::VK_NV_ray_tracing[] vertex shaders. + The variable decorated with code:InstanceIndex must: be declared using the @@ -1669,44 +1692,44 @@ code:Input storage class. The variable decorated with code:InstanceIndex must: be declared as a scalar 32-bit integer. -ifdef::VK_NVX_raytracing[] +ifdef::VK_NV_ray_tracing[] [[interfaces-builtin-variables-launchid]] -code:LaunchIDNVX:: +code:LaunchIDNV:: -A variable decorated with the code:LaunchIDNVX decoration will specify the +A variable decorated with the code:LaunchIDNV decoration will specify the index of the work item being process. One work item is generated for each of the pname:width {times} pname:height -items dispatched by a flink:vkCmdTraceRaysNVX command. +items dispatched by a flink:vkCmdTraceRaysNV command. All shader invocations inherit the same value for variables decorated with -code:LaunchIDNVX. +code:LaunchIDNV. + -The code:LaunchIDNVX decoration must: only be used within the ray -generation, intersection, any hit, closest hit, and miss shaders. +The code:LaunchIDNV decoration must: only be used within the ray generation, +intersection, any hit, closest hit, and miss shaders. + -Any variable decorated with code:LaunchIDNVX must: be declared using the +Any variable decorated with code:LaunchIDNV must: be declared using the code:Input storage class. + -Any variable decorated with code:LaunchIDNVX must: be declared as a +Any variable decorated with code:LaunchIDNV must: be declared as a two-component vector of 32-bit floating-point values. [[interfaces-builtin-variables-launchsize]] -code:LaunchSizeNVX:: +code:LaunchSizeNV:: -A variable decorated with the code:LaunchSizeNVX decoration will contain the -pname:width and pname:height dimensions passed to the -flink:vkCmdTraceRaysNVX command that initiated this shader execution. +A variable decorated with the code:LaunchSizeNV decoration will contain the +pname:width and pname:height dimensions passed to the flink:vkCmdTraceRaysNV +command that initiated this shader execution. The pname:width is in the first component, and the pname:height is in the second component. + -The code:LaunchSizeNVX decoration must: only be used within ray generation, +The code:LaunchSizeNV decoration must: only be used within ray generation, intersection, any hit, closest hit, and miss shaders. + -Any variable decorated with code:LaunchSizeNVX must: be declared using the +Any variable decorated with code:LaunchSizeNV must: be declared using the code:Input storage class. + -Any variable decorated with code:LaunchSizeNVX must: be declared as a +Any variable decorated with code:LaunchSizeNV must: be declared as a two-component vector of 32-bit floating-point values. -endif::VK_NVX_raytracing[] +endif::VK_NV_ray_tracing[] [[interfaces-builtin-variables-layer]] code:Layer:: @@ -1936,54 +1959,54 @@ code:Input storage class. The variable decorated with code:NumWorkgroups must: be declared as a three-component vector of 32-bit integers. -ifdef::VK_NVX_raytracing[] +ifdef::VK_NV_ray_tracing[] [[interfaces-builtin-variables-objectraydirection]] -code:ObjectRayDirectionNVX:: +code:ObjectRayDirectionNV:: -A variable decorated with the code:ObjectRayDirectionNVX decoration will +A variable decorated with the code:ObjectRayDirectionNV decoration will specify the direction of the ray being processed, in object space. + -The code:ObjectRayDirectionNVX decoration must: only be used within +The code:ObjectRayDirectionNV decoration must: only be used within intersection, any hit, closest hit, and miss shaders. + -Any variable decorated with code:ObjectRayDirectionNVX must: be declared +Any variable decorated with code:ObjectRayDirectionNV must: be declared using the code:Input storage class. + -Any variable decorated with code:ObjectRayDirectionNVX must: be declared as -a three-component vector of 32-bit floating-point values. +Any variable decorated with code:ObjectRayDirectionNV must: be declared as a +three-component vector of 32-bit floating-point values. [[interfaces-builtin-variables-objectrayorigin]] -code:ObjectRayOriginNVX:: +code:ObjectRayOriginNV:: -A variable decorated with the code:ObjectRayOriginNVX decoration will -specify the origin of the ray being processed, in object space. +A variable decorated with the code:ObjectRayOriginNV decoration will specify +the origin of the ray being processed, in object space. + -The code:ObjectRayOriginNVX decoration must: only be used within +The code:ObjectRayOriginNV decoration must: only be used within intersection, any hit, closest hit, and miss shaders. + -Any variable decorated with code:ObjectRayOriginNVX must: be declared using +Any variable decorated with code:ObjectRayOriginNV must: be declared using the code:Input storage class. + -Any variable decorated with code:ObjectRayOriginNVX must: be declared as a +Any variable decorated with code:ObjectRayOriginNV must: be declared as a three-component vector of 32-bit floating-point values. [[interfaces-builtin-variables-objecttoworld]] -code:ObjectToWorldNVX:: +code:ObjectToWorldNV:: -A variable decorated with the code:ObjectToWorldNVX decoration will contain +A variable decorated with the code:ObjectToWorldNV decoration will contain the current object-to-world transformation matrix, which is determined by the instance of the current intersection. + -The code:ObjectToWorldNVX decoration must: only be used within intersection, +The code:ObjectToWorldNV decoration must: only be used within intersection, any hit, and closest hit shaders. + -Any variable decorated with code:ObjectToWorldNVX must: be declared using -the code:Input storage class. +Any variable decorated with code:ObjectToWorldNV must: be declared using the +code:Input storage class. + -Any variable decorated with code:ObjectToWorldNVX must: be declared as a +Any variable decorated with code:ObjectToWorldNV must: be declared as a matrix with four columns of three-component vectors of 32-bit floating-point values. -endif::VK_NVX_raytracing[] +endif::VK_NV_ray_tracing[] code:PatchVertices:: @@ -2195,11 +2218,11 @@ In a fragment shader, it will contain the primitive index written by the geometry shader if a geometry shader is present, or with the value that would have been presented as input to the geometry shader had it been present. -ifdef::VK_NVX_raytracing[] +ifdef::VK_NV_ray_tracing[] + In an intersection, any hit, or closest hit shader, it will contain the index of the triangle or bounding box being processed. -endif::VK_NVX_raytracing[] +endif::VK_NV_ray_tracing[] + If a geometry shader is present and the fragment shader reads from an input variable decorated with code:PrimitiveId, then the geometry shader must: @@ -2217,19 +2240,19 @@ The code:PrimitiveId decoration must: be used only within ifdef::VK_NV_mesh_shader[] mesh, endif::VK_NV_mesh_shader[] -ifdef::VK_NVX_raytracing[] +ifdef::VK_NV_ray_tracing[] intersection, any hit, closest hit, -endif::VK_NVX_raytracing[] +endif::VK_NV_ray_tracing[] fragment, tessellation control, tessellation evaluation, and geometry shaders. + In -ifdef::VK_NVX_raytracing[] +ifdef::VK_NV_ray_tracing[] an intersection, any hit, closest hit, -endif::VK_NVX_raytracing[] -ifndef::VK_NVX_raytracing[] +endif::VK_NV_ray_tracing[] +ifndef::VK_NV_ray_tracing[] a -endif::VK_NVX_raytracing[] +endif::VK_NV_ray_tracing[] tessellation control, or tessellation evaluation shader, any variable decorated with code:PrimitiveId must: be declared using the code:Input storage class. @@ -2293,11 +2316,11 @@ code:OutputPrimitivesNV execution modes, where the size is: execution mode is code:OutputTrianglesNV. endif::VK_NV_mesh_shader[] -ifdef::VK_NVX_raytracing[] +ifdef::VK_NV_ray_tracing[] [[interfaces-builtin-variables-raytmax]] -code:RayTmaxNVX:: +code:RayTmaxNV:: -A variable decorated with the code:RayTmaxNVX decoration will contain the +A variable decorated with the code:RayTmaxNV decoration will contain the parametric pname:tmax values of the ray being processed. The values are independent of the space in which the ray and origin exist. + @@ -2310,38 +2333,38 @@ being intersected. In the intersection shader, it reflects the distance to the closest primitive intersected so far. The value can change in the intersection shader after calling -code:OpReportIntersectionNVX if the corresponding any hit shader does not +code:OpReportIntersectionNV if the corresponding any hit shader does not ignore the intersection. In a miss shader, the value is identical to the parameter passed into -code:OpTraceNVX. +code:OpTraceNV. + -The code:RayTmaxNVX decoration must: only be used with the intersection, any +The code:RayTmaxNV decoration must: only be used with the intersection, any hit, closest hit, and miss shaders. + -Any variable decorated with code:RayTmaxNVX must: be declared with the +Any variable decorated with code:RayTmaxNV must: be declared with the code:Input storage class. + -Any variable decorated with code:RayTmaxNVX must: be declared as a scalar +Any variable decorated with code:RayTmaxNV must: be declared as a scalar 32-bit floating-point value. [[interfaces-builtin-variables-raytmin]] -code:RayTminNVX:: +code:RayTminNV:: -A variable decorated with the code:RayTminNVX decoration will contain the +A variable decorated with the code:RayTminNV decoration will contain the parametric code:tmin values of the ray being processed. The values are independent of the space in which the ray and origin exist. + The code:tmin value remains constant for the duration of the ray query. + -The code:RayTminNVX decoration must: only be used with the intersection, any +The code:RayTminNV decoration must: only be used with the intersection, any hit, closest hit, and miss shaders. + -Any variable decorated with code:RayTminNVX must: be declared with the +Any variable decorated with code:RayTminNV must: be declared with the code:Input storage class. + -Any variable decorated with code:RayTminNVX must: be declared as a scalar +Any variable decorated with code:RayTminNV must: be declared as a scalar 32-bit floating-point value. -endif::VK_NVX_raytracing[] +endif::VK_NV_ray_tracing[] code:SampleId:: @@ -2963,51 +2986,51 @@ constant or a constant. The object decorated with code:WorkgroupSize must: be declared as a three-component vector of 32-bit integers. -ifdef::VK_NVX_raytracing[] +ifdef::VK_NV_ray_tracing[] [[interfaces-builtin-variables-worldraydirection]] -code:WorldRayDirectionNVX:: +code:WorldRayDirectionNV:: -A variable decorated with the code:WorldRayDirectionNVX decoration will +A variable decorated with the code:WorldRayDirectionNV decoration will specify the direction of the ray being processed, in world space. + -The code:WorldRayDirectionNVX decoration must: only be used within +The code:WorldRayDirectionNV decoration must: only be used within intersection, any hit, closest hit, and miss shaders. + -Any variable decorated with code:WorldRayDirectionNVX must: be declared -using the code:Input storage class. +Any variable decorated with code:WorldRayDirectionNV must: be declared using +the code:Input storage class. + -Any variable decorated with code:WorldRayDirectionNVX must: be declared as a +Any variable decorated with code:WorldRayDirectionNV must: be declared as a three-component vector of 32-bit floating-point values. [[interfaces-builtin-variables-worldrayorigin]] -code:WorldRayOriginNVX:: +code:WorldRayOriginNV:: -A variable decorated with the code:WorldRayOriginNVX decoration will specify +A variable decorated with the code:WorldRayOriginNV decoration will specify the origin of the ray being processed, in world space. + -The code:WorldRayOriginNVX decoration must: only be used within -intersection, any hit, closest hit, and miss shaders. +The code:WorldRayOriginNV decoration must: only be used within intersection, +any hit, closest hit, and miss shaders. + -Any variable decorated with code:WorldRayOriginNVX must: be declared using +Any variable decorated with code:WorldRayOriginNV must: be declared using the code:Input storage class. + -Any variable decorated with code:WorldRayOriginNVX must: be declared as a +Any variable decorated with code:WorldRayOriginNV must: be declared as a three-component vector of 32-bit floating-point values. [[interfaces-builtin-variables-worldtoobject]] -code:WorldToObjectNVX:: +code:WorldToObjectNV:: -A variable decorated with the code:WorldToObjectNVX decoration will contain +A variable decorated with the code:WorldToObjectNV decoration will contain the current world-to-object transformation matrix, which is determined by the instance of the current intersection. + -The code:WorldToObjectNVX decoration must: only be used within intersection, +The code:WorldToObjectNV decoration must: only be used within intersection, any hit, and closest hit shaders. + -Any variable decorated with code:WorldToObjectNVX must: be declared using -the code:Input storage class. +Any variable decorated with code:WorldToObjectNV must: be declared using the +code:Input storage class. + -Any variable decorated with code:WorldToObjectNVX must: be declared as a +Any variable decorated with code:WorldToObjectNV must: be declared as a matrix with four columns of three-component vectors of 32-bit floating-point values. -endif::VK_NVX_raytracing[] +endif::VK_NV_ray_tracing[] diff --git a/chapters/memory.txt b/chapters/memory.txt index 3afe713f..07926ec2 100644 --- a/chapters/memory.txt +++ b/chapters/memory.txt @@ -877,6 +877,18 @@ This limit is advertised in slink:VkPhysicalDeviceMaintenance3Properties::pname:maxMemoryAllocationSize. endif::VK_KHR_maintenance3[] +ifdef::VK_AMD_memory_overallocation_behavior[] + +The cumulative memory size allocated to a heap can: be limited by the size +of the specified heap. +In such cases, allocated memory is tracked on a per-device and per-heap +basis. +Some platforms allow overallocation into other heaps. +The overallocation behavior can: be specified through the +slink:VK_AMD_memory_overallocation_behavior extension. + +endif::VK_AMD_memory_overallocation_behavior[] + .Valid Usage **** * [[VUID-vkAllocateMemory-pAllocateInfo-01713]] @@ -1078,22 +1090,32 @@ ifdef::VK_EXT_external_memory_host[] sname:VkPhysicalDeviceExternalMemoryHostPropertiesEXT::pname:minImportedHostPointerAlignment endif::VK_EXT_external_memory_host[] ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] - * [[VUID-VkMemoryAllocateInfo-None-01873]] + * [[VUID-VkMemoryAllocateInfo-allocationSize-02383]] If the parameters define an import operation and the external handle type is - ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID: - ** pname:allocationSize must: be the size returned by - flink:vkGetAndroidHardwareBufferPropertiesANDROID for the Android - hardware buffer - ** If the pname:pNext chain does not contain an instance of - slink:VkMemoryDedicatedAllocateInfo or - pname:VkMemoryDedicatedAllocateInfo::pname:image is - dlink:VK_NULL_HANDLE, the Android hardware buffer must: have a format - of code:AHARDWAREBUFFER_FORMAT_BLOB and a usage that includes - code:AHARDWAREBUFFER_USAGE_GPU_DATA_BUFFER - ** pname:memoryTypeIndex must: be one of those returned by - flink:vkGetAndroidHardwareBufferPropertiesANDROID for the Android - hardware buffer + ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID, + pname:allocationSize must: be the size returned by + flink:vkGetAndroidHardwareBufferPropertiesANDROID for the Android + hardware buffer. + * [[VUID-VkMemoryAllocateInfo-pNext-02384]] + If the parameters define an import operation and the external handle + type is + ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID, + and the pname:pNext chain does not contain an instance of + slink:VkMemoryDedicatedAllocateInfo or + pname:VkMemoryDedicatedAllocateInfo::pname:image is + dlink:VK_NULL_HANDLE, the Android hardware buffer must: have a + code:AHardwareBuffer_Desc::code:format of + code:AHARDWAREBUFFER_FORMAT_BLOB and a + code:AHardwareBuffer_Desc::code:usage that includes + code:AHARDWAREBUFFER_USAGE_GPU_DATA_BUFFER. + * [[VUID-VkMemoryAllocateInfo-memoryTypeIndex-02385]] + If the parameters define an import operation and the external handle + type is + ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID, + pname:memoryTypeIndex must: be one of those returned by + flink:vkGetAndroidHardwareBufferPropertiesANDROID for the Android + hardware buffer. * [[VUID-VkMemoryAllocateInfo-pNext-01874]] If the parameters do not define an import operation, and the pname:pNext chain contains an instance of sname:VkExportMemoryAllocateInfo with @@ -1102,29 +1124,49 @@ ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] an instance of slink:VkMemoryDedicatedAllocateInfo with pname:image not equal to dlink:VK_NULL_HANDLE, then pname:allocationSize must: be `0`, otherwise pname:allocationSize must: be greater than `0`. - * [[VUID-VkMemoryAllocateInfo-pNext-01875]] + * [[VUID-VkMemoryAllocateInfo-pNext-02386]] If the parameters define an import operation, the external handle is an Android hardware buffer, and the pname:pNext chain includes an instance of slink:VkMemoryDedicatedAllocateInfo with pname:image that is not - dlink:VK_NULL_HANDLE: - ** The Android hardware buffer's usage must: include at least one of - code:AHARDWAREBUFFER_USAGE_GPU_COLOR_OUTPUT or - code:AHARDWAREBUFFER_USAGE_GPU_SAMPLED_IMAGE - ** The format of pname:image must: be ename:VK_FORMAT_UNDEFINED or the - format returned by flink:vkGetAndroidHardwareBufferPropertiesANDROID - in slink:VkAndroidHardwareBufferFormatPropertiesANDROID::pname:format - for the Android hardware buffer. - ** The width, height, and array layer dimensions of pname:image and the - Android hardware buffer must: be identical - ** If the Android hardware buffer's usage includes - code:AHARDWAREBUFFER_USAGE_GPU_MIPMAP_COMPLETE, the pname:image must: - either have a complete mipmap chain, or it must: have exactly `1` mip - level. - ** Each bit set in the usage of pname:image must: be listed in - <>, and if there is a corresponding - code:AHARDWAREBUFFER_USAGE bit listed that bit must: be included in - the Android hardware buffer's usage + dlink:VK_NULL_HANDLE, the Android hardware buffer's + code:AHardwareBuffer::code:usage must: include at least one of + code:AHARDWAREBUFFER_USAGE_GPU_COLOR_OUTPUT or + code:AHARDWAREBUFFER_USAGE_GPU_SAMPLED_IMAGE. + * [[VUID-VkMemoryAllocateInfo-pNext-02387]] + If the parameters define an import operation, the external handle is an + Android hardware buffer, and the pname:pNext chain includes an instance + of slink:VkMemoryDedicatedAllocateInfo with pname:image that is not + dlink:VK_NULL_HANDLE, the format of pname:image must: be + ename:VK_FORMAT_UNDEFINED or the format returned by + flink:vkGetAndroidHardwareBufferPropertiesANDROID in + slink:VkAndroidHardwareBufferFormatPropertiesANDROID::pname:format for + the Android hardware buffer. + * [[VUID-VkMemoryAllocateInfo-pNext-02388]] + If the parameters define an import operation, the external handle is an + Android hardware buffer, and the pname:pNext chain includes an instance + of slink:VkMemoryDedicatedAllocateInfo with pname:image that is not + dlink:VK_NULL_HANDLE, the width, height, and array layer dimensions of + pname:image and the Android hardware buffer's code:AHardwareBuffer_Desc + must: be identical. + * [[VUID-VkMemoryAllocateInfo-pNext-02389]] + If the parameters define an import operation, the external handle is an + Android hardware buffer, and the pname:pNext chain includes an instance + of slink:VkMemoryDedicatedAllocateInfo with pname:image that is not + dlink:VK_NULL_HANDLE, and the Android hardware buffer's + code:AHardwareBuffer::code:usage includes + code:AHARDWAREBUFFER_USAGE_GPU_MIPMAP_COMPLETE, the pname:image must: + either have a complete mipmap chain, or it must: have exactly `1` mip + level. + * [[VUID-VkMemoryAllocateInfo-pNext-02390]] + If the parameters define an import operation, the external handle is an + Android hardware buffer, and the pname:pNext chain includes an instance + of slink:VkMemoryDedicatedAllocateInfo with pname:image that is not + dlink:VK_NULL_HANDLE, each bit set in the usage of pname:image must: be + listed in + <>, and if there is a corresponding + code:AHARDWAREBUFFER_USAGE bit listed that bit must: be included in the + Android hardware buffer's code:AHardwareBuffer_Desc::code:usage. endif::VK_ANDROID_external_memory_android_hardware_buffer[] **** @@ -1906,8 +1948,10 @@ If the command fails, the implementation must: not retain a reference. slink:VkExternalBufferProperties. * [[VUID-VkImportAndroidHardwareBufferInfoANDROID-buffer-01881]] If pname:buffer is not `NULL`, it must: be a valid Android hardware - buffer object with format and usage compatible with Vulkan as described - by elink:VkExternalMemoryHandleTypeFlagBits. + buffer object with code:AHardwareBuffer_Desc::code:format and + code:AHardwareBuffer_Desc::code:usage compatible with Vulkan as + described in <>. **** include::../validity/structs/VkImportAndroidHardwareBufferInfoANDROID.txt[] @@ -1992,7 +2036,8 @@ include::../api/protos/vkGetAndroidHardwareBufferPropertiesANDROID.txt[] **** * [[VUID-vkGetAndroidHardwareBufferPropertiesANDROID-buffer-01884]] pname:buffer must: be a valid Android hardware buffer object with at - least one of the code:AHARDWAREBUFFER_USAGE_GPU_* usage flags. + least one of the code:AHARDWAREBUFFER_USAGE_GPU_* flags in its + code:AHardwareBuffer_Desc::code:usage **** include::../validity/protos/vkGetAndroidHardwareBufferPropertiesANDROID.txt[] @@ -2734,6 +2779,16 @@ variety of media APIs and the hardware used to implement them. These Android hardware buffer objects may: be imported into slink:VkDeviceMemory objects for access via Vulkan, or exported from Vulkan. +[NOTE] +.Note +==== +The NDK format, usage, and size/dimensions of an code:AHardwareBuffer object +can be obtained with the code:AHardwareBuffer_describe function. +While Android hardware buffers can be imported to or exported from Vulkan +without using that function, valid usage and implementation behavior is +defined in terms of the code:AHardwareBuffer_Desc properties it returns. +==== + Android hardware buffer objects are reference-counted using Android NDK functions outside of the scope of this specification. A slink:VkDeviceMemory imported from an Android hardware buffer or that can: @@ -2844,16 +2899,16 @@ exported to an Android hardware buffer until it has been bound to that image, and the implementation must: return an Android hardware buffer with properties derived from the image: - * The code:width and code:height members of code:AHardwareBuffer_desc + * The code:width and code:height members of code:AHardwareBuffer_Desc must: be the same as the pname:width and pname:height members of slink:VkImageCreateInfo::pname:extent, respectively. - * The code:layers member of code:AHardwareBuffer_desc must: be the same as + * The code:layers member of code:AHardwareBuffer_Desc must: be the same as the pname:arrayLayers member of slink:VkImageCreateInfo. - * The code:format member of code:AHardwareBuffer_desc must: be equivalent + * The code:format member of code:AHardwareBuffer_Desc must: be equivalent to slink:VkImageCreateInfo::pname:format as defined by <>. - * The code:usage member of code:AHardwareBuffer_desc must: include bits + * The code:usage member of code:AHardwareBuffer_Desc must: include bits corresponding to bits included in slink:VkImageCreateInfo::pname:usage and slink:VkImageCreateInfo::pname:flags where such a correspondence exists according to @@ -2865,7 +2920,7 @@ properties derived from the image: usable in ways indicated by the image creation parameters, even when used outside Vulkan, in a similar way that allocating the Android hardware buffer with usage returned in - slink:VkAndroidHardwareBufferUsageANDROID. + slink:VkAndroidHardwareBufferUsageANDROID does. Implementations may: support fewer combinations of image creation parameters for images with Android hardware buffer external handle type than for diff --git a/chapters/pipelines.txt b/chapters/pipelines.txt index a058fd75..aced2ee1 100644 --- a/chapters/pipelines.txt +++ b/chapters/pipelines.txt @@ -11,8 +11,14 @@ Some Vulkan 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. +ifndef::VK_NV_raytracing[] Commands are effectively sent through a processing pipeline, either a _graphics pipeline_ or a _compute pipeline_. +endif::VK_NV_raytracing[] +ifdef::VK_NV_raytracing[] +Commands are effectively sent through a processing pipeline, either a +_graphics pipeline_, a _compute pipeline_, or a _ray tracing pipeline_. +endif::VK_NV_raytracing[] ifdef::VK_NV_mesh_shader[] The graphics pipeline can be operated in two modes, as either _primitive @@ -88,7 +94,7 @@ ifndef::VK_NV_mesh_shader[] image::images/pipeline.svg[title="Block diagram of the Vulkan pipeline",align="center",opts="{imageopts}"] endif::VK_NV_mesh_shader[] ifdef::VK_NV_mesh_shader[] -image::images/pipelinemesh.svg[title="Block diagram of the Vulkan pipeline",{fullimagewidth},align="center",opts="{imageopts}"] +image::images/pipelinemesh.svg[title="Block diagram of the Vulkan pipeline",align="center",opts="{imageopts}"] endif::VK_NV_mesh_shader[] Each pipeline is controlled by a monolithic object created from a @@ -111,8 +117,14 @@ another. [open,refpage='VkPipeline',desc='Opaque handle to a pipeline object',type='handles'] -- +ifndef::VK_NV_raytracing[] Compute and graphics pipelines are each represented by sname:VkPipeline handles: +endif::VK_NV_raytracing[] +ifdef::VK_NV_raytracing[] +Compute, graphics, and ray tracing pipelines are each represented by +sname:VkPipeline handles: +endif::VK_NV_raytracing[] include::../api/handles/VkPipeline.txt[] @@ -411,16 +423,16 @@ endif::VK_NV_mesh_shader[] * ename:VK_SHADER_STAGE_ALL is a combination of bits used as shorthand to specify all shader stages supported by the device, including all additional stages which are introduced by extensions. -ifdef::VK_NVX_raytracing[] - * ename:VK_SHADER_STAGE_RAYGEN_BIT_NVX specifies the ray generation stage. - * ename:VK_SHADER_STAGE_ANY_HIT_BIT_NVX specifies the any hit stage. - * ename:VK_SHADER_STAGE_CLOSEST_HIT_BIT_NVX specifies the closest hit +ifdef::VK_NV_ray_tracing[] + * ename:VK_SHADER_STAGE_RAYGEN_BIT_NV specifies the ray generation stage. + * ename:VK_SHADER_STAGE_ANY_HIT_BIT_NV specifies the any hit stage. + * ename:VK_SHADER_STAGE_CLOSEST_HIT_BIT_NV specifies the closest hit stage. - * ename:VK_SHADER_STAGE_MISS_BIT_NVX specifies the miss stage. - * ename:VK_SHADER_STAGE_INTERSECTION_BIT_NVX specifies the intersection + * ename:VK_SHADER_STAGE_MISS_BIT_NV specifies the miss stage. + * ename:VK_SHADER_STAGE_INTERSECTION_BIT_NV specifies the intersection stage. - * ename:VK_SHADER_STAGE_CALLABLE_BIT_NVX specifies the callable stage. -endif::VK_NVX_raytracing[] + * ename:VK_SHADER_STAGE_CALLABLE_BIT_NV specifies the callable stage. +endif::VK_NV_ray_tracing[] [NOTE] .Note @@ -973,7 +985,13 @@ include::../validity/structs/VkGraphicsPipelineCreateInfo.txt[] -- Possible values of the pname:flags member of +ifndef::VK_NV_ray_tracing[] slink:VkGraphicsPipelineCreateInfo and slink:VkComputePipelineCreateInfo, +endif::VK_NV_ray_tracing[] +ifdef::VK_NV_ray_tracing[] +slink:VkGraphicsPipelineCreateInfo, slink:VkComputePipelineCreateInfo, and +slink:VkRayTracingPipelineCreateInfoNV, +endif::VK_NV_ray_tracing[] specifying how a pipeline is created, are: include::../api/enums/VkPipelineCreateFlagBits.txt[] @@ -997,6 +1015,13 @@ endif::VK_VERSION_1_1,VK_KHR_multiview[] can: be used with flink:vkCmdDispatchBase with a non-zero base workgroup. endif::VK_VERSION_1_1,VK_KHR_device_group[] +ifdef::VK_NV_ray_tracing[] + * ename:VK_PIPELINE_CREATE_DEFER_COMPILE_BIT_NV specifies that a pipeline + is created with all shaders in the deferred state. + Before using the pipeline the application must: call + flink:vkCompileDeferredNV exactly once on each shader in the pipeline + before using the pipeline. +endif::VK_NV_ray_tracing[] It is valid to set both ename:VK_PIPELINE_CREATE_ALLOW_DERIVATIVES_BIT and ename:VK_PIPELINE_CREATE_DERIVATIVE_BIT. @@ -1829,6 +1854,10 @@ 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 all <>. +ifdef::VK_NV_ray_tracing[] +The pipeline bound to ename:VK_PIPELINE_BIND_POINT_RAY_TRACING_NV controls +the behavior of flink:vkCmdTraceRaysNV. +endif::VK_NV_ray_tracing[] No other commands are affected by the pipeline state. .Valid Usage @@ -1875,6 +1904,17 @@ ifdef::VK_EXT_transform_feedback[] * [[VUID-vkCmdBindPipeline-None-02323]] This command must: not be recorded when transform feedback is active endif::VK_EXT_transform_feedback[] +ifdef::VK_NV_ray_tracing[] + * [[VUID-vkCmdBindPipeline-pipelineBindPoint-02391]] + If pname:pipelineBindPoint is + ename:VK_PIPELINE_BIND_POINT_RAY_TRACING_NV, the sname:VkCommandPool + that pname:commandBuffer was allocated from must: support compute + operations + * [[VUID-vkCmdBindPipeline-pipelineBindPoint-02392]] + If pname:pipelineBindPoint is + ename:VK_PIPELINE_BIND_POINT_RAY_TRACING_NV, the pname:pipeline must: be + a ray tracing pipeline +endif::VK_NV_ray_tracing[] **** include::../validity/protos/vkCmdBindPipeline.txt[] @@ -1892,7 +1932,10 @@ include::../api/enums/VkPipelineBindPoint.txt[] pipeline. * ename:VK_PIPELINE_BIND_POINT_GRAPHICS specifies binding as a graphics pipeline. - +ifdef::VK_NV_ray_tracing[] + * ename:VK_PIPELINE_BIND_POINT_RAY_TRACING_NV specifies binding as a ray + tracing pipeline. +endif::VK_NV_ray_tracing[] -- @@ -1941,6 +1984,6 @@ ifdef::VK_AMD_shader_info[] include::VK_AMD_shader_info.txt[] endif::VK_AMD_shader_info[] -ifdef::VK_NVX_raytracing[] -include::VK_NVX_raytracing/raytracing-pipelines.txt[] -endif::VK_NVX_raytracing[] +ifdef::VK_NV_ray_tracing[] +include::VK_NV_ray_tracing/raytracing-pipelines.txt[] +endif::VK_NV_ray_tracing[] diff --git a/chapters/primsrast.txt b/chapters/primsrast.txt index d57349c0..777ac63c 100644 --- a/chapters/primsrast.txt +++ b/chapters/primsrast.txt @@ -507,11 +507,11 @@ pixel. [eq]#(0.9375, 0.25)# + [eq]#(0.875, 0.9375)# + [eq]#(0.0625, 0.0)# -|image:images/sample_count_1.svg[align="center"] -|image:images/sample_count_2.svg[align="center"] -|image:images/sample_count_4.svg[align="center"] -|image:images/sample_count_8.svg[align="center"] -|image:images/sample_count_16.svg[align="center"] +|image:images/sample_count_1.svg[align="center",opts="{imageopts}"] +|image:images/sample_count_2.svg[align="center",opts="{imageopts}"] +|image:images/sample_count_4.svg[align="center",opts="{imageopts}"] +|image:images/sample_count_8.svg[align="center",opts="{imageopts}"] +|image:images/sample_count_16.svg[align="center",opts="{imageopts}"] |==== ifdef::VK_AMD_shader_fragment_mask[] diff --git a/chapters/resources.txt b/chapters/resources.txt index 25804fae..ec2ad843 100644 --- a/chapters/resources.txt +++ b/chapters/resources.txt @@ -234,7 +234,11 @@ ifdef::VK_EXT_transform_feedback[] flink:vkCmdBeginTransformFeedbackEXT and flink:vkCmdEndTransformFeedbackEXT. endif::VK_EXT_transform_feedback[] - +ifdef::VK_NV_ray_tracing[] + * ename:VK_BUFFER_USAGE_RAY_TRACING_BIT_NV specifies that the buffer is + suitable for use in flink:vkCmdTraceRaysNV and + flink:vkCmdBuildAccelerationStructureNV. +endif::VK_NV_ray_tracing[] -- [open,refpage='VkBufferUsageFlags',desc='Bitmask of VkBufferUsageFlagBits',type='enums'] @@ -1184,26 +1188,40 @@ ifdef::VK_EXT_sample_locations[] pname:format must: be a depth or depth/stencil format endif::VK_EXT_sample_locations[] ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] - * [[VUID-VkImageCreateInfo-pNext-01892]] + * [[VUID-VkImageCreateInfo-pNext-02393]] If the pname:pNext chain includes a slink:VkExternalMemoryImageCreateInfo structure whose pname:handleTypes member includes - ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID: - ** pname:imageType must: be ename:VK_IMAGE_TYPE_2D - ** pname:mipLevels must: either be `1` or equal to the number of levels - in the complete mipmap chain based on [eq]#pname:extent.width#, - [eq]#pname:extent.height#, and [eq]#pname:extent.depth#. - ** If pname:format is ename:VK_FORMAT_UNDEFINED, then the pname:pNext - chain must: include a slink:VkExternalFormatANDROID structure whose - pname:externalFormat member is not `0` - * [[VUID-VkImageCreateInfo-pNext-01893]] + ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID, + pname:imageType must: be ename:VK_IMAGE_TYPE_2D. + * [[VUID-VkImageCreateInfo-pNext-02394]] + If the pname:pNext chain includes a + slink:VkExternalMemoryImageCreateInfo structure whose pname:handleTypes + member includes + ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID, + pname:mipLevels must: either be `1` or equal to the number of levels in + the complete mipmap chain based on [eq]#pname:extent.width#, + [eq]#pname:extent.height#, and [eq]#pname:extent.depth#. + * [[VUID-VkImageCreateInfo-pNext-02395]] + If the pname:pNext chain includes a + slink:VkExternalMemoryImageCreateInfo structure whose pname:handleTypes + member includes + ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID, + and pname:format is ename:VK_FORMAT_UNDEFINED, then the pname:pNext + chain must: include a slink:VkExternalFormatANDROID structure whose + pname:externalFormat member is not `0`. + * [[VUID-VkImageCreateInfo-pNext-02396]] If the pname:pNext chain includes a slink:VkExternalFormatANDROID - structure whose pname:externalFormat member is not `0`: - ** pname:flags must: not include - ename:VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT - ** pname:usage must: not include any usages except - pname:VK_IMAGE_USAGE_SAMPLED_BIT - ** pname:tiling must: be ename:VK_IMAGE_TILING_OPTIMAL + structure whose pname:externalFormat member is not `0`, pname:flags + must: not include ename:VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT. + * [[VUID-VkImageCreateInfo-pNext-02397]] + If the pname:pNext chain includes a slink:VkExternalFormatANDROID + structure whose pname:externalFormat member is not `0`, pname:usage + must: not include any usages except pname:VK_IMAGE_USAGE_SAMPLED_BIT. + * [[VUID-VkImageCreateInfo-pNext-02398]] + If the pname:pNext chain includes a slink:VkExternalFormatANDROID + structure whose pname:externalFormat member is not `0`, pname:tiling + must: be ename:VK_IMAGE_TILING_OPTIMAL. endif::VK_ANDROID_external_memory_android_hardware_buffer[] ifdef::VK_NV_corner_sampled_image[] * [[VUID-VkImageCreateInfo-flags-02050]] @@ -3047,16 +3065,21 @@ endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] image, as described in the <> ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] - * [[VUID-VkImageViewCreateInfo-image-01896]] + * [[VUID-VkImageViewCreateInfo-image-02399]] If pname:image has an <>: - ** pname:format must: be ename:VK_FORMAT_UNDEFINED - ** The pname:pNext chain must: contain an instance of - slink:VkSamplerYcbcrConversionInfo with a pname:conversion object - created with the same external format as pname:image - ** All members of pname:components must: be - ename:VK_COMPONENT_SWIZZLE_IDENTITY + format>>, pname:format must: be ename:VK_FORMAT_UNDEFINED. + * [[VUID-VkImageViewCreateInfo-image-02400]] + If pname:image has an + <>, the pname:pNext chain must: contain an instance of + slink:VkSamplerYcbcrConversionInfo with a pname:conversion object + created with the same external format as pname:image. + * [[VUID-VkImageViewCreateInfo-image-02401]] + If pname:image has an + <>, all members of pname:components must: be + ename:VK_COMPONENT_SWIZZLE_IDENTITY. endif::VK_ANDROID_external_memory_android_hardware_buffer[] ifdef::VK_NV_shading_rate_image[] * [[VUID-VkImageViewCreateInfo-image-02086]] @@ -5235,6 +5258,6 @@ of memory, and signaling a fence involves sufficient implicit dependencies to satisfy all the above requirements. ==== -ifdef::VK_NVX_raytracing[] -include::VK_NVX_raytracing/raytracing-resources.txt[] -endif::VK_NVX_raytracing[] +ifdef::VK_NV_ray_tracing[] +include::VK_NV_ray_tracing/raytracing-resources.txt[] +endif::VK_NV_ray_tracing[] diff --git a/chapters/shaders.txt b/chapters/shaders.txt index 5b4145f3..5cb3edb3 100644 --- a/chapters/shaders.txt +++ b/chapters/shaders.txt @@ -162,7 +162,7 @@ include::VK_EXT_validation_cache/shader-module-validation-cache.txt[] endif::VK_EXT_validation_cache[] -[open,refpage='vkDestroyShaderModule',desc='Destroy a shader module module',type='protos'] +[open,refpage='vkDestroyShaderModule',desc='Destroy a shader module',type='protos'] -- To destroy a shader module, call: @@ -762,9 +762,9 @@ array dimension, where the extra index identifies one of the vertices of the primitive that produced the fragment. endif::VK_NV_fragment_shader_barycentric[] -ifdef::VK_NVX_raytracing[] -include::VK_NVX_raytracing/raytracing-shaders.txt[] -endif::VK_NVX_raytracing[] +ifdef::VK_NV_ray_tracing[] +include::VK_NV_ray_tracing/raytracing-shaders.txt[] +endif::VK_NV_ray_tracing[] [[shaders-staticuse]] == Static Use diff --git a/chapters/synchronization.txt b/chapters/synchronization.txt index 21487388..11087217 100644 --- a/chapters/synchronization.txt +++ b/chapters/synchronization.txt @@ -360,10 +360,14 @@ endif::VK_NV_mesh_shader[] * ename:VK_PIPELINE_STAGE_HOST_BIT specifies a pseudo-stage indicating execution on the host of reads/writes of device memory. This stage is not invoked by any commands recorded in a command buffer. -ifdef::VK_NVX_raytracing[] - * ename:VK_PIPELINE_STAGE_RAYTRACING_BIT_NVX specifies the execution of - the ray tracing stages. -endif::VK_NVX_raytracing[] +ifdef::VK_NV_ray_tracing[] + * ename:VK_PIPELINE_STAGE_RAY_TRACING_SHADER_BIT_NV specifies the + execution of the ray tracing shader stages. + * ename:VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_NV specifies + the execution of vkCmdBuildAccelerationStructureNV, + vkCmdCopyAccelerationStructureNV, and + vkCmdWriteAccelerationStructuresPropertiesNV. +endif::VK_NV_ray_tracing[] * ename:VK_PIPELINE_STAGE_ALL_GRAPHICS_BIT specifies the execution of all graphics pipeline stages, and is equivalent to the logical OR of: ** ename:VK_PIPELINE_STAGE_TOP_OF_PIPE_BIT @@ -528,9 +532,10 @@ ifdef::VK_NV_mesh_shader[] |ename:VK_PIPELINE_STAGE_TASK_SHADER_BIT_NV | ename:VK_QUEUE_GRAPHICS_BIT |ename:VK_PIPELINE_STAGE_MESH_SHADER_BIT_NV | ename:VK_QUEUE_GRAPHICS_BIT endif::VK_NV_mesh_shader[] -ifdef::VK_NVX_raytracing[] -|ename:VK_PIPELINE_STAGE_RAYTRACING_BIT_NVX | ename:VK_QUEUE_COMPUTE_BIT -endif::VK_NVX_raytracing[] +ifdef::VK_NV_ray_tracing[] +|ename:VK_PIPELINE_STAGE_RAY_TRACING_SHADER_BIT_NV | ename:VK_QUEUE_COMPUTE_BIT +|ename:VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_NV | ename:VK_QUEUE_COMPUTE_BIT +endif::VK_NV_ray_tracing[] |==== [[synchronization-pipeline-stages-order]] @@ -654,12 +659,18 @@ order: * ename:VK_PIPELINE_STAGE_BOTTOM_OF_PIPE_BIT endif::VK_NVX_device_generated_commands[] -ifdef::VK_NVX_raytracing[] -For the ray tracing pipeline, only one pipeline stage occurs, so no order is -guaranteed: +ifdef::VK_NV_ray_tracing[] +For the ray tracing shader pipeline, only one pipeline stage occurs, so no +order is guaranteed: - * ename:VK_PIPELINE_STAGE_RAYTRACING_BIT_NVX -endif::VK_NVX_raytracing[] + * ename:VK_PIPELINE_STAGE_RAY_TRACING_SHADER_BIT_NV + +For ray tracing acceleration structure operations, only one pipeline stage +occurs, so no order is guaranteed: + + * ename:VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_NV + +endif::VK_NV_ray_tracing[] [[synchronization-access-types]] === Access Types @@ -791,6 +802,12 @@ ifdef::VK_NV_shading_rate_image[] a shading rate image as part of a drawing command, as bound by flink:vkCmdBindShadingRateImageNV. endif::VK_NV_shading_rate_image[] +ifdef::VK_NV_ray_tracing[] + * ename:VK_ACCESS_ACCELERATION_STRUCTURE_READ_BIT_NV specifies read access + to an acceleration structure as part of a trace or build command. + * ename:VK_ACCESS_ACCELERATION_STRUCTURE_WRITE_BIT_NV specifies write + access to an acceleration structure as part of a build command. +endif::VK_NV_ray_tracing[] Certain access types are only performed by a subset of pipeline stages. Any synchronization command that takes both stage masks and access masks @@ -843,13 +860,17 @@ ifdef::VK_EXT_conditional_rendering[] |ename:VK_ACCESS_CONDITIONAL_RENDERING_READ_BIT_EXT | ename:VK_PIPELINE_STAGE_CONDITIONAL_RENDERING_BIT_EXT endif::VK_EXT_conditional_rendering[] ifdef::VK_NV_shading_rate_image[] -|ename:VK_ACCESS_SHADING_RATE_IMAGE_BIT_NV | ename:VK_PIPELINE_STAGE_SHADING_RATE_IMAGE_BIT_NV +|ename:VK_ACCESS_SHADING_RATE_IMAGE_READ_BIT_NV | ename:VK_PIPELINE_STAGE_SHADING_RATE_IMAGE_BIT_NV endif::VK_NV_shading_rate_image[] ifdef::VK_EXT_transform_feedback[] |ename:VK_ACCESS_TRANSFORM_FEEDBACK_WRITE_BIT_EXT | ename:VK_PIPELINE_STAGE_TRANSFORM_FEEDBACK_BIT_EXT |ename:VK_ACCESS_TRANSFORM_FEEDBACK_COUNTER_WRITE_BIT_EXT | ename:VK_PIPELINE_STAGE_TRANSFORM_FEEDBACK_BIT_EXT |ename:VK_ACCESS_TRANSFORM_FEEDBACK_COUNTER_READ_BIT_EXT | ename:VK_PIPELINE_STAGE_DRAW_INDIRECT_BIT endif::VK_EXT_transform_feedback[] +ifdef::VK_NV_ray_tracing[] +|ename:VK_ACCESS_ACCELERATION_STRUCTURE_READ_BIT_NV | ename:VK_PIPELINE_STAGE_RAY_TRACING_SHADER_BIT_NV, or ename:VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_NV +|ename:VK_ACCESS_ACCELERATION_STRUCTURE_WRITE_BIT_NV | ename:VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_NV +endif::VK_NV_ray_tracing[] |==== [[synchronization-host-access-types]] @@ -3585,8 +3606,8 @@ framebuffer-space>> pipeline stages is contains a subset of the bit values in sname:VkSubpassDependency::pname:dstStageMask, pname:dependencyFlags is equal to sname:VkSubpassDependency::pname:dependencyFlags, - pname:srcAccessMask member of each each element of pname:pMemoryBarriers - and pname:pImageMemoryBarriers contains a subset of the bit values in + pname:srcAccessMask member of each element of pname:pMemoryBarriers and + pname:pImageMemoryBarriers contains a subset of the bit values in sname:VkSubpassDependency::pname:srcAccessMask, and pname:dstAccessMask member of each element of pname:pMemoryBarriers and pname:pImageMemoryBarriers contains a subset of the bit values in diff --git a/config/katex_replace/extension.rb b/config/katex_replace/extension.rb index 1bd77e38..b01ea19e 100644 --- a/config/katex_replace/extension.rb +++ b/config/katex_replace/extension.rb @@ -19,7 +19,7 @@ include ::Asciidoctor class ReplaceMathjaxWithKatex < Extensions::Postprocessor MathJaXScript = /' + MathJaXCDN = /