Struct Instance 

pub struct Instance { /* private fields */ }

Available on crate feature unstable-wgpu-27 only.

Contains the various entry points to start interacting with the system’s GPUs.

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(desc: &InstanceDescriptor) -> Instance

Create an new instance of wgpu using the given options and enabled backends.

Panics

• If no backend feature for the active target platform is enabled, this method will panic; see Instance::enabled_backend_features().

pub const fn enabled_backend_features() -> Backends

Returns which backends can be picked for the current build configuration.

The returned set depends on a combination of target platform and enabled features. This does not do any runtime checks and is exclusively based on compile time information.

InstanceDescriptor::backends does not need to be a subset of this, but any backend that is not in this set, will not be picked.

pub fn wgsl_language_features(&self) -> WgslLanguageFeatures

Returns the set of WGSL language extensions supported by this instance.

pub fn enumerate_adapters(&self, backends: Backends) -> Vec<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<&Surface<'_>>, ) -> impl Future<Output = Result<Adapter, RequestAdapterError>> + WasmNotSend

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 satisfy all the “hard” options, an error is returned.

When targeting WebGL2, a compatible_surface must be specified; using RequestAdapterOptions::default() will not succeed.

pub fn create_surface<'window>( &self, target: impl Into<SurfaceTarget<'window>>, ) -> Result<Surface<'window>, CreateSurfaceError>

Creates a new surface targeting a given window/canvas/surface/etc..

Internally, this creates surfaces for all backends that are enabled for this instance.

See SurfaceTarget for what targets are supported. See Instance::create_surface_unsafe for surface creation with unsafe target variants.

Most commonly used are window handles (or provider of windows handles) which can be passed directly as they’re automatically converted to SurfaceTarget.

pub unsafe fn create_surface_unsafe<'window>( &self, target: SurfaceTargetUnsafe, ) -> Result<Surface<'window>, CreateSurfaceError>

Creates a new surface targeting a given window/canvas/surface/etc. using an unsafe target.

Internally, this creates surfaces for all backends that are enabled for this instance.

See SurfaceTargetUnsafe for what targets are supported. See Instance::create_surface for surface creation with safe target variants.

Safety

• See respective SurfaceTargetUnsafe variants for safety requirements.

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) -> Option<GlobalReport>

Generates memory report.

Returns None if the feature is not supported by the backend which happens only when WebGPU is pre-selected by the instance creation.

impl Instance

Interop with wgpu-hal.

pub unsafe fn from_hal<A>(hal_instance: <A as Api>::Instance) -> Instance

where A: Api,

Create an new instance of wgpu from a wgpu-hal instance. This is often useful when you need to do backend specific logic, or interop with an existing backend instance.

Types

The type of A::Instance depends on the backend:

• hal::api::Vulkan uses hal::vulkan::Instance
• hal::api::Metal uses hal::metal::Instance
• hal::api::Dx12 uses hal::dx12::Instance
• hal::api::Gles uses hal::gles::Instance

Safety

• The hal_instance must be a valid and usable instance of the backend specified by A.
• wgpu will act like it has complete ownership of this instance, and will destroy it when the last reference to the instance, internal or external, is dropped.

pub unsafe fn as_hal<A>(&self) -> Option<&<A as Api>::Instance>

where A: Api,

Get the wgpu_hal instance from this Instance.

Find the Api struct corresponding to the active backend in wgpu_hal::api, and pass that struct to the to the A type parameter.

Returns a guard that dereferences to the type of the hal backend which implements A::Instance.

Types

• hal::api::Vulkan uses hal::vulkan::Instance
• hal::api::Metal uses hal::metal::Instance
• hal::api::Dx12 uses hal::dx12::Instance
• hal::api::Gles uses hal::gles::Instance

Errors

This method will return None if:

• The instance is not from the backend specified by A.
• The instance is from the webgpu or custom backend.

Safety

• The returned resource must not be destroyed unless the guard is the last reference to it and it is not in use by the GPU. The guard and handle may be dropped at any time however.
• All the safety requirements of wgpu-hal must be upheld.

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

where A: Api,

Converts a wgpu-hal hal::ExposedAdapter to a wgpu Adapter.

Types

The type of hal_adapter.adapter depends on the backend:

• hal::api::Vulkan uses hal::vulkan::Adapter
• hal::api::Metal uses hal::metal::Adapter
• hal::api::Dx12 uses hal::dx12::Adapter
• hal::api::Gles uses hal::gles::Adapter

Safety

hal_adapter must be created from this instance internal handle.

impl Instance

Interop with wgpu-core.

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

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.

Trait Implementations

impl Clone for Instance

fn clone(&self) -> Instance

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Instance

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

Formats the value using the given formatter.

impl Default for Instance

fn default() -> Instance

Creates a new instance of wgpu with default options.

Backends are set to Backends::all(), and FXC is chosen as the dx12_shader_compiler.

Panics

If no backend feature for the active target platform is enabled, this method will panic, see Instance::enabled_backend_features().

impl Hash for Instance

fn hash<H>(&self, state: &mut H)

where H: Hasher,

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Ord for Instance

fn cmp(&self, other: &Instance) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl PartialEq for Instance

fn eq(&self, other: &Instance) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialOrd for Instance

fn partial_cmp(&self, other: &Instance) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl Eq for Instance