Lines Matching full:vulkan
1 # Architecture of the Vulkan Loader Interfaces
13 * [Interfacing with Vulkan Functions](#interfacing-with-vulkan-functions)
34 * [Vulkan Installable Client Driver interface with the loader](#vulkan-installable-client-driver-interface-with-the-loader)
37 * [ICD Vulkan Entry-Point Discovery](#icd-vulkan-entry-point-discovery)
48 Vulkan is a layered architecture, made up of the following elements:
49 * The Vulkan Application
50 * [The Vulkan Loader](#the-loader)
51 * [Vulkan Layers](#layers)
62 While this document is primarily targeted at developers of Vulkan applications,
64 wanting a better understanding of the Vulkan runtime.
71 control the Vulkan-capable hardware. An important point to remember is that
72 Vulkan-capable hardware can be graphics-based, compute-based, or both. Between
77 supporting multiple GPUs and their drivers. Any Vulkan function may
79 The loader is critical to managing the proper dispatching of Vulkan
80 functions to the appropriate set of layers and ICDs. The Vulkan object
82 can process Vulkan functions prior to the ICD being called.
91 1. Support one or more Vulkan-capable ICD on a user's computer system without
93 2. Support Vulkan Layers which are optional modules that can be enabled by an
95 3. Impact the overall performance of a Vulkan application in the lowest
101 Layers are optional components that augment the Vulkan system. They can
102 intercept, evaluate, and modify existing Vulkan functions on their way from the
105 during CreateInstance. Each layer can choose to hook (intercept) any Vulkan
107 intercept all Vulkan functions. It may choose to intercept all known functions,
112 * Adding the ability to perform Vulkan API tracing and debugging
122 Vulkan allows multiple Installable Client Drivers (ICDs) each supporting one
123 or more devices (represented by a Vulkan `VkPhysicalDevice` object) to be used
124 collectively. The loader is responsible for discovering available Vulkan ICDs on
134 Vulkan are separated into two main groups:
141 A Vulkan Instance is a high-level construct used to provide Vulkan system-level
142 information, or functionality. Vulkan objects associated directly with an
147 An Instance function is any Vulkan function which takes as its first parameter
148 either an object from the Instance list, or nothing at all. Some Vulkan
155 You query Vulkan Instance functions using `vkGetInstanceProcAddr`.
161 Similarly, an Instance extension is a set of Vulkan Instance functions extending
162 the Vulkan language. These will be discussed in more detail later.
167 A Vulkan Device, on the other-hand, is a logical identifier used to associate
168 functions with a particular physical device on a user's system. Vulkan
175 A Device function is any Vulkan function which takes any Device Object as its
176 first parameter. Some Vulkan Device functions are:
181 You can query Vulkan Device functions using either `vkGetInstanceProcAddr` or
185 any device created later, as long as it is associated with the same Vulkan
189 `vkGetDeviceProcAddr` can only be used on core Vulkan Device functions, or
198 As with Instance extensions, a Device extension is a set of Vulkan Device
199 functions extending the Vulkan language. You can read more about these later in
205 Vulkan uses an object model to control the scope of a particular action /
206 operation. The object to be acted on is always the first parameter of a Vulkan
207 call and is a dispatchable object (see Vulkan specification section 2.3 Object
210 the loader. This dispatch table contains pointers to the Vulkan functions
221 chain for each Vulkan function and each entry of the dispatch table will point
226 When an application calls a Vulkan function, this typically will first hit a
270 * [Interfacing with Vulkan Functions](#interfacing-with-vulkan-functions)
271 * [Vulkan Direct Exports](#vulkan-direct-exports)
289 #### Interfacing with Vulkan Functions
290 There are several ways you can interface with Vulkan functions through the
294 ##### Vulkan Direct Exports
295 The loader library on Windows, Linux and Android will export all core Vulkan
297 make it simpler to get started with Vulkan development. When an application
298 links directly to the loader library in this way, the Vulkan calls are simple
320 user does not need to have a Vulkan runtime installed, and it also guarantees
338 provides the fastest mechanism for the application to call Vulkan functions. An
357 versus the call chain of a Device functions. Remember, a [Vulkan Instance is a
358 high-level construct used to provide Vulkan system-level information](#instance-
365 This is also how a Vulkan Device function call chain looks if you query it
370 any enabled layers and the ICD. Thus, if you used a loader-exported Vulkan
403 The Vulkan loader library will be distributed in various ways including Vulkan
406 and versioning of the Vulkan loader library is specified so an app can link to
407 the correct Vulkan ABI library version. Vulkan versioning is such that ABI
411 can peacefully coexist on a given system. The Vulkan loader library file name is
412 `vulkan-<ABI version>.dll`. For example, for Vulkan version 1.X on Windows the
413 library filename is vulkan-1.dll. And this library file can typically be found
420 Linux an application wanting to link to the latest Vulkan ABI version would
421 just link to the name vulkan (libvulkan.so). A specific Vulkan ABI version can
427 Applications desiring Vulkan functionality beyond what the core API offers may
428 use various layers or extensions. A layer cannot introduce new Vulkan core API
429 entry-points to an application that are not exposed in Vulkan.h. However,
430 layers may offer extensions that introduce new Vulkan commands that can be
448 active for all Vulkan functions using the created `VkInstance`, and any of
602 ICD. Extensions can modify the behavior of the Vulkan API and need to be
607 found in the Vulkan Spec, and vulkan.h header file.
636 Looking at `vulkan.h`, you'll notice that they are both similar. For example,
647 layer or the Vulkan platform implementation. If "pLayerName" is NULL, extensions
648 from Vulkan implementation components (including loader, implicit layers, and
702 Only then can you expect to properly use a WSI extension in your Vulkan program.
707 With the ability to expand Vulkan so easily, extensions will be created that the
777 * [Associating Private Data with Vulkan Objects Within a Layer](#associating-private-data-with-vulkan-objects-within-a-layer)
819 layer information. In order to find system-installed layers, the Vulkan loader
838 /data/local/debug/vulkan folder. An application enabled for debug has the
844 In order to find system-installed layers, the Vulkan loader will scan the
848 HKEY_LOCAL_MACHINE\SOFTWARE\Khronos\Vulkan\ExplicitLayers
849 HKEY_CURRENT_USER\SOFTWARE\Khronos\Vulkan\ExplicitLayers
850 HKEY_LOCAL_MACHINE\SOFTWARE\Khronos\Vulkan\ImplicitLayers
851 HKEY_CURRENT_USER\SOFTWARE\Khronos\Vulkan\ImplicitLayers
862 for base settings, including Vulkan, OpenGL, and Direct3D ICD location.
891 In general, applications should install layers into the `SOFTWARE\Khrosos\Vulkan`
897 The Vulkan loader will open each manifest file that is given
908 On Linux, the Vulkan loader will scan the files in the following Linux
911 /usr/local/etc/vulkan/explicit_layer.d
912 /usr/local/etc/vulkan/implicit_layer.d
913 /usr/local/share/vulkan/explicit_layer.d
914 /usr/local/share/vulkan/implicit_layer.d
915 /etc/vulkan/explicit_layer.d
916 /etc/vulkan/implicit_layer.d
917 /usr/share/vulkan/explicit_layer.d
918 /usr/share/vulkan/implicit_layer.d
919 $HOME/.local/share/vulkan/explicit_layer.d
920 $HOME/.local/share/vulkan/implicit_layer.d
927 3. The "/usr/local/etc/vulkan/\*\_layer.d" and
928 "/usr/local/share/vulkan/\*\_layer.d" directories are for layers that are
930 4. The "/usr/share/vulkan/\*\_layer.d" directories are for layers that are
949 provided for this interface in include/vulkan/vk_layer.h:
970 Vulkan structures. The "sType" field, in this case takes a new enum defined
1031 What's important to note here is that a layer can intercept Vulkan
1039 Normally, when a layer intercepts a given Vulkan function, it will call down the
1047 all Vulkan functions that a layer intercepts. If a Vulkan function is not
1059 The loader is responsible for dispatching all core and instance extension Vulkan
1155 until at least a Vulkan version bump, because an older loader may still be
1161 * Layers intercept a Vulkan function by defining a C/C++ function with
1162 signature **identical** to the Vulkan API for that function.
1167 * For any Vulkan function a layer intercepts which has a non-void return value,
1170 corresponding Vulkan function in the next entity.
1182 * These functions only call down the chain for Vulkan functions that they
1184 * Layer intercept functions **may insert extra calls** to Vulkan functions in
1206 table (see include/vulkan/vk_layer.h).
1208 dispatch table (see include/vulkan/vk_layer.h).
1222 A layer, when inserted into an otherwise compliant Vulkan implementation, must
1223 still result in a compliant Vulkan implementation. The intention is for layers
1257 - `vkGetInstanceProcAddr` intercepts a Vulkan function by returning a local
1261 - `vkGetDeviceProcAddr` intercepts a Vulkan function by returning a local
1287 `include/vulkan/vk_layer.h` for details.
1316 Get*ProcAddr function once for each Vulkan function needed in your dispatch
1430 4. All component layers **must be** at the same Vulkan API major and minor
1460 Vulkan includes a small number of functions which are called without any dispatchable object.
1532 Because Vulkan does not store any state until an instance has been created, all layer libraries are released at the end of each pre-instance call.
1538 ##### Associating Private Data with Vulkan Objects Within a Layer
1540 A layer may want to associate it's own private data with one or more Vulkan
1546 The loader supports layers wrapping any Vulkan object, including dispatchable
1552 receives a Vulkan function using something that it previously returned a handle
1554 to the layer below it. This means that the layer **must intercept every Vulkan
1626 - layers which insert extra Vulkan functions in the stream of functions they
1649 `VkLayerInstanceCreateInfo` as defined in `include/vulkan/vk_layer.h`.
1657 `VkLayerDeviceCreateInfo` as defined in `include/vulkan/vk_layer.h`.
1783 | "api\_version" | The major.minor.patch version number of the Vulkan API that the shared library file for the library was built against. For example: 1.0.33. | vkEnumerateInstanceLayerProperties |
1788 | "device\_extensions" | **OPTIONAL:** Contains the list of device extension names supported by this layer. One "device_\extensions" node with an array of one or more elements is required if any device extensions are supported by a layer, otherwise the node is optional. Each element of the array must have the nodes "name" and "spec_version" which correspond to `VkExtensionProperties` "extensionName" and "specVersion" respectively. Additionally, each element of the array of device extensions must have the node "entrypoints" if the device extension adds Vulkan API functions, otherwise this node is not required. The "entrypoint" node is an array of the names of all entrypoints added by the supported extension. | vkEnumerateDeviceExtensionProperties |
1790 | "disable\_environment" | **Implicit Layers Only** - **REQUIRED:**Indicates an environment variable used to disable the Implicit Layer (w/ value of 1). 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) must be set (not particularly to any value). If both the "enable_environment" and "disable_environment" variables are set, the implicit layer is disabled. | N/A |
1792 | "pre_instance_functions" | **Implicit Layers Only** - **OPTIONAL:** Indicates which functions the layer wishes to intercept, that do not require that an instance has been created. This should be an object where each function to be intercepted is defined as a string entry where the key is the Vulkan function name and the value is the name of the intercept function in the layer's dynamic library. Available in layer manifest versions 1.1.2 and up. See [Pre-Instance Functions](#pre-instance-functions) for more information. | vkEnumerateInstance*Properties |
1883 introspection functions, unrelated to any Vulkan function despite the names,
1932 ## Vulkan Installable Client Driver Interface With the Loader
1934 This section discusses the various requirements for the loader and a Vulkan
1947 * [ICD Vulkan Entry-Point Discovery](#icd-vulkan-entry-point-discovery)
1965 Vulkan allows multiple drivers each with one or more devices (represented by a
1966 Vulkan `VkPhysicalDevice` object) to be used collectively. The loader is
1967 responsible for discovering available Vulkan ICDs on the system. Given a list
1993 to the Nvidia Vulkan driver's ICD Manifest file.
1998 export VK_ICD_FILENAMES=/home/user/dev/mesa/share/vulkan/icd.d/intel_icd.x86_64.json
2009 Vulkan loader will read the JSON files to identify the names and attributes of
2048 Additionally, the Vulkan loader will scan the values in the following Windows registry key:
2051 HKEY_LOCAL_MACHINE\SOFTWARE\Khronos\Vulkan\Drivers
2058 HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\Khronos\Vulkan\Drivers
2062 the name of the value is the full path to a JSON manifest file. The Vulkan loader
2069 [HKEY_LOCAL_MACHINE\SOFTWARE\Khronos\Vulkan\Drivers\]
2081 The Vulkan loader will open each enabled manifest file found to obtain the name
2086 `SOFTWARE\Khronos\Vulkan\Drivers` location is the older method for locating ICDs,
2095 In order to find installed ICDs, the Vulkan loader will scan the files
2099 /usr/local/etc/vulkan/icd.d
2100 /usr/local/share/vulkan/icd.d
2101 /etc/vulkan/icd.d
2102 /usr/share/vulkan/icd.d
2103 $HOME/.local/share/vulkan/icd.d
2113 | $HOME/.local/share/vulkan/icd.d | $HOME is the current home directory of the application's user id; this path will be ignored for suid programs |
2114 | "/usr/local/etc/vulkan/icd.d" | Directory for locally built ICDs |
2115 | "/usr/local/share/vulkan/icd.d" | Directory for locally built ICDs |
2116 | "/etc/vulkan/icd.d" | Location of ICDs installed from non-Linux-distribution-provided packages |
2117 | "/usr/share/vulkan/icd.d" | Location of ICDs installed from Linux-distribution-provided packages |
2119 The Vulkan loader will open each manifest file found to obtain the name or
2129 there is a problem with an ICD missing symbols on your system, this will expose it and cause the Vulkan loader
2160 of "vulkan". **Due to security policies in Android, none of this can be modified
2187 | "api_version" | The major.minor.patch version number of the Vulkan API that the shared library files for the ICD was built against. For example: 1.0.33. |
2208 ### ICD Vulkan Entry-Point Discovery
2210 The Vulkan symbols exported by an ICD must not clash with the loader's exported
2211 Vulkan symbols. This could be for several reasons. Because of this, all ICDs
2212 must export the following function that is used for discovery of ICD Vulkan
2213 entry-points. This entry-point is not a part of the Vulkan API itself, only a
2225 level and instance-level Vulkan functions, and also for `vkGetDeviceProcAddr`.
2233 should be available via `vk_icdGetInstanceProcAddr`. Future Vulkan instance
2239 All other Vulkan entry-points must either:
2241 * or NOT use the official Vulkan function names if they are exported
2245 application prior to when the Vulkan loader library is loaded by the
2248 Beware of interposing by dynamic OS library loaders if the official Vulkan
2327 until at least a Vulkan version bump, because an older loader may still be
2334 within Vulkan dispatchable objects, such as: `VkInstance`, `VkPhysicalDevice`,
2350 dispatchable objects, as follows (see `include/vulkan/vk_icd.h`):
2375 Normally, ICDs handle object creation and destruction for various Vulkan
2395 * The `VkIcdSurfaceXXX` structures are defined in `include/vulkan/vk_icd.h`.
2436 comply with that are not part of any requirements from the Vulkan specification.
2447 used. This entry-point is not a part of the Vulkan API itself, only a private
2519 | <= 4 | <= 4 | ICD must fail with `VK_ERROR_INCOMPATIBLE_DRIVER` for all vkCreateInstance calls with apiVersion set to > Vulkan 1.0 because both the loader and ICD support interface version <= 4. Otherwise, the ICD should behave as normal. |
2520 | <= 4 | >= 5 | ICD must fail with `VK_ERROR_INCOMPATIBLE_DRIVER` for all vkCreateInstance calls with apiVersion set to > Vulkan 1.0 because the loader is still at interface version <= 4. Otherwise, the ICD should behave as normal. |
2521 | >= 5 | <= 4 | Loader will fail with `VK_ERROR_INCOMPATIBLE_DRIVER` if it can't handle the apiVersion. ICD may pass for all apiVersions, but since it's interface is <= 4, it is best if it assumes it needs to do the work of rejecting anything > Vulkan 1.0 and fail with `VK_ERROR_INCOMPATIBLE_DRIVER`. Otherwise, the ICD should behave as normal. |
2542 loader/ICD interface, as well as any Vulkan function that uses a KHR_surface
2561 1. ICD Vulkan entry-point discovery,
2563 3. Vulkan dispatchable object creation requirements.
2573 interface requirements for obtaining ICD Vulkan entry-points are as follows:
2576 and returns valid function pointers for all the Vulkan API entry-points.
2628 | Desktop Loader | The loader designed to work on both Windows and Linux. This is generated from a different [code-base](#https://github.com/KhronosGroup/Vulkan-LoaderAndValidationLayers) than the Android loader. But in all important aspects, should be functionally equivalent. |
2629 | Core Function | A function that is already part of the Vulkan core specification and not an extension. For example, vkCreateDevice(). |
2631 | Device Function | A Device function is any Vulkan function which takes a `VkDevice`, `VkQueue`, `VkCommandBuffer`, or any child of these, as its first parameter. Some Vulkan Device functions are: `vkQueueSubmit`, `vkBeginCommandBuffer`, `vkCreateEvent`. See the [Instance Versus Device](#instance-versus-device) section for more information. |
2632 | Discovery | The process of the loader searching for ICD and Layer files to setup the internal list of Vulkan objects available. On Windows/Linux, the discovery process typically focuses on searching for Manifest files. While on Android, the process focuses on searching for library files. |
2634 | Extension | A concept of Vulkan used to expand the core Vulkan functionality. Extensions may be IHV-specific, platform-specific, or more broadly available. You should always query if an extension exists, and enable it during `vkCreateInstance` (if it is an instance extension) or during `vkCreateDevice` (if it is a device extension). |
2638 | Instance Function | An Instance function is any Vulkan function which takes as its first parameter either a `VkInstance` or a `VkPhysicalDevice` or nothing at all. Some Vulkan Instance functions are: `vkEnumerateInstanceExtensionProperties`, `vkEnumeratePhysicalDevices`, `vkCreateInstance`, `vkDestroyInstance`. See the [Instance Versus Device](#instance-versus-device) section for more information. |
2639 | Layer | Layers are optional components that augment the Vulkan system. They can intercept, evaluate, and modify existing Vulkan functions on their way from the application down to the hardware. See the [Layers](#layers) section for more information. |
2640 | Loader | The middle-ware program which acts as the mediator between Vulkan applications, Vulkan layers and Vulkan drivers. See [The Loader](#the loader) section for more information. |
2644 | WSI Extension | Acronym for Windowing System Integration. A Vulkan extension targeting a particular Windowing and designed to interface between the Windowing system and Vulkan. See [WSI Extensions](#wsi-extensions) for more information. |
