1// Copyright 2015-2021 The Khronos Group, Inc. 2// 3// SPDX-License-Identifier: CC-BY-4.0 4 5 6[[introduction]] 7= Introduction 8 9This document, referred to as the "`Vulkan Specification`" or just the 10"`Specification`" hereafter, describes the Vulkan Application Programming 11Interface (API). 12Vulkan is a http://www.open-std.org/jtc1/sc22/wg14/www/standards[C99] API 13designed for explicit control of low-level graphics and compute 14functionality. 15 16The canonical version of the Specification is available in the official 17https://www.khronos.org/registry/vulkan/[Vulkan Registry] 18(https://www.khronos.org/registry/vulkan/). 19The source files used to generate the Vulkan specification are stored in the 20https://github.com/KhronosGroup/Vulkan-Docs[Vulkan Documentation Repository] 21(https://github.com/KhronosGroup/Vulkan-Docs). 22The source repository additionally has a public issue tracker and allows the 23submission of pull requests that improve the specification. 24 25 26[[introduction-conventions]] 27== Document Conventions 28 29The Vulkan specification is intended for use by both implementors of the API 30and application developers seeking to make use of the API, forming a 31contract between these parties. 32Specification text may address either party; typically the intended audience 33can be inferred from context, though some sections are defined to address 34only one of these parties. 35(For example, <<fundamentals-validusage>> sections only address application 36developers). 37Any requirements, prohibitions, recommendations or options defined by 38<<introduction-normative-terminology, normative terminology>> are imposed 39only on the audience of that text. 40 41[NOTE] 42.Note 43==== 44Structure and enumerated types defined in extensions that were promoted to 45core in a later version of Vulkan are now defined in terms of the equivalent 46Vulkan core interfaces. 47This affects the Vulkan Specification, the Vulkan header files, and the 48corresponding XML Registry. 49==== 50 51 52[[introduction-informative-language]] 53=== Informative Language 54 55Some language in the specification is purely informative, intended to give 56background or suggestions to implementors or developers. 57 58If an entire chapter or section contains only informative language, its 59title will be suffixed with "`(Informative)`". 60 61All NOTEs are implicitly informative. 62 63 64[[introduction-normative-terminology]] 65=== Normative Terminology 66 67Within this specification, the key words *must*, *required*, *should*, 68*recommended*, *may*, and *optional* are to be interpreted as described in 69https://www.ietf.org/rfc/rfc2119.txt[RFC 2119 - Key words for use in RFCs to 70Indicate Requirement Levels] (https://www.ietf.org/rfc/rfc2119.txt). 71The additional key word *optionally* is an alternate form of *optional*, for 72use where grammatically appropriate. 73 74These key words are highlighted in the specification for clarity. 75In text addressing application developers, their use expresses requirements 76that apply to application behavior. 77In text addressing implementors, their use expresses requirements that apply 78to implementations. 79 80In text addressing application developers, the additional key words *can* 81and *cannot* are to be interpreted as describing the capabilities of an 82application, as follows: 83 84*can*:: 85This word means that the application is able to perform the action 86described. 87 88*cannot*:: 89This word means that the API and/or the execution environment provide no 90mechanism through which the application can express or accomplish the action 91described. 92 93These key words are never used in text addressing implementors. 94 95[NOTE] 96.Note 97================== 98There is an important distinction between *cannot* and *must not*, as used 99in this Specification. 100*Cannot* means something the application literally is unable to express or 101accomplish through the API, while *must not* means something that the 102application is capable of expressing through the API, but that the 103consequences of doing so are undefined: and potentially unrecoverable for 104the implementation (see <<fundamentals-validusage>>). 105================== 106 107Unless otherwise noted in the section heading, all sections and appendices 108in this document are normative. 109 110 111[[introduction-technical-terminology]] 112=== Technical Terminology 113 114The Vulkan Specification makes use of common engineering and graphics terms 115such as *Pipeline*, *Shader*, and *Host* to identify and describe Vulkan API 116constructs and their attributes, states, and behaviors. 117The <<glossary,Glossary>> defines the basic meanings of these terms in the 118context of the Specification. 119The Specification text provides fuller definitions of the terms and may 120elaborate, extend, or clarify the <<glossary,Glossary>> definitions. 121When a term defined in the <<glossary,Glossary>> is used in normative 122language within the Specification, the definitions within the Specification 123govern and supersede any meanings the terms may have in other technical 124contexts (i.e. outside the Specification). 125 126 127[[introduction-normative-references]] 128=== Normative References 129 130References to external documents are considered normative references if the 131Specification uses any of the normative terms defined in 132<<introduction-normative-terminology>> to refer to them or their 133requirements, either as a whole or in part. 134 135The following documents are referenced by normative sections of the 136specification: 137 138[[ieee-754]] 139IEEE. 140August, 2008. 141_IEEE Standard for Floating-Point Arithmetic_. 142IEEE Std 754-2008. 143https://dx.doi.org/10.1109/IEEESTD.2008.4610935 . 144 145[[data-format]] Andrew Garrard. 146_Khronos Data Format Specification, version 1.3_. 147https://www.khronos.org/registry/DataFormat/specs/1.3/dataformat.1.3.html . 148 149[[spirv-extended]] John Kessenich. 150_SPIR-V Extended Instructions for GLSL, Version 1.00_ (February 10, 2016). 151https://www.khronos.org/registry/spir-v/ . 152 153[[spirv-spec]] John Kessenich, Boaz Ouriel, and Raun Krisch. 154_SPIR-V Specification, Version 1.5, Revision 3, Unified_ (April 24, 2020). 155https://www.khronos.org/registry/spir-v/ . 156 157[[vulkan-registry]] Jon Leech. 158_The Khronos Vulkan API Registry_. 159https://www.khronos.org/registry/vulkan/specs/1.2/registry.html . 160 161[[vulkan-styleguide]] Jon Leech and Tobias Hector. 162_Vulkan Documentation and Extensions: Procedures and Conventions_. 163https://www.khronos.org/registry/vulkan/specs/1.2/styleguide.html . 164 165[[LoaderInterfaceArchitecture]] 166_Architecture of the Vulkan Loader Interfaces_ (October, 2021). 167https://github.com/KhronosGroup/Vulkan-Loader/blob/master/docs/LoaderInterfaceArchitecture.md 168. 169 170