wgpu

https://docs.rs/wgpu/latest/
Admin
wgpu is a cross-platform, safe, pure-Rust graphics API that runs natively on Vulkan, Metal, D3D12,...
Tokens:1,616,468
Snippets:14,376
Trust Score:9.7
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Using get on a slice

Source: https://docs.rs/wgpu/latest/wgpu/util/struct.DownloadBuffer.html?search=u32+-%3E+bool

Shows `get` returning a reference to an element or subslice depending on the index type. The example covers a position, a range, an out-of-bounds position, and an out-of-bounds range, all returning `Option`.

```rust
let v = [10, 40, 30];
assert_eq!(Some(&40), v.get(1));
assert_eq!(Some(&[10, 40][..]), v.get(0..2));
assert_eq!(None, v.get(3));
assert_eq!(None, v.get(0..4));

```

--------------------------------

### Fill a wgpu buffer with f32 values using map_async

Source: https://docs.rs/wgpu/latest/src/wgpu/api/buffer.rs.html?search=u32+-%3E+bool

This example shows how to map a buffer with MAP_WRITE usage and fill it with f32 values. It uses buffer.clone() to capture the buffer for the callback, map_async with MapMode::Write, and get_mapped_range_mut to obtain a mutable view. The example includes setup code for device and buffer creation, and demonstrates using bytemuck to fill the buffer with 42.0f32.

```rust
```
# #[cfg(feature = "noop")]
# let (device, _queue) = wgpu::Device::noop(&wgpu::DeviceDescriptor::default());
# #[cfg(not(feature = "noop"))]
# let device: wgpu::Device = { return; };
#
# let buffer = device.create_buffer(&wgpu::BufferDescriptor {
#     label: None,
#     size: 400,
#     usage: wgpu::BufferUsages::MAP_WRITE,
#     mapped_at_creation: false,
# });
let capturable = buffer.clone();
buffer.map_async(wgpu::MapMode::Write, .., move |result| {
    if result.is_ok() {
        let mut view = capturable.get_mapped_range_mut(..).unwrap();
        let mut floats: wgpu::WriteOnly<[[u8; 4]]> = view.slice(..).into_chunks::<4>().0;
        floats.fill(42.0f32.to_ne_bytes());
        drop(view);
        capturable.unmap();
    }
});
```
```

--------------------------------

### Storage buffer read_write WGSL example

Source: https://docs.rs/wgpu/latest/wgpu/enum.BufferBindingType.html?search=

WGSL example for a read-write storage buffer binding.

```wgsl
@group(0) @binding(0)
var<storage, read_write> my_element: array<vec4<f32>>;
```

--------------------------------

### rchunks_exact

Source: https://docs.rs/wgpu/latest/wgpu/util/struct.DownloadBuffer.html?search=u32+-%3E+bool

Method to iterate over exact chunks of a slice starting from the end.

```APIDOC
## rchunks_exact(&self, chunk_size: usize) -> RChunksExact<'_, T>

### Description
Returns an iterator over `chunk_size` elements of the slice at a time, starting at the end of the slice. The chunks are slices and do not overlap. If `chunk_size` does not divide the length of the slice, then the last up to `chunk_size-1` elements will be omitted and can be retrieved from the `remainder` function of the iterator.

### Method
rchunks_exact

### Parameters
- **chunk_size** (usize) - Required - The size of each chunk.

### Panics
Panics if `chunk_size` is zero.

### Examples
```rust
let slice = ['l', 'o', 'r', 'e', 'm'];
let mut iter = slice.rchunks_exact(2);
assert_eq!(iter.next().unwrap(), &['e', 'm']);
assert_eq!(iter.next().unwrap(), &['o', 'r']);
assert!(iter.next().is_none());
assert_eq!(iter.remainder(), &['l']);
```
```

--------------------------------

### Instance::new

Source: https://docs.rs/wgpu/latest/src/wgpu/api/instance.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Creates a new instance of wgpu using the given options and enabled backends. Panics if no backend feature for the active target platform is enabled.

```APIDOC
## Instance::new

### Description
Creates a new instance of wgpu using the given options and enabled backends. This is the primary constructor for the Instance struct.

### Method
`pub fn new(desc: InstanceDescriptor) -> Self`

### Parameters
- **desc** (InstanceDescriptor) - Required - The options and enabled backends for the new instance.

### Panics
- If no backend feature for the active target platform is enabled, this method will panic. See `Instance::enabled_backend_features()`.

### Returns
- **Self** - A new Instance object.

### Example
```rust
let instance = Instance::new(InstanceDescriptor::default());
```
```

