Struct Global

pub struct Global<T: Layer> {
    pub layer_info: T,
    /* private fields */
}

A struct that implements all necessarily functions for a layer given a type that implements Layer.

The layer implementation should use Global::default to construct a Global object. When all VkInstances and VkDevices are destroyed, the drop of Global is no-op if the drop of T is no-op under such circumstances. See the document of Layer for details on global initialization and clean-up.

This is supposed to be a global singleton for a layer to store all necessary data to implement a Vulkan layer including dispatch tables, maps between the Vulkan objects and their wrappers, etc.

Fields

layer_info: T

Access to the underlying T.

Implementations

impl<T: Layer> Global<T>

pub unsafe extern "system" fn enumerate_instance_layer_properties( property_count: *mut u32, properties: *mut LayerProperties, ) -> Result

The vkEnumerateInstanceLayerProperties entry point provided by the layer framework.

The return value is decided by Layer::manifest. Only enumerate the layer itself according to the layer rule.

Safety

See valid usage of vkEnumerateInstanceLayerProperties at https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/vkEnumerateInstanceLayerProperties.html.

pub unsafe extern "system" fn enumerate_instance_extension_properties( layer_name: *const c_char, property_count: *mut u32, _: *mut ExtensionProperties, ) -> Result

The vkEnumerateInstanceExtensionProperties entry point provided by the layer framework.

Returns an empty list with VK_SUCCESS if the layer name matches; returns VK_ERROR_LAYER_NOT_PRESENT with all the out pointers untouched, according to the LLP_LAYER_15 rule.

Safety

See valid usage of vkEnumerateInstanceExtensionProperties at https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/vkEnumerateInstanceExtensionProperties.html.

pub unsafe extern "system" fn enumerate_device_layer_properties( _: PhysicalDevice, p_property_count: *mut u32, p_properties: *mut LayerProperties, ) -> Result

The vkEnumerateDeviceLayerProperties entry point provided by the layer framework.

The return value is decided by Layer::manifest. Only enumerate the layer itself according to the layer interface version 0 requirement. Note that although this function is deprecated in the Khronos Vulkan loader, it is still used in the Android Vulkan loader.

Safety

See valid usage of vkEnumerateDeviceLayerProperties at https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/vkEnumerateDeviceLayerProperties.html.

pub unsafe extern "system" fn enumerate_device_extension_properties( physical_device: PhysicalDevice, p_layer_name: *const c_char, p_property_count: *mut u32, p_properties: *mut ExtensionProperties, ) -> Result

The vkEnumerateDeviceExtensionProperties entry point provided by the layer framework.

The return value is decided by Layer::manifest where p_layer_name is itself. If the p_layer_name doesn’t match, the behavior depends on whether the physical_device argument is VK_NULL_HANDLE or not: if physical_device argument is VK_NULL_HANDLE, VK_ERROR_LAYER_NOT_PRESENT is returned; if physical_device is not VK_NULL_HANDLE, the layer framework calls into the next layer of the call chain. This behavior is defined by the layer interface version 0 and LLP_LAYER_16.

Safety

See valid usage of vkEnumerateDeviceExtensionProperties at https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/vkEnumerateDeviceExtensionProperties.html. A NULL VkPhysicalDevice can also be used to call this interface, according to the layer interface version 0.

pub unsafe extern "system" fn get_instance_proc_addr( instance: Instance, p_name: *const c_char, ) -> PFN_vkVoidFunction

The vkGetInstanceProcAddr entry point provided by the layer framework.

The layer framework will make use of Layer::hooked_instance_commands and Layer::hooked_device_commands (with the device_info argument being None) to decide whether a local function pointer should be returned or should just passthrough to the next layer in the call chain. Note that the layer implementation doesn’t have to take care of whether the command is enabled/available, and only needs to use the interfaces to express the intent. The layer framework should handle most of the logic(e.g. the requirement of LLP_LAYER_18) here unless the layer implementation decides to intercept vkGetInstanceProcAddr.

