loader: Update the interface document
Mostly formatting and typos.
diff --git a/loader/LoaderAndLayerInterface.md b/loader/LoaderAndLayerInterface.md
index a563720..7781c79 100644
--- a/loader/LoaderAndLayerInterface.md
+++ b/loader/LoaderAndLayerInterface.md
@@ -65,33 +65,31 @@
The Vulkan loader library will be distributed in various ways including Vulkan SDKs, OS package distributions and IHV driver packages. These details are beyond the scope of this document. However, the name and versioning of the Vulkan loader library is specified so an app can link to the correct Vulkan ABI library version. Vulkan versioning is such that ABI backwards compatibility is guaranteed for all versions with the same major number (eg 1.0 and 1.1). On Windows, the loader library encodes the ABI version in its name such that multiple ABI incompatible versions of the loader can peacefully coexist on a given system. The vulkan loader library key name is “vulkan-<ABI version>”. For example, for Vulkan version 1.X on Windows the library filename is vulkan-1.dll. And this library file can typically be found in the windows/system32 directory.
-For Linux, shared libraries are versioned based on a suffix. Thus, the ABI number is not encoded in the base of the library filename as on Windows. On Linux an application wanting to link to the latest Vulkan ABI version would just linkt to the name vulkan (libvulkan.so).
+For Linux, shared libraries are versioned based on a suffix. Thus, the ABI number is not encoded in the base of the library filename as on Windows. On Linux an application wanting to link to the latest Vulkan ABI version would just link to the name vulkan (libvulkan.so). A specific Vulkan ABI version can also be linked to by applications (eg libvulkan.so.1).
-Applications desiring Vulkan functionality beyond what the core API offers may use various layers or extensions. A layer cannot add or modify Vulkan commands, but may offer extensions that do. A common use of layers is for API validation. A developer can use validation layers during application development, but during production the layers can be disabled by the application. Thus, eliminating the overhead of validating the applications usage of the API. Layers discovered by the loader can be reported to the application via vkEnumerateInstanceLayerProperties and vkEnumerateDeviceLayerProperties, for instance and device layers respectively. Instance layers are enabled at vkCreateInstance; device layers are enabled at vkCreateDevice. For example, the ppEnabledLayerNames array in the VkDeviceCreateInfo structure is used by the application to list the device layer names to be enabled at vkCreateDevice. At vkCreateInstance and vkCreateDevice, the loader will construct call chains that include the application specified (enabled) layers. Order is important in the ppEnabledLayerNames array; array element 0 is the topmost (closest to the application) layer inserted in the chain and the last array element is closest to the driver.
+Applications desiring Vulkan functionality beyond what the core API offers may use various layers or extensions. A layer cannot add new or modify existing Vulkan commands, but may offer extensions that do. A common use of layers is for API validation. A developer can use validation layers during application development, but during production the layers can be disabled by the application. Thus, eliminating the overhead of validating the applications usage of the API. Layers discovered by the loader can be reported to the application via vkEnumerateInstanceLayerProperties and vkEnumerateDeviceLayerProperties, for instance and device layers respectively. Instance layers are enabled at vkCreateInstance; device layers are enabled at vkCreateDevice. For example, the ppEnabledLayerNames array in the VkDeviceCreateInfo structure is used by the application to list the device layer names to be enabled at vkCreateDevice. At vkCreateInstance and vkCreateDevice, the loader will construct call chains that include the application specified (enabled) layers. Order is important in the ppEnabledLayerNames array; array element 0 is the topmost (closest to the application) layer inserted in the chain and the last array element is closest to the driver.
-Developers may want to enable layers that are not enabled by the given application they are using. On Linux and Windows, the environment variables
-
-“VK\_INSTANCE\_LAYERS” and “VK\_DEVICE\_LAYERS” can be used to enable additional layers which are not specified (enabled) by the application at vkCreateInstance/vkCreateDevice. VK\_INSTANCE\_LAYERS is a colon (Linux)/semi-colon (Windows) separated list of layer names to enable. Order is relevant with the first layer in the list being the topmost layer (closest to the application) and the last layer in the list being the bottommost layer (closest to the driver).
+Developers may want to enable layers that are not enabled by the given application they are using. On Linux and Windows, the environment variables “VK\_INSTANCE\_LAYERS” and “VK\_DEVICE\_LAYERS” can be used to enable additional layers which are not specified (enabled) by the application at vkCreateInstance/vkCreateDevice. VK\_INSTANCE\_LAYERS is a colon (Linux)/semi-colon (Windows) separated list of layer names to enable. Order is relevant with the first layer in the list being the topmost layer (closest to the application) and the last layer in the list being the bottommost layer (closest to the driver).
Application specified layers and user specified layers (via environment variables) are aggregated and duplicates removed by the loader when enabling layers. Layers specified via environment variable are topmost (closest to the application) while layers specified by the application are bottommost.
-An example of using these environment variables to activate the validation layer LUNARG\_param\_checker on Windows or Linux is as follows:
+An example of using these environment variables to activate the validation layer VK\_LAYER\_LUNARG\_param\_checker on Windows or Linux is as follows:
```
-> $ export VK\_INSTANCE\_LAYERS=VK\_LAYER\_LUNARG\_param\_checker
+> $ export VK_INSTANCE_LAYERS=VK_LAYER_LUNARG_param_checker
-> $ export VK\_DEVICE\_LAYERS=VK\_LAYER\_LUNARG\_param\_checker
+> $ export VK_DEVICE_LAYERS=VK_LAYER_LUNARG_param_checker
```
**Note**: Many layers, including all LunarG validation layers are “global” (i.e. both instance and device) layers and *must* be enabled on both the instance and device chains to function properly. This is required for “global” layers regardless of which method is used to enable the layer (application or environment variable).
-Some platforms, including Linux and Windows, support layers which are enabled automatically by the loader rather than explicitly by the application (or via environment variable). Explicit layers are those layers enabled by the application (or environment variable) by providing the layer name. Implicit layers are those layers enabled by the loader automatically. Any implicit layers the loader discovers installed on the system in the appropriate location will be enabled (subject to environment variable overrides describe later). Layer discovery is described later. Explicitly enabling a layer that is implicitly enabled has no additional effect: the layer will still be enabled implicitly by the loader.
+Some platforms, including Linux and Windows, support layers which are enabled automatically by the loader rather than explicitly by the application (or via environment variable). Explicit layers are those layers enabled by the application (or environment variable) by providing the layer name. Implicit layers are those layers enabled by the loader automatically. Any implicit layers the loader discovers on the system in the appropriate location will be enabled (subject to environment variable overrides described later). Discovery of properly installed implicit and explicit layers is described later. Explicitly enabling a layer that is implicitly enabled has no additional effect: the layer will still be enabled implicitly by the loader.
Extensions are optional functionality provided by a layer, the loader or an ICD. Extensions can modify the behavior of the Vulkan API and need to be specified and registered with Khronos.
-Instance extensions can be discovered via vkEnumerateInstanceExtensionProperties. Device extensions can be discovered via vkEnumerateDeviceExtensionProperties. The loader discovers and aggregates all extensions from layers (both explicit and implicit), ICDs and the loader before reporting them to the application in vkEnumerate\*ExtensionProperties. The pLayerName parameter in these functions are used to select either a single layer or the Vulkan platform implementation components for enumeration. If pLayerName is NULL, extensions from Vulkan implementation components (including loader, implicit layers, and ICDs) are enumerated. If pLayerName is equal to a discovered layer module name then any extensions from that layer (which may be implicit or explicit) are enumerated. Duplicate extensions (eg an implicit layer and ICD might report support for the same extension) are eliminated by the loader. Extensions must be enabled (in vkCreateInstance or vkCreateDevice) before they can be used.
+Instance extensions can be discovered via vkEnumerateInstanceExtensionProperties. Device extensions can be discovered via vkEnumerateDeviceExtensionProperties. The loader discovers and aggregates all extensions from layers (both explicit and implicit), ICDs and the loader before reporting them to the application in vkEnumerate\*ExtensionProperties. The pLayerName parameter in these functions are used to select either a single layer or the Vulkan platform implementation. If pLayerName is NULL, extensions from Vulkan implementation components (including loader, implicit layers, and ICDs) are enumerated. If pLayerName is equal to a discovered layer module name then any extensions from that layer (which may be implicit or explicit) are enumerated. Duplicate extensions (eg an implicit layer and ICD might report support for the same extension) are eliminated by the loader. Extensions must be enabled (in vkCreateInstance or vkCreateDevice) before they can be used.
-Extension command entry points should be queried via vkGetInstanceProcAddr or vkGetDeviceProcAddr. vkGetDeviceProcAddr can only be used to query for device extension or core device entry points. Device entry points include any command that uses a VkDevice as the first parameter or a dispatchable object that is a child of a VkDevice (currently this is VkQueue and VkCommandBuffer). vkGetInstanceProcAddr can be used to query either device or instance extension entry points in addition to all core entry points.
+Extension command entry points should be queried via vkGetInstanceProcAddr or vkGetDeviceProcAddr. vkGetDeviceProcAddr can only be used to query for device extension or core device entry points. Device entry points include any command that uses a VkDevice as the first parameter or a dispatchable object that is a child of a VkDevice (currently this includes VkQueue and VkCommandBuffer). vkGetInstanceProcAddr can be used to query either device or instance extension entry points in addition to all core entry points.
VkGetDeviceProcAddr is particularly interesting because it will provide the most efficient way to call into the ICD. For example, the diagram below shows what could happen if the application were to use vkGetDeviceProcAddr for the function “vkGetDeviceQueue” and “vkDestroyDevice” but not “vkAllocateMemory”. The resulting function pointer (fpGetDeviceQueue) would be the ICD’s entry point if the loader and any enabled layers do not need to see that call. Even if an enabled layer intercepts the call (eg vkDestroyDevice) the loader trampoline code is skipped for function pointers obtained via vkGetDeviceProcAddr. This also means that function pointers obtained via vkGetDeviceProcAddr will only work with the specific VkDevice it was created for, using it with another device has undefined results. For extensions, Get\*ProcAddr will often be the only way to access extension API features.
@@ -111,66 +109,67 @@
HKEY\_LOCAL\_MACHINE\\SOFTWARE\\Khronos\\Vulkan\\Drivers
-For each value in this key which has DWORD data set to 0, the loader opens the JSON format text information file (a.k.a. "manifest file") specified by the name of the value. Each name must be a full pathname to the text info file. The Vulkan loader will open each info file to obtain the name or pathname of an ICD shared library (".dll") file. For example:
+For each value in this key which has DWORD data set to 0, the loader opens the JSON format text information file (a.k.a. "manifest file") specified by the name of the value. Each name must be a full pathname to the text manifest file. The Vulkan loader will open each manifest file to obtain the name or pathname of an ICD shared library (".dll") file. For example:
- \{
+ ```
+ {
"file_format_version": "1.0.0",
"ICD": {
"library_path": "path to ICD library",
"api_version": "1.0.3"
}
}
+ ```
-The "library\_path" specifies either a filename, a relative pathname, or a full pathname to an ICD shared library file, which the loader will attempt to load using LoadLibrary(). If the ICD is specified via a filename, the shared library lives in the system's DLL search path (e.g. in the "C:\\\\Windows\\\\System32" folder). If the ICD is specified via a relative pathname, it is relative to the path of the info file. Relative pathnames are those that do not start with a drive specifier (e.g. "C:"), nor with a directory separator (i.e. the '\\' character), but do contain at least one directory separator.
+The "library\_path" specifies either a filename, a relative pathname, or a full pathname to an ICD shared library file, which the loader will attempt to load using LoadLibrary(). If the ICD is specified via a filename, the shared library lives in the system's DLL search path (e.g. in the "C:\\\\Windows\\\\System32" folder). If the ICD is specified via a relative pathname, it is relative to the path of the manifest file. Relative pathnames are those that do not start with a drive specifier (e.g. "C:"), nor with a directory separator (i.e. the '\\' character), but do contain at least one directory separator.
-The "file\_format\_version" specifies a major.minor.patch version number in case the format of the text information file changes in the future. If the same ICD shared library supports multiple, incompatible versions of text info file format versions, it must have multiple text info files (all of which may point to the same shared library).
+The "file\_format\_version" specifies a major.minor.patch version number in case the format of the text information file changes in the future. If the same ICD shared library supports multiple, incompatible versions of text manifest file format versions, it must have multiple text info files (all of which may point to the same shared library).
The “api\_version” specifies the major.minor.patch version number of the Vulkan API that the shared library (referenced by "library\_path") was built with.
-There are no rules about the name of the text information files (except the .json suffix). There are no rules about the name of the ICD shared library files. For example, if the registry contains the following values:
+There are no rules about the name of the text information files (except the .json suffix).
-\[HKEY\_LOCAL\_MACHINE\\SOFTWARE\\Khronos\\Vulkan\\Drivers\]
+There are no rules about the name of the ICD shared library files. For example, if the registry contains the following values,
-"c:\\\\vendor a\\\\vk\_vendora.json"=dword:00000000
+```
+[HKEY_LOCAL_MACHINE\SOFTWARE\Khronos\Vulkan\Drivers\]
-"c:\\\\windows\\\\system32\\\\vendorb\_vk.json"=dword:00000000
+"C:\vendor a\vk\_vendora.json"=dword:00000000
-"c:\\\\windows\\\\system32\\\\vendorc\_icd.json"=dword:00000000
+"C:\windows\system32\vendorb\_vk.json"=dword:00000000
+"C:\windows\system32\vendorc\_icd.json"=dword:00000000
+```
then the loader will open the following text information files, with the specified contents:
-Text File Name Text File Contents
+| Text File Name | Text File Contents |
+|-------------------------------------|
+|vk\_vendora.json | "ICD": { "library\_path": "C:\\\\VENDORA\\\\vk\_vendora.dll", "api_version": "1.0.3" } |
+| vendorb\_vk.json | "ICD": { "library\_path": "vendorb\_vk.dll", "api_version": "1.0.3" } |
+|vendorc\_icd.json | "ICD": { "library\_path": "vedorc\_icd.dll", "api_version": "1.0.3" }|
---------------------------------------------------------------------------
-
-vk\_vendora.json { "ICD": { "library\_path": "C:\\\\VENDORA\\\\vk\_vendora.dll" }}
-
-vendorb\_vk.json { "ICD": { "library\_path": "vendorb\_vk.dll" }}
-
-vendorc\_icd.json { "ICD": { "library\_path": "vedorc\_icd.dll" }}
-
-Then the loader will open the three files mentioned in the "Text File Contents" column, and then try to load and use the three shared libraries mentioned indicated by the ICD.library\_path value.
+Then the loader will open the three files mentioned in the "Text File Contents" column, and then try to load and use the three shared libraries indicated by the ICD.library\_path value.
##### Using Pre-Production ICDs
IHV developers (and sometimes other developers) need to use special, pre-production ICDs. In some cases, a pre-production ICD may be in an installable package. In other cases, a pre-production ICD may simply be a shared library in the developer's build tree. In this latter case, we want to allow developers to point to such an ICD without modifying the properly-installed ICD(s) on their system.
-This need is met with the use of the "VK\_ICD\_FILENAMES" environment variable, which will override the mechanism used for finding properly-installed ICDs. In other words, only the ICDs listed in "VK\_ICD\_FILENAMES" will be used. The "VK\_ICD\_FILENAMES" environment variable is a semi-colon-separated list of ICD text information files, containing the following:
+This need is met with the use of the "VK\_ICD\_FILENAMES" environment variable, which will override the mechanism used for finding properly-installed ICDs. In other words, only the ICDs listed in "VK\_ICD\_FILENAMES" will be used. The "VK\_ICD\_FILENAMES" environment variable is a semi-colon-separated list of ICD text information files (aka manifest files), containing the following:
-- A full pathname (e.g. "C:\\\\my\_build\\\\my\_icd.json")
+- A full pathname (e.g. "C:\\my\_build\\my\_icd.json")
Typically, "VK\_ICD\_FILENAMES" will only contain a full pathname to one info file for a developer-built ICD. A semi-colon is only used if more than one ICD is listed.
For example, if a developer wants to refer to one ICD that they built, they could set the "VK\_ICD\_FILENAMES" environment variable to:
-C:\\\\my\_build\\\\my\_icd.json
+C:\\my\_build\\my\_icd.json
If a developer wants to refer to two ICDs, one of which is a properly-installed ICD, they can use the full pathname of the text file:
-C:\\\\Windows\\\\System32\\\\vendorc\_icd.json;C:\\\\my\_build\\\\my\_icd.json
+C:\\Windows\\System32\\vendorc\_icd.json;C:\\my\_build\\my\_icd.json
-Notice the semi-colon between "C:\\\\Windows\\\\System32\\\\vendorc\_icd.json" and "C:\\\\my\_build\\\\my\_icd.json".
+Notice the semi-colon between "C:\\Windows\\System32\\vendorc\_icd.json" and "C:\\my\_build\\my\_icd.json".
#### Linux
@@ -179,24 +178,24 @@
In order to find properly-installed ICDs, the Vulkan loader will scan the files in the following Linux directories:
/usr/share/vulkan/icd.d
-
/etc/vulkan/icd.d
-These directories will contain text information files (a.k.a. "manifest files"), that use a JSON format (NOTE: The JSON in this version of the specification is for illustration purposes, and isn't completely valid yet).
+These directories will contain text information files (a.k.a. "manifest files"), that use a JSON format.
-The Vulkan loader will open each info file to obtain the name or pathname of an ICD shared library (".so") file. For example:
+The Vulkan loader will open each manifest file found to obtain the name or pathname of an ICD shared library (".so") file. For example:
-\{
+```
+{
"file_format_version": "1.0.0",
"ICD": {
"library_path": "path to ICD library",
"api_version": "1.0.3"
}
}
-
+```
The "library\_path" specifies either a filename, a relative pathname, or a full pathname to an ICD shared library file. If the ICD is specified via a filename, the loader will attempt to open that file as a shared object using dlopen(), and the file must be in a directory that dlopen is configured to look in (Note: various distributions are configured differently). A distribution is free to create Vulkan-specific system directories (e.g. ".../vulkan/icd"), but is not required to do so. If the ICD is specified via a relative pathname, it is relative to the path of the info file. Relative pathnames are those that do not start with, but do contain at least one directory separator (i.e. the '/' character). For example, "lib/vendora.so" and "./vendora.so" are examples of relative pathnames.
-The "file\_format\_version" provides a major.minor.patch version number in case the format of the text information file changes in the future. If the same ICD shared library supports multiple, incompatible versions of text info file format versions, it must have multiple text info files (all of which may point to the same shared library).
+The "file\_format\_version" provides a major.minor.patch version number in case the format of the manifest file changes in the future. If the same ICD shared library supports multiple, incompatible versions of manifest file format versions, it must have multiple manifest files (all of which may point to the same shared library).
The “api\_version” specifies the major.minor.patch version number of the Vulkan API that the shared library (referenced by "library\_path") was built with.
@@ -206,17 +205,13 @@
There are no rules about the name of the ICD shared library files. For example, if the "/usr/share/vulkan/icd.d" directory contain the following files, with the specified contents:
-Text File Name Text File Contents
+| Text File Name | Text File Contents |
+|-----------------|--------------------|
+|vk\_vendora.json | "ICD": { "library\_path": "vendora.so", "api_version": "1.0.3" } |
+| vendorb\_vk.json | "ICD": { "library\_path": "vendorb\_vulkan\_icd.so", "api_version": "1.0.3" } |
+| vendorc\_icd.json | "ICD": { "library\_path": "/usr/lib/VENDORC/icd.so", "api_version": "1.0.1" }|
---------------------------------------------------------------------------
-
-vk\_vendora.json { "ICD": { "library\_path": "vendora.so" }}
-
-vendorb\_vk.json { "ICD": { "library\_path": "vendorb\_vulkan\_icd.so" }}
-
-vendorc\_icd.json { "ICD": { "library\_path": "/usr/lib/VENDORC/icd.so" }}
-
-then the loader will open the three files mentioned in the "Text File Contents" column, and then try to load and use the three shared libraries mentioned indicated by the ICD.library\_path value.
+then the loader will open the three files mentioned in the "Text File Contents" column, and then try to load and use the three shared libraries indicated by the ICD.library\_path value.
##### Using Pre-Production ICDs
@@ -224,7 +219,7 @@
This need is met with the use of the "VK\_ICD\_FILENAMES" environment variable, which will override the mechanism used for finding properly-installed ICDs. In other words, only the ICDs listed in "VK\_ICD\_FILENAMES" will be used.
-The "VK\_ICD\_FILENAMES" environment variable is a colon-separated list of ICD text information files, containing the following:
+The "VK\_ICD\_FILENAMES" environment variable is a colon-separated list of ICD manifest files, containing the following:
- A filename (e.g. "libvkicd.json") in the "/usr/share/vulkan/icd.d" or "/etc/vulkan/icd.d" system directories
@@ -249,7 +244,8 @@
TODO: Fill out this section
-### ICD interface requirements
+ICD interface requirements
+----------------------------------------
Generally, for all Vulkan commands issued by an application, the loader can be viewed as a pass through. That is, the loader generally doesn’t modified the commands or their parameters but simply calls the ICDs entry point for that command. Thus, the loader to ICD interface requirements will be specified by covering two areas: 1) Obtaining ICD Vulkan entry points; 2) Specifying requirements for a given Vulkan command(s) over and above the Vulkan specification requirements.
@@ -261,9 +257,9 @@
1) Recommended
-- vk\_icdGetInstanceProcAddr exported in the ICD library and it returns valid function pointers for all the global level and instance level Vulkan commands, and also vkGetDeviceProcAddr. Global level commands are those which contain no dispatchable object as the first parameter, such as vkCreateInstance, vkEnumerateInstanceExtensionProperties. The ICD must support querying global level entry points by calling vk\_icdGetInstanceProcAddr with a NULL VkInstance parameter. Instance level commands are those that have either VkInstance, or VkPhysicalDevice as the first parameter dispatchable object. Both core entry points and any instance extension entry points the ICD supports should be available via vk\_icdGetInstanceProcAddr. Future Vulkan instance extensions may define ans use new instance level dispatchable objects other than VkInstance and VkPhysicalDevice, in which case, extensions entry points using these newly defined dispatchable oibjects must be queryable via vk\_icdGetInstanceProcAddr.
+- vk\_icdGetInstanceProcAddr exported in the ICD library and it returns valid function pointers for all the global level and instance level Vulkan commands, and also vkGetDeviceProcAddr. Global level commands are those which contain no dispatchable object as the first parameter, such as vkCreateInstance and vkEnumerateInstanceExtensionProperties. The ICD must support querying global level entry points by calling vk\_icdGetInstanceProcAddr with a NULL VkInstance parameter. Instance level commands are those that have either VkInstance, or VkPhysicalDevice as the first parameter dispatchable object. Both core entry points and any instance extension entry points the ICD supports should be available via vk\_icdGetInstanceProcAddr. Future Vulkan instance extensions may define and use new instance level dispatchable objects other than VkInstance and VkPhysicalDevice, in which case, extensions entry points using these newly defined dispatchable oibjects must be queryable via vk\_icdGetInstanceProcAddr.
-- all other Vulkan entry points must either NOT be exported from the ICD library or else NOT use the official Vulkan function names if they are exported. This requirement is for ICD libraries that include other functionality (such as OpenGL library) and thus could be loaded by the application prior to when the Vulkan loader library is loaded by the application. In other words, the ICD library exported Vulkan symbols must not clash with the loader's exported Vulkan symbols.
+- All other Vulkan entry points must either NOT be exported from the ICD library or else NOT use the official Vulkan function names if they are exported. This requirement is for ICD libraries that include other functionality (such as OpenGL library) and thus could be loaded by the application prior to when the Vulkan loader library is loaded by the application. In other words, the ICD library exported Vulkan symbols must not clash with the loader's exported Vulkan symbols.
2) Deprecated
@@ -277,64 +273,53 @@
Normally, ICDs handle object creation and destruction for various Vulkan objects. The WSI surface extensions for Linux and Windows (VK\_KHR\_win32\_surface, VK\_KHR\_xcb\_surface, VK\_KHR\_xlib\_surface, VK\_KHR\_mir\_surface, VK\_KHR\_wayland\_surface, and VK\_KHR\_surface) are handled differently. For these extensions, the VkSurfaceKHR object creation and destruction is handled by the loader as follows:
-1. Loader handles the vkCreate\*SurfaceKHR() and vkDestroySurfaceKHR() functions including creating/destroying the VkSurfaceKHR object
+1. Loader handles the vkCreate\*SurfaceKHR() and vkDestroySurfaceKHR() functions including creating/destroying the VkSurfaceKHR object.
-2. VkSurfaceKHR objects have the underlying structure (VKIcdSurface\*) as defined in include/vulkan/vk\_icd.h
+2. VkSurfaceKHR objects have the underlying structure (VkIcdSurface\*) as defined in include/vulkan/vk\_icd.h.
-3. ICDs can cast any VkSurfaceKHR object to a pointer to the appropriate VKIcdSurface\* structure
+3. ICDs can cast any VkSurfaceKHR object to a pointer to the appropriate VkIcdSurface\* structure.
-4. VkIcdSurface\* structures include VkIcdSurfaceWin32, VkIcdSurfaceXcb, VkIcdSurfaceXlib, VkIcdSurfaceMir, and VkIcdSurfaceWayland
+4. VkIcdSurface\* structures include VkIcdSurfaceWin32, VkIcdSurfaceXcb, VkIcdSurfaceXlib, VkIcdSurfaceMir, and VkIcdSurfaceWayland. The first field in the structure is a VkIcdSurfaceBase enumerant that indicates westher the surface object is Win32, Xcb, Xlib, Mir, or Wayland.
As previously covered, the loader requires dispatch tables to be accessible within Vulkan dispatchable objects, which include VkInstance, VkPhysicalDevice, VkDevice, VkQueue, and VkCommandBuffer. The specific requirements on all dispatchable objects created by ICDs are as follows:
-- all dispatchable objects created by an ICD can be cast to void \*\*,
+- All dispatchable objects created by an ICD can be cast to void \*\*
--the loader will replace the first entry with a pointer to the dispatch table which is owned by the loader. This implies three things for ICD drivers:
+- The loader will replace the first entry with a pointer to the dispatch table which is owned by the loader. This implies three things for ICD drivers:
-1. The ICD must return a pointer for the opaque object handle
+1. The ICD must return a pointer for the opaque dispatchable object handle.
-2. This pointer points to a regular C structure with the first entry being a pointer. Note: for any C++ ICD's that implement VK objects directly as C++ classes. The C++ compiler may put a vtable at offset zero if your class is virtual. In this case use a regular C structure (see below).
+2. This pointer points to a regular C structure with the first entry being a pointer. Note: for any C\++ ICD's that implement VK objects directly as C\++ classes. The C\++ compiler may put a vtable at offset zero if your class is virtual. In this case use a regular C structure (see below).
-3. The loader checks for a magic value (ICD\\\_LOADER\\\_MAGIC) in all the created dispatchable objects, as follows (see include/vulkan/vk\_icd.h):
+3. The loader checks for a magic value (ICD\_LOADER\_MAGIC) in all the created dispatchable objects, as follows (see include/vulkan/vk\_icd.h):
```
-\#include "vk\_icd.h"
+#include "vk_icd.h"
-union \\\_VK\\\_LOADER\\\_DATA {
+union _VK_LOADER_DATA {
+ uintptr loadermagic;
+ void *loaderData;
+} VK_LOADER_DATA;
-uintptr loadermagic;
-
-void \*loaderData;
-
-} VK\_LOADER\_DATA;
-
-vkObj alloc\_icd\_obj()
-
+vkObj alloc_icd_obj()
{
+ vkObj *newObj = alloc_obj();
+ ...
+ // Initialize pointer to loader's dispatch table with ICD_LOADER_MAGIC
-vkObj \*newObj = alloc\_obj();
-
-...
-
-// Initialize pointer to loader's dispatch table with ICD\_LOADER\_MAGIC
-
-set\_loader\_magic\_value(newObj);
-
-...
-
-return newObj;
-
+ set_loader_magic_value(newObj);
+ ...
+ return newObj;
}
-
```
Additional Notes:
-- loader will filter out extensions requested in vkCreateInstance and vkCreateDevice before calling into the ICD; Filtering will be of extensions advertised by entities (eg layers) different from the ICD in question.
-- loader will not call ICD for vkEnumerate\*LayerProperties() as layer properties are obtained from the layer libraries and layer JSON files.
--if an ICD library wants to implement a layer it can do so by having the appropriate layer JSON manifest file refer to the ICD library file.
-- loader will not call ICD for vkEnumerate\*ExtensionProperties(pLayerName != NULL)
+- The loader will filter out extensions requested in vkCreateInstance and vkCreateDevice before calling into the ICD; Filtering will be of extensions advertised by entities (eg layers) different from the ICD in question.
+- The loader will not call ICD for vkEnumerate\*LayerProperties() as layer properties are obtained from the layer libraries and layer JSON files.
+- If an ICD library wants to implement a layer it can do so by having the appropriate layer JSON manifest file refer to the ICD library file.
+- The loader will not call ICD for vkEnumerate\*ExtensionProperties(pLayerName != NULL).
- The ICD may or may not implement a dispatch table.
#### Android
@@ -350,7 +335,7 @@
##### Properly-Installed Layers
-In order to find properly-installed layers, the Vulkan loader will use a similar mechanism as used for ICDs. Text information files, that use a JSON format, are read in order to identify the names and attributes of layers and their extensions. The use of text info files allows the loader to avoid loading any shared library files when the application does not query nor request any extensions. Layers and extensions have additional complexity, and so their info files contain more information than ICD info files. For example, a layer shared library file may contain multiple layers/extensions (perhaps even an ICD).
+In order to find properly-installed layers, the Vulkan loader will use a similar mechanism as used for ICDs. Text information files (aka manifest files), that use a JSON format, are read in order to identify the names and attributes of layers and their extensions. The use of manifest files allows the loader to avoid loading any shared library files when the application does not query nor request any extensions. Layers and extensions have additional complexity, and so their manifest files contain more information than ICD info files. For example, a layer shared library file may contain multiple layers/extensions (perhaps even an ICD).
In order to find properly-installed layers, the Vulkan loader will scan the values in the following Windows registry keys:
@@ -362,21 +347,20 @@
Implicit layers are those which are enabled by their existence. For example, certain application environments (e.g. Steam or an automotive infotainment system) may have layers which they always want enabled for all applications that they start. Other implicit layers may be for all applications started on a given system (e.g. layers that overlay frames-per-second). Implicit layers are enabled automatically, whereas explicit layers must be enabled explicitly. What distinguishes a layer as implicit or explicit is by which registry key its layer information file is referenced by.
-For each value in these keys which has DWORD data set to 0, the loader opens the JSON format text information file (a.k.a. "manifest file") specified by the name of the value. Each name must be a full pathname to the text info file.
+For each value in these keys which has DWORD data set to 0, the loader opens the JSON manifest file specified by the name of the value. Each name must be a full pathname to the manifest file.
The Vulkan loader will open each info file to obtain information about the layer, including the name or pathname of a shared library (".dll") file.
-The information file is in the JSON format and contains the following information:
+This manifest file is in the JSON format and contains the following information:
- (required) "file\_format\_version" - same as for ICDs, except that the format version can vary independently for ICDs and layers.
- (required) "name" - layer name
- (required) "type" - which layer chains should the layer be activated on.
-
Allowable values are "INSTANCE", "DEVICE", "GLOBAL". Global means activate on both device and instance chains.
-- (required) "library\_path" - filename / full path / relative path to the text file
+- (required) "library\_path" - filename / full path / relative path to the library file
- (required) "api\_version" - same as for ICDs.
@@ -386,17 +370,17 @@
- (optional) "device\_extensions" or "instance\_extensions" - array of extension information as follows
-- (optional) extension "name" - Vulkan registered name
+ - (required) extension "name" - Vulkan registered name
-- (optional) extension "spec\_version" - extension specification version, a single number, increasing with backward compatible changes.
+ - (required) extension "spec\_version" - extension specification version, a single number, increasing with backward compatible changes.
-- (optional) extension "entrypoints" - array of device extension entrypoints; not used for instance extensions
+ - (required for device\_extensions with entry points) extension "entrypoints" - array of device extension entrypoints; not used for instance extensions
- (sometimes required) "functions" - mapping list of function entry points. If multiple layers exist within the same shared library (or if a layer is in the same shared library as an ICD), this must be specified to allow each layer to have its own vkGet\*ProcAddr entrypoints that can be found by the loader. At this time, only the following two functions are required:
-- "vkGetInstanceProcAddr" name
+ - "vkGetInstanceProcAddr" name
-- "vkGetDeviceProcAddr" name
+ - "vkGetDeviceProcAddr" name
- (optional for implicit layers) "enable\_environment" requirement(s) - environment variable and value required to enable an implicit layer. This environment variable (which should vary with each "version" of the layer, as in "ENABLE\_LAYER\_FOO\_1") must be set to the given value or else the implicit layer is not loaded. This is for application environments (e.g. Steam) which want to enable a layer(s) only for applications that they launch, and allows for applications run outside of an application environment to not get that implicit layer(s).
@@ -404,81 +388,45 @@
For example:
+```
{
-
-"file\_format\_version" : "1.0.0",
-
-"layer":
-
-{
-
-"name": "OverlayLayer",
-
-"type": "DEVICE",
-
-"library\_path": "vkOverlayLayer.dll"
-
-"api\_version" : "1.0.3",
-
-"implementation\_version" : "2",
-
-"description" : "LunarG HUD layer",
-
-"functions": {
-
-"vkGetInstanceProcAddr": "OverlayLayer\_GetInstanceProcAddr",
-
-“vkGetDeviceProcAddr": "OverlayLayer\_GetDeviceProcAddr"
-
-},
-
-instance\_extensions": \[
-
-{
-
-"name": "VK\_LUNARG\_debug\_report\_EXT",
-
-"spec\_version": "1"
-
-},
-
-{
-
-"name": "VK\_VENDOR\_DEBUG\_X",
-
-"spec\_version": "3"
-
+"file_format_version" : "1.0.0",
+"layer": {
+ "name": "VK_LAYER_LUNARG_OverlayLayer",
+ "type": "DEVICE",
+ "library_path": "vkOverlayLayer.dll"
+ "api_version" : "1.0.3",
+ "implementation_version" : "2",
+ "description" : "LunarG HUD layer",
+ "functions": {
+ "vkGetInstanceProcAddr": "OverlayLayer_GetInstanceProcAddr",
+ "vkGetDeviceProcAddr": "OverlayLayer_GetDeviceProcAddr"
+ },
+ instance_extensions": [
+ {
+ "name": "VK_debug_report_EXT",
+ "spec_version": "1"
+ },
+ {
+ "name": "VK_VENDOR_DEBUG_X",
+ "spec_version": "3"
+ }
+ ],
+ device_extensions": [
+ {
+ "name": "VK_LUNARG_DEBUG_MARKER",
+ "spec_version": "1",
+ "entrypoints": ["vkCmdDbgMarkerBegin", "vkCmdDbgMarkerEnd"]
+ }
+ ],
+ "disable_environment": {
+ "DISABLE_LAYER_OVERLAY_1": ""
+ }
}
-
-\],
-
-device\_extensions": \[
-
-{
-
-"name": "VK\_LUNARG\_DEBUG\_MARKER",
-
-"spec\_version": "1",
-
-"entrypoints": \["vkCmdDbgMarkerBegin", "vkCmdDbgMarkerEnd"\]
-
}
+```
-\],
-
-"disable\_environment": {
-
-"DISABLE\_LAYER\_OVERLAY\_1": ""
-
-}
-
-}
-
-}
-
-The "library\_path" specifies either a filename, a relative pathname, or a full pathname to a layer shared library (".dll") file, which the loader will attempt to load using LoadLibrary(). If the layer is specified via a relative pathname, it is relative to the path of the info file (e.g. for cases when an application provides a layer that is in the same folder hierarchy as the rest of the application files). If the layer is specified via a filename, the shared library lives in the system's DLL search path (e.g. in the
-
-"C:\\\\Windows\\\\System32" folder).
+The "library\_path" specifies either a filename, a relative pathname, or a full pathname to a layer shared library (".dll") file, which the loader will attempt to load using LoadLibrary(). If the layer is specified via a relative pathname, it is relative to the path of the info file (e.g. for cases when an application provides a layer that is in the same folder hierarchy as the rest of the application files). If the layer is specified via a filename, the shared library lives in the system's DLL search path (e.g. in the "C:\\Windows\\System32" folder).
There are no rules about the name of the text files (except the .json suffix).
@@ -499,16 +447,13 @@
The Vulkan loader will scan the files in the following Linux directories:
/usr/share/vulkan/explicit\_layer.d
-
/usr/share/vulkan/implicit\_layer.d
-
/etc/vulkan/explicit\_layer.d
-
/etc/vulkan/implicit\_layer.d
Explicit layers are those which are enabled by an application (e.g. with the vkCreateInstance function), or by an environment variable (as mentioned previously). Implicit layers are those which are enabled by their existence. For example, certain application environments (e.g. Steam or an automotive infotainment system) may have layers which they always want enabled for all applications that they start. Other implicit layers may be for all applications started on a given system (e.g. layers that overlay frames-per-second). Implicit layers are enabled automatically, whereas explicit layers must be enabled explicitly. What distinguishes a layer as implicit or explicit is by which directory its layer information file exists in.
-The "/usr/share/vulkan/\*\_layer.d" directories are for ICDs that are installed from Linux-distribution-provided packages. The "/etc/vulkan/\*\_layer.d" directories are for ICDs that are installed from non-Linux-distribution-provided packages.
+The "/usr/share/vulkan/\*\_layer.d" directories are for layers that are installed from Linux-distribution-provided packages. The "/etc/vulkan/\*\_layer.d" directories are for layers that are installed from non-Linux-distribution-provided packages.
The information file is in the JSON format and contains the following information:
@@ -528,93 +473,58 @@
- (optional) "device\_extensions" or "instance\_extensions" - array of extension information as follows
-- (optional) extension "name" - Vulkan registered name
+ - (required) extension "name" - Vulkan registered name
-- (optional) extension "spec\_version" - extension specification version, a single number, increasing with backward compatible changes.
+ - (required) extension "spec\_version" - extension specification version, a single number, increasing with backward compatible changes.
-- (optional) extension "entrypoints" - array of device extension entrypoints; not used for instance extensions
+ - (required for device extensions with entry points) extension "entrypoints" - array of device extension entrypoints; not used for instance extensions
- (sometimes required) "functions" - mapping list of function entry points. If multiple layers exist within the same shared library (or if a layer is in the same shared library as an ICD), this must be specified to allow each layer to have its own vkGet\*ProcAddr entrypoints that can be found by the loader. At this time, only the following two functions are required:
-- "vkGetInstanceProcAddr" name
-
-- "vkGetDeviceProcAddr" name
+ - "vkGetInstanceProcAddr" name
+ - "vkGetDeviceProcAddr" name
- (optional for implicit layers) "enable\_environment" requirement(s) - environment variable and value required to enable an implicit layer. This environment variable (which should vary with each "version" of the layer, as in "ENABLE\_LAYER\_FOO\_1") must be set to the given value or else the implicit layer is not loaded. This is for application environments (e.g. Steam) which want to enable a layer(s) only for applications that they launch, and allows for applications run outside of an application environment to not get that implicit layer(s).
- (required for implicit layers) "disable\_environment" requirement(s) - environment variable and value required to disable an implicit layer. Note: in rare cases of an application not working with an implicit layer, the application can set this environment variable (before calling Vulkan functions) in order to "blacklist" the layer. This environment variable (which should vary with each "version" of the layer, as in "DISABLE\_LAYER\_FOO\_1") must be set (not particularly to any value). If both the "enable\_environment" and "disable\_environment" variables are set, the implicit layer is disabled.
For example:
-
+```
{
-
-"file\_format\_version" : "1.0.0",
-
+"file_format_version" : "1.0.0",
"layer": {
-
-"name": "OverlayLayer",
-
-"type": "DEVICE",
-
-"library\_path": "libvkOverlayLayer.so",
-
-"api\_version" : "1.0.2",
-
-"implementation\_version" : "2",
-
-"description" : "LunarG HUD layer",
-
-"functions": {
-
-"vkGetInstanceProcAddr": "Overlaylayer\_GetInstanceProcAddr",
-
-"vkGetDeviceProcAddr": "OverlayLayer\_GetDeviceProcAddr"
-
-},
-
-"instance\_extensions": \[
-
-{
-
-"name": "VK\_LUNARG\_DEBUG\_REPORT",
-
-"spec\_version": "1"
-
-},
-
-{
-
-"name": "VK\_VENDOR\_DEBUG\_X",
-
-"spec\_version": "3"
-
+ "name": "VK_LAYER_LUNARG_OverlayLayer",
+ "type": "DEVICE",
+ "library_path": "vkOverlayLayer.dll"
+ "api_version" : "1.0.3",
+ "implementation_version" : "2",
+ "description" : "LunarG HUD layer",
+ "functions": {
+ "vkGetInstanceProcAddr": "OverlayLayer_GetInstanceProcAddr",
+ "vkGetDeviceProcAddr": "OverlayLayer_GetDeviceProcAddr"
+ },
+ instance_extensions": [
+ {
+ "name": "VK_debug_report_EXT",
+ "spec_version": "1"
+ },
+ {
+ "name": "VK_VENDOR_DEBUG_X",
+ "spec_version": "3"
+ }
+ ],
+ device_extensions": [
+ {
+ "name": "VK_LUNARG_DEBUG_MARKER",
+ "spec_version": "1",
+ "entrypoints": ["vkCmdDbgMarkerBegin", "vkCmdDbgMarkerEnd"]
+ }
+ ],
+ "disable_environment": {
+ "DISABLE_LAYER_OVERLAY_1": ""
+ }
}
-
-\],
-
-"device\_extensions": \[
-
-{
-
-"name": "VK\_LUNARG\_DEBUG\_MARKER",
-
-"spec\_version": "1",
-
-"entrypoints": \["vkCmdDbgMarkerBegin", "vkCmdDbgMarkerEnd"\]
-
}
-
-\],
-
-"disable\_environment": {
-
-"DISABLE\_LAYER\_OVERLAY\_1": ""
-
-}
-
-}
-
-}
-
+```
The "library\_path" specifies either a filename, a relative pathname, or a full pathname to a layer shared library (".so") file, which the loader will attempt to load using dlopen(). If the layer is specified via a filename, the loader will attempt to open that file as a shared object using dlopen(), and the file must be in a directory that dlopen is configured to look in (Note: various distributions are configured differently). A distribution is free to create Vulkan-specific system directories (e.g. ".../vulkan/layers"), but is not required to do so. If the layer is specified via a relative pathname, it is relative to the path of the info file (e.g. for cases when an application provides a layer that is in the same directory hierarchy as the rest of the application files).
There are no rules about the name of the text files (except the .json suffix).
@@ -633,7 +543,8 @@
TODO: Fill out this section
-### Layer interface requirements
+Layer interface requirements
+------------------------------------------------------
#### Architectural interface overview
@@ -685,13 +596,19 @@
- The VkLayerInstanceLink contains the next entity's vkGetInstanceProcAddr used by a layer.
- The VkLayerDeviceLink contains the next entity's vkGetInstanceProcAddr and vkGetDeviceProcAddr used by a layer.
- Given the above structures set up by the loader, layer must initialize their dispatch table as follows:
- -Find the VkLayerInstanceCreateInfo/VkLayerDeviceCreateInfo structure in the VkInstanceCreateInfo/VkDeviceCreateInfo structure.
- -Get the next entity's vkGet*ProcAddr from the "pLayerInfo" field.
- -For CreateInstance get the next entity's vkCreateInstance by calling the "pfnNextGetInstanceProcAddr":
+ - Find the VkLayerInstanceCreateInfo/VkLayerDeviceCreateInfo structure in the VkInstanceCreateInfo/VkDeviceCreateInfo structure.
+ - Get the next entity's vkGet*ProcAddr from the "pLayerInfo" field.
+ - For CreateInstance get the next entity's vkCreateInstance by calling the "pfnNextGetInstanceProcAddr":
pfnNextGetInstanceProcAddr(NULL, "vkCreateInstance").
- -For CreateDevice get the next entity's vkCreateDevice by calling the "pfnNextGetInstanceProcAddr":
+ - For CreateDevice get the next entity's vkCreateDevice by calling the "pfnNextGetInstanceProcAddr":
pfnNextGetInstanceProcAddr(NULL, "vkCreateDevice").
- -Advanced the linked list to the next node: pLayerInfo = pLayerInfo->pNext.
- -Call down the chain either CreateDevice or CreateInstance
- -Initialize your layer dispatch table by calling the next entity's Get*ProcAddr function once for each Vulkan command needed in your dispatch table
+ - Advanced the linked list to the next node: pLayerInfo = pLayerInfo->pNext.
+ - Call down the chain either CreateDevice or CreateInstance
+ - Initialize your layer dispatch table by calling the next entity's Get*ProcAddr function once for each Vulkan command needed in your dispatch table
+
+Example code for CreateInstance:
+Example code for CreateDevice
+#### Special Considerations
+Wrapping versus maps.
+create dispatchable objects