mirror of
https://github.com/status-im/Vulkan-Docs.git
synced 2025-01-12 06:54:14 +00:00
dd9919749a
* Update release number to 83.
Public Issues:
* Use [%inline] directive for all SVGs to reduce file size (public pull
request 734).
* Convert XML `value` aliases into \<alias> tags (public pull request
747).
* Fix metadoc script showing non-selected extensions (public pull request
748).
* Reapply public pull request 742 to make
ename:VK_PIPELINE_STAGE_CONDITIONAL_RENDERING_BIT_EXT part of the
graphices pipeline (public pull request 749).
* Fix numerous typos related to accidental duplication of words (public
pull request 760).
* Fix `vk.xml` contact typos (public pull request 761).
Internal Issues:
* Add images to the <<Standard sample locations>> table (internal issue
1115).
* Add a definition of "`Inherited from`" precision in the
<<spirvenv-precision-operation, Precision and Operation of SPIR-V
Instructions>> section (internal issue 1314).
* Clarify that both built-in and user-defined variables count against the
location limits for shader interfaces in the
<<interfaces-iointerfaces-locations, Location Assignment>> section
(internal issue 1316).
* Merge "`required`" capabilities into the <<spirvenv-capabilities-table,
list of optional: SPIR-V capabilities>> (internal issue 1320).
* Relax the layout matching rules of descriptors referring to only a
single aspect of a depth/stencil image, by reference to the new
<<resources-image-layouts-matching-rule, Image Layout Matching Rules>>
section (internal issue 1346).
* Revert extension metadoc generator warning about name mismatches to a
diagnostic, due to annoying warnings in build output for conscious
choices we've made (internal issue 1351).
Other Issues:
* Reserve bits for pending vendor extensions.
* Make Vulkan consistent with SPIR-V regarding code:DepthReplacing and
code:FragDepth in the <<interfaces-builtin-variables, Built-In
Variables>> section.
* Add missing ChangeLog entries for the previous three spec updates.
152 lines
6.0 KiB
Plaintext
152 lines
6.0 KiB
Plaintext
// Copyright (c) 2015-2018 Khronos Group. This work is licensed under a
|
|
// Creative Commons Attribution 4.0 International License; see
|
|
// http://creativecommons.org/licenses/by/4.0/
|
|
|
|
|
|
[[introduction]]
|
|
= Introduction
|
|
|
|
This document, referred to as the "`Vulkan Specification`" or just the
|
|
"`Specification`" hereafter, describes the Vulkan Application Programming
|
|
Interface (API).
|
|
Vulkan is a http://www.open-std.org/jtc1/sc22/wg14/www/standards[C99] API
|
|
designed for explicit control of low-level graphics and compute
|
|
functionality.
|
|
|
|
The canonical version of the Specification is available in the official
|
|
http://www.khronos.org/registry/vulkan/[Vulkan Registry]
|
|
(http://www.khronos.org/registry/vulkan/).
|
|
The source files used to generate the Vulkan specification are stored in the
|
|
https://github.com/KhronosGroup/Vulkan-Docs[Vulkan Documentation Repository]
|
|
(https://github.com/KhronosGroup/Vulkan-Docs).
|
|
The source repository additionally has a public issue tracker and allows the
|
|
submission of pull requests that improve the specification.
|
|
|
|
|
|
[[introduction-conventions]]
|
|
== Document Conventions
|
|
|
|
The Vulkan specification is intended for use by both implementors of the API
|
|
and application developers seeking to make use of the API, forming a
|
|
contract between these parties.
|
|
Specification text may address either party; typically the intended audience
|
|
can be inferred from context, though some sections are defined to address
|
|
only one of these parties.
|
|
(For example, <<fundamentals-validusage>> sections only address application
|
|
developers).
|
|
Any requirements, prohibitions, recommendations or options defined by
|
|
<<introduction-normative-terminology, normative terminology>> are imposed
|
|
only on the audience of that text.
|
|
|
|
[NOTE]
|
|
.Note
|
|
====
|
|
Structure and enumerated types defined in extensions that were promoted to
|
|
core in Vulkan 1.1 are now defined in terms of the equivalent Vulkan 1.1
|
|
interfaces.
|
|
This affects the Vulkan Specification, the Vulkan header files, and the
|
|
corresponding XML Registry.
|
|
====
|
|
|
|
|
|
[[introduction-normative-terminology]]
|
|
=== Normative Terminology
|
|
|
|
Within this specification, the key words *must*, *required*, *should*,
|
|
*recommended*, *may*, and *optional* are to be interpreted as described in
|
|
http://www.ietf.org/rfc/rfc2119.txt[RFC 2119 - Key words for use in RFCs to
|
|
Indicate Requirement Levels] (http://www.ietf.org/rfc/rfc2119.txt).
|
|
These key words are highlighted in the specification for clarity.
|
|
In text addressing application developers, their use expresses requirements
|
|
that apply to application behavior.
|
|
In text addressing implementors, their use expresses requirements that apply
|
|
to implementations.
|
|
|
|
In text addressing application developers, the additional key words *can*
|
|
and *cannot* are to be interpreted as describing the capabilities of an
|
|
application, as follows:
|
|
|
|
*can*::
|
|
This word means that the application is able to perform the action
|
|
described.
|
|
|
|
*cannot*::
|
|
This word means that the API and/or the execution environment provide no
|
|
mechanism through which the application can express or accomplish the action
|
|
described.
|
|
|
|
These key words are never used in text addressing implementors.
|
|
|
|
[NOTE]
|
|
.Note
|
|
==================
|
|
There is an important distinction between *cannot* and *must not*, as used
|
|
in this Specification.
|
|
*Cannot* means something the application literally is unable to express or
|
|
accomplish through the API, while *must not* means something that the
|
|
application is capable of expressing through the API, but that the
|
|
consequences of doing so are undefined and potentially unrecoverable for the
|
|
implementation.
|
|
==================
|
|
|
|
Unless otherwise noted in the section heading, all sections and appendices
|
|
in this document are normative.
|
|
|
|
|
|
[[introduction-technical-terminology]]
|
|
=== Technical Terminology
|
|
|
|
The Vulkan Specification makes use of common engineering and graphics terms
|
|
such as *Pipeline*, *Shader*, and *Host* to identify and describe Vulkan API
|
|
constructs and their attributes, states, and behaviors.
|
|
The <<glossary,Glossary>> defines the basic meanings of these terms in the
|
|
context of the Specification.
|
|
The Specification text provides fuller definitions of the terms and may
|
|
elaborate, extend, or clarify the <<glossary,Glossary>> definitions.
|
|
When a term defined in the <<glossary,Glossary>> is used in normative
|
|
language within the Specification, the definitions within the Specification
|
|
govern and supersede any meanings the terms may have in other technical
|
|
contexts (i.e. outside the Specification).
|
|
|
|
|
|
[[introduction-normative-references]]
|
|
=== Normative References
|
|
|
|
References to external documents are considered normative references if the
|
|
Specification uses any of the normative terms defined in
|
|
<<introduction-normative-terminology>> to refer to them or their
|
|
requirements, either as a whole or in part.
|
|
|
|
The following documents are referenced by normative sections of the
|
|
specification:
|
|
|
|
[[ieee-754]]
|
|
_IEEE Standard for Floating-Point Arithmetic_, IEEE Std 754-2008,
|
|
http://dx.doi.org/10.1109/IEEESTD.2008.4610935, August, 2008.
|
|
|
|
[[data-format]] A. Garrard, _Khronos Data Format Specification, version
|
|
1.2_,
|
|
https://www.khronos.org/registry/DataFormat/specs/1.2/dataformat.1.2.html,
|
|
September, 2017.
|
|
|
|
// If the author name is placed on a standalone line, we see the mysterious
|
|
// asciidoc error 'list item index: expected 2 got 10'. Apparently the 'A.'
|
|
// of the previous paragraph and the 'J.' of this one get misinterpreted.
|
|
|
|
[[spirv-extended]] J. Kessenich, _SPIR-V Extended Instructions for GLSL,
|
|
Version 1.00_, https://www.khronos.org/registry/spir-v/, February 10, 2016.
|
|
|
|
[[spirv-spec]] J. Kessenich, B. Ouriel, and R. Krisch, _SPIR-V
|
|
Specification, Version 1.3, Revision 2, Unified_,
|
|
https://www.khronos.org/registry/spir-v/, May 11, 2018.
|
|
|
|
[[vulkan-styleguide]] J. Leech and T. Hector, _Vulkan Documentation and
|
|
Extensions: Procedures and Conventions_,
|
|
https://www.khronos.org/registry/vulkan/specs/1.1/styleguide.html
|
|
|
|
[[LoaderAndLayerInterface]]
|
|
_Vulkan Loader Specification and Architecture Overview_,
|
|
https://github.com/KhronosGroup/Vulkan-Loader/blob/master/loader/LoaderAndLayerInterface.md,
|
|
August, 2016.
|
|
|