Trait Dispatcher

pub trait Dispatcher: Clone {
    // Required methods
    fn get_command_dispatcher(&self) -> &CommandsDispatcher;
    unsafe fn new(get_instance_proc_addr: GetInstanceProcAddrSignature) -> Self;
    fn clone_with_instance(&self, instance: &Instance) -> Self;
    fn clone_with_device(&self, device: &Device) -> Self;
    unsafe fn new_loaded() -> Result<Self, LoadingError>;

    // Provided method
    unsafe fn new_loaded_and_lib() -> Result<(Self, Library), LoadingError> { ... }
}

Dispatcher type used to hold the vk::CommandsDispatcher object The dispatcher type loads once all the vulkan commands that can be used then is used every time a vulkan command is called. It is initialized by calling Dispatcher::new with the GetInstanceProcAddrSignature entry point Or when the loaded feature is enabled by calling Dispatcher::new_loaded which will load the library There are two Dispatcher implementation provided:

• DynamicDispatcher: Store the commands in static memory, this allows for a cost-free command retrieval but requires only at most one instance and one device to exist at any time. If this is not the case use the following implementation
• MultiDispatcher: Allocate the commands storage on the heap and reference count it. This allows for any number of vulkan devices and instances to co-exist with their own dispatch table but incurs a small overhead cost (smart handles need to store an additional pointer and arc cloning needs to be done each time a new smart handle is created)

Required Methods

fn get_command_dispatcher(&self) -> &CommandsDispatcher

Return the associated vk::CommandsDispatcher with this Dispatcher You can then use the command table to call any command that has been loaded or load new commands

unsafe fn new(get_instance_proc_addr: GetInstanceProcAddrSignature) -> Self

Create a new dispatcher given the get_instance_proc_addr entry point this will load basic (non-instance and non-device dependent) commands

Safety

get_instance_proc_addr must behave as expected (for any input it should either return ptr::null() or a pointer to a function with the expected parameters and return value)

fn clone_with_instance(&self, instance: &Instance) -> Self

fn clone_with_device(&self, device: &Device) -> Self

unsafe fn new_loaded() -> Result<Self, LoadingError>

Create a loads the Vulkan library, retrieve the entry point from it and initialize the dispatcher using it* This will return an error if the vulkan library or its entry point cannot be found Library unloading depends on the implementation, for MultiDispatcher it happends as soon as all dispatcher are dropped. While for DynamicDispatcher one should call DynamicDispatcher::unload() SAFETY:

• The Vulkan library being loaded follows the Vulkan specification
• When using a DynamicDispatcher, there should be a call to DynamicDispatcher::unload() between two calls to this function

Provided Methods

unsafe fn new_loaded_and_lib() -> Result<(Self, Library), LoadingError>

Internal function used to load a library and return the dispatcher along with a library object which ensures the llibrary is kept loaded while the object is alive

Safety

• The libloading::Library object must be dropped only after Vulkan is done being used (all objects have been unitialized and no vulkan command is called after)

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors

impl Dispatcher for DynamicDispatcher

impl Dispatcher for MultiDispatcher