Struct WgpuOptions 

pub struct WgpuOptions { /* private fields */ }

Available on crate feature wgpu only.

Options for initializing Burn’s wgpu runtime.

Construct with Device::wgpu_options or Default::default. Options cover device acquisition and runtime settings such as memory management and task batching. Setters do not acquire a GPU. Initialization registers the selected runtime for reuse. Dropping the returned device does not deregister that runtime.

Implementations

impl WgpuOptions

pub fn device_kind(self, kind: DeviceKind) -> Self

Select an adapter kind. Existing identifiers cannot be initialized here; register an existing setup with Self::setup instead.

Browser selection follows the runtime’s power preferences; browsers do not expose native adapter indices. The default prefers a high-performance GPU.

pub fn graphics_api(self, api: WgpuBackend) -> Self

Pin the graphics API, or let WgpuBackend::Auto choose it.

An explicit API never falls back to another API. This selects the graphics API, not a shader compiler; the runtime chooses a supported compiler. With the metal feature enabled, an explicit Metal selection requires native MSL support. Initialization returns an error if it is unavailable; automatic selection permits WGSL fallback.

pub fn memory_config(self, config: MemoryConfiguration) -> Self

Set the runtime’s memory allocation policy.

pub fn tasks_max(self, tasks: usize) -> Self

Set the maximum tasks aggregated into a GPU command. Must be nonzero. Overrides CUBECL_WGPU_MAX_TASKS, including a malformed environment value.

pub fn setup(self, setup: WgpuSetup) -> WgpuSetupOptions

Register existing wgpu handles instead of acquiring another device.

Memory and task options carry over. Explicit calls to Self::device_kind or Self::graphics_api conflict with a supplied setup, even when those options name defaults; WgpuSetupOptions::init returns an error.

Handles must belong to one coherent setup. Compiler selection follows the same backend and adapter checks as acquired setups. The supplied device must enable the selected compiler’s required features, including native extensions for SPIR-V or MSL; registration does not validate all of them.

pub fn init(self) -> Result<Device, WgpuInitError>

Available on non-target_family=wasm only.

Initialize the device synchronously on native targets.

Use Self::init_async when running in a browser or an async application.

Errors

Returns acquisition, configuration, or registration errors.

Returns an error if the runtime for the selected device kind and graphics API has already been initialized, either explicitly or by a tensor operation. Runtime options must be set before first use.

pub async fn init_async(self) -> Result<Device, WgpuInitError>

Initialize the device asynchronously on native or browser targets.

Errors

Returns acquisition, configuration, or registration errors.

Returns an error if the runtime for the selected device kind and graphics API has already been initialized, either explicitly or by a tensor operation. Runtime options must be set before first use.

pub fn init_with_setup(self) -> Result<(Device, WgpuSetup), WgpuInitError>

Available on non-target_family=wasm only.

Initialize synchronously and return the exact handles used by this runtime.

Share these handles with another wgpu component. Do not register the returned setup again; clone the accompanying Burn device to reuse it.

Errors

Returns acquisition, configuration, or registration errors.

Returns an error if the runtime for the selected device kind and graphics API has already been initialized, either explicitly or by a tensor operation. Runtime options must be set before first use.

pub async fn init_with_setup_async( self, ) -> Result<(Device, WgpuSetup), WgpuInitError>

Initialize asynchronously and return the exact handles used by this runtime.

Available on native and browser targets. The returned device is ready for tensor operations; the setup is ready to share with another wgpu component.

Errors

Returns acquisition, configuration, or registration errors.

Returns an error if the runtime for the selected device kind and graphics API has already been initialized, either explicitly or by a tensor operation. Runtime options must be set before first use.

Trait Implementations

impl Default for WgpuOptions

fn default() -> Self

Returns the “default value” for a type.