--------------------------------

### get() example

Source: https://docs.rs/wgpu/latest/wgpu/struct.BufferView.html

Demonstrates `get` to retrieve an element or subslice by index or range, returning `None` if out of bounds.

```rust
let v = [10, 40, 30];
assert_eq!(Some(&40), v.get(1));
assert_eq!(Some(&[10, 40][..]), v.get(0..2));
assert_eq!(None, v.get(3));
assert_eq!(None, v.get(0..4));
```

--------------------------------

### Instance::default

Source: https://docs.rs/wgpu/latest/src/wgpu/api/instance.rs.html?search=std%3A%3Avec

Creates a new wgpu instance with default options.

```APIDOC
## Instance::default

### Description
Creates a new instance of wgpu with default options. Backends are set to `Backends::all()`, and FXC is chosen as the `dx12_shader_compiler`.

### Method
Default trait implementation

### Parameters
None

### Panics
- If no backend feature for the active target platform is enabled, this method will panic. See `Instance::enabled_backend_features()`.

### Returns
- `Instance` - The newly created instance with default options.
```

--------------------------------

### Get slice length with len

Source: https://docs.rs/wgpu/latest/wgpu/struct.BufferView.html

Shows how to get the length of a slice using the `len` method. The example asserts the length of an array slice.

```rust
let a = [1, 2, 3];
assert_eq!(a.len(), 3);
```

--------------------------------

### Instance::new method implementation

Source: https://docs.rs/wgpu/latest/src/wgpu/api/instance.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Creates a new wgpu instance with the given options and enabled backends. Panics if no backend feature is enabled for the target platform. Handles WebGPU and wgpu_core backends conditionally.

```rust
55impl Instance {
56    /// Create an new instance of wgpu using the given options and enabled backends.
57    ///
58    /// # Panics
59    ///
60    /// - If no backend feature for the active target platform is enabled,
61    ///   this method will panic; see [`Instance::enabled_backend_features()`].
62    #[allow(clippy::allow_attributes, unreachable_code)]
63    pub fn new(desc: InstanceDescriptor) -> Self {
64        if Self::enabled_backend_features().is_empty() {
65            panic!(
66                "No wgpu backend feature that is implemented for the target platform was enabled. \
67                 See `wgpu::Instance::enabled_backend_features()` for more information."
68            );
69        }
70
71        #[cfg(webgpu)]
72        {
73            let is_only_available_backend = !cfg!(wgpu_core);
74            let requested_webgpu = desc.backends.contains(Backends::BROWSER_WEBGPU);
75            let support_webgpu = crate::backend::get_browser_gpu_property()
76                .map(|maybe_gpu| maybe_gpu.is_some())
77                .unwrap_or(false);
78
79            if is_only_available_backend || (requested_webgpu && support_webgpu) {
80                return Self {
81                    inner: crate::backend::ContextWebGpu::new(desc).into(),
82                };
83            }
84        }
85
86        #[cfg(wgpu_core)]
87        {
88            return Self {
89                inner: crate::backend::ContextWgpuCore::new(desc).into(),
90            };
91        }
92
93        // Silence unused variable warnings without adding _ to the parameter name (which shows up in docs).
94        let _ = desc;
95
96        unreachable!(
97            "Earlier check of `enabled_backend_features` should have prevented getting here!"
98        );
99    }
```

--------------------------------

### Get first element with first

Source: https://docs.rs/wgpu/latest/wgpu/struct.BufferView.html

Shows how to get the first element of a slice with `first`, returning `Option<&T>`. Includes a non-empty and an empty slice example.

```rust
let v = [10, 40, 30];
assert_eq!(Some(&10), v.first());

let w: &[i32] = &[];
assert_eq!(None, w.first());
```

--------------------------------

### starts_with example: check if slice starts with a prefix

Source: https://docs.rs/wgpu/latest/wgpu/struct.BufferView.html

Returns true if the slice starts with the given needle or is equal to it. Always returns true for an empty needle.

```rust
let v = [10, 40, 30];
assert!(v.starts_with(&[10]));
assert!(v.starts_with(&[10, 40]));
assert!(v.starts_with(&v));
assert!(!v.starts_with(&[50]));
assert!(!v.starts_with(&[10, 50]));
```

--------------------------------

### Instance::from_custom

