mirror of
https://github.com/status-im/Vulkan-Docs.git
synced 2025-02-18 01:06:46 +00:00
* Update release number to 106. Public Issues: * Add searchbox and generate search index for the chunked HTML target. Note that doing this requires several new toolchain components to build the `chunked` target (public issue 578 / internal issue 1352). * Remove descriptions of flink:vkCreateSampler sampler constraints which were repeated in the valid usage statements (public pull request 648). * Fix sense of conditional around a valid usage statement in the <<copies>> chapter (public issue 942). Internal Issues: * Add missing pname:extent.width and pname:extent.height valid usage statements for flink:vkCmdClearAttachments (internal issue 1583). * Fix some inconsistencies in structures and corresponding pname:sType enumerant names by renaming sname:VkPhysicalDeviceShaderDrawParameterFeatures -> slink:slink:VkPhysicalDeviceShaderDrawParametersFeatures; sname:VkPhysicalDeviceVariablePointerFeatures -> slink:VkPhysicalDeviceVariablePointerFeatures; sname:VkPhysicalDeviceVariablePointerFeaturesKHR -> slink:VkPhysicalDeviceVariablePointerFeaturesKHR; sname:VkPhysicalDeviceBufferAddressFeaturesEXT -> slink:VkPhysicalDeviceBufferDeviceAddressFeaturesEXT; etext:VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_DRAW_PARAMETER_FEATURES -> ename:VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_DRAW_PARAMETERS_FEATURES; etext:VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VARIABLE_POINTER_FEATURES -> ename:VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VARIABLE_POINTERS_FEATURES; etext:VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VARIABLE_POINTER_FEATURES_KHR -> ename:VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VARIABLE_POINTERS_FEATURES_KHR; and etext:VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_BUFFER_ADDRESS_FEATURES_EXT -> ename:VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_BUFFER_DEVICE_ADDRESS_FEATURES_EXT. The old names are still available as aliases for backwards compatibility. This change required introducing valid XML markup which externally written XML processing scripts may need to be modified to accomodate, to support multiple aliases of a single command or token name (internal issue 1592). * Add slink:VkDevice as the first parameter to flink:vkSetLocalDimmingAMD (internal issue 1618). * Improve CI header compilation tests to test all Vulkan platform includes, using fake platform headers where needed, and change the `allchecks` Makefile target to use the more comprehensive `check_spec_links.py` script instead of the retired `checkinc` and `checklinks` targets. * Move descriptions of the ASTC compressed texture decode mode from the <<appendix-compressedtex-astc,appendix>> to the recently updated external Khronos Data Format Specification. * Fix minor markup and spelling issues in the `VK_NV_ray_tracing` extension.
152 lines
6.0 KiB
Plaintext
152 lines
6.0 KiB
Plaintext
// Copyright (c) 2015-2019 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 (see <<fundamentals-errors>>).
|
|
==================
|
|
|
|
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,
|
|
March, 2019.
|
|
|
|
// 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.
|
|
|