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.
|
|
|