Source: https://docs.rs/wgpu/latest/src/wgpu/api/instance.rs.html?search=std%3A%3Avec

Documentation for the `Instance::from_custom` method, which creates a wgpu `Instance` from a custom backend implementation.

```APIDOC
## Instance::from_custom

### Description
Creates an instance from a custom context implementation. This method is available when the `custom` feature is enabled.

### Method
`from_custom`

### Signature
```rust
pub fn from_custom<T: InstanceInterface>(instance: T) -> Self
```

### Parameters
- `T` (type parameter) - The custom instance interface type.
- `instance` (`T`) - The custom instance implementation.

### Returns
- `Self` - A new `Instance` using the custom backend.
```

--------------------------------

### initialize_adapter_from_env_or_default

Source: https://docs.rs/wgpu/latest/src/wgpu/util/init.rs.html

Initializes an adapter using the WGPU_ADAPTER_NAME environment variable if set, otherwise falls back to requesting a default adapter from the instance.

```APIDOC
## initialize_adapter_from_env_or_default

### Description
Initializes an adapter using the `WGPU_ADAPTER_NAME` environment variable if set, otherwise falls back to requesting a default adapter from the instance.

### Function Signature
```rust
pub async fn initialize_adapter_from_env_or_default(
    instance: &Instance,
    compatible_surface: Option<&Surface<'_>>,
) -> Result<Adapter, wgt::RequestAdapterError>
```

### Parameters
- **instance** (`&Instance`) - Required - The wgpu instance to use for adapter enumeration and default adapter request.
- **compatible_surface** (`Option<&Surface<'_>>`) - Optional - A surface that the adapter must be compatible with. Passed to both the environment-based initialization and the default adapter request.

### Behavior
- Attempts to initialize an adapter using `initialize_adapter_from_env`.
- If that fails, requests a default adapter using `instance.request_adapter` with a `RequestAdapterOptions` that includes the compatible surface and a power preference from the environment (or default).

### Return Value
- `Result<Adapter, wgt::RequestAdapterError>` - The selected adapter on success, or an error if both methods fail.
```

--------------------------------

### unwrap_or_default example

Source: https://docs.rs/wgpu/latest/wgpu/type.Label.html

Shows how to use unwrap_or_default to get the contained value or a default for the type.

```rust
assert_eq!(x.unwrap_or_default(), 0);
assert_eq!(y.unwrap_or_default(), 12);
```

--------------------------------

### Instance::default

Source: https://docs.rs/wgpu/latest/src/wgpu/api/instance.rs.html

Creates a new wgpu instance with default options, setting backends to all and FXC as the DX12 shader compiler.

```APIDOC
## Instance::default

### Description
Creates a new instance of wgpu with default options. Backends are set to `Backends::all()`, and FXC is chosen as the `dx12_shader_compiler`.

### Method
`fn default() -> Self`

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

### Returns
- `Self` - A new `Instance` object with default options.

### Example
```rust
let instance = Instance::default();
```
```

--------------------------------

### unwrap example

Source: https://docs.rs/wgpu/latest/wgpu/type.Label.html

Shows how to use Option::unwrap to get the contained Some value, panicking if None.

```rust
let x = Some("air");
assert_eq!(x.unwrap(), "air");
```

--------------------------------

### Instance::from_custom

Source: https://docs.rs/wgpu/latest/src/wgpu/api/instance.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Creates a wgpu Instance from a custom context implementation, enabling interop with custom backends.

```APIDOC
## Instance::from_custom

### Description
Creates a wgpu Instance from a custom context implementation, enabling interop with custom backends.

### Method
`pub fn from_custom<T: InstanceInterface>(instance: T) -> Self`

### Parameters
- `instance` (`T`) - The custom instance implementation.

### Return Value
- `Self` - A new wgpu `Instance`.
```

--------------------------------

### Instance::from_core

Source: https://docs.rs/wgpu/latest/src/wgpu/api/instance.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Creates a wgpu Instance from a wgpu-core instance, enabling interop with wgpu-core.

```APIDOC
## Instance::from_core

### Description
Creates a new wgpu Instance from a wgpu-core instance, enabling interop with wgpu-core.

### Method
`pub unsafe fn from_core(core_instance: wgc::instance::Instance) -> Self`

### Parameters
- `core_instance` (`wgc::instance::Instance`) - The wgpu-core instance to wrap.

### Return Value
- `Self` - A new wgpu `Instance`.

