openharmony/third_party_vulkan-loader
1
0
Fork 0
mirror of https://gitee.com/openharmony/third_party_vulkan-loader synced 2024-11-27 09:21:56 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Update Docs table of contents

Browse Source
This commit is contained in:
Charles Giessen 2022-02-07 15:47:01 -07:00 committed by Charles Giessen
parent 610a0516d0
commit d921cef633
5 changed files with 217 additions and 169 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

80
BUILD.md
View File

@ -2,16 +2,36 @@
Instructions for building this repository on Linux, Windows, and MacOS.
## Index
## Table Of Contents
- [Contributing to the Repository](#contributing-to-the-repository)
- [Repository Content](#repository-content)
- [Installed Files](#installed-files)
- [Repository Set-Up](#repository-set-up)
- [Display Drivers](#display-drivers)
- [Download the Repository](#download-the-repository)
- [Repository Dependencies](#repository-dependencies)
- [Build and Install Directories](#build-and-install-directories)
- [Building Dependent Repositories with Known-Good Revisions](#building-dependent-repositories-with-known-good-revisions)
- [Generated source code](#generated-source-code)
- [Build Options](#build-options)
- [Building On Windows](#building-on-windows)
- [Windows Development Environment Requirements](#windows-development-environment-requirements)
- [Windows Build - Microsoft Visual Studio](#windows-build---microsoft-visual-studio)
- [Windows Notes](#windows-notes)
- [CMake Visual Studio Generators](#cmake-visual-studio-generators)
- [Using The Vulkan Loader Library in this Repository on Windows](#using-the-vulkan-loader-library-in-this-repository-on-windows)
- [Building On Linux](#building-on-linux)
- [Linux Development Environment Requirements](#linux-development-environment-requirements)
- [Linux Build](#linux-build)
- [Building on MacOS](#building-on-macos)
- [MacOS Development Environment Requirements](#macos-development-environment-requirements)
- [Clone the Repository](#clone-the-repository)
- [MacOS build](#macos-build)
- [Building on Fuchsia](#building-on-fuchsia)
- [Building on QNX](#building-on-qnx)
- [SDK Symbols](#sdk-symbols)
1. [Contributing](#contributing-to-the-repository)
1. [Repository Content](#repository-content)
1. [Repository Set-Up](#repository-set-up)
1. [Windows Build](#building-on-windows)
1. [Linux Build](#building-on-linux)
1. [MacOS build](#building-on-macos)
1. [Fuchsia build](#building-on-fuchsia)
1. [QNX build](#building-on-qnx)
## Contributing to the Repository
@ -191,29 +211,29 @@ be specified to customize the build. Some of the options are binary on/off
options, while others take a string as input. The following is a table of all
on/off options currently supported by this repository:
| Option | Platform | Default | Description |
| ------ | -------- | ------- | ----------- |
| BUILD_LOADER | All | `ON` | Controls whether or not the loader is built. Setting this to `OFF` will allow building the tests against a loader that is installed to the system. |
| BUILD_TESTS | All | `???` | Controls whether or not the loader tests are built. The default is `ON` when the Google Test repository is cloned into the `external` directory. Otherwise, the default is `OFF`. |
| BUILD_WSI_XCB_SUPPORT | Linux | `ON` | Build the loader with the XCB entry points enabled. Without this, the XCB headers should not be needed, but the extension `VK_KHR_xcb_surface` won't be available. |
| BUILD_WSI_XLIB_SUPPORT | Linux | `ON` | Build the loader with the Xlib entry points enabled. Without this, the X11 headers should not be needed, but the extension `VK_KHR_xlib_surface` won't be available. |
| BUILD_WSI_WAYLAND_SUPPORT | Linux | `ON` | Build the loader with the Wayland entry points enabled. Without this, the Wayland headers should not be needed, but the extension `VK_KHR_wayland_surface` won't be available. |
| BUILD_WSI_DIRECTFB_SUPPORT | Linux | `OFF` | Build the loader with the DirectFB entry points enabled. Without this, the DirectFB headers should not be needed, but the extension `VK_EXT_directfb_surface` won't be available. |
| BUILD_WSI_SCREEN_QNX_SUPPORT | QNX | `OFF` | Build the loader with the QNX Screen entry points enabled. Without this the extension `VK_QNX_screen_surface` won't be available. |
| ENABLE_WIN10_ONECORE | Windows | `OFF` | Link the loader to the [OneCore](https://msdn.microsoft.com/en-us/library/windows/desktop/mt654039.aspx) umbrella library, instead of the standard Win32 ones. |
| USE_CCACHE | Linux | `OFF` | Enable caching with the CCache program. |
| USE_GAS | Linux | `ON` | Controls whether to build assembly files with the GNU assembler, else fallback to C code. |
| USE_MASM | Windows | `ON` | Controls whether to build assembly files with MS assembler, else fallback to C code |
| BUILD_STATIC_LOADER | macOS | `OFF` | This allows the loader to be built as a static library on macOS. Not tested, use at your own risk. |
| Option | Platform | Default | Description |
| ---------------------------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| BUILD_LOADER | All | `ON` | Controls whether or not the loader is built. Setting this to `OFF` will allow building the tests against a loader that is installed to the system. |
| BUILD_TESTS | All | `???` | Controls whether or not the loader tests are built. The default is `ON` when the Google Test repository is cloned into the `external` directory. Otherwise, the default is `OFF`. |
| BUILD_WSI_XCB_SUPPORT | Linux | `ON` | Build the loader with the XCB entry points enabled. Without this, the XCB headers should not be needed, but the extension `VK_KHR_xcb_surface` won't be available. |
| BUILD_WSI_XLIB_SUPPORT | Linux | `ON` | Build the loader with the Xlib entry points enabled. Without this, the X11 headers should not be needed, but the extension `VK_KHR_xlib_surface` won't be available. |
| BUILD_WSI_WAYLAND_SUPPORT | Linux | `ON` | Build the loader with the Wayland entry points enabled. Without this, the Wayland headers should not be needed, but the extension `VK_KHR_wayland_surface` won't be available. |
| BUILD_WSI_DIRECTFB_SUPPORT | Linux | `OFF` | Build the loader with the DirectFB entry points enabled. Without this, the DirectFB headers should not be needed, but the extension `VK_EXT_directfb_surface` won't be available. |
| BUILD_WSI_SCREEN_QNX_SUPPORT | QNX | `OFF` | Build the loader with the QNX Screen entry points enabled. Without this the extension `VK_QNX_screen_surface` won't be available. |
| ENABLE_WIN10_ONECORE | Windows | `OFF` | Link the loader to the [OneCore](https://msdn.microsoft.com/en-us/library/windows/desktop/mt654039.aspx) umbrella library, instead of the standard Win32 ones. |
| USE_CCACHE | Linux | `OFF` | Enable caching with the CCache program. |
| USE_GAS | Linux | `ON` | Controls whether to build assembly files with the GNU assembler, else fallback to C code. |
| USE_MASM | Windows | `ON` | Controls whether to build assembly files with MS assembler, else fallback to C code |
| BUILD_STATIC_LOADER | macOS | `OFF` | This allows the loader to be built as a static library on macOS. Not tested, use at your own risk. |
The following is a table of all string options currently supported by this repository:
| Option | Platform | Default | Description |
| ------ | -------- | ------- | ----------- |
| CMAKE_OSX_DEPLOYMENT_TARGET | MacOS | `10.12` | The minimum version of MacOS for loader deployment. |
| FALLBACK_CONFIG_DIRS | Linux/MacOS | `/etc/xdg` | Configuration path(s) to use instead of `XDG_CONFIG_DIRS` if that environment variable is unavailable. The default setting is freedesktop compliant. |
| FALLBACK_DATA_DIRS | Linux/MacOS | `/usr/local/share:/usr/share` | Configuration path(s) to use instead of `XDG_DATA_DIRS` if that environment variable is unavailable. The default setting is freedesktop compliant. |
| BUILD_DLL_VERSIONINFO | Windows | `""` (empty string) | Allows setting the Windows specific version information for the Loader DLL. Format is "major.minor.patch.build". |
| Option | Platform | Default | Description |
| --------------------------- | ----------- | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| CMAKE_OSX_DEPLOYMENT_TARGET | MacOS | `10.12` | The minimum version of MacOS for loader deployment. |
| FALLBACK_CONFIG_DIRS | Linux/MacOS | `/etc/xdg` | Configuration path(s) to use instead of `XDG_CONFIG_DIRS` if that environment variable is unavailable. The default setting is freedesktop compliant. |
| FALLBACK_DATA_DIRS | Linux/MacOS | `/usr/local/share:/usr/share` | Configuration path(s) to use instead of `XDG_DATA_DIRS` if that environment variable is unavailable. The default setting is freedesktop compliant. |
| BUILD_DLL_VERSIONINFO | Windows | `""` (empty string) | Allows setting the Windows specific version information for the Loader DLL. Format is "major.minor.patch.build". |
These variables should be set using the `-D` option when invoking CMake to generate the native platform files.
@ -373,7 +393,7 @@ have installed. Generator strings that correspond to versions of Visual Studio
include:
| Build Platform | 64-bit Generator | 32-bit Generator |
|------------------------------|-------------------------------|-------------------------|
| ---------------------------- | ----------------------------- | ----------------------- |
| Microsoft Visual Studio 2015 | "Visual Studio 14 2015 Win64" | "Visual Studio 14 2015" |
| Microsoft Visual Studio 2017 | "Visual Studio 15 2017 Win64" | "Visual Studio 15 2017" |
| Microsoft Visual Studio 2019 | "Visual Studio 16 2019" | "Visual Studio 16 2019" |

79
docs/LoaderApplicationInterface.md
View File

@ -14,41 +14,42 @@
## Table of Contents
* [Overview](#overview)
* [Interfacing with Vulkan Functions](#interfacing-with-vulkan-functions)
* [Vulkan Direct Exports](#vulkan-direct-exports)
* [Directly Linking to the Loader](#directly-linking-to-the-loader)
* [Dynamic Linking](#dynamic-linking)
* [Static Linking](#static-linking)
* [Indirectly Linking to the Loader](#indirectly-linking-to-the-loader)
* [Best Application Performance Setup](#best-application-performance-setup)
* [ABI Versioning](#abi-versioning)
* [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)
* [Override Layer](#override-layer)
* [Forcing Layer Source Folders](#forcing-layer-source-folders)
* [Exception for Elevated Privileges](#exception-for-elevated-privileges)
* [Forcing Layers to be Enabled](#forcing-layers-to-be-enabled)
* [Overall Layer Ordering](#overall-layer-ordering)
* [Debugging Possible Layer Issues](#debugging-possible-layer-issues)
* [Enable Loader Debug Layer Output](#enable-loader-debug-layer-output)
* [Disable All Layers](#disable-all-layers)
* [Enable More Loader Debug Output](#enable-more-loader-debug-output)
* [Application Usage of Extensions](#application-usage-of-extensions)
* [Instance and Device Extensions](#instance-and-device-extensions)
* [WSI Extensions](#wsi-extensions)
* [Unknown Extensions](#unknown-extensions)
* [Physical Device Ordering](#physical-device-ordering)
- [Overview](#overview)
- [Interfacing with Vulkan Functions](#interfacing-with-vulkan-functions)
- [Vulkan Direct Exports](#vulkan-direct-exports)
- [Directly Linking to the Loader](#directly-linking-to-the-loader)
- [Dynamic Linking](#dynamic-linking)
- [Static Linking](#static-linking)
- [Indirectly Linking to the Loader](#indirectly-linking-to-the-loader)
- [Best Application Performance Setup](#best-application-performance-setup)
- [ABI Versioning](#abi-versioning)
- [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)
- [Override Layer](#override-layer)
- [Forcing Layer Source Folders](#forcing-layer-source-folders)
- [Exception for Elevated Privileges](#exception-for-elevated-privileges)
- [Forcing Layers to be Enabled on Windows, Linux and macOS](#forcing-layers-to-be-enabled-on-windows-linux-and-macos)
- [Overall Layer Ordering](#overall-layer-ordering)
- [Debugging Possible Layer Issues](#debugging-possible-layer-issues)
- [Enable Loader Debug Layer Output](#enable-loader-debug-layer-output)
- [Disable All Layers](#disable-all-layers)
- [Enable More Loader Debug Output](#enable-more-loader-debug-output)
- [Application Usage of Extensions](#application-usage-of-extensions)
- [Instance and Device Extensions](#instance-and-device-extensions)
- [WSI Extensions](#wsi-extensions)
- [Unknown Extensions](#unknown-extensions)
- [Filtering Out Unknown Instance Extension Names](#filtering-out-unknown-instance-extension-names)
- [Physical Device Ordering](#physical-device-ordering)
## Overview
This is the Application-centric view of working with the Vulkan loader.
For the complete overview of all sections of the loader, please refer
For the complete overview of all sections of the loader, please refer
to the [LoaderInterfaceArchitecture.md](LoaderInterfaceArchitecture.md) file.
## Interfacing with Vulkan Functions
@ -447,7 +448,7 @@ The table below details more information:
#### Override Layer
The "Override Layer" is a special implicit meta-layer created by the
The "Override Layer" is a special implicit meta-layer created by the
[VkConfig](https://github.com/LunarG/VulkanTools/blob/master/vkconfig/README.md)
tool and available by default when the tool is running.
Once VkConfig exits, the override layer is removed, and the system should
@ -809,13 +810,13 @@ extension support:
In addition, each of the following OS targets for the loader support target-
specific extensions:
| Windowing System | Extensions available |
|----------------|--------------------|
| Windows | VK_KHR_win32_surface |
| Linux (Wayland) | VK_KHR_wayland_surface |
| Linux (X11) | VK_KHR_xcb_surface and VK_KHR_xlib_surface |
| macOS (MoltenVK) | VK_MVK_macos_surface |
| QNX (Screen) | VK_QNX_screen_surface |
| Windowing System | Extensions available |
| ---------------- | ------------------------------------------ |
| Windows | VK_KHR_win32_surface |
| Linux (Wayland) | VK_KHR_wayland_surface |
| Linux (X11) | VK_KHR_xcb_surface and VK_KHR_xlib_surface |
| macOS (MoltenVK) | VK_MVK_macos_surface |
| QNX (Screen) | VK_QNX_screen_surface |
It is important to understand that while the loader may support the various
entry-points for these extensions, there is a handshake required to actually

88
docs/LoaderDriverInterface.md
View File

@ -15,46 +15,54 @@
## Table of Contents
* [Overview](#overview)
* [Driver Discovery](#driver-discovery)
* [Overriding the Default Driver Discovery](#overriding-the-default-driver-discovery)
* [Exception for Elevated Privileges](#exception-for-elevated-privileges)
* [Driver Manifest File Usage](#driver-manifest-file-usage)
* [Driver Discovery on Windows](#driver-discovery-on-windows)
* [Driver Discovery on Linux](#driver-discovery-on-linux)
* [Example Linux Driver Search Path](#example-linux-driver-search-path)
* [Driver Discovery on Fuchsia](#driver-discovery-on-fuchsia)
* [Driver Discovery on macOS](#driver-discovery-on-macos)
* [Example macOS Driver Search Path](#example-macos-driver-search-path)
* [Using Pre-Production ICDs or Software Drivers](#using-pre-production-icds-or-software-drivers)
* [Driver Discovery on Android](#driver-discovery-on-android)
* [Driver Manifest File Format](#driver-manifest-file-format)
* [Driver Manifest File Versions](#driver-manifest-file-versions)
* [Driver Manifest File Version 1.0.0](#driver-manifest-file-version-100)
* [Driver Vulkan Entry Point Discovery](#driver-vulkan-entry-point-discovery)
* [Driver API Version](#driver-api-version)
* [Mixed Driver Instance Extension Support](#mixed-driver-instance-extension-support)
* [Filtering Out Instance Extension Names](#filtering-out-instance-extension-names)
* [Loader Instance Extension Emulation Support](#loader-instance-extension-emulation-support)
* [Driver Unknown Physical Device Extensions](#driver-unknown-physical-device-extensions)
* [Driver Dispatchable Object Creation](#driver-dispatchable-object-creation)
* [Handling KHR Surface Objects in WSI Extensions](#handling-khr-surface-objects-in-wsi-extensions)
* [Loader and Driver Interface Negotiation](#loader-and-driver-interface-negotiation)
* [Windows, Linux, and macOS Driver Negotiation](#windows-linux-and-macos-driver-negotiation)
* [Version Negotiation Between Loader and Drivers](#version-negotiation-between-loader-and-drivers)
* [Interfacing With Legacy Drivers or Loaders](#interfacing-with-legacy-drivers-or-loaders)
* [Loader Version 6 Interface Requirements](#loader-version-6-interface-requirements)
* [Loader Version 5 Interface Requirements](#loader-version-5-interface-requirements)
* [Loader Version 4 Interface Requirements](#loader-version-4-interface-requirements)
* [Loader Version 3 Interface Requirements](#loader-version-3-interface-requirements)
* [Loader Version 2 Interface Requirements](#loader-version-2-interface-requirements)
* [Loader Version 1 Interface Requirements](#loader-version-1-interface-requirements)
* [Loader Version 0 Interface Requirements](#loader-version-0-interface-requirements)
* [Additional Interface Notes](#additional-interface-notes)
* [Android Driver Negotiation](#android-driver-negotiation)
* [Loader and Driver Policy](#loader-and-driver-policy)
* [Requirements of Well-Behaved Drivers](#requirements-of-well-behaved-drivers)
* [Requirements of a Well-Behaved Loader](#requirements-of-a-well-behaved-loader)
- [Overview](#overview)
- [Driver Discovery](#driver-discovery)
- [Overriding the Default Driver Discovery](#overriding-the-default-driver-discovery)
- [Exception for Elevated Privileges](#exception-for-elevated-privileges)
- [Examples](#examples)
- [On Windows](#on-windows)
- [On Linux](#on-linux)
- [On macOS](#on-macos)
- [Driver Manifest File Usage](#driver-manifest-file-usage)
- [Driver Discovery on Windows](#driver-discovery-on-windows)
- [Driver Discovery on Linux](#driver-discovery-on-linux)
- [Example Linux Driver Search Path](#example-linux-driver-search-path)
- [Driver Discovery on Fuchsia](#driver-discovery-on-fuchsia)
- [Driver Discovery on macOS](#driver-discovery-on-macos)
- [Example macOS Driver Search Path](#example-macos-driver-search-path)
- [Additional Settings For Driver Debugging](#additional-settings-for-driver-debugging)
- [Using Pre-Production ICDs or Software Drivers](#using-pre-production-icds-or-software-drivers)
- [Driver Discovery on Android](#driver-discovery-on-android)
- [Driver Manifest File Format](#driver-manifest-file-format)
- [Driver Manifest File Versions](#driver-manifest-file-versions)
- [Driver Manifest File Version 1.0.0](#driver-manifest-file-version-100)
- [Driver Vulkan Entry Point Discovery](#driver-vulkan-entry-point-discovery)
- [Driver API Version](#driver-api-version)
- [Mixed Driver Instance Extension Support](#mixed-driver-instance-extension-support)
- [Filtering Out Instance Extension Names](#filtering-out-instance-extension-names)
- [Loader Instance Extension Emulation Support](#loader-instance-extension-emulation-support)
- [Driver Unknown Physical Device Extensions](#driver-unknown-physical-device-extensions)
- [Physical Device Sorting](#physical-device-sorting)
- [Driver Dispatchable Object Creation](#driver-dispatchable-object-creation)
- [Handling KHR Surface Objects in WSI Extensions](#handling-khr-surface-objects-in-wsi-extensions)
- [Loader and Driver Interface Negotiation](#loader-and-driver-interface-negotiation)
- [Windows, Linux and macOS Driver Negotiation](#windows-linux-and-macos-driver-negotiation)
- [Version Negotiation Between Loader and Drivers](#version-negotiation-between-loader-and-drivers)
- [Interfacing With Legacy Drivers or Loaders](#interfacing-with-legacy-drivers-or-loaders)
- [Loader Version 6 Interface Requirements](#loader-version-6-interface-requirements)
- [Loader Version 5 Interface Requirements](#loader-version-5-interface-requirements)
- [Loader Version 4 Interface Requirements](#loader-version-4-interface-requirements)
- [Loader Version 3 Interface Requirements](#loader-version-3-interface-requirements)
- [Loader Version 2 Interface Requirements](#loader-version-2-interface-requirements)
- [Loader Version 1 Interface Requirements](#loader-version-1-interface-requirements)
- [Loader Version 0 Interface Requirements](#loader-version-0-interface-requirements)
- [Additional Interface Notes:](#additional-interface-notes)
- [Android Driver Negotiation](#android-driver-negotiation)
- [Loader and Driver Policy](#loader-and-driver-policy)
- [Number Format](#number-format)
- [Android Differences](#android-differences)
- [Requirements of Well-Behaved Drivers](#requirements-of-well-behaved-drivers)
- [Requirements of a Well-Behaved Loader](#requirements-of-a-well-behaved-loader)
## Overview

55
docs/LoaderInterfaceArchitecture.md
View File

@ -12,26 +12,35 @@
[3]: https://i.creativecommons.org/l/by-nd/4.0/88x31.png "Creative Commons License"
[4]: https://creativecommons.org/licenses/by-nd/4.0/
## Table of Contents
* [Overview](#overview)
* [Who Should Read This Document](#who-should-read-this-document)
* [The Loader](#the-loader)
* [Layers](#layers)
* [Drivers](#drivers)
* [VkConfig](#vkconfig)
* [Important Vulkan Concepts](#important-vulkan-concepts)
* [Instance Versus Device](#instance-versus-device)
* [Dispatch Tables and Call Chains](#dispatch-tables-and-call-chains)
* [Elevated Privilege Caveats](#elevated-privilege-caveats)
* [Application Interface to the Loader](#application-interface-to-the-loader)
* [Layer Interface with the Loader](#layer-interface-with-the-loader)
* [Driver Interface with the Loader](#driver-interface-with-the-loader)
* [Loader Policies](#loader-policies)
* [Table of Debug Environment Variables](#table-of-debug-environment-variables)
* [Glossary of Terms](#glossary-of-terms)
- [Overview](#overview)
- [Who Should Read This Document](#who-should-read-this-document)
- [The Loader](#the-loader)
- [Goals of the Loader](#goals-of-the-loader)
- [Layers](#layers)
- [Drivers](#drivers)
- [Installable Client Drivers](#installable-client-drivers)
- [VkConfig](#vkconfig)
- [Important Vulkan Concepts](#important-vulkan-concepts)
- [Instance Versus Device](#instance-versus-device)
- [Instance-Specific](#instance-specific)
- [Instance Objects](#instance-objects)
- [Instance Functions](#instance-functions)
- [Instance Extensions](#instance-extensions)
- [Device-Specific](#device-specific)
- [Device Objects](#device-objects)
- [Device Functions](#device-functions)
- [Device Extensions](#device-extensions)
- [Dispatch Tables and Call Chains](#dispatch-tables-and-call-chains)
- [Instance Call Chain Example](#instance-call-chain-example)
- [Device Call Chain Example](#device-call-chain-example)
- [Elevated Privilege Caveats](#elevated-privilege-caveats)
- [Application Interface to the Loader](#application-interface-to-the-loader)
- [Layer Interface with the Loader](#layer-interface-with-the-loader)
- [Driver Interface With the Loader](#driver-interface-with-the-loader)
- [Loader Policies](#loader-policies)
- [Table of Debug Environment Variables](#table-of-debug-environment-variables)
- [Glossary of Terms](#glossary-of-terms)
## Overview
@ -113,7 +122,7 @@ Some examples of features that layers may expose include:
Because layers are optional and dynamically loaded, they can be enabled
and disabled as desired.
For example, while developing and debugging an application, enabling
For example, while developing and debugging an application, enabling
certain layers can assist in making sure it properly uses the Vulkan API.
But when releasing the application, those layers are unnecessary
and thus won't be enabled, increasing the speed of the application.
@ -365,7 +374,7 @@ layers to marshall the appropriate information to all available drivers.
For example, the diagram below represents what happens in the call chain for
`vkCreateInstance`.
After initializing the chain, the loader calls into the first layer's
`vkCreateInstance`, which will call the next layer's `vkCreateInstance
`vkCreateInstance`, which will call the next layer's `vkCreateInstance
before finally terminating in the loader again where it will call
every driver's `vkCreateInstance`.
This allows every enabled layer in the chain to set up what it needs based on
@ -413,7 +422,7 @@ These behaviors also result in ignoring certain environment variables, such as:
* `XDG_CONFIG_HOME` (Linux/Mac-specific)
* `XDG_DATA_HOME` (Linux/Mac-specific)
For more information on the affected search paths, refer to
For more information on the affected search paths, refer to
[Layer Discovery](LoaderLayerInterface.md#layer-discovery) and
[Driver Discovery](LoaderDriverInterface.md#driver-discovery).
<br/>
@ -715,7 +724,7 @@ discovery.
These are drivers that are provided by IHVs to interact with the
hardware they provide. <br/>
These are the most common type of Vulkan drivers. <br/>
See <a href="#installable-client-drivers">Installable Client Drivers</a>
See <a href="#installable-client-drivers">Installable Client Drivers</a>
section for more information.
</td>
</tr>

84
docs/LoaderLayerInterface.md
View File

@ -15,43 +15,53 @@
## Table of Contents
* [Overview](#overview)
* [Layer Discovery](#layer-discovery)
* [Layer Manifest File Usage](#layer-manifest-file-usage)
* [Android Layer Discovery](#android-layer-discovery)
* [Windows Layer Discovery](#windows-layer-discovery)
* [Linux Layer Discovery](#linux-layer-discovery)
* [Example Linux Implicit Layer Search Path](#example-linux-implicit-layer-search-path)
* [Fuchsia Layer Discovery](#fuchsia-layer-discovery)
* [macOS Layer Discovery](#macos-layer-discovery)
* [Example macOS Implicit Layer Search Path](#example-macos-implicit-layer-search-path)
* [Exception for Elevated Privileges](#exception-for-elevated-privileges)
* [Layer Version Negotiation](#layer-version-negotiation)
* [Layer Call Chains and Distributed Dispatch](#layer-call-chains-and-distributed-dispatch)
* [Layer Unknown Physical Device Extensions](#layer-unknown-physical-device-extensions)
* [Layer Intercept Requirements](#layer-intercept-requirements)
* [Distributed Dispatching Requirements](#distributed-dispatching-requirements)
* [Layer Conventions and Rules](#layer-conventions-and-rules)
* [Layer Dispatch Initialization](#layer-dispatch-initialization)
* [Example Code for CreateInstance](#example-code-for-createinstance)
* [Example Code for CreateDevice](#example-code-for-createdevice)
* [Meta-layers](#meta-layers)
* [Pre-Instance Functions](#pre-instance-functions)
* [Special Considerations](#special-considerations)
* [Associating Private Data with Vulkan Objects Within a Layer](#associating-private-data-with-vulkan-objects-within-a-layer)
* [Wrapping](#wrapping)
* [Hash Maps](#hash-maps)
* [Creating New Dispatchable Objects](#creating-new-dispatchable-objects)
* [Layer Versioning and Activation Interactions](#layer-versioning-and-activation-interactions)
* [Layer Manifest File Format](#layer-manifest-file-format)
* [Layer Manifest File Version History](#layer-manifest-file-version-history)
* [Layer Interface Versions](#layer-interface-versions)
* [Layer Interface Version 2](#layer-interface-api-version-2)
* [Layer Interface Version 1](#layer-interface-api-version-1)
* [Layer Interface Version 0](#layer-interface-api-version-0)
* [Loader and Layer Interface Policy](#loader-and-layer-interface-policy)
* [Requirements of Well-Behaved Layers](#requirements-of-well-behaved-layers)
* [Requirements of a Well-Behaved Loader](#requirements-of-a-well-behaved-loader)
- [Overview](#overview)
- [Layer Discovery](#layer-discovery)
- [Layer Manifest File Usage](#layer-manifest-file-usage)
- [Android Layer Discovery](#android-layer-discovery)
- [Windows Layer Discovery](#windows-layer-discovery)
- [Linux Layer Discovery](#linux-layer-discovery)
- [Example Linux Explicit Layer Search Path](#example-linux-explicit-layer-search-path)
- [Fuchsia Layer Discovery](#fuchsia-layer-discovery)
- [macOS Layer Discovery](#macos-layer-discovery)
- [Example macOS Implicit Layer Search Path](#example-macos-implicit-layer-search-path)
- [Exception for Elevated Privileges](#exception-for-elevated-privileges)
- [Layer Version Negotiation](#layer-version-negotiation)
- [Layer Call Chains and Distributed Dispatch](#layer-call-chains-and-distributed-dispatch)
- [Layer Unknown Physical Device Extensions](#layer-unknown-physical-device-extensions)
- [Layer Intercept Requirements](#layer-intercept-requirements)
- [Distributed Dispatching Requirements](#distributed-dispatching-requirements)
- [Layer Conventions and Rules](#layer-conventions-and-rules)
- [Layer Dispatch Initialization](#layer-dispatch-initialization)
- [Example Code for CreateInstance](#example-code-for-createinstance)
- [Example Code for CreateDevice](#example-code-for-createdevice)
- [Meta-layers](#meta-layers)
- [Override Meta-Layer](#override-meta-layer)
- [Pre-Instance Functions](#pre-instance-functions)
- [Special Considerations](#special-considerations)
- [Associating Private Data with Vulkan Objects Within a Layer](#associating-private-data-with-vulkan-objects-within-a-layer)
- [Wrapping](#wrapping)
- [Cautions About Wrapping](#cautions-about-wrapping)
- [Hash Maps](#hash-maps)
- [Creating New Dispatchable Objects](#creating-new-dispatchable-objects)
- [Versioning and Activation Interactions](#versioning-and-activation-interactions)
- [Layer Manifest File Format](#layer-manifest-file-format)
- [Layer Manifest File Version History](#layer-manifest-file-version-history)
- [Layer Manifest File Version 1.2.0](#layer-manifest-file-version-120)
- [Layer Manifest File Version 1.1.2](#layer-manifest-file-version-112)
- [Layer Manifest File Version 1.1.1](#layer-manifest-file-version-111)
- [Layer Manifest File Version 1.1.0](#layer-manifest-file-version-110)
- [Layer Manifest File Version 1.0.1](#layer-manifest-file-version-101)
- [Layer Manifest File Version 1.0.0](#layer-manifest-file-version-100)
- [Layer Interface Versions](#layer-interface-versions)
- [Layer Interface Version 2](#layer-interface-version-2)
- [Layer Interface Version 1](#layer-interface-version-1)
- [Layer Interface Version 0](#layer-interface-version-0)
- [Loader and Layer Interface Policy](#loader-and-layer-interface-policy)
- [Number Format](#number-format)
- [Android Differences](#android-differences)
- [Requirements of Well-Behaved Layers](#requirements-of-well-behaved-layers)
- [Requirements of a Well-Behaved Loader](#requirements-of-a-well-behaved-loader)
## Overview