Struct Surface

pub struct Surface<'window> {
    pub(crate) inner: DispatchSurface,
    pub(crate) config: Mutex<Option<SurfaceConfiguration>>,
    pub(crate) _handle_source: Option<Box<dyn WindowHandle + 'window>>,
}

Handle to a presentable surface.

A Surface represents a platform-specific surface (e.g. a window) onto which rendered images may be presented. A Surface may be created with the function Instance::create_surface.

This type is unique to the Rust API of wgpu. In the WebGPU specification, GPUCanvasContext serves a similar role.

Fields

inner: DispatchSurface

Additional surface data returned by [DynContext::instance_create_surface].

config: Mutex<Option<SurfaceConfiguration>>

_handle_source: Option<Box<dyn WindowHandle + 'window>>

Optionally, keep the source of the handle used for the surface alive.

This is useful for platforms where the surface is created from a window and the surface would become invalid when the window is dropped.

SAFETY: This field must be dropped after all other fields to ensure proper cleanup.

Implementations

impl Surface<'_>

pub fn get_capabilities(&self, adapter: &Adapter) -> SurfaceCapabilities

Returns the capabilities of the surface when used with the given adapter.

Returns specified values (see SurfaceCapabilities) if surface is incompatible with the adapter.

pub fn get_default_config( &self, adapter: &Adapter, width: u32, height: u32, ) -> Option<SurfaceConfiguration>

Return a default SurfaceConfiguration from width and height to use for the Surface with this adapter.

Returns None if the surface isn’t supported by this adapter

pub fn configure(&self, device: &Device, config: &SurfaceConfiguration)

Initializes Surface for presentation.

If the surface is already configured, this will wait for the GPU to come idle before recreating the swapchain to prevent race conditions.

Validation Errors

• Submissions that happen during the configure may cause the internal wait-for-idle to fail, raising a validation error.

Panics

• A old SurfaceTexture is still alive referencing an old surface.
• Texture format requested is unsupported on the surface.
• config.width or config.height is zero.

pub fn get_current_texture(&self) -> Result<SurfaceTexture, SurfaceError>

Returns the next texture to be presented by the swapchain for drawing.

In order to present the SurfaceTexture returned by this method, first a Queue::submit needs to be done with some work rendering to this texture. Then SurfaceTexture::present needs to be called.

If a SurfaceTexture referencing this surface is alive when the swapchain is recreated, recreating the swapchain will panic.

pub unsafe fn as_hal<A: HalApi>( &self, ) -> Option<impl Deref<Target = A::Surface> + WasmNotSendSync>

Available on wgpu_core only.

Get the wgpu_hal surface from this Surface.

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

Errors

This method will return None if:

• The surface is not from the backend specified by A.
• The surface 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 fn as_custom<T: SurfaceInterface>(&self) -> Option<&T>

Available on custom only.

Returns custom implementation of Surface (if custom backend and is internally T)

Trait Implementations

impl Debug for Surface<'_>

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

Formats the value using the given formatter.

impl Hash for Surface<'_>

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

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 Surface<'_>

fn cmp(&self, other: &Self) -> 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 Surface<'_>

fn eq(&self, other: &Self) -> 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 Surface<'_>

fn partial_cmp(&self, other: &Self) -> 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 Surface<'_>