### Safety
Refer to the creation of wgpu-core Instance.
```

--------------------------------

### expect example

Source: https://docs.rs/wgpu/latest/wgpu/type.Label.html

Shows how to use Option::expect to get the contained Some value, panicking with a custom message if None.

```rust
let x = Some("value");
assert_eq!(x.expect("fruits are healthy"), "value");
```

--------------------------------

### is_full_resource usage example

Source: https://docs.rs/wgpu/latest/wgpu/struct.ImageSubresourceRange.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Example demonstrating the is_full_resource method with various ranges, showing true for full resource and false for partial.

```rust
let range_none = wgpu::ImageSubresourceRange {
    aspect: wgpu::TextureAspect::All,
    base_mip_level: 0,
    mip_level_count: None,
    base_array_layer: 0,
    array_layer_count: None,
};
assert_eq!(range_none.is_full_resource(wgpu::TextureFormat::Stencil8, 5, 10), true);

let range_some = wgpu::ImageSubresourceRange {
    aspect: wgpu::TextureAspect::All,
    base_mip_level: 0,
    mip_level_count: Some(5),
    base_array_layer: 0,
    array_layer_count: Some(10),
};
assert_eq!(range_some.is_full_resource(wgpu::TextureFormat::Stencil8, 5, 10), true);

let range_mixed = wgpu::ImageSubresourceRange {
    aspect: wgpu::TextureAspect::StencilOnly,
    base_mip_level: 0,
    // Only partial resource
    mip_level_count: Some(3),
    base_array_layer: 0,
    array_layer_count: None,
};
assert_eq!(range_mixed.is_full_resource(wgpu::TextureFormat::Stencil8, 5, 10), false);
```

--------------------------------

### as_ptr() example

Source: https://docs.rs/wgpu/latest/wgpu/struct.BufferView.html

Demonstrates `as_ptr` to get a raw pointer to the slice's buffer, with an unsafe loop to iterate over elements.

```rust
let x = &[1, 2, 4];
let x_ptr = x.as_ptr();

unsafe {
    for i in 0..x.len() {
        assert_eq!(x.get_unchecked(i), &*x_ptr.add(i));
    }
}
```

--------------------------------

### last_chunk() example

Source: https://docs.rs/wgpu/latest/wgpu/struct.BufferView.html

Shows `last_chunk` to get an array reference to the last N items, returning `None` if the slice is too short.

```rust
let u = [10, 40, 30];
assert_eq!(Some(&[40, 30]), u.last_chunk::<2>());

let v: &[i32] = &[10];
assert_eq!(None, v.last_chunk::<2>());

let w: &[i32] = &[];
assert_eq!(Some(&[]), w.last_chunk::<0>());
```

--------------------------------

### wgpu util/mod.rs source with DownloadBuffer and pipeline_cache_key example

Source: https://docs.rs/wgpu/latest/src/wgpu/util/mod.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

The full source of wgpu's util/mod.rs, including the DownloadBuffer utility and the pipeline_cache_key documentation example. The DownloadBuffer::read_buffer method requires the source buffer to have COPY_SRC usage and a slice size multiple of 4; it copies to a staging buffer and invokes the callback asynchronously, requiring repeated Device::poll() calls if no further work is submitted. The pipeline_cache_key example shows how to build a cache file path from the adapter info, treating any read failure as lost data.

```rust
//! Utility structures and functions that are built on top of the main `wgpu` API.
//!
//! Nothing in this module is a part of the WebGPU API specification;
//! they are unique to the `wgpu` library.

// TODO: For [`belt::StagingBelt`] to be available in `no_std` its usage of [`std::sync::mpsc`]
// must be replaced with an appropriate alternative.
#[cfg(std)]
mod belt;
mod device;
mod encoder;
mod init;
mod mutex;
mod panicking;
mod spirv;
mod texture_blitter;

use alloc::{format, string::String};

#[cfg(std)]
pub use belt::StagingBelt;
pub use device::{BufferInitDescriptor, DeviceExt};
pub use encoder::RenderEncoder;
pub use init::*;
pub use spirv::*;
#[cfg(feature = "wgsl")]
pub use texture_blitter::{TextureBlitter, TextureBlitterBuilder};
pub use wgt::{
    math::*, DispatchIndirectArgs, DrawIndexedIndirectArgs, DrawIndirectArgs, TextureDataOrder,
};

pub(crate) use mutex::Mutex;
pub(crate) use panicking::is_panicking;

use crate::BufferUsages;

