diff --git a/docs/LoaderApplicationInterface.md b/docs/LoaderApplicationInterface.md index 4430cf32..5b44102c 100644 --- a/docs/LoaderApplicationInterface.md +++ b/docs/LoaderApplicationInterface.md @@ -26,6 +26,7 @@ * [Windows Dynamic Library Usage](#windows-dynamic-library-usage) * [Linux Dynamic Library Usage](#linux-dynamic-library-usage) * [MacOs Dynamic Library Usage](#macos-dynamic-library-usage) + * [Bundling the Loader With An Application](#bundling-the-loader-with-an-application) * [Application Layer Usage](#application-layer-usage) * [Meta-Layers](#meta-layers) * [Implicit vs Explicit Layers](#implicit-vs-explicit-layers) @@ -222,6 +223,47 @@ dynamic library is named `libvulkan.dylib` and the ABI versioned library is currently named `libvulkan.1.dylib`. +### Bundling the Loader With An Application + +The Khronos loader is typically installed on platforms either in a +platform-specific way (i.e. packages on Linux) or as part of a driver install +(i.e. using the Vulkan Runtime installer on Windows). +Applications or engines may desire to install the Vulkan loader locally to their +execution tree as part of their own installation process. +This may be because providing the specific loader: + + 1) Guarantees certain Vulkan API exports are available in the loader + 2) Ensures certain behavior is well-known in that loader + 3) Provides consistency across more users installation + +However, this **is strongly discouraged** as it can prevent: + + 1) The application/engine from taking advantage of new Vulkan API version +exports + 2) Missing out on necessary bug-fixes + 3) Missing out on feature updates (like improved loader debugability) + +Of course, even if an application/engine does initially release with a specific +version of the Khronos loader, it may chose to update or remove that loader at +some point in the future. +This could be due to the exposure of needed functionality in the loader as time +progresses. +But, that relies upon end-users correctly performing whatever update process is +necessary at that future time which may result in different behavior across +different user's systems. + +One better alternative, at least on Windows, is to package the Vulkan Runtime +installer for the desired version of the Vulkan loader with your product. +Then, the installation process can use that to ensure the end-user's system +is up to date. +The Runtime installer will detect the version already installed and will only +install a newer runtime if necessary. + +Another alternative is to write the application so it can fallback to earlier +versions of Vulkan yet display a warning indicating functionality is disabled +until the user updates their system to a specific runtime/driver. + + ## Application Layer Usage Applications desiring Vulkan functionality beyond what Vulkan drivers @@ -748,12 +790,12 @@ Integration support for various execution environments. It is important to understand that some WSI extensions are valid for all targets, but others are particular to a given execution environment (and loader). -This desktop loader (currently targeting Windows, Linux, and macOS) only -enables and directly exports those WSI extensions that are appropriate to the -current environment. +This Khronos loader (currently targeting Windows, Linux, macOS, Stadia, and +Fuchsia) only enables and directly exports those WSI extensions that are +appropriate to the current environment. For the most part, the selection is done in the loader using compile-time preprocessor flags. -All versions of the desktop loader currently expose at least the following WSI +All versions of the Khronos loader currently expose at least the following WSI extension support: - VK_KHR_surface - VK_KHR_swapchain diff --git a/docs/LoaderInterfaceArchitecture.md b/docs/LoaderInterfaceArchitecture.md index 40f7b47f..27821984 100644 --- a/docs/LoaderInterfaceArchitecture.md +++ b/docs/LoaderInterfaceArchitecture.md @@ -563,13 +563,14 @@ discovery. Android Loader The loader designed to work primarily for the Android OS. - This is generated from a different code base than the desktop loader. + This is generated from a different code base than the Khronos loader. But, in all important aspects, it should be functionally equivalent. - Desktop Loader - The loader designed to work on Windows, Linux and macOS. + Khronos Loader + The loader released by Khronos and currently designed to work primarily + on Windows, Linux, macOS, Stadia, and Fuchsia. This is generated from a different code base than the Android loader. @@ -739,7 +740,7 @@ discovery. Manifest Files - Data files in JSON format used by the desktop loader. + Data files in JSON format used by the Khronos loader. These files contain specific information for either a Layer or a diff --git a/docs/LoaderLayerInterface.md b/docs/LoaderLayerInterface.md index 6a9f1af5..feb37015 100644 --- a/docs/LoaderLayerInterface.md +++ b/docs/LoaderLayerInterface.md @@ -122,7 +122,7 @@ Instead, the loader queries the layer properties using special functions known as "introspection" functions. The intent of these functions is to determine the same required information gathered from reading the manifest files. -These introspection functions are not used by the desktop loader but should be +These introspection functions are not used by the Khronos loader but should be present in layers to maintain consistency. The specific "introspection" functions are called out in the [Layer Manifest File Format](#layer-manifest-file-format) table. @@ -950,7 +950,7 @@ instance handle from the physical device. ## Meta-layers Meta-layers are a special kind of layer which is only available through the -desktop loader. +Khronos loader. While normal layers are associated with one particular library, a meta-layer is actually a collection layer which contains an ordered list of other layers (called component layers). @@ -1258,7 +1258,7 @@ loader *trampoline* code is as follows: intercept from the application - Drivers which add extensions that create dispatchable objects -The desktop loader provides a callback that can be used for initializing a +The Khronos loader provides a callback that can be used for initializing a dispatchable object. The callback is passed as an extension structure via the `pNext` field in the create info structure when creating an instance (`VkInstanceCreateInfo`) or @@ -1315,10 +1315,9 @@ dispatch pointer from the `VkDevice` object, which is the parent of the ## Layer Manifest File Format -On Windows, Linux and macOS (desktop), the loader uses manifest files to -discover layer libraries and layers. -The desktop loader doesn't directly query the layer's dynamic library except -during chaining. +The Khronos loader uses manifest files to discover available layer libraries +and layers. +It doesn't directly query the layer's dynamic library except during chaining. This is to reduce the likelihood of loading a malicious layer into memory. Instead, details are read from the Manifest file, which are then provided for applications to determine what layers should actually be loaded.