pub struct Instance {
inner: DispatchInstance,
}
Expand description
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 Adapter
s and Surface
s.
Does not have to be kept alive.
Corresponds to WebGPU GPU
.
Fields§
§inner: DispatchInstance
Implementations§
Source§impl Instance
impl Instance
Sourcepub fn new(desc: &InstanceDescriptor) -> Self
pub fn new(desc: &InstanceDescriptor) -> Self
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()
.
Sourcepub const fn enabled_backend_features() -> Backends
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.
Sourcepub fn wgsl_language_features(&self) -> WgslLanguageFeatures
Available on crate feature wgsl
only.
pub fn wgsl_language_features(&self) -> WgslLanguageFeatures
wgsl
only.Returns the set of WGSL language extensions supported by this instance.
Sourcepub fn enumerate_adapters(&self, backends: Backends) -> Vec<Adapter>
Available on wgpu_core
only.
pub fn enumerate_adapters(&self, backends: Backends) -> Vec<Adapter>
wgpu_core
only.Sourcepub fn request_adapter(
&self,
options: &RequestAdapterOptions<'_, '_>,
) -> impl Future<Output = Result<Adapter, RequestAdapterError>> + WasmNotSend
pub fn request_adapter( &self, options: &RequestAdapterOptions<'_, '_>, ) -> 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.
Sourcepub fn create_surface<'window>(
&self,
target: impl Into<SurfaceTarget<'window>>,
) -> Result<Surface<'window>, CreateSurfaceError>
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
.
Sourcepub unsafe fn create_surface_unsafe<'window>(
&self,
target: SurfaceTargetUnsafe,
) -> Result<Surface<'window>, CreateSurfaceError>
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.
Sourcepub fn poll_all(&self, force_wait: bool) -> bool
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
Queue
s associated with this Instance
is coordinated somehow,
this information could be out of date by the time the caller receives
it. Queue
s can be shared between threads, and other threads could
submit new work at any time.)
On the web, this is a no-op. Device
s are automatically polled.
Sourcepub fn generate_report(&self) -> Option<GlobalReport>
Available on wgpu_core
only.
pub fn generate_report(&self) -> Option<GlobalReport>
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.
Source§impl Instance
Interop with wgpu-hal.
impl Instance
Interop with wgpu-hal.
Sourcepub unsafe fn from_hal<A: Api>(hal_instance: A::Instance) -> Self
Available on wgpu_core
only.
pub unsafe fn from_hal<A: Api>(hal_instance: A::Instance) -> Self
wgpu_core
only.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
useshal::vulkan::Instance
hal::api::Metal
useshal::metal::Instance
hal::api::Dx12
useshal::dx12::Instance
hal::api::Gles
useshal::gles::Instance
§Safety
- The
hal_instance
must be a valid and usable instance of the backend specified byA
. - 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.
Sourcepub unsafe fn as_hal<A: Api>(&self) -> Option<&A::Instance>
Available on wgpu_core
only.
pub unsafe fn as_hal<A: Api>(&self) -> Option<&A::Instance>
wgpu_core
only.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
useshal::vulkan::Instance
hal::api::Metal
useshal::metal::Instance
hal::api::Dx12
useshal::dx12::Instance
hal::api::Gles
useshal::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
orcustom
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.
Sourcepub unsafe fn create_adapter_from_hal<A: Api>(
&self,
hal_adapter: ExposedAdapter<A>,
) -> Adapter
Available on wgpu_core
only.
pub unsafe fn create_adapter_from_hal<A: Api>( &self, hal_adapter: ExposedAdapter<A>, ) -> Adapter
wgpu_core
only.Converts a wgpu-hal hal::ExposedAdapter
to a wgpu Adapter
.
§Types
The type of hal_adapter.adapter
depends on the backend:
hal::api::Vulkan
useshal::vulkan::Adapter
hal::api::Metal
useshal::metal::Adapter
hal::api::Dx12
useshal::dx12::Adapter
hal::api::Gles
useshal::gles::Adapter
§Safety
hal_adapter
must be created from this instance internal handle.
Source§impl Instance
Interop with custom backends.
impl Instance
Interop with custom backends.
Sourcepub fn from_custom<T: InstanceInterface>(instance: T) -> Self
Available on custom
only.
pub fn from_custom<T: InstanceInterface>(instance: T) -> Self
custom
only.Creates instance from custom context implementation
Sourcepub fn as_custom<T: InstanceInterface>(&self) -> Option<&T>
Available on custom
only.
pub fn as_custom<T: InstanceInterface>(&self) -> Option<&T>
custom
only.Returns custom implementation of Instance (if custom backend and is internally T)
Trait Implementations§
Source§impl Default for Instance
impl Default for Instance
Source§fn default() -> Self
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::enabled_backend_features()
.
Source§impl Ord for Instance
impl Ord for Instance
Source§impl PartialOrd for Instance
impl PartialOrd for Instance
impl Eq for Instance
Auto Trait Implementations§
impl Freeze for Instance
impl !RefUnwindSafe for Instance
impl Send for Instance
impl Sync for Instance
impl Unpin for Instance
impl !UnwindSafe for Instance
Blanket Implementations§
Source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
Source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Source§impl<T> CloneToUninit for Twhere
T: Clone,
impl<T> CloneToUninit for Twhere
T: Clone,
§impl<Q, K> Comparable<K> for Q
impl<Q, K> Comparable<K> for Q
§impl<Q, K> Equivalent<K> for Q
impl<Q, K> Equivalent<K> for Q
§fn equivalent(&self, key: &K) -> bool
fn equivalent(&self, key: &K) -> bool
key
and return true
if they are equal.