/// CPU-accessible buffer used to retrieve data from buffers that cannot or must not be mapped.
///
/// This utility is a convenience wrapper around creating and mapping a temporary
/// [`Buffer`][crate::Buffer].
#[derive(Debug)]
pub struct DownloadBuffer {
    view: crate::BufferView,
}

impl DownloadBuffer {
    /// Asynchronously read the contents of a buffer by copying it to a staging buffer.
    ///
    /// `buffer_slice`’s buffer must have been created with [`BufferUsages::COPY_SRC`].
    /// The slice’s size must be a multiple of 4.
    ///
    /// `callback` will be called when the data is available.
    /// If you are not submitting further work, you must call
    /// [`Device::poll()`][crate::Device::poll] repeatedly until the callback completes.
    pub fn read_buffer(
        device: &super::Device,
        queue: &super::Queue,
        buffer_slice: &super::BufferSlice<'_>,
        callback: impl FnOnce(Result<Self, super::BufferAsyncError>) + Send + 'static,
    ) {
        let size = buffer_slice.size;

        let temporary_buffer = device.create_buffer(&super::BufferDescriptor {
            size,
            usage: BufferUsages::COPY_DST | BufferUsages::MAP_READ,
            mapped_at_creation: false,
            label: None,
        });

        let mut encoder =
            device.create_command_encoder(&super::CommandEncoderDescriptor { label: None });
        encoder.copy_buffer_to_buffer(
            buffer_slice.buffer,
            buffer_slice.offset,
            &temporary_buffer,
            0,
            size,
        );
        queue.submit([encoder.finish()]);

        temporary_buffer
            .clone()
            .map_async(super::MapMode::Read, .., move |result| {
                if let Err(e) = result {
                    callback(Err(e));
                    return;
                }

                let view = match temporary_buffer.get_mapped_range(0..size) {
                    Ok(range) => range,
                    Err(e) => {
                        callback(Err(super::BufferAsyncError));
                        log::error!("Failed to get mapped range: {e}");
                        return;
                    }
                };
                callback(Ok(Self { view }));
            });
    }
}

impl core::ops::Deref for DownloadBuffer {
    type Target = [u8];
    fn deref(&self) -> &[u8] {
        &self.view
    }
}

/// A recommended key for storing [`PipelineCache`]s for the adapter
/// associated with the given [`AdapterInfo`](wgt::AdapterInfo)
/// This key will define a class of adapters for which the same cache
/// might be valid.
///
/// If this returns `None`, the adapter doesn't support [`PipelineCache`].
/// This may be because the API doesn't support application managed caches
/// (such as browser WebGPU), or that `wgpu` hasn't implemented it for
/// that API yet.
///
/// This key could be used as a filename, as seen in the example below.
///
/// # Examples
///
/// ```no_run
/// # use std::path::PathBuf;
/// use wgpu::PipelineCacheDescriptor;
/// # let adapter_info = todo!();
/// # let device: wgpu::Device = todo!();
/// let cache_dir: PathBuf = unimplemented!("Some reasonable platform-specific cache directory for your app.");
/// let filename = wgpu::util::pipeline_cache_key(&adapter_info);
/// let (pipeline_cache, cache_file) = if let Some(filename) = filename {
///     let cache_path = cache_dir.join(&filename);
///     // If we failed to read the cache, for whatever reason, treat the data as lost.

```

--------------------------------

### first_chunk() example

Source: https://docs.rs/wgpu/latest/wgpu/struct.BufferView.html

Demonstrates `first_chunk` to get an array reference to the first N items, returning `None` if the slice is too short.

```rust
let u = [10, 40, 30];
assert_eq!(Some(&[10, 40]), u.first_chunk::<2>());

let v: &[i32] = &[10];
assert_eq!(None, v.first_chunk::<2>());

