1// Copyright (c) 2015-2018 Khronos Group. This work is licensed under a 2// Creative Commons Attribution 4.0 International License; see 3// http://creativecommons.org/licenses/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 17http://www.khronos.org/registry/vulkan/[Vulkan Registry] 18(http://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 Vulkan 1.1 are now defined in terms of the equivalent Vulkan 1.1 46interfaces. 47This affects the Vulkan Specification, the Vulkan header files, and the 48corresponding XML Registry. 49==== 50 51 52[[introduction-normative-terminology]] 53=== Normative Terminology 54 55Within this specification, the key words *must*, *required*, *should*, 56*recommended*, *may*, and *optional* are to be interpreted as described in 57http://www.ietf.org/rfc/rfc2119.txt[RFC 2119 - Key words for use in RFCs to 58Indicate Requirement Levels] (http://www.ietf.org/rfc/rfc2119.txt). 59These key words are highlighted in the specification for clarity. 60In text addressing application developers, their use expresses requirements 61that apply to application behavior. 62In text addressing implementors, their use expresses requirements that apply 63to implementations. 64 65In text addressing application developers, the additional key words *can* 66and *cannot* are to be interpreted as describing the capabilities of an 67application, as follows: 68 69*can*:: 70This word means that the application is able to perform the action 71described. 72 73*cannot*:: 74This word means that the API and/or the execution environment provide no 75mechanism through which the application can express or accomplish the action 76described. 77 78These key words are never used in text addressing implementors. 79 80[NOTE] 81.Note 82================== 83There is an important distinction between *cannot* and *must not*, as used 84in this Specification. 85*Cannot* means something the application literally is unable to express or 86accomplish through the API, while *must not* means something that the 87application is capable of expressing through the API, but that the 88consequences of doing so are undefined and potentially unrecoverable for the 89implementation. 90================== 91 92Unless otherwise noted in the section heading, all sections and appendices 93in this document are normative. 94 95 96[[introduction-technical-terminology]] 97=== Technical Terminology 98 99The Vulkan Specification makes use of common engineering and graphics terms 100such as *Pipeline*, *Shader*, and *Host* to identify and describe Vulkan API 101constructs and their attributes, states, and behaviors. 102The <<glossary,Glossary>> defines the basic meanings of these terms in the 103context of the Specification. 104The Specification text provides fuller definitions of the terms and may 105elaborate, extend, or clarify the <<glossary,Glossary>> definitions. 106When a term defined in the <<glossary,Glossary>> is used in normative 107language within the Specification, the definitions within the Specification 108govern and supersede any meanings the terms may have in other technical 109contexts (i.e. outside the Specification). 110 111 112[[introduction-normative-references]] 113=== Normative References 114 115References to external documents are considered normative references if the 116Specification uses any of the normative terms defined in 117<<introduction-normative-terminology>> to refer to them or their 118requirements, either as a whole or in part. 119 120The following documents are referenced by normative sections of the 121specification: 122 123[[ieee-754]] 124_IEEE Standard for Floating-Point Arithmetic_, IEEE Std 754-2008, 125http://dx.doi.org/10.1109/IEEESTD.2008.4610935, August, 2008. 126 127[[data-format]] A. Garrard, _Khronos Data Format Specification, version 1281.2_, 129https://www.khronos.org/registry/DataFormat/specs/1.2/dataformat.1.2.html, 130September, 2017. 131 132// If the author name is placed on a standalone line, we see the mysterious 133// asciidoc error 'list item index: expected 2 got 10'. Apparently the 'A.' 134// of the previous paragraph and the 'J.' of this one get misinterpreted. 135 136[[spirv-extended]] J. Kessenich, _SPIR-V Extended Instructions for GLSL, 137Version 1.00_, https://www.khronos.org/registry/spir-v/, February 10, 2016. 138 139[[spirv-spec]] J. Kessenich, B. Ouriel, and R. Krisch, _SPIR-V 140Specification, Version 1.3, Revision 2, Unified_, 141https://www.khronos.org/registry/spir-v/, May 11, 2018. 142 143[[vulkan-styleguide]] J. Leech and T. Hector, _Vulkan Documentation and 144Extensions: Procedures and Conventions_, 145https://www.khronos.org/registry/vulkan/specs/1.1/styleguide.html 146 147[[LoaderAndLayerInterface]] 148_Vulkan Loader Specification and Architecture Overview_, 149https://github.com/KhronosGroup/Vulkan-Loader/blob/master/loader/LoaderAndLayerInterface.md, 150August, 2016. 151 152