Struct wgpu::Instance

pub struct Instance { /* private fields */ }

Context for all other wgpu objects. Instance of wgpu.

This is the first thing you create when using wgpu. Its primary use is to create Adapters and Surfaces.

Does not have to be kept alive.

Corresponds to WebGPU GPU.

Implementations

impl Instance

pub fn new(backends: Backends) -> Self

Create an new instance of wgpu.

Arguments

• backends - Controls from which backends wgpu will choose during instantiation.

pub unsafe fn from_hal<A: HalApi>(hal_instance: A::Instance) -> Self

Create an new instance of wgpu from a wgpu-hal instance.

Arguments

• hal_instance - wgpu-hal instance.

Safety

Refer to the creation of wgpu-hal Instance for every backend.

pub unsafe fn as_hal<A: HalApi, F: FnOnce(Option<&A::Instance>) -> R, R>(
    &self,
    hal_instance_callback: F
) -> R

Returns the inner hal Instance using a callback. The hal instance will be None if the backend type argument does not match with this wgpu Instance

Safety

• The raw handle obtained from the hal Instance must not be manually destroyed

pub unsafe fn from_core(core_instance: Instance) -> Self

Create an new instance of wgpu from a wgpu-core instance.

Arguments

• core_instance - wgpu-core instance.

Safety

Refer to the creation of wgpu-core Instance.

pub fn enumerate_adapters(
    &self,
    backends: Backends
) -> impl Iterator<Item = Adapter>

Retrieves all available Adapters that match the given Backends.

Arguments

• backends - Backends from which to enumerate adapters.

pub fn request_adapter(
    &self,
    options: &RequestAdapterOptions<'_>
) -> impl Future<Output = Option<Adapter>> + Send

Retrieves an Adapter which matches the given RequestAdapterOptions.

Some options are “soft”, so treated as non-mandatory. Others are “hard”.

If no adapters are found that suffice all the “hard” options, None is returned.

pub unsafe fn create_adapter_from_hal<A: HalApi>(
    &self,
    hal_adapter: ExposedAdapter<A>
) -> Adapter

Converts a wgpu-hal ExposedAdapter to a wgpu Adapter.

Safety

hal_adapter must be created from this instance internal handle.

pub unsafe fn create_surface<W: HasRawWindowHandle>(
    &self,
    window: &W
) -> Surface

Creates a surface from a raw window handle.

Safety

• Raw Window Handle must be a valid object to create a surface upon and must remain valid for the lifetime of the returned surface.
• If not called on the main thread, metal backend will panic.

pub fn poll_all(&self, force_wait: bool) -> bool

Polls all devices.

If force_wait is true and this is not running on the web, then this function will block until all in-flight buffers have been mapped and all submitted commands have finished execution.

Return true if all devices’ queues are empty, or false if there are queue submissions still in flight. (Note that, unless access to all Queues associated with this Instance is coordinated somehow, this information could be out of date by the time the caller receives it. Queues can be shared between threads, and other threads could submit new work at any time.)

On the web, this is a no-op. Devices are automatically polled.

pub fn generate_report(&self) -> GlobalReport

Generates memory report.

Trait Implementations

impl Debug for Instance

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.