let w: &[i32] = &[];
assert_eq!(Some(&[]), w.first_chunk::<0>());
```

--------------------------------

### Instance::new constructor with backend selection

Source: https://docs.rs/wgpu/latest/src/wgpu/api/instance.rs.html?search=std%3A%3Avec

Creates a new `Instance` using the given options and enabled backends. Panics if no backend feature for the active target platform is enabled. Selects between WebGPU and wgpu-core backends based on compile-time features and runtime support.

```rust
impl 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()`].
    #[allow(clippy::allow_attributes, unreachable_code)]
    pub fn new(desc: InstanceDescriptor) -> Self {
        if Self::enabled_backend_features().is_empty() {
            panic!(
                "No wgpu backend feature that is implemented for the target platform was enabled. \
                 See `wgpu::Instance::enabled_backend_features()` for more information."
            );
        }

        #[cfg(webgpu)]
        {
            let is_only_available_backend = !cfg!(wgpu_core);
            let requested_webgpu = desc.backends.contains(Backends::BROWSER_WEBGPU);
            let support_webgpu = crate::backend::get_browser_gpu_property()
                .map(|maybe_gpu| maybe_gpu.is_some())
                .unwrap_or(false);

            if is_only_available_backend || (requested_webgpu && support_webgpu) {
                return Self {
                    inner: crate::backend::ContextWebGpu::new(desc).into(),
                };
            }
        }

        #[cfg(wgpu_core)]
        {
            return Self {
                inner: crate::backend::ContextWgpuCore::new(desc).into(),
            };
        }

        // Silence unused variable warnings without adding _ to the parameter name (which shows up in docs).
        let _ = desc;

        unreachable!(
            "Earlier check of `enabled_backend_features` should have prevented getting here!"
        );
    }
```

--------------------------------

### last() example

Source: https://docs.rs/wgpu/latest/wgpu/struct.BufferView.html

Shows how to use the `last` method to get the last element of a slice, returning `None` for empty slices.

```rust
let v = [10, 40, 30];
assert_eq!(Some(&30), v.last());

let w: &[i32] = &[];
assert_eq!(None, w.last());
```

--------------------------------

### ContextWgpuCore methods for HAL instance, adapter, device, and texture creation

Source: https://docs.rs/wgpu/latest/src/wgpu/backend/wgpu_core.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Implements methods on ContextWgpuCore for creating and accessing HAL instances, adapters, buffers, devices, and textures. Includes safety notes for instance_as_hal and create_device_from_hal, and uses a cfg(wgpu_core) attribute for enumerate_adapters.

```rust
60impl ContextWgpuCore {
61    pub unsafe fn from_hal_instance<A: hal::Api>(hal_instance: A::Instance) -> Self {
62        Self(unsafe {
63            Arc::new(wgc::global::Global::from_hal_instance::<A>(
64                "wgpu",
65                hal_instance,
66            ))
67        })
68    }
69
70    /// # Safety
71    ///
72    /// - The raw instance handle returned must not be manually destroyed.
73    pub unsafe fn instance_as_hal<A: hal::Api>(&self) -> Option<&A::Instance> {
74        unsafe { self.0.instance_as_hal::<A>() }
75    }
76
77    pub unsafe fn from_core_instance(core_instance: wgc::instance::Instance) -> Self {
78        Self(unsafe { Arc::new(wgc::global::Global::from_instance(core_instance)) })
79    }
80
81    #[cfg(wgpu_core)]
82    pub fn enumerate_adapters(&self, backends: wgt::Backends) -> Vec<wgc::id::AdapterId> {
83        self.0
84            .enumerate_adapters(backends, false /* no limit bucketing */)
85    }
86
87    pub unsafe fn create_adapter_from_hal<A: hal::Api>(
88        &self,
89        hal_adapter: hal::ExposedAdapter<A>,
90    ) -> wgc::id::AdapterId {
91        unsafe { self.0.create_adapter_from_hal(hal_adapter.into(), None) }
92    }
93
94    pub unsafe fn adapter_as_hal<A: hal::Api>(
95        &self,
96        adapter: &CoreAdapter,
97    ) -> Option<impl Deref<Target = A::Adapter> + WasmNotSendSync> {
98        unsafe { self.0.adapter_as_hal::<A>(adapter.id) }
99    }
100
101    pub unsafe fn buffer_as_hal<A: hal::Api>(
102        &self,
103        buffer: &CoreBuffer,
104    ) -> Option<impl Deref<Target = A::Buffer>> {
105        unsafe { self.0.buffer_as_hal::<A>(buffer.id) }
106    }
107
108    pub unsafe fn create_device_from_hal<A: hal::Api>(
109        &self,
110        adapter: &CoreAdapter,
111        hal_device: hal::OpenDevice<A>,
112        desc: &crate::DeviceDescriptor<'_>,
113    ) -> Result<(CoreDevice, CoreQueue), crate::RequestDeviceError> {
114        let (device_id, queue_id) = unsafe {
115            self.0.create_device_from_hal(
116                adapter.id,
117                hal_device.into(),
118                &desc.map_label(|l| l.map(Borrowed)),
119                None,
120                None,
121            )
122        }?;
123        let error_sink = Arc::new(Mutex::new(ErrorSinkRaw::new()));
124        let device = CoreDevice {
125            context: self.clone(),
126            id: device_id,
127            error_sink: error_sink.clone(),
128            features: desc.required_features,
129        };
130        let queue = CoreQueue {
131            context: self.clone(),
132            id: queue_id,
133            error_sink,
134        };
135        Ok((device, queue))
136    }
137
138    pub unsafe fn create_texture_from_hal<A: hal::Api>(
139        &self,
140        hal_texture: A::Texture,
141        device: &CoreDevice,
142        desc: &TextureDescriptor<'_>,
143        initial_state: wgt::TextureUses,
144    ) -> CoreTexture {
145        let descriptor = desc.map_label_and_view_formats(|l| l.map(Borrowed), |v| v.to_vec());
146        let (id, error) = unsafe {
147            self.0.create_texture_from_hal(
148                Box::new(hal_texture),
149                device.id,
150                &descriptor,
151                initial_state,
152                None,
153            )
154        };
155        if let Some(cause) = error {
```

