Macro gfx_select

macro_rules! gfx_select {
    ($id:expr => $c0:ident.$c1:tt.$method:ident $params:tt) => { ... };
    ($id:expr => $c0:ident.$method:ident $params:tt) => { ... };
    ($id:expr => {$($c:tt)*}, $method:ident $params:tt) => { ... };
}

Dispatch on an Id’s backend to a backend-generic method.

Uses of this macro have the form:

    gfx_select!(id => value.method(args...))

This expands to an expression that calls value.method::<A>(args...) for the backend A selected by id. The expansion matches on id.backend(), with an arm for each backend type in wgpu_types::Backend which calls the specialization of method for the given backend. This allows resource identifiers to select backends dynamically, even though many wgpu_core methods are compiled and optimized for a specific back end.

This macro is typically used to call methods on wgpu_core::global::Global, many of which take a single hal::Api type parameter. For example, to create a new buffer on the device indicated by device_id, one would say:

gfx_select!(device_id => global.device_create_buffer(device_id, ...))

where the device_create_buffer method is defined like this:

impl Global {
   pub fn device_create_buffer<A: HalApi>(&self, ...) -> ...
   { ... }
}

That gfx_select! call uses device_id’s backend to select the right backend type A for a call to Global::device_create_buffer<A>.

However, there’s nothing about this macro that is specific to hub::Global. For example, Firefox’s embedding of wgpu_core defines its own types with methods that take hal::Api type parameters. Firefox uses gfx_select! to dynamically dispatch to the right specialization based on the resource’s id.