openharmony/third_party_vulkan-loader
1
0
Fork 0
mirror of https://gitee.com/openharmony/third_party_vulkan-loader synced 2025-02-05 23:36:51 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

docs: Fix weird characters in Loader.md file

Browse Source
This commit is contained in:
Mark Young 2016-06-01 17:49:30 -06:00
parent dc647c75a3
commit e335c40509
1 changed files with 29 additions and 23 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

52
loader/LoaderAndLayerInterface.md
View File

@ -33,7 +33,7 @@ Architectural overview of layers and loader
-------------------------------------------
Vulkan is a layered architecture. Layers can hook (intercept) Vulkan commands to
achieve various functionality that a Vulkan driver (aka ICD) or loader doesn’t
achieve various functionality that a Vulkan driver (aka ICD) or loader doesn't
support. Functionality such as Vulkan API tracing and debugging, API usage
validation, and other tools such as framebuffer overlays are all natural
candidates for Vulkan layers. Layers are implemented as libraries that are
@ -49,12 +49,12 @@ ICD being called.
Vulkan uses an object model to control the scope of a particular action /
operation. The object to be acted on is always the first parameter of a Vulkan
call and is a dispatchable object (see Vulkan specification section 2.2 Object
call and is a dispatchable object (see Vulkan specification section 2.3 Object
Model). Under the covers, the dispatchable object handle is a pointer to a
structure that contains a pointer to a dispatch table maintained by the loader.
This dispatch table contains pointers to the Vulkan functions appropriate to
that object. There are two types of dispatch tables the loader maintains,
Instance and Device. I.e. a VkInstance object’s dispatch table will point to Vulkan
Instance and Device. I.e. a VkInstance object's dispatch table will point to Vulkan
functions such as vkEnumeratePhysicalDevices, vkDestroyInstance,
vkCreateInstance, etc. Instance functions take a VkInstance or VkPhysicalDevice as
their first argument.
@ -73,8 +73,8 @@ created and a device call chain for each VkDevice that is created.
For example, the diagram below represents what happens in the call chain for
vkCreateInstance. After initializing the chain, the loader will call into the
first layer’s vkCreateInstance which will call the next finally terminating in
the loader again where this function calls every ICD’s vkCreateInstance and
first layer's vkCreateInstance which will call the next finally terminating in
the loader again where this function calls every ICD's vkCreateInstance and
saves the results. This allows every enabled layer for this chain to set up
what it needs based on the VkInstanceCreateInfo structure from the application.
![Instance call chain](instance_call_chain.png)
@ -93,7 +93,7 @@ instance) can skip intercepting any given Vulkan entry point.
Application interface to loader
-------------------------------
In this section we’ll discuss how an application interacts with the loader.
In this section we'll discuss how an application interacts with the loader.
- Linking to loader library for core and WSI extension symbols.
@ -116,7 +116,7 @@ object they are given.
Applications are not required to link directly to the loader library, instead
they can use the appropriate platform specific dynamic symbol lookup on the
loader library to initialize the application’s own dispatch table. This allows
loader library to initialize the application's own dispatch table. This allows
an application to fail gracefully if the loader cannot be found, and it
provides the fastest mechanism for the application to call Vulkan functions. An
application will only need to query (via system calls such as dlsym()) the
@ -134,10 +134,11 @@ library version. Vulkan versioning is such that ABI backwards compatibility is
guaranteed for all versions with the same major number (e.g. 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 file name is “vulkan-<ABI
version>.dll”. For example, for Vulkan version 1.X on Windows the library
given system. The Vulkan loader library file name is "vulkan-<ABI
version>.dll". 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.
windows/system32 directory (on 64-bit Windows installs, the 32-bit version of
the loader with the same name can be found in the windows/sysWOW64 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
@ -145,6 +146,8 @@ 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 (e.g. libvulkan.so.1).
####Layer Usage
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
@ -154,13 +157,12 @@ application. Thus, eliminating the overhead of validating the application's
usage of the API. Layers discovered by the loader are reported to the
application via vkEnumerateInstanceLayerProperties.
Layers are enabled at vkCreateInstance and are active for all Vulkan commands
that using the given VkIstance and any of it's child objects.
For example, the ppEnabledLayerNames array in the
VkInstanceCreateInfo structure is used by the application to list the
layer names to be enabled at vkCreateInstance. At vkCreateInstance and
vkCreateDevice, the loader will construct call chains that include the
application specified (enabled) layers. vkCreateDevice will use the layers
specified at vkCreateInstance. vkEnumerateDeviceLayerProperties and
using the given VkIstance and any of it's child objects. For example, the
ppEnabledLayerNames array in the VkInstanceCreateInfo structure is used by
the application to list the layer names to be enabled at vkCreateInstance. At
vkCreateInstance and vkCreateDevice, the loader will construct call chains that
include the application specified (enabled) layers. vkCreateDevice will use the
layers specified at vkCreateInstance. vkEnumerateDeviceLayerProperties and
device layers are deprecated. 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
@ -168,7 +170,7 @@ 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 variable
“VK\_INSTANCE\_LAYERS” can be used to enable
"VK\_INSTANCE\_LAYERS" can be used to enable
additional layers which are not specified (enabled) by the application at
vkCreateInstance. VK\_INSTANCE\_LAYERS is a colon
(Linux)/semi-colon (Windows) separated list of layer names to enable. Order is
@ -189,6 +191,8 @@ layer VK\_LAYER\_LUNARG\_parameter\_validation on Windows or Linux is as follows
```
#### Implicit vs Explicit Layers
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
@ -204,6 +208,8 @@ 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/Device Extensions
Instance extensions can be discovered via
vkEnumerateInstanceExtensionProperties. Device extensions can be discovered via
vkEnumerateDeviceExtensionProperties. The loader discovers and aggregates all
@ -230,8 +236,8 @@ 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
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 (e.g. vkDestroyDevice) the loader
trampoline code is skipped for function pointers obtained via
@ -298,7 +304,7 @@ 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
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
@ -410,7 +416,7 @@ 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
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.
The "/usr/share/vulkan/icd.d" directory is for ICDs that are installed from
@ -483,7 +489,7 @@ 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
viewed as a pass through. That is, the loader generally doesn't modify the
commands or their parameters, but simply calls the ICDs entry point for that
command. There are specific additional interface requirements an ICD needs to comply with that
are over and above any requirements from the Vulkan specification including WSI extension specification.