Struct wgpu::Instance

source ·
pub struct Instance { /* private fields */ }
Expand description

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§

source§

impl Instance

source

pub const fn any_backend_feature_enabled() -> bool

Returns true if any backend feature is enabled for the current build configuration.

Which feature makes this method return true depends on the target platform:

  • MacOS/iOS: metal, vulkan-portability or angle
  • Wasm32: webgpu, webgl or Emscripten target.
  • All other: Always returns true

TODO: Right now it’s otherwise not possible yet to opt-out of all features on most platforms. See https://github.com/gfx-rs/wgpu/issues/3514

  • Windows: always enables Vulkan and GLES with no way to opt out
  • Linux: always enables Vulkan and GLES with no way to opt out
source

pub fn new(_instance_desc: InstanceDescriptor) -> Self

Create an new instance of wgpu.

§Arguments
  • instance_desc - Has fields for which backends wgpu will choose during instantiation, and which DX12 shader compiler wgpu will use.

    Backends::BROWSER_WEBGPU takes a special role: If it is set and WebGPU support is detected, this instance will only be able to create WebGPU adapters. If you instead want to force use of WebGL, either disable the webgpu compile-time feature or do add the Backends::BROWSER_WEBGPU flag to the the instance_desc’s backends field. If it is set and WebGPU support is not detected, the instance will use wgpu-core to create adapters. Meaning that if the webgl feature is enabled, it is able to create a WebGL adapter.

§Panics

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

source

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

Available on wgpu_core only.

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.

source

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

Available on wgpu_core only.

Return a reference to a specific backend instance, if available.

If this Instance has a wgpu-hal Instance for backend A, return a reference to it. Otherwise, return None.

§Safety
  • The raw instance handle returned must not be manually destroyed.
source

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

Available on wgpu_core only.

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.

source

pub fn enumerate_adapters(&self, backends: Backends) -> Vec<Adapter>

Available on wgpu_core only.

Retrieves all available Adapters that match the given Backends.

Always returns an empty vector if the instance decided upon creation to target WebGPU since adapter creation is always async on WebGPU.

§Arguments
  • backends - Backends from which to enumerate adapters.
source

pub fn request_adapter( &self, options: &RequestAdapterOptions<'_, '_> ) -> impl Future<Output = Option<Adapter>> + 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 suffice all the “hard” options, None is returned.

source

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

Available on wgpu_core only.

Converts a wgpu-hal ExposedAdapter to a wgpu Adapter.

§Safety

hal_adapter must be created from this instance internal handle.

source

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..

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.

source

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.

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

§Safety
source

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.

source

pub fn generate_report(&self) -> Option<GlobalReport>

Available on wgpu_core only.

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.

Trait Implementations§

source§

impl Debug for Instance

source§

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

Formats the value using the given formatter. Read more
source§

impl Default for Instance

source§

fn default() -> Self

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::any_backend_feature_enabled().

Auto Trait Implementations§

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> Downcast<T> for T

source§

fn downcast(&self) -> &T

source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
source§

impl<T> Upcast<T> for T

source§

fn upcast(&self) -> Option<&T>

source§

impl<T> WasmNotSend for T
where T: Send,

source§

impl<T> WasmNotSendSync for T

source§

impl<T> WasmNotSync for T
where T: Sync,