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 usage guaranteed to be supported is [TextureUsages::RENDER_ATTACHMENT].

format: TextureFormat

The texture format of the swap chain. The only formats that are guaranteed are [TextureFormat::Bgra8Unorm] and [TextureFormat::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 monitor refreshes between a Surface::get_current_texture call and the texture being presented to the screen. This is sometimes called “Frames in Flight”.

Defaults to 2 when created via Surface::get_default_config as this is a reasonable default.

This is ultimately a hint to the backend implementation and will always be clamped to the supported range.

Typical values are 1 to 3, but higher values are valid, though likely to be clamped.

• Choose 1 to minimize latency above all else. This only gives a single monitor refresh for all of the CPU and GPU work to complete. ⚠️ As a result of these short swapchains, the CPU and GPU cannot run in parallel, prioritizing latency over throughput. For applications like GUIs doing a small amount of GPU work each frame that need low latency, this is a reasonable choice.
• Choose 2 for a balance between latency and throughput. The CPU and GPU both can each use a full monitor refresh to do their computations. This is a reasonable default for most applications.
• Choose 3 or higher to maximize throughput, sacrificing latency when the the CPU and GPU are using less than a full monitor refresh each. For applications that use CPU-side pipelining of frames this may be a reasonable choice. ⚠️ On 60hz displays the latency can be very noticeable.

This maps to the backend in the following ways:

• Vulkan: Number of frames in the swapchain is desired_maximum_frame_latency + 1, clamped to the supported range.
• DX12: Calls IDXGISwapChain2::SetMaximumFrameLatency(desired_maximum_frame_latency).
• Metal: Sets the maximumDrawableCount of the underlying CAMetalLayer to desired_maximum_frame_latency + 1, clamped to the supported range.
• OpenGL: Ignored

It also has various subtle interactions with various present modes and APIs.

• DX12 + Mailbox: Limits framerate to desired_maximum_frame_latency * Monitor Hz fps.
• Vulkan/Metal + Mailbox: If this is set to 2, limits framerate to 2 * Monitor Hz fps. 3 or higher is unlimited.

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 Texture::create_view on the texture returned by Surface::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)