--------------------------------

### expect recommended message style example

Source: https://docs.rs/wgpu/latest/wgpu/type.Label.html

Shows the recommended style for expect messages, describing why the Option should be Some.

```rust
let item = slice.get(0)
    .expect("slice should not be empty");
```

--------------------------------

### rchunks example

Source: https://docs.rs/wgpu/latest/wgpu/struct.BufferView.html

Shows the rchunks method, which returns an iterator over chunks of a given size starting from the end of the slice. The example uses a slice of characters and chunk size 2, demonstrating that the last chunk may be smaller than the chunk size.

```rust
let slice = ['l', 'o', 'r', 'e', 'm'];
let mut iter = slice.rchunks(2);
assert_eq!(iter.next().unwrap(), &['e', 'm']);
assert_eq!(iter.next().unwrap(), &['o', 'r']);
assert_eq!(iter.next().unwrap(), &['l']);
assert!(iter.next().is_none());
```

--------------------------------

### Instance Methods

Source: https://docs.rs/wgpu/latest/wgpu/struct.Instance.html?search=

Documentation for the Instance struct methods in the wgpu crate.

```APIDOC
## Instance::new

### Description
Creates a new instance of wgpu using the given options and enabled backends.

### Method
`pub fn new(desc: InstanceDescriptor) -> Self`

### Parameters
- `desc` (InstanceDescriptor) - Required - Options for instance creation.

### Panics
- Panics if no backend feature for the active target platform is enabled. See `Instance::enabled_backend_features()`.
```

```APIDOC
## Instance::enabled_backend_features

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

### Method
`pub const fn enabled_backend_features() -> Backends`

### Returns
- `Backends` - The set of backends available based on compile-time information.
```

```APIDOC
## Instance::wgsl_language_features

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

### Method
`pub fn wgsl_language_features(&self) -> WgslLanguageFeatures`

### Availability
- Only available with the `wgsl` crate feature.
```

```APIDOC
## Instance::enumerate_adapters

### Description
Retrieves all available `Adapter`s that match the given `Backends`.

### Method
`pub fn enumerate_adapters(&self, backends: Backends) -> impl Future<Output = Vec<Adapter>>`

### Parameters
- `backends` (Backends) - Required - Backends from which to enumerate adapters.

### Returns
- A future resolving to a vector of `Adapter` objects.
```

```APIDOC
## Instance::request_adapter

### Description
Retrieves an `Adapter` which matches the given `RequestAdapterOptions`. Some options are soft (non-mandatory), others are hard. If no adapters satisfy all hard options, an error is returned.

### Method
`pub fn request_adapter(&self, options: &RequestAdapterOptions<'_, '_>) -> impl Future<Output = Result<Adapter, RequestAdapterError>> + WasmNotSend`

### Parameters
- `options` (RequestAdapterOptions) - Required - Options for adapter selection.

### Returns
- A future resolving to `Result<Adapter, RequestAdapterError>`.

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

```APIDOC
## Instance::create_surface

### Description
Creates a new surface targeting a given window/canvas/surface/etc. Internally creates surfaces for all backends enabled for this instance.

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

### Parameters
- `target` (impl Into<SurfaceTarget>) - Required - The target surface (e.g., window handle).

### Returns
- `Result<Surface<'window>, CreateSurfaceError>`.
```

```APIDOC
## Instance::create_surface_unsafe

