Type Alias SurfaceConfiguration

pub type SurfaceConfiguration = SurfaceConfiguration<Vec<TextureFormat>>;

Describes a Surface.

For use with Surface::configure.

Corresponds to WebGPU GPUCanvasConfiguration.

Aliased Type

struct SurfaceConfiguration {
    pub usage: TextureUsages,
    pub format: TextureFormat,
    pub width: u32,
    pub height: u32,
    pub present_mode: PresentMode,
    pub desired_maximum_frame_latency: u32,
    pub alpha_mode: CompositeAlphaMode,
    pub view_formats: Vec<TextureFormat>,
}

Fields

usage: TextureUsages

The usage of the swap chain. The only supported usage is RENDER_ATTACHMENT.

format: TextureFormat

The texture format of the swap chain. The only formats that are guaranteed are Bgra8Unorm and Bgra8UnormSrgb

width: u32

Width of the swap chain. Must be the same size as the surface, and nonzero.

If this is not the same size as the underlying surface (e.g. if it is set once, and the window is later resized), the behaviour is defined but platform-specific, and may change in the future (currently macOS scales the surface, other platforms may do something else).

height: u32

Height of the swap chain. Must be the same size as the surface, and nonzero.

If this is not the same size as the underlying surface (e.g. if it is set once, and the window is later resized), the behaviour is defined but platform-specific, and may change in the future (currently macOS scales the surface, other platforms may do something else).

present_mode: PresentMode

Presentation mode of the swap chain. Fifo is the only mode guaranteed to be supported. FifoRelaxed, Immediate, and Mailbox will crash if unsupported, while AutoVsync and AutoNoVsync will gracefully do a designed sets of fallbacks if their primary modes are unsupported.

desired_maximum_frame_latency: u32

Desired maximum number of frames that the presentation engine should queue in advance.

This is a hint to the backend implementation and will always be clamped to the supported range. As a consequence, either the maximum frame latency is set directly on the swap chain, or waits on present are scheduled to avoid exceeding the maximum frame latency if supported, or the swap chain size is set to (max-latency + 1).

Defaults to 2 when created via wgpu::Surface::get_default_config.

Typical values range from 3 to 1, but higher values are possible:

• Choose 2 or higher for potentially smoother frame display, as it allows to be at least one frame to be queued up. This typically avoids starving the GPU’s work queue. Higher values are useful for achieving a constant flow of frames to the display under varying load.
• Choose 1 for low latency from frame recording to frame display. ⚠️ If the backend does not support waiting on present, this will cause the CPU to wait for the GPU to finish all work related to the previous frame when calling wgpu::Surface::get_current_texture, causing CPU-GPU serialization (i.e. when wgpu::Surface::get_current_texture returns, the GPU might be idle). It is currently not possible to query this. See https://github.com/gfx-rs/wgpu/issues/2869.
• A value of 0 is generally not supported and always clamped to a higher value.

alpha_mode: CompositeAlphaMode

Specifies how the alpha channel of the textures should be handled during compositing.

view_formats: Vec<TextureFormat>

Specifies what view formats will be allowed when calling create_view() on texture returned by get_current_texture().

View formats of the same format as the texture are always allowed.

Note: currently, only the srgb-ness is allowed to change. (ex: Rgba8Unorm texture + Rgba8UnormSrgb view)