Struct Surface 

pub struct Surface<'window> { /* private fields */ }

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.

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 display_hdr_info(&self, adapter: &Adapter) -> DisplayHdrInfo

Returns the HDR and luminance characteristics of the display backing this surface, or DisplayHdrInfo::default (all fields None) when nothing is known - which means unknown, not an SDR display. Never panics, including on wasm. See DisplayHdrInfo for the fields and how to use them.

Threading

Each call re-queries the OS; nothing is cached. On the Metal backend the display’s HDR state lives on main-thread-only AppKit objects (NSScreen / NSWindow), so call this from the main thread. Off the main thread it logs once and returns DisplayHdrInfo::default; a later main-thread call still returns real data. No other backend has this requirement.

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.

The returned configuration requests the surface’s preferred format and SurfaceColorSpace::Auto, reproducing wgpu’s historical SDR / standard behavior. Set the color_space field to opt into wide-gamut or HDR output; see SurfaceColorSpace for what each color space means.

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

• An old SurfaceTexture is still alive referencing an old surface.
• Texture format requested is unsupported on the surface.
• The requested color space is unsupported for the requested format (see SurfaceCapabilities::format_capabilities).
• config.width or config.height is zero.

pub fn get_configuration(&self) -> Option<SurfaceConfiguration>

Returns the current configuration of Surface, if configured.

This is similar to WebGPU GPUcCanvasContext::getConfiguration.

Note that this returns the configuration as passed to Surface::configure: automatic values such as SurfaceColorSpace::Auto are returned as-is, not as the concrete values they resolved to.

pub fn get_current_texture(&self) -> CurrentSurfaceTexture

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

After rendering to the returned SurfaceTexture, submit work via Queue::submit and then call Queue::present to display it.

If a SurfaceTexture referencing this surface is alive when Surface::configure() is called, the configure call will panic.

See the documentation of CurrentSurfaceTexture for how each possible result should be handled.

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

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.

Types

The returned type depends on the backend:

• hal::api::Vulkan uses hal::vulkan::Surface
• hal::api::Metal uses hal::metal::Surface
• hal::api::Dx12 uses hal::dx12::Surface
• hal::api::Gles uses hal::gles::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.

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