The actual behavior is defined as follow:

1. If the instance parameter is VK_NULL_HANDLE, returns the local function pointers of the current layer for all global commands and vkGetInstanceProcAddr; NULL is returned for other Vulkan commands. One culprit for now is that currently the layer framework always returns NULL for vkEnumerateInstanceVersion, but that should be Ok, because the layer framework currently doesn’t allow to intercept pre-instance functions anyway, so this function should be completely handled by the Vulkan loader.

2. If instance is not null, the situation is more complicated:

   If the layer implementation intercepts the vkGetInstanceProcAddr function(i.e. Layer::hooked_instance_commands returns vkGetInstanceProcAddr), the layer framework just calls InstanceHooks::get_instance_proc_addr and return the return value if LayerResult::Handled is returned.

   Otherwise, the layer framework handles most of the logic according to Layer::hooked_instance_commands and Layer::hooked_device_commands:

   1. For dispatchable commands that are introspection queries: vkEnumerateDeviceExtensionProperties, vkEnumerateDeviceLayerProperties, always returns a local function pointer of the current layer.

   2. For vkDestroyInstance, vkCreateDevice, vkDestroyDevice, always returns a local function pointer. The layer framework needs to intercept those functions to build the dispatch table and perform instance/device specific initialization. Note that vkCreateInstance is a global command, so NULL will be returned if the instance argument is not VK_NULL_HANDLE.

   3. For vkEnumeratePhysicalDevices, vkEnumeratePhysicalDeviceGroups, always returns a local function pointer. The layer framework needs to intercept those functions to build a map between VkPhysicalDevice and VkInstance so that the layer framework can find the correspondent VkInstance in vkCreateDevice.

   4. For other core dispatchable commands and enabled instance extension dispatchable commands, if the layer implementation decides to intercept(according to Layer::hooked_instance_commands and Layer::hooked_device_commands), returns a local function pointer, otherwise returns the function pointer from the next layer.

   5. For disabled instance extension dispatchable commands(either because the API version is not high enough or the extension is not enabled), directly call to the next layer regardless of whether the layer implementation wants to intercept the command or not, and rely on the next layer to return NULL.

   6. For device extension dispatchable commands directly supported by the layer implementation according to LayerManifest::device_extensions, always returns a local function pointer if the layer implementation intercepts the command. Otherwise, returns the function pointer of the next layer.

   7. For device extension dispatchable commands not directly supported by the layer(i.e. the extension doesn’t appear in the LayerManifest::device_extensions of the current layer):

      • If the next layer returns NULL, NULL is always returned regardless of whether the layer implementation wants to intercept the command. This indicates that this device extension dispathcable command is not available for the instance.

      • if the next layer returns non-NULL, a local function pointer is returned if the layer implementation wants to intercept the command, otherwise returns the function pointer of the next layer This indicates that this device extension dispathcable command is available for the instance.

   8. Passthrough to the next layer if the command is not recognized.

Safety

See valid usage of vkGetInstanceProcAddr at https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/vkGetInstanceProcAddr.html.

pub unsafe extern "system" fn get_device_proc_addr( device: Device, p_name: *const c_char, ) -> PFN_vkVoidFunction

The vkGetDeviceProcAddr entry point provided by the layer framework.

The layer framework will make use of Layer::hooked_device_commands to decide whether a local function pointer should be returned or should passthrough to the next layer in the call chain. Note that the layer implementation doesn’t have to take care of whether the command is enabled(either included in the requested core version or enabled extension), and only needs to use the Layer::hooked_device_commands interface to express the intent. The layer framework should handle most of the logic(e.g. the requirement of LLP_LAYER_18) here unless the layer implementation decides to intercept vkGetDeviceProcAddr.

Safety

See valid usage of vkGetDeviceProcAddr at https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/vkGetDeviceProcAddr.html.

Trait Implementations

impl<T: Layer> Default for Global<T>

fn default() -> Self

Returns the “default value” for a type.