registry/vulkan/chapters/introduction.txt - third_party/platform/external/gfxstream-protocols - Git at Google

 // Copyright 2015-2021 The Khronos Group, Inc.
 //
 // SPDX-License-Identifier: CC-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
 https://www.khronos.org/registry/vulkan/[Vulkan Registry]
 (https://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 a later version of Vulkan are now defined in terms of the equivalent
 Vulkan core interfaces.
 This affects the Vulkan Specification, the Vulkan header files, and the
 corresponding XML Registry.
 ====


 [[introduction-informative-language]]
 === Informative Language

 Some language in the specification is purely informative, intended to give
 background or suggestions to implementors or developers.

 If an entire chapter or section contains only informative language, its
 title will be suffixed with "`(Informative)`".

 All NOTEs are implicitly informative.


 [[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
 https://www.ietf.org/rfc/rfc2119.txt[RFC 2119 - Key words for use in RFCs to
 Indicate Requirement Levels] (https://www.ietf.org/rfc/rfc2119.txt).
 The additional key word *optionally* is an alternate form of *optional*, for
 use where grammatically appropriate.

 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-validusage>>).
 ==================

 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.
 August, 2008.
 _IEEE Standard for Floating-Point Arithmetic_.
 IEEE Std 754-2008.
 https://dx.doi.org/10.1109/IEEESTD.2008.4610935 .

 [[data-format]] Andrew Garrard.
 _Khronos Data Format Specification, version 1.3_.
 https://www.khronos.org/registry/DataFormat/specs/1.3/dataformat.1.3.html .

 [[spirv-extended]] John Kessenich.
 _SPIR-V Extended Instructions for GLSL, Version 1.00_ (February 10, 2016).
 https://www.khronos.org/registry/spir-v/ .

 [[spirv-spec]] John Kessenich, Boaz Ouriel, and Raun Krisch.
 _SPIR-V Specification, Version 1.5, Revision 3, Unified_ (April 24, 2020).
 https://www.khronos.org/registry/spir-v/ .

 [[vulkan-registry]] Jon Leech.
 _The Khronos Vulkan API Registry_.
 https://www.khronos.org/registry/vulkan/specs/1.2/registry.html .

 [[vulkan-styleguide]] Jon Leech and Tobias Hector.
 _Vulkan Documentation and Extensions: Procedures and Conventions_.
 https://www.khronos.org/registry/vulkan/specs/1.2/styleguide.html .

 [[LoaderInterfaceArchitecture]]
 _Architecture of the Vulkan Loader Interfaces_ (October, 2021).
 https://github.com/KhronosGroup/Vulkan-Loader/blob/master/docs/LoaderInterfaceArchitecture.md
 .
	// Copyright 2015-2021 The Khronos Group, Inc.
	//
	// SPDX-License-Identifier: CC-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
	https://www.khronos.org/registry/vulkan/[Vulkan Registry]
	(https://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 a later version of Vulkan are now defined in terms of the equivalent
	Vulkan core interfaces.
	This affects the Vulkan Specification, the Vulkan header files, and the
	corresponding XML Registry.
	====


	[[introduction-informative-language]]
	=== Informative Language

	Some language in the specification is purely informative, intended to give
	background or suggestions to implementors or developers.

	If an entire chapter or section contains only informative language, its
	title will be suffixed with "`(Informative)`".

	All NOTEs are implicitly informative.


	[[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
	https://www.ietf.org/rfc/rfc2119.txt[RFC 2119 - Key words for use in RFCs to
	Indicate Requirement Levels] (https://www.ietf.org/rfc/rfc2119.txt).
	The additional key word optionally is an alternate form of optional, for
	use where grammatically appropriate.

	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-validusage>>).
	==================

	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.
	August, 2008.
	_IEEE Standard for Floating-Point Arithmetic_.
	IEEE Std 754-2008.
	https://dx.doi.org/10.1109/IEEESTD.2008.4610935 .

	[[data-format]] Andrew Garrard.
	_Khronos Data Format Specification, version 1.3_.
	https://www.khronos.org/registry/DataFormat/specs/1.3/dataformat.1.3.html .

	[[spirv-extended]] John Kessenich.
	_SPIR-V Extended Instructions for GLSL, Version 1.00_ (February 10, 2016).
	https://www.khronos.org/registry/spir-v/ .

	[[spirv-spec]] John Kessenich, Boaz Ouriel, and Raun Krisch.
	_SPIR-V Specification, Version 1.5, Revision 3, Unified_ (April 24, 2020).
	https://www.khronos.org/registry/spir-v/ .

	[[vulkan-registry]] Jon Leech.
	_The Khronos Vulkan API Registry_.
	https://www.khronos.org/registry/vulkan/specs/1.2/registry.html .

	[[vulkan-styleguide]] Jon Leech and Tobias Hector.
	_Vulkan Documentation and Extensions: Procedures and Conventions_.
	https://www.khronos.org/registry/vulkan/specs/1.2/styleguide.html .

	[[LoaderInterfaceArchitecture]]
	_Architecture of the Vulkan Loader Interfaces_ (October, 2021).
	https://github.com/KhronosGroup/Vulkan-Loader/blob/master/docs/LoaderInterfaceArchitecture.md
	.