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

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

 [[extended-functionality]]
 = Extended Functionality

 Additional functionality may: be provided by layers or extensions.
 A layer cannot: add or modify Vulkan commands, while an extension may: do
 so.

 The set of layers to enable is specified when creating an instance, and
 those layers are able to intercept any Vulkan command dispatched to that
 instance or any of its child objects.

 Extensions can operate at either the instance or device _extension scope_.
 Enabled instance extensions are able to affect the operation of the instance
 and any of its child objects, while device extensions may: only be available
 on a subset of physical devices, must: be individually enabled per-device,
 and only affect the operation of the devices where they are enabled.

 [NOTE]
 .Note
 ====
 Examples of these might be:

   * Whole API validation is an example of a layer.
   * Debug capabilities might make a good instance extension.
   * A layer that provides implementation-specific performance telemetry and
     analysis could be a layer that is only active for devices created from
     compatible physical devices.
   * Functions to allow an application to use additional implementation
     features beyond the core would be a good candidate for a device
     extension.
 ====

 [[extended-functionality-layers]]
 == Layers

 When a layer is enabled, it inserts itself into the call chain for Vulkan
 commands the layer is interested in.
 A common use of layers is to validate application behavior during
 development.
 For example, the implementation will not check that Vulkan enums used by the
 application fall within allowed ranges.
 Instead, a validation layer would do those checks and flag issues.
 This avoids a performance penalty during production use of the application
 because those layers would not be enabled in production.

 Vulkan layers may: wrap object handles (i.e. return a different handle value
 to the application than that generated by the implementation).
 This is generally discouraged, as it increases the probability of
 incompatibilities with new extensions.
 The validation layers wrap handles in order to track the proper use and
 destruction of each object.
 See the <<LoaderAndLayerInterface, "`Vulkan Loader Specification and
 Architecture Overview`">> document for additional information.

 [open,refpage='vkEnumerateInstanceLayerProperties',desc='Returns up to requested number of global layer properties',type='protos']
 --

 To query the available layers, call:

 include::../api/protos/vkEnumerateInstanceLayerProperties.txt[]

   * pname:pPropertyCount is a pointer to an integer related to the number of
     layer properties available or queried, as described below.
   * pname:pProperties is either `NULL` or a pointer to an array of
     slink:VkLayerProperties structures.

 If pname:pProperties is `NULL`, then the number of layer properties
 available is returned in pname:pPropertyCount.
 Otherwise, pname:pPropertyCount must: point to a variable set by the user to
 the number of elements in the pname:pProperties array, and on return the
 variable is overwritten with the number of structures actually written to
 pname:pProperties.
 If pname:pPropertyCount is less than the number of layer properties
 available, at most pname:pPropertyCount structures will be written.
 If pname:pPropertyCount is smaller than the number of layers available,
 ename:VK_INCOMPLETE will be returned instead of ename:VK_SUCCESS, to
 indicate that not all the available layer properties were returned.

 The list of available layers may change at any time due to actions outside
 of the Vulkan implementation, so two calls to
 fname:vkEnumerateInstanceLayerProperties with the same parameters may:
 return different results, or retrieve different pname:pPropertyCount values
 or pname:pProperties contents.
 Once an instance has been created, the layers enabled for that instance will
 continue to be enabled and valid for the lifetime of that instance, even if
 some of them become unavailable for future instances.

 include::../validity/protos/vkEnumerateInstanceLayerProperties.txt[]
 --

 [open,refpage='VkLayerProperties',desc='Structure specifying layer properties',type='structs']
 --

 The sname:VkLayerProperties structure is defined as:

 include::../api/structs/VkLayerProperties.txt[]

   * pname:layerName is a null-terminated UTF-8 string specifying the name of
     the layer.
     Use this name in the pname:ppEnabledLayerNames array passed in the
     slink:VkInstanceCreateInfo structure to enable this layer for an
     instance.
   * pname:specVersion is the Vulkan version the layer was written to,
     encoded as described in the <<fundamentals-versionnum,API Version
     Numbers and Semantics>> section.
   * pname:implementationVersion is the version of this layer.
     It is an integer, increasing with backward compatible changes.
   * pname:description is a null-terminated UTF-8 string providing additional
     details that can: be used by the application to identify the layer.

 include::../validity/structs/VkLayerProperties.txt[]
 --

 To enable a layer, the name of the layer should: be added to the
 pname:ppEnabledLayerNames member of slink:VkInstanceCreateInfo when creating
 a sname:VkInstance.

 Loader implementations may: provide mechanisms outside the Vulkan API for
 enabling specific layers.
 Layers enabled through such a mechanism are _implicitly enabled_, while
 layers enabled by including the layer name in the pname:ppEnabledLayerNames
 member of slink:VkInstanceCreateInfo are _explicitly enabled_.
 Except where otherwise specified, implicitly enabled and explicitly enabled
 layers differ only in the way they are enabled.
 Explicitly enabling a layer that is implicitly enabled has no additional
 effect.


 [[extended-functionality-device-layer-deprecation]]
 === Device Layer Deprecation

 Previous versions of this specification distinguished between instance and
 device layers.
 Instance layers were only able to intercept commands that operate on
 sname:VkInstance and sname:VkPhysicalDevice, except they were not able to
 intercept flink:vkCreateDevice.
 Device layers were enabled for individual devices when they were created,
 and could only intercept commands operating on that device or its child
 objects.

 Device-only layers are now deprecated, and this specification no longer
 distinguishes between instance and device layers.
 Layers are enabled during instance creation, and are able to intercept all
 commands operating on that instance or any of its child objects.
 At the time of deprecation there were no known device-only layers and no
 compelling reason to create one.

 In order to maintain compatibility with implementations released prior to
 device-layer deprecation, applications should: still enumerate and enable
 device layers.
 The behavior of fname:vkEnumerateDeviceLayerProperties and valid usage of
 the pname:ppEnabledLayerNames member of sname:VkDeviceCreateInfo maximizes
 compatibility with applications written to work with the previous
 requirements.

 [open,refpage='vkEnumerateDeviceLayerProperties',desc='Returns properties of available physical device layers',type='protos']
 --

 To enumerate device layers, call:

 include::../api/protos/vkEnumerateDeviceLayerProperties.txt[]

   * pname:pPropertyCount is a pointer to an integer related to the number of
     layer properties available or queried.
   * pname:pProperties is either `NULL` or a pointer to an array of
     slink:VkLayerProperties structures.

 If pname:pProperties is `NULL`, then the number of layer properties
 available is returned in pname:pPropertyCount.
 Otherwise, pname:pPropertyCount must: point to a variable set by the user to
 the number of elements in the pname:pProperties array, and on return the
 variable is overwritten with the number of structures actually written to
 pname:pProperties.
 If pname:pPropertyCount is less than the number of layer properties
 available, at most pname:pPropertyCount structures will be written.
 If pname:pPropertyCount is smaller than the number of layers available,
 ename:VK_INCOMPLETE will be returned instead of ename:VK_SUCCESS, to
 indicate that not all the available layer properties were returned.

 The list of layers enumerated by fname:vkEnumerateDeviceLayerProperties
 must: be exactly the sequence of layers enabled for the instance.
 The members of sname:VkLayerProperties for each enumerated layer must: be
 the same as the properties when the layer was enumerated by
 fname:vkEnumerateInstanceLayerProperties.

 include::../validity/protos/vkEnumerateDeviceLayerProperties.txt[]
 --

 The pname:ppEnabledLayerNames and pname:enabledLayerCount members of
 sname:VkDeviceCreateInfo are deprecated and their values must: be ignored by
 implementations.
 However, for compatibility, only an empty list of layers or a list that
 exactly matches the sequence enabled at instance creation time are valid,
 and validation layers should: issue diagnostics for other cases.

 Regardless of the enabled layer list provided in sname:VkDeviceCreateInfo,
 the sequence of layers active for a device will be exactly the sequence of
 layers enabled when the parent instance was created.


 [[extended-functionality-extensions]]
 == Extensions

 Extensions may: define new Vulkan commands, structures, and enumerants.
 For compilation purposes, the interfaces defined by registered extensions,
 including new structures and enumerants as well as function pointer types
 for new commands, are defined in the Khronos-supplied `vulkan_core.h`
 together with the core API.
 However, commands defined by extensions may: not be available for static
 linking - in which case function pointers to these commands should: be
 queried at runtime as described in <<initialization-functionpointers>>.
 Extensions may: be provided by layers as well as by a Vulkan implementation.

 Because extensions may: extend or change the behavior of the Vulkan API,
 extension authors should: add support for their extensions to the Khronos
 validation layers.
 This is especially important for new commands whose parameters have been
 wrapped by the validation layers.
 See the <<LoaderAndLayerInterface, "`Vulkan Loader Specification and
 Architecture Overview`">> document for additional information.

 [NOTE]
 .Note
 ====
 Valid Usage sections for individual commands and structures do not currently
 contain which extensions have to be enabled in order to make their use
 valid, although it might do so in the future.
 It is defined only in the <<fundamentals-validusage-extensions>> section.
 ====

 [open,refpage='vkEnumerateInstanceExtensionProperties',desc='Returns up to requested number of global extension properties',type='protos']
 --

 To query the available instance extensions, call:

 include::../api/protos/vkEnumerateInstanceExtensionProperties.txt[]

   * pname:pLayerName is either `NULL` or a pointer to a null-terminated
     UTF-8 string naming the layer to retrieve extensions from.
   * pname:pPropertyCount is a pointer to an integer related to the number of
     extension properties available or queried, as described below.
   * pname:pProperties is either `NULL` or a pointer to an array of
     slink:VkExtensionProperties structures.

 When pname:pLayerName parameter is `NULL`, only extensions provided by the
 Vulkan implementation or by implicitly enabled layers are returned.
 When pname:pLayerName is the name of a layer, the instance extensions
 provided by that layer are returned.

 If pname:pProperties is `NULL`, then the number of extensions properties
 available is returned in pname:pPropertyCount.
 Otherwise, pname:pPropertyCount must: point to a variable set by the user to
 the number of elements in the pname:pProperties array, and on return the
 variable is overwritten with the number of structures actually written to
 pname:pProperties.
 If pname:pPropertyCount is less than the number of extension properties
 available, at most pname:pPropertyCount structures will be written.
 If pname:pPropertyCount is smaller than the number of extensions available,
 ename:VK_INCOMPLETE will be returned instead of ename:VK_SUCCESS, to
 indicate that not all the available properties were returned.

 Because the list of available layers may change externally between calls to
 pname:vkEnumerateInstanceExtensionProperties, two calls may retrieve
 different results if a pname:pLayerName is available in one call but not in
 another.
 The extensions supported by a layer may also change between two calls, e.g.
 if the layer implementation is replaced by a different version between those
 calls.

 include::../validity/protos/vkEnumerateInstanceExtensionProperties.txt[]
 --

 To enable an instance extension, the name of the extension should: be added
 to the pname:ppEnabledExtensionNames member of slink:VkInstanceCreateInfo
 when creating a sname:VkInstance.

 Enabling an extension does not change behavior of functionality exposed by
 the core Vulkan API or any other extension, other than making valid the use
 of the commands, enums and structures defined by that extension.

 [open,refpage='vkEnumerateDeviceExtensionProperties',desc='Returns properties of available physical device extensions',type='protos']
 --

 To query the extensions available to a given physical device, call:

 include::../api/protos/vkEnumerateDeviceExtensionProperties.txt[]

   * pname:physicalDevice is the physical device that will be queried.
   * pname:pLayerName is either `NULL` or a pointer to a null-terminated
     UTF-8 string naming the layer to retrieve extensions from.
   * pname:pPropertyCount is a pointer to an integer related to the number of
     extension properties available or queried, and is treated in the same
     fashion as the
     flink:vkEnumerateInstanceExtensionProperties::pname:pPropertyCount
     parameter.
   * pname:pProperties is either `NULL` or a pointer to an array of
     slink:VkExtensionProperties structures.

 When pname:pLayerName parameter is `NULL`, only extensions provided by the
 Vulkan implementation or by implicitly enabled layers are returned.
 When pname:pLayerName is the name of a layer, the device extensions provided
 by that layer are returned.

 include::../validity/protos/vkEnumerateDeviceExtensionProperties.txt[]
 --

 [open,refpage='VkExtensionProperties',desc='Structure specifying an extension properties',type='structs']
 --

 The sname:VkExtensionProperties structure is defined as:

 include::../api/structs/VkExtensionProperties.txt[]

   * pname:extensionName is a null-terminated string specifying the name of
     the extension.
   * pname:specVersion is the version of this extension.
     It is an integer, incremented with backward compatible changes.

 include::../validity/structs/VkExtensionProperties.txt[]
 --


 [[extended-functionality-instance-extensions-and-devices]]
 === Instance Extensions and Device Extensions

 This section provides some guidelines and rules for when to expose new
 functionality as an instance extension, as a device extension, or as both.
 The decision depends on the scope of the new functionality; such as whether
 it extends instance-level or device-level functionality.
 All Vulkan commands, structures, and enumerants are considered either
 instance-level, physical-device-level, or device-level.

 New instance-level extension functionality must: be structured within an
 instance extension.
 New device-level extension functionality may: be structured within a device
 extension.
 Vulkan 1.0 initially required all new physical-device-level extension
 functionality to be structured within an instance extension.
 ifdef::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[]
 In order to avoid using an instance extension, which often requires loader
 support, physical-device-level extension functionality may: be implemented
 within device extensions (which must: depend on the
 `<<VK_KHR_get_physical_device_properties2>>` extension, or on Vulkan 1.1 or
 later).
 endif::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[]


 [[extended-functionality-extensions-dependencies]]
 == Extension Dependencies

 Some extensions are dependent on other extensions to function.
 To enable extensions with dependencies, such _required extensions_ must:
 also be enabled through the same API mechanisms when creating an instance
 with flink:vkCreateInstance or a device with flink:vkCreateDevice.
 Each extension which has such dependencies documents them in the
 <<extensions, appendix summarizing that extension>>.

 If an extension is supported (as queried by
 flink:vkEnumerateInstanceExtensionProperties or
 flink:vkEnumerateDeviceExtensionProperties), then _required extensions_ of
 that extension must: also be supported for the same instance or physical
 device.

 Any device extension that has an instance extension dependency that is not
 enabled by flink:vkCreateInstance is considered to be unsupported, hence it
 must: not be returned by flink:vkEnumerateDeviceExtensionProperties for any
 slink:VkPhysicalDevice child of the instance.


 [[extended-functionality-extensions-compatibility]]
 == Extension Compatibility

 By default, all extensions are considered compatible with each other and any
 core API version, unless otherwise stated.
 Thus enabling such extensions does not otherwise alter the behavior of the
 application.

 Each extension that is mutually exclusive or otherwise incompatible with
 another extension or set of extensions documents them in the <<extensions,
 appendix summarizing that extension>> and has a corresponding Valid Usage
 statement disallowing enabling such an incompatible combination of
 extensions at sname:VkInstance creation time or sname:VkDevice creation
 time, depending on the type of extensions participating in the interaction.
	// 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/

	[[extended-functionality]]
	= Extended Functionality

	Additional functionality may: be provided by layers or extensions.
	A layer cannot: add or modify Vulkan commands, while an extension may: do
	so.

	The set of layers to enable is specified when creating an instance, and
	those layers are able to intercept any Vulkan command dispatched to that
	instance or any of its child objects.

	Extensions can operate at either the instance or device _extension scope_.
	Enabled instance extensions are able to affect the operation of the instance
	and any of its child objects, while device extensions may: only be available
	on a subset of physical devices, must: be individually enabled per-device,
	and only affect the operation of the devices where they are enabled.

	[NOTE]
	.Note
	====
	Examples of these might be:

	* Whole API validation is an example of a layer.
	* Debug capabilities might make a good instance extension.
	* A layer that provides implementation-specific performance telemetry and
	analysis could be a layer that is only active for devices created from
	compatible physical devices.
	* Functions to allow an application to use additional implementation
	features beyond the core would be a good candidate for a device
	extension.
	====

	[[extended-functionality-layers]]
	== Layers

	When a layer is enabled, it inserts itself into the call chain for Vulkan
	commands the layer is interested in.
	A common use of layers is to validate application behavior during
	development.
	For example, the implementation will not check that Vulkan enums used by the
	application fall within allowed ranges.
	Instead, a validation layer would do those checks and flag issues.
	This avoids a performance penalty during production use of the application
	because those layers would not be enabled in production.

	Vulkan layers may: wrap object handles (i.e. return a different handle value
	to the application than that generated by the implementation).
	This is generally discouraged, as it increases the probability of
	incompatibilities with new extensions.
	The validation layers wrap handles in order to track the proper use and
	destruction of each object.
	See the <<LoaderAndLayerInterface, "`Vulkan Loader Specification and
	Architecture Overview`">> document for additional information.

	[open,refpage='vkEnumerateInstanceLayerProperties',desc='Returns up to requested number of global layer properties',type='protos']
	--

	To query the available layers, call:

	include::../api/protos/vkEnumerateInstanceLayerProperties.txt[]

	* pname:pPropertyCount is a pointer to an integer related to the number of
	layer properties available or queried, as described below.
	* pname:pProperties is either `NULL` or a pointer to an array of
	slink:VkLayerProperties structures.

	If pname:pProperties is `NULL`, then the number of layer properties
	available is returned in pname:pPropertyCount.
	Otherwise, pname:pPropertyCount must: point to a variable set by the user to
	the number of elements in the pname:pProperties array, and on return the
	variable is overwritten with the number of structures actually written to
	pname:pProperties.
	If pname:pPropertyCount is less than the number of layer properties
	available, at most pname:pPropertyCount structures will be written.
	If pname:pPropertyCount is smaller than the number of layers available,
	ename:VK_INCOMPLETE will be returned instead of ename:VK_SUCCESS, to
	indicate that not all the available layer properties were returned.

	The list of available layers may change at any time due to actions outside
	of the Vulkan implementation, so two calls to
	fname:vkEnumerateInstanceLayerProperties with the same parameters may:
	return different results, or retrieve different pname:pPropertyCount values
	or pname:pProperties contents.
	Once an instance has been created, the layers enabled for that instance will
	continue to be enabled and valid for the lifetime of that instance, even if
	some of them become unavailable for future instances.

	include::../validity/protos/vkEnumerateInstanceLayerProperties.txt[]
	--

	[open,refpage='VkLayerProperties',desc='Structure specifying layer properties',type='structs']
	--

	The sname:VkLayerProperties structure is defined as:

	include::../api/structs/VkLayerProperties.txt[]

	* pname:layerName is a null-terminated UTF-8 string specifying the name of
	the layer.
	Use this name in the pname:ppEnabledLayerNames array passed in the
	slink:VkInstanceCreateInfo structure to enable this layer for an
	instance.
	* pname:specVersion is the Vulkan version the layer was written to,
	encoded as described in the <<fundamentals-versionnum,API Version
	Numbers and Semantics>> section.
	* pname:implementationVersion is the version of this layer.
	It is an integer, increasing with backward compatible changes.
	* pname:description is a null-terminated UTF-8 string providing additional
	details that can: be used by the application to identify the layer.

	include::../validity/structs/VkLayerProperties.txt[]
	--

	To enable a layer, the name of the layer should: be added to the
	pname:ppEnabledLayerNames member of slink:VkInstanceCreateInfo when creating
	a sname:VkInstance.

	Loader implementations may: provide mechanisms outside the Vulkan API for
	enabling specific layers.
	Layers enabled through such a mechanism are _implicitly enabled_, while
	layers enabled by including the layer name in the pname:ppEnabledLayerNames
	member of slink:VkInstanceCreateInfo are _explicitly enabled_.
	Except where otherwise specified, implicitly enabled and explicitly enabled
	layers differ only in the way they are enabled.
	Explicitly enabling a layer that is implicitly enabled has no additional
	effect.


	[[extended-functionality-device-layer-deprecation]]
	=== Device Layer Deprecation

	Previous versions of this specification distinguished between instance and
	device layers.
	Instance layers were only able to intercept commands that operate on
	sname:VkInstance and sname:VkPhysicalDevice, except they were not able to
	intercept flink:vkCreateDevice.
	Device layers were enabled for individual devices when they were created,
	and could only intercept commands operating on that device or its child
	objects.

	Device-only layers are now deprecated, and this specification no longer
	distinguishes between instance and device layers.
	Layers are enabled during instance creation, and are able to intercept all
	commands operating on that instance or any of its child objects.
	At the time of deprecation there were no known device-only layers and no
	compelling reason to create one.

	In order to maintain compatibility with implementations released prior to
	device-layer deprecation, applications should: still enumerate and enable
	device layers.
	The behavior of fname:vkEnumerateDeviceLayerProperties and valid usage of
	the pname:ppEnabledLayerNames member of sname:VkDeviceCreateInfo maximizes
	compatibility with applications written to work with the previous
	requirements.

	[open,refpage='vkEnumerateDeviceLayerProperties',desc='Returns properties of available physical device layers',type='protos']
	--

	To enumerate device layers, call:

	include::../api/protos/vkEnumerateDeviceLayerProperties.txt[]

	* pname:pPropertyCount is a pointer to an integer related to the number of
	layer properties available or queried.
	* pname:pProperties is either `NULL` or a pointer to an array of
	slink:VkLayerProperties structures.

	If pname:pProperties is `NULL`, then the number of layer properties
	available is returned in pname:pPropertyCount.
	Otherwise, pname:pPropertyCount must: point to a variable set by the user to
	the number of elements in the pname:pProperties array, and on return the
	variable is overwritten with the number of structures actually written to
	pname:pProperties.
	If pname:pPropertyCount is less than the number of layer properties
	available, at most pname:pPropertyCount structures will be written.
	If pname:pPropertyCount is smaller than the number of layers available,
	ename:VK_INCOMPLETE will be returned instead of ename:VK_SUCCESS, to
	indicate that not all the available layer properties were returned.

	The list of layers enumerated by fname:vkEnumerateDeviceLayerProperties
	must: be exactly the sequence of layers enabled for the instance.
	The members of sname:VkLayerProperties for each enumerated layer must: be
	the same as the properties when the layer was enumerated by
	fname:vkEnumerateInstanceLayerProperties.

	include::../validity/protos/vkEnumerateDeviceLayerProperties.txt[]
	--

	The pname:ppEnabledLayerNames and pname:enabledLayerCount members of
	sname:VkDeviceCreateInfo are deprecated and their values must: be ignored by
	implementations.
	However, for compatibility, only an empty list of layers or a list that
	exactly matches the sequence enabled at instance creation time are valid,
	and validation layers should: issue diagnostics for other cases.

	Regardless of the enabled layer list provided in sname:VkDeviceCreateInfo,
	the sequence of layers active for a device will be exactly the sequence of
	layers enabled when the parent instance was created.


	[[extended-functionality-extensions]]
	== Extensions

	Extensions may: define new Vulkan commands, structures, and enumerants.
	For compilation purposes, the interfaces defined by registered extensions,
	including new structures and enumerants as well as function pointer types
	for new commands, are defined in the Khronos-supplied `vulkan_core.h`
	together with the core API.
	However, commands defined by extensions may: not be available for static
	linking - in which case function pointers to these commands should: be
	queried at runtime as described in <<initialization-functionpointers>>.
	Extensions may: be provided by layers as well as by a Vulkan implementation.

	Because extensions may: extend or change the behavior of the Vulkan API,
	extension authors should: add support for their extensions to the Khronos
	validation layers.
	This is especially important for new commands whose parameters have been
	wrapped by the validation layers.
	See the <<LoaderAndLayerInterface, "`Vulkan Loader Specification and
	Architecture Overview`">> document for additional information.

	[NOTE]
	.Note
	====
	Valid Usage sections for individual commands and structures do not currently
	contain which extensions have to be enabled in order to make their use
	valid, although it might do so in the future.
	It is defined only in the <<fundamentals-validusage-extensions>> section.
	====

	[open,refpage='vkEnumerateInstanceExtensionProperties',desc='Returns up to requested number of global extension properties',type='protos']
	--

	To query the available instance extensions, call:

	include::../api/protos/vkEnumerateInstanceExtensionProperties.txt[]

	* pname:pLayerName is either `NULL` or a pointer to a null-terminated
	UTF-8 string naming the layer to retrieve extensions from.
	* pname:pPropertyCount is a pointer to an integer related to the number of
	extension properties available or queried, as described below.
	* pname:pProperties is either `NULL` or a pointer to an array of
	slink:VkExtensionProperties structures.

	When pname:pLayerName parameter is `NULL`, only extensions provided by the
	Vulkan implementation or by implicitly enabled layers are returned.
	When pname:pLayerName is the name of a layer, the instance extensions
	provided by that layer are returned.

	If pname:pProperties is `NULL`, then the number of extensions properties
	available is returned in pname:pPropertyCount.
	Otherwise, pname:pPropertyCount must: point to a variable set by the user to
	the number of elements in the pname:pProperties array, and on return the
	variable is overwritten with the number of structures actually written to
	pname:pProperties.
	If pname:pPropertyCount is less than the number of extension properties
	available, at most pname:pPropertyCount structures will be written.
	If pname:pPropertyCount is smaller than the number of extensions available,
	ename:VK_INCOMPLETE will be returned instead of ename:VK_SUCCESS, to
	indicate that not all the available properties were returned.

	Because the list of available layers may change externally between calls to
	pname:vkEnumerateInstanceExtensionProperties, two calls may retrieve
	different results if a pname:pLayerName is available in one call but not in
	another.
	The extensions supported by a layer may also change between two calls, e.g.
	if the layer implementation is replaced by a different version between those
	calls.

	include::../validity/protos/vkEnumerateInstanceExtensionProperties.txt[]
	--

	To enable an instance extension, the name of the extension should: be added
	to the pname:ppEnabledExtensionNames member of slink:VkInstanceCreateInfo
	when creating a sname:VkInstance.

	Enabling an extension does not change behavior of functionality exposed by
	the core Vulkan API or any other extension, other than making valid the use
	of the commands, enums and structures defined by that extension.

	[open,refpage='vkEnumerateDeviceExtensionProperties',desc='Returns properties of available physical device extensions',type='protos']
	--

	To query the extensions available to a given physical device, call:

	include::../api/protos/vkEnumerateDeviceExtensionProperties.txt[]

	* pname:physicalDevice is the physical device that will be queried.
	* pname:pLayerName is either `NULL` or a pointer to a null-terminated
	UTF-8 string naming the layer to retrieve extensions from.
	* pname:pPropertyCount is a pointer to an integer related to the number of
	extension properties available or queried, and is treated in the same
	fashion as the
	flink:vkEnumerateInstanceExtensionProperties::pname:pPropertyCount
	parameter.
	* pname:pProperties is either `NULL` or a pointer to an array of
	slink:VkExtensionProperties structures.

	When pname:pLayerName parameter is `NULL`, only extensions provided by the
	Vulkan implementation or by implicitly enabled layers are returned.
	When pname:pLayerName is the name of a layer, the device extensions provided
	by that layer are returned.

	include::../validity/protos/vkEnumerateDeviceExtensionProperties.txt[]
	--

	[open,refpage='VkExtensionProperties',desc='Structure specifying an extension properties',type='structs']
	--

	The sname:VkExtensionProperties structure is defined as:

	include::../api/structs/VkExtensionProperties.txt[]

	* pname:extensionName is a null-terminated string specifying the name of
	the extension.
	* pname:specVersion is the version of this extension.
	It is an integer, incremented with backward compatible changes.

	include::../validity/structs/VkExtensionProperties.txt[]
	--


	[[extended-functionality-instance-extensions-and-devices]]
	=== Instance Extensions and Device Extensions

	This section provides some guidelines and rules for when to expose new
	functionality as an instance extension, as a device extension, or as both.
	The decision depends on the scope of the new functionality; such as whether
	it extends instance-level or device-level functionality.
	All Vulkan commands, structures, and enumerants are considered either
	instance-level, physical-device-level, or device-level.

	New instance-level extension functionality must: be structured within an
	instance extension.
	New device-level extension functionality may: be structured within a device
	extension.
	Vulkan 1.0 initially required all new physical-device-level extension
	functionality to be structured within an instance extension.
	ifdef::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[]
	In order to avoid using an instance extension, which often requires loader
	support, physical-device-level extension functionality may: be implemented
	within device extensions (which must: depend on the
	`<<VK_KHR_get_physical_device_properties2>>` extension, or on Vulkan 1.1 or
	later).
	endif::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[]


	[[extended-functionality-extensions-dependencies]]
	== Extension Dependencies

	Some extensions are dependent on other extensions to function.
	To enable extensions with dependencies, such _required extensions_ must:
	also be enabled through the same API mechanisms when creating an instance
	with flink:vkCreateInstance or a device with flink:vkCreateDevice.
	Each extension which has such dependencies documents them in the
	<<extensions, appendix summarizing that extension>>.

	If an extension is supported (as queried by
	flink:vkEnumerateInstanceExtensionProperties or
	flink:vkEnumerateDeviceExtensionProperties), then _required extensions_ of
	that extension must: also be supported for the same instance or physical
	device.

	Any device extension that has an instance extension dependency that is not
	enabled by flink:vkCreateInstance is considered to be unsupported, hence it
	must: not be returned by flink:vkEnumerateDeviceExtensionProperties for any
	slink:VkPhysicalDevice child of the instance.


	[[extended-functionality-extensions-compatibility]]
	== Extension Compatibility

	By default, all extensions are considered compatible with each other and any
	core API version, unless otherwise stated.
	Thus enabling such extensions does not otherwise alter the behavior of the
	application.

	Each extension that is mutually exclusive or otherwise incompatible with
	another extension or set of extensions documents them in the <<extensions,
	appendix summarizing that extension>> and has a corresponding Valid Usage
	statement disallowing enabling such an incompatible combination of
	extensions at sname:VkInstance creation time or sname:VkDevice creation
	time, depending on the type of extensions participating in the interaction.