### Description
Creates a new surface using an unsafe target variant. Internally creates surfaces for all backends enabled for this instance.

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

### Parameters
- `target` (SurfaceTargetUnsafe) - Required - The unsafe surface target.

### Returns
- `Result<Surface<'window>, CreateSurfaceError>`.

### Safety
- See respective `SurfaceTargetUnsafe` variants for safety requirements.
```

```APIDOC
## Instance::poll_all

### Description
Polls all devices. If `force_wait` is true and not on the web, blocks until all in-flight buffers are mapped and all submitted commands have finished execution.

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

### Parameters
- `force_wait` (bool) - Required - Whether to block until all work is complete.

### Returns
- `bool` - `true` if all devices' queues are empty, `false` if there are queue submissions still in flight.

### Notes
- On the web, this is a no-op; devices are automatically polled.
```

```APIDOC
## Instance::generate_report

### Description
Generates a memory report. Returns `None` if the feature is not supported by the backend (only when WebGPU is pre-selected).

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

### Availability
- Only available with the `wgpu_core` feature.

### Returns
- `Option<GlobalReport>` - The memory report, or `None` if unsupported.
```

--------------------------------

### as_mut_slice example

Source: https://docs.rs/wgpu/latest/wgpu/type.Label.html

Shows how to use Option::as_mut_slice to get a mutable slice of the contained value or an empty mutable slice for None.

```rust
assert_eq!(
    [Some(1234).as_mut_slice(), None.as_mut_slice()],
    [&mut [1234][..], &mut [][..]],
);
```

--------------------------------

### Using pipeline_cache_key to create a pipeline cache file

Source: https://docs.rs/wgpu/latest/src/wgpu/util/mod.rs.html

Shows how to use wgpu::util::pipeline_cache_key to generate a cache key and create a cache file. The example uses a platform-specific cache directory and handles the case where the key is None. It also demonstrates reading the cache file if it exists.

```rust
```no_run
# use std::path::PathBuf;
use wgpu::PipelineCacheDescriptor;
# let adapter_info = todo!();
# let device: wgpu::Device = todo!();
let cache_dir: PathBuf = unimplemented!("Some reasonable platform-specific cache directory for your app.");
let filename = wgpu::util::pipeline_cache_key(&adapter_info);
let (pipeline_cache, cache_file) = if let Some(filename) = filename {
    let cache_path = cache_dir.join(&filename);
    // If we failed to read the cache, for whatever reason, treat the data as lost.
```
```

--------------------------------

### rsplitn example: split slice from the end into at most n subslices

Source: https://docs.rs/wgpu/latest/wgpu/struct.BufferView.html

Splits the slice into at most n subslices starting from the end, using the predicate. The matched element is not included. The last element returned contains the remainder. This example prints groups [50] and [10, 40, 30, 20].

```rust
let v = [10, 40, 30, 20, 60, 50];

for group in v.rsplitn(2, |num| *num % 3 == 0) {
    println!("{group:?}");
}
```

--------------------------------

### initialize_adapter_from_env

Source: https://docs.rs/wgpu/latest/wgpu/util/fn.initialize_adapter_from_env.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Documentation for the initialize_adapter_from_env function, which initializes a WGPU adapter based on the WGPU_ADAPTER_NAME environment variable.

```APIDOC
## initialize_adapter_from_env

### Description
Initializes the adapter obeying the `WGPU_ADAPTER_NAME` environment variable.

### Function Signature
```rust
pub async fn initialize_adapter_from_env(
    instance: &Instance,
    compatible_surface: Option<&Surface<'_>>,
) -> Result<Adapter, RequestAdapterError>
```

### Parameters
- **instance** (`&Instance`) - Required - The WGPU instance to use for adapter initialization.
- **compatible_surface** (`Option<&Surface<'_>>`) - Optional - A surface that the adapter must be compatible with, if provided.

### Return Value
- **Result<Adapter, RequestAdapterError>** - Returns the initialized adapter on success, or a `RequestAdapterError` on failure.

### Availability
- Available on **`wgpu_core`** only.
```

--------------------------------

### as_slice example

Source: https://docs.rs/wgpu/latest/wgpu/type.Label.html

Shows how to use Option::as_slice to get a slice of the contained value or an empty slice for None. Useful for iterating over Option or slice uniformly.

```rust
assert_eq!(
    [Some(1234).as_slice(), None.as_slice()],
    [&[1234][..], &[][..]],
);
```
Tokens:
Raw