registry/vulkan/appendices/boilerplate.txt - platform/external/gfxstream-protocols - Git at Google

 // Copyright (c) 2016-2018 Khronos Group. This work is licensed under a
 // Creative Commons Attribution 4.0 International License; see
 // http://creativecommons.org/licenses/by/4.0/

 [appendix]
 [[boilerplate]]
 = API Boilerplate

 This appendix defines Vulkan API features that are infrastructure required
 for a complete functional description of Vulkan, but do not logically belong
 elsewhere in the Specification.


 [[boilerplate-headers]]
 == Vulkan Header Files

 Vulkan is defined as an API in the C99 language.
 Khronos provides a corresponding set of header files for applications using
 the API, which may be used in either C or C++ code.
 The interface descriptions in the specification are the same as the
 interfaces defined in these header files, and both are derived from the
 `vk.xml` XML API Registry, which is the canonical machine-readable
 description of the Vulkan API.
 The Registry, scripts used for processing it into various forms, and
 documentation of the registry schema are available as described at
 https://www.khronos.org/registry/vulkan/#apiregistry .

 Language bindings for other languages can be defined using the information
 in the Specification and the Registry.
 Khronos does not provide any such bindings, but third-party developers have
 created some additional bindings.


 [[boilerplate-vulkan-h]]
 === Vulkan Combined API Header `vulkan.h` (Informative)

 Applications normally will include the header `vulkan.h`.
 In turn, `vulkan.h` always includes the following headers:

   * <<boilerplate-platform-macros,`vk_platform.h`>>, defining
     platform-specific macros and headers.
   * <<boilerplate-vulkan-core,`vulkan_core.h`>>, defining APIs for the
     Vulkan core and all registered extensions _other_ than window
     system-specific extensions.

 In addition, specific preprocessor macros defined at the time `vulkan.h` is
 included cause header files for the corresponding <<boilerplate-wsi-header,
 window system-specific extension interfaces>> to be included.


 [[boilerplate-platform-macros]]
 === Vulkan Platform-Specific Header `vk_platform.h` (Informative)

 Platform-specific macros and interfaces are defined in `vk_platform.h`.
 These macros are used to control platform-dependent behavior, and their
 exact definitions are under the control of specific platforms and Vulkan
 implementations.


 [[boilerplate-platform-specific-calling-conventions]]
 ==== Platform-Specific Calling Conventions

 On many platforms the following macros are empty strings, causing platform-
 and compiler-specific default calling conventions to be used.

 // @refBegin VKAPI_ATTR Vulkan function attributes

 dname:VKAPI_ATTR is a macro placed before the return type in Vulkan API
 function declarations.
 This macro controls calling conventions for C++11 and GCC/Clang-style
 compilers.

 // @refEnd VKAPI_ATTR VKAPI_CALL VKAPI_PTR

 // @refBegin VKAPI_CALL Vulkan function calling conventions

 dname:VKAPI_CALL is a macro placed after the return type in Vulkan API
 function declarations.
 This macro controls calling conventions for MSVC-style compilers.

 // @refEnd VKAPI_CALL VKAPI_ATTR VKAPI_PTR

 // @refBegin VKAPI_PTR Vulkan function pointer calling conventions

 dname:VKAPI_PTR is a macro placed between the '(' and '*' in Vulkan API
 function pointer declarations.
 This macro also controls calling conventions, and typically has the same
 definition as dname:VKAPI_ATTR or dname:VKAPI_CALL, depending on the
 compiler.

 // @refEnd VKAPI_PTR VKAPI_ATTR VKAPI_CALL

 With these macros, a Vulkan function declaration takes the form of:

 [source,c++]
 ----------------------------------------
 VKAPI_ATTR <return_type> VKAPI_CALL <command_name>(<command_parameters>);
 ----------------------------------------

 Additionaly, a Vulkan function pointer type declaration takes the form of:

 [source,c++]
 ----------------------------------------
 typedef <return_type> (VKAPI_PTR *PFN_<command_name>)(<command_parameters>);
 ----------------------------------------


 ==== Platform-Specific Header Control

 // @refBegin VK_NO_STDINT_H Control definition of `<stdint.h>` types

 If the code:VK_NO_STDINT_H macro is defined by the application at compile
 time, extended integer types used by the Vulkan API, such as code:uint8_t,
 must: also be defined by the application.
 Otherwise, the Vulkan headers will not compile.
 If code:VK_NO_STDINT_H is not defined, the system `<stdint.h>` is used to
 define these types.
 There is a fallback path when Microsoft Visual Studio version 2008 and
 earlier versions are detected at compile time.

 // @refEnd VK_NO_STDINT_H


 [[boilerplate-vulkan-core]]
 === Vulkan Core API Header `vulkan_core.h`

 Applications that do not make use of window system-specific extensions may
 simply include `vulkan_core.h` instead of `vulkan.h`, although there is
 usually no reason to do so.
 In addition to the Vulkan API, `vulkan_core.h` also defines a small number
 of C preprocessor macros that are described below.


 [[boilerplate-versions]]
 ==== Vulkan Version Number Macros

 <<fundamentals-versionnum,API Version Numbers>> are packed into integers.
 These macros manipulate version numbers in useful ways.

 [open,refpage='VK_VERSION_MAJOR',desc='Extract API major version number',type='defines']
 --

 dname:VK_VERSION_MAJOR extracts the API major version number from a packed
 version number:

 include::../api/defines/VK_VERSION_MAJOR.txt[]

 --

 [open,refpage='VK_VERSION_MINOR',desc='Extract API minor version number',type='defines']
 --

 dname:VK_VERSION_MINOR extracts the API minor version number from a packed
 version number:

 include::../api/defines/VK_VERSION_MINOR.txt[]

 --

 [open,refpage='VK_VERSION_PATCH',desc='Extract API patch version number',type='defines']
 --

 dname:VK_VERSION_PATCH extracts the API patch version number from a packed
 version number:

 include::../api/defines/VK_VERSION_PATCH.txt[]

 --

 [open,refpage='VK_API_VERSION_1_0',desc='Return API version number for Vulkan 1.0',type='defines',xrefs='vkCreateInstance vkGetPhysicalDeviceProperties']
 --

 dname:VK_API_VERSION_1_0 returns the API version number for Vulkan 1.0.
 The patch version number in this macro will always be zero.
 The supported patch version for a physical device can: be queried with
 flink:vkGetPhysicalDeviceProperties.

 include::../api/defines/VK_API_VERSION_1_0.txt[]

 --

 ifdef::VK_VERSION_1_1[]
 [open,refpage='VK_API_VERSION_1_1',desc='Return API version number for Vulkan 1.1',type='defines',xrefs='vkCreateInstance vkGetPhysicalDeviceProperties']
 --

 dname:VK_API_VERSION_1_1 returns the API version number for Vulkan 1.1.
 The patch version number in this macro will always be zero.
 The supported patch version for a physical device can: be queried with
 flink:vkGetPhysicalDeviceProperties.

 include::../api/defines/VK_API_VERSION_1_1.txt[]

 --
 endif::VK_VERSION_1_1[]

 [open,refpage='VK_API_VERSION',desc='Deprecated version number macro',type='defines']
 --

 dname:VK_API_VERSION is now commented out of `vulkan_core.h` and cannot: be
 used.

 include::../api/defines/VK_API_VERSION.txt[]

 --

 [open,refpage='VK_MAKE_VERSION',desc='Construct an API version number',type='defines',xrefs='VkApplicationInfo vkCreateInstance']
 --

 dname:VK_MAKE_VERSION constructs an API version number.

 include::../api/defines/VK_MAKE_VERSION.txt[]

   * pname:major is the major version number.
   * pname:minor is the minor version number.
   * pname:patch is the patch version number.

 This macro can: be used when constructing the
 slink:VkApplicationInfo::pname:apiVersion parameter passed to
 flink:vkCreateInstance.

 --


 ==== Vulkan Header File Version Number

 [open,refpage='VK_HEADER_VERSION',desc='Vulkan header file version number',type='defines']
 --

 dname:VK_HEADER_VERSION is the version number of the `vulkan_core.h` header.
 This value is kept synchronized with the patch version of the released
 Specification.

 include::../api/defines/VK_HEADER_VERSION.txt[]

 --


 ==== Vulkan Handle Macros

 [open,refpage='VK_DEFINE_HANDLE',desc='Declare a dispatchable object handle',type='defines',xrefs='VkCommandBuffer VkDevice VkInstance VkPhysicalDevice VkQueue']
 --

 dname:VK_DEFINE_HANDLE defines a <<fundamentals-objectmodel-overview,
 dispatchable handle>> type.

 include::../api/defines/VK_DEFINE_HANDLE.txt[]

   * pname:object is the name of the resulting C type.

 The only dispatchable handle types are those related to device and instance
 management, such as slink:VkDevice.

 --

 [open,refpage='VK_DEFINE_NON_DISPATCHABLE_HANDLE',desc='Declare a non-dispatchable object handle',type='defines',xrefs='VkBuffer']
 --

 dname:VK_DEFINE_NON_DISPATCHABLE_HANDLE defines a
 <<fundamentals-objectmodel-overview, non-dispatchable handle>> type.

 include::../api/defines/VK_DEFINE_NON_DISPATCHABLE_HANDLE.txt[]

   * pname:object is the name of the resulting C type.

 Most Vulkan handle types, such as slink:VkBuffer, are non-dispatchable.

 [NOTE]
 .Note
 ====
 The `vulkan_core.h` header allows the
 dname:VK_DEFINE_NON_DISPATCHABLE_HANDLE definition to be overridden by the
 application.
 If dname:VK_DEFINE_NON_DISPATCHABLE_HANDLE is already defined when
 `vulkan_core.h` is compiled, the default definition is skipped.
 This allows the application to define a binary-compatible custom handle
 which may: provide more type-safety or other features needed by the
 application.
 Behavior is undefined if the application defines a non-binary-compatible
 handle and may: result in memory corruption or application termination.
 Binary compatibility is platform dependent so the application must: be
 careful if it overrides the default dname:VK_DEFINE_NON_DISPATCHABLE_HANDLE
 definition.
 ====

 --

 [open,refpage='VK_NULL_HANDLE',desc='Reserved non-valid object handle',type='defines']
 --

 dname:VK_NULL_HANDLE is a reserved value representing a non-valid object
 handle.
 It may be passed to and returned from Vulkan commands only when
 <<fundamentals-validusage-handles, specifically allowed>>.

 include::../api/defines/VK_NULL_HANDLE.txt[]

 --


 [[boilerplate-wsi-header]]
 == Window System-Specific Header Control (Informative)

 // @refBegin WSIheaders Control inclusion of window system interface extensions

 To use a Vulkan extension supporting a platform-specific window system,
 header files for that window systems must: be included at compile time, or
 platform-specific types must: be forward-declared.
 The Vulkan header files cannot determine whether or not an external header
 is available at compile time, so platform-specific extensions are provided
 in separate headers from the core API and platform-independent extensions,
 allowing applications to decide which ones should be defined and how the
 external headers are included.

 Extensions dependent on particular sets of platform headers, or that
 forward-declare platform-specific types, are declared in a header named for
 that platform.
 Before including these platform-specific Vulkan headers, applications must:
 include both `vulkan_core.h` and any external native headers the platform
 extensions depend on.

 As a convenience for applications that do not need the flexibility of
 separate platform-specific Vulkan headers, `vulkan.h` includes
 `vulkan_core.h`, and then conditionally includes platform-specific Vulkan
 headers and the external headers they depend on.
 Applications control which platform-specific headers are included by
 #defining macros before including `vulkan.h`.

 The correspondence between platform-specific extensions, external headers
 they require, the platform-specific header which declares them, and the
 preprocessor macros which enable inclusion by `vulkan.h` are shown in the
 <<boilerplate-wsi-header-table,following table>>.

 [[boilerplate-wsi-header-table]]
 .Window System Extensions and Headers
 [options="header"]
 |====
 | Extension Name                     | Window System Name | Platform-specific Header | Required External Headers      | Controlling `vulkan.h` Macro
 | `<<VK_KHR_android_surface>>`       | Android            | `vulkan_android.h`       | None                           | dname:VK_USE_PLATFORM_ANDROID_KHR
 | `<<VK_KHR_mir_surface>>`           | Mir                | `vulkan_mir.h`           | `<mir_toolkit/client_types.h>` | dname:VK_USE_PLATFORM_MIR_KHR
 | `<<VK_KHR_wayland_surface>>`       | Wayland            | `vulkan_wayland.h`       | `<wayland-client.h>`           | dname:VK_USE_PLATFORM_WAYLAND_KHR
 | `<<VK_KHR_win32_surface>>`,
   `<<VK_KHR_external_memory_win32>>`,
   `<<VK_KHR_win32_keyed_mutex>>`,
   `<<VK_KHR_external_semaphore_win32>>`,
   `<<VK_KHR_external_fence_win32>>`,
 ifdef::VK_NV_external_memory_win32[]
   `<<VK_NV_external_memory_win32>>`,
 endif::VK_NV_external_memory_win32[]
 ifdef::VK_NV_win32_keyed_mutex[]
   `<<VK_NV_win32_keyed_mutex>>`
 endif::VK_NV_win32_keyed_mutex[]
                                      | Microsoft Windows  | `vulkan_win32.h`         | `<windows.h>`                  | dname:VK_USE_PLATFORM_WIN32_KHR
 | `<<VK_KHR_xcb_surface>>`           | X11 Xcb            | `vulkan_xcb.h`           | `<xcb/xcb.h>`                  | dname:VK_USE_PLATFORM_XCB_KHR
 | `<<VK_KHR_xlib_surface>>`          | X11 Xlib           | `vulkan_xlib.h`          | `<X11/Xlib.h>`                 | dname:VK_USE_PLATFORM_XLIB_KHR
 ifdef::VK_EXT_acquire_xlib_display[]
 | `<<VK_EXT_acquire_xlib_display>>`  | X11 XRAndR         | `vulkan_xlib_xrandr.h`   | `<X11/Xlib.h>`,
                                                                                        `<X11/extensions/Xrandr.h>`    | dname:VK_USE_PLATFORM_XLIB_XRANDR_EXT
 endif::VK_EXT_acquire_xlib_display[]
 ifdef::VK_MVK_ios_surface[]
 | `<<VK_MVK_ios_surface>>`           | iOS                | `vulkan_ios.h`           | None                           | dname:VK_USE_PLATFORM_IOS_MVK
 endif::VK_MVK_ios_surface[]
 ifdef::VK_MVK_macos_surface[]
 | `<<VK_MVK_macos_surface>>`         | macOS              | `vulkan_macos.h`         | None                           | dname:VK_USE_PLATFORM_MACOS_MVK
 endif::VK_MVK_macos_surface[]
 ifdef::VK_NN_vi_surface[]
 | `<<VK_NN_vi_surface>>`             | VI                 | `vulkan_vi.h`            | None                           | dname:VK_USE_PLATFORM_VI_NN
 endif::VK_NN_vi_surface[]
 |====

 [NOTE]
 .Note
 ====
 This section describes the purpose of the headers independently of the
 specific underlying functionality of the window system extensions
 themselves.
 Each extension name will only link to a description of that extension when
 viewing a specification built with that extension included.
 ====

 // @refEnd WSIheaders
	// Copyright (c) 2016-2018 Khronos Group. This work is licensed under a
	// Creative Commons Attribution 4.0 International License; see
	// http://creativecommons.org/licenses/by/4.0/

	[appendix]
	[[boilerplate]]
	= API Boilerplate

	This appendix defines Vulkan API features that are infrastructure required
	for a complete functional description of Vulkan, but do not logically belong
	elsewhere in the Specification.


	[[boilerplate-headers]]
	== Vulkan Header Files

	Vulkan is defined as an API in the C99 language.
	Khronos provides a corresponding set of header files for applications using
	the API, which may be used in either C or C++ code.
	The interface descriptions in the specification are the same as the
	interfaces defined in these header files, and both are derived from the
	`vk.xml` XML API Registry, which is the canonical machine-readable
	description of the Vulkan API.
	The Registry, scripts used for processing it into various forms, and
	documentation of the registry schema are available as described at
	https://www.khronos.org/registry/vulkan/#apiregistry .

	Language bindings for other languages can be defined using the information
	in the Specification and the Registry.
	Khronos does not provide any such bindings, but third-party developers have
	created some additional bindings.


	[[boilerplate-vulkan-h]]
	=== Vulkan Combined API Header `vulkan.h` (Informative)

	Applications normally will include the header `vulkan.h`.
	In turn, `vulkan.h` always includes the following headers:

	* <<boilerplate-platform-macros,`vk_platform.h`>>, defining
	platform-specific macros and headers.
	* <<boilerplate-vulkan-core,`vulkan_core.h`>>, defining APIs for the
	Vulkan core and all registered extensions _other_ than window
	system-specific extensions.

	In addition, specific preprocessor macros defined at the time `vulkan.h` is
	included cause header files for the corresponding <<boilerplate-wsi-header,
	window system-specific extension interfaces>> to be included.


	[[boilerplate-platform-macros]]
	=== Vulkan Platform-Specific Header `vk_platform.h` (Informative)

	Platform-specific macros and interfaces are defined in `vk_platform.h`.
	These macros are used to control platform-dependent behavior, and their
	exact definitions are under the control of specific platforms and Vulkan
	implementations.


	[[boilerplate-platform-specific-calling-conventions]]
	==== Platform-Specific Calling Conventions

	On many platforms the following macros are empty strings, causing platform-
	and compiler-specific default calling conventions to be used.

	// @refBegin VKAPI_ATTR Vulkan function attributes

	dname:VKAPI_ATTR is a macro placed before the return type in Vulkan API
	function declarations.
	This macro controls calling conventions for C++11 and GCC/Clang-style
	compilers.

	// @refEnd VKAPI_ATTR VKAPI_CALL VKAPI_PTR

	// @refBegin VKAPI_CALL Vulkan function calling conventions

	dname:VKAPI_CALL is a macro placed after the return type in Vulkan API
	function declarations.
	This macro controls calling conventions for MSVC-style compilers.

	// @refEnd VKAPI_CALL VKAPI_ATTR VKAPI_PTR

	// @refBegin VKAPI_PTR Vulkan function pointer calling conventions

	dname:VKAPI_PTR is a macro placed between the '(' and '*' in Vulkan API
	function pointer declarations.
	This macro also controls calling conventions, and typically has the same
	definition as dname:VKAPI_ATTR or dname:VKAPI_CALL, depending on the
	compiler.

	// @refEnd VKAPI_PTR VKAPI_ATTR VKAPI_CALL

	With these macros, a Vulkan function declaration takes the form of:

	[source,c++]
	----------------------------------------
	VKAPI_ATTR <return_type> VKAPI_CALL <command_name>(<command_parameters>);
	----------------------------------------

	Additionaly, a Vulkan function pointer type declaration takes the form of:

	[source,c++]
	----------------------------------------
	typedef <return_type> (VKAPI_PTR *PFN_<command_name>)(<command_parameters>);
	----------------------------------------


	==== Platform-Specific Header Control

	// @refBegin VK_NO_STDINT_H Control definition of `<stdint.h>` types

	If the code:VK_NO_STDINT_H macro is defined by the application at compile
	time, extended integer types used by the Vulkan API, such as code:uint8_t,
	must: also be defined by the application.
	Otherwise, the Vulkan headers will not compile.
	If code:VK_NO_STDINT_H is not defined, the system `<stdint.h>` is used to
	define these types.
	There is a fallback path when Microsoft Visual Studio version 2008 and
	earlier versions are detected at compile time.

	// @refEnd VK_NO_STDINT_H


	[[boilerplate-vulkan-core]]
	=== Vulkan Core API Header `vulkan_core.h`

	Applications that do not make use of window system-specific extensions may
	simply include `vulkan_core.h` instead of `vulkan.h`, although there is
	usually no reason to do so.
	In addition to the Vulkan API, `vulkan_core.h` also defines a small number
	of C preprocessor macros that are described below.


	[[boilerplate-versions]]
	==== Vulkan Version Number Macros

	<<fundamentals-versionnum,API Version Numbers>> are packed into integers.
	These macros manipulate version numbers in useful ways.

	[open,refpage='VK_VERSION_MAJOR',desc='Extract API major version number',type='defines']
	--

	dname:VK_VERSION_MAJOR extracts the API major version number from a packed
	version number:

	include::../api/defines/VK_VERSION_MAJOR.txt[]

	--

	[open,refpage='VK_VERSION_MINOR',desc='Extract API minor version number',type='defines']
	--

	dname:VK_VERSION_MINOR extracts the API minor version number from a packed
	version number:

	include::../api/defines/VK_VERSION_MINOR.txt[]

	--

	[open,refpage='VK_VERSION_PATCH',desc='Extract API patch version number',type='defines']
	--

	dname:VK_VERSION_PATCH extracts the API patch version number from a packed
	version number:

	include::../api/defines/VK_VERSION_PATCH.txt[]

	--

	[open,refpage='VK_API_VERSION_1_0',desc='Return API version number for Vulkan 1.0',type='defines',xrefs='vkCreateInstance vkGetPhysicalDeviceProperties']
	--

	dname:VK_API_VERSION_1_0 returns the API version number for Vulkan 1.0.
	The patch version number in this macro will always be zero.
	The supported patch version for a physical device can: be queried with
	flink:vkGetPhysicalDeviceProperties.

	include::../api/defines/VK_API_VERSION_1_0.txt[]

	--

	ifdef::VK_VERSION_1_1[]
	[open,refpage='VK_API_VERSION_1_1',desc='Return API version number for Vulkan 1.1',type='defines',xrefs='vkCreateInstance vkGetPhysicalDeviceProperties']
	--

	dname:VK_API_VERSION_1_1 returns the API version number for Vulkan 1.1.
	The patch version number in this macro will always be zero.
	The supported patch version for a physical device can: be queried with
	flink:vkGetPhysicalDeviceProperties.

	include::../api/defines/VK_API_VERSION_1_1.txt[]

	--
	endif::VK_VERSION_1_1[]

	[open,refpage='VK_API_VERSION',desc='Deprecated version number macro',type='defines']
	--

	dname:VK_API_VERSION is now commented out of `vulkan_core.h` and cannot: be
	used.

	include::../api/defines/VK_API_VERSION.txt[]

	--

	[open,refpage='VK_MAKE_VERSION',desc='Construct an API version number',type='defines',xrefs='VkApplicationInfo vkCreateInstance']
	--

	dname:VK_MAKE_VERSION constructs an API version number.

	include::../api/defines/VK_MAKE_VERSION.txt[]

	* pname:major is the major version number.
	* pname:minor is the minor version number.
	* pname:patch is the patch version number.

	This macro can: be used when constructing the
	slink:VkApplicationInfo::pname:apiVersion parameter passed to
	flink:vkCreateInstance.

	--


	==== Vulkan Header File Version Number

	[open,refpage='VK_HEADER_VERSION',desc='Vulkan header file version number',type='defines']
	--

	dname:VK_HEADER_VERSION is the version number of the `vulkan_core.h` header.
	This value is kept synchronized with the patch version of the released
	Specification.

	include::../api/defines/VK_HEADER_VERSION.txt[]

	--


	==== Vulkan Handle Macros

	[open,refpage='VK_DEFINE_HANDLE',desc='Declare a dispatchable object handle',type='defines',xrefs='VkCommandBuffer VkDevice VkInstance VkPhysicalDevice VkQueue']
	--

	dname:VK_DEFINE_HANDLE defines a <<fundamentals-objectmodel-overview,
	dispatchable handle>> type.

	include::../api/defines/VK_DEFINE_HANDLE.txt[]

	* pname:object is the name of the resulting C type.

	The only dispatchable handle types are those related to device and instance
	management, such as slink:VkDevice.

	--

	[open,refpage='VK_DEFINE_NON_DISPATCHABLE_HANDLE',desc='Declare a non-dispatchable object handle',type='defines',xrefs='VkBuffer']
	--

	dname:VK_DEFINE_NON_DISPATCHABLE_HANDLE defines a
	<<fundamentals-objectmodel-overview, non-dispatchable handle>> type.

	include::../api/defines/VK_DEFINE_NON_DISPATCHABLE_HANDLE.txt[]

	* pname:object is the name of the resulting C type.

	Most Vulkan handle types, such as slink:VkBuffer, are non-dispatchable.

	[NOTE]
	.Note
	====
	The `vulkan_core.h` header allows the
	dname:VK_DEFINE_NON_DISPATCHABLE_HANDLE definition to be overridden by the
	application.
	If dname:VK_DEFINE_NON_DISPATCHABLE_HANDLE is already defined when
	`vulkan_core.h` is compiled, the default definition is skipped.
	This allows the application to define a binary-compatible custom handle
	which may: provide more type-safety or other features needed by the
	application.
	Behavior is undefined if the application defines a non-binary-compatible
	handle and may: result in memory corruption or application termination.
	Binary compatibility is platform dependent so the application must: be
	careful if it overrides the default dname:VK_DEFINE_NON_DISPATCHABLE_HANDLE
	definition.
	====

	--

	[open,refpage='VK_NULL_HANDLE',desc='Reserved non-valid object handle',type='defines']
	--

	dname:VK_NULL_HANDLE is a reserved value representing a non-valid object
	handle.
	It may be passed to and returned from Vulkan commands only when
	<<fundamentals-validusage-handles, specifically allowed>>.

	include::../api/defines/VK_NULL_HANDLE.txt[]

	--


	[[boilerplate-wsi-header]]
	== Window System-Specific Header Control (Informative)

	// @refBegin WSIheaders Control inclusion of window system interface extensions

	To use a Vulkan extension supporting a platform-specific window system,
	header files for that window systems must: be included at compile time, or
	platform-specific types must: be forward-declared.
	The Vulkan header files cannot determine whether or not an external header
	is available at compile time, so platform-specific extensions are provided
	in separate headers from the core API and platform-independent extensions,
	allowing applications to decide which ones should be defined and how the
	external headers are included.

	Extensions dependent on particular sets of platform headers, or that
	forward-declare platform-specific types, are declared in a header named for
	that platform.
	Before including these platform-specific Vulkan headers, applications must:
	include both `vulkan_core.h` and any external native headers the platform
	extensions depend on.

	As a convenience for applications that do not need the flexibility of
	separate platform-specific Vulkan headers, `vulkan.h` includes
	`vulkan_core.h`, and then conditionally includes platform-specific Vulkan
	headers and the external headers they depend on.
	Applications control which platform-specific headers are included by
	#defining macros before including `vulkan.h`.

	The correspondence between platform-specific extensions, external headers
	they require, the platform-specific header which declares them, and the
	preprocessor macros which enable inclusion by `vulkan.h` are shown in the
	<<boilerplate-wsi-header-table,following table>>.

	[[boilerplate-wsi-header-table]]
	.Window System Extensions and Headers
	[options="header"]
	\|====
	\| Extension Name \| Window System Name \| Platform-specific Header \| Required External Headers \| Controlling `vulkan.h` Macro
	\| `<<VK_KHR_android_surface>>` \| Android \| `vulkan_android.h` \| None \| dname:VK_USE_PLATFORM_ANDROID_KHR
	\| `<<VK_KHR_mir_surface>>` \| Mir \| `vulkan_mir.h` \| `<mir_toolkit/client_types.h>` \| dname:VK_USE_PLATFORM_MIR_KHR
	\| `<<VK_KHR_wayland_surface>>` \| Wayland \| `vulkan_wayland.h` \| `<wayland-client.h>` \| dname:VK_USE_PLATFORM_WAYLAND_KHR
	\| `<<VK_KHR_win32_surface>>`,
	`<<VK_KHR_external_memory_win32>>`,
	`<<VK_KHR_win32_keyed_mutex>>`,
	`<<VK_KHR_external_semaphore_win32>>`,
	`<<VK_KHR_external_fence_win32>>`,
	ifdef::VK_NV_external_memory_win32[]
	`<<VK_NV_external_memory_win32>>`,
	endif::VK_NV_external_memory_win32[]
	ifdef::VK_NV_win32_keyed_mutex[]
	`<<VK_NV_win32_keyed_mutex>>`
	endif::VK_NV_win32_keyed_mutex[]
	\| Microsoft Windows \| `vulkan_win32.h` \| `<windows.h>` \| dname:VK_USE_PLATFORM_WIN32_KHR
	\| `<<VK_KHR_xcb_surface>>` \| X11 Xcb \| `vulkan_xcb.h` \| `<xcb/xcb.h>` \| dname:VK_USE_PLATFORM_XCB_KHR
	\| `<<VK_KHR_xlib_surface>>` \| X11 Xlib \| `vulkan_xlib.h` \| `<X11/Xlib.h>` \| dname:VK_USE_PLATFORM_XLIB_KHR
	ifdef::VK_EXT_acquire_xlib_display[]
	\| `<<VK_EXT_acquire_xlib_display>>` \| X11 XRAndR \| `vulkan_xlib_xrandr.h` \| `<X11/Xlib.h>`,
	`<X11/extensions/Xrandr.h>` \| dname:VK_USE_PLATFORM_XLIB_XRANDR_EXT
	endif::VK_EXT_acquire_xlib_display[]
	ifdef::VK_MVK_ios_surface[]
	\| `<<VK_MVK_ios_surface>>` \| iOS \| `vulkan_ios.h` \| None \| dname:VK_USE_PLATFORM_IOS_MVK
	endif::VK_MVK_ios_surface[]
	ifdef::VK_MVK_macos_surface[]
	\| `<<VK_MVK_macos_surface>>` \| macOS \| `vulkan_macos.h` \| None \| dname:VK_USE_PLATFORM_MACOS_MVK
	endif::VK_MVK_macos_surface[]
	ifdef::VK_NN_vi_surface[]
	\| `<<VK_NN_vi_surface>>` \| VI \| `vulkan_vi.h` \| None \| dname:VK_USE_PLATFORM_VI_NN
	endif::VK_NN_vi_surface[]
	\|====

	[NOTE]
	.Note
	====
	This section describes the purpose of the headers independently of the
	specific underlying functionality of the window system extensions
	themselves.
	Each extension name will only link to a description of that extension when
	viewing a specification built with that extension included.
	====

	// @refEnd WSIheaders