Module surface 

Swapchain surfaces: creation, cross-thread hand-off, alpha-mode policy and configuration.

Three types cover the whole life of a swapchain, in the order a shell meets them:

1. SurfaceFactory — a cheap clone of the wgpu::Instance that creates a surface on the thread the windowing backend requires (the main/UI thread on winit/AppKit).
2. DetachedSurface — the created-but-unconfigured surface, opaque and Send, moved to whichever thread owns the renderer.
3. ConfiguredSurface — the surface plus the swapchain configuration it was brought up with, and the one derived answer everything downstream keys off: whether it actually came up translucent (ConfiguredSurface::resolved_translucent).

Every decision this module makes — which composite alpha mode to resolve (resolve_alpha_mode), which swapchain format to pick (select_surface_format), what the configuration should be (surface_config) — is a pure function over plain values, so it is host-testable with neither a GPU nor a window server. Only ConfiguredSurface::configure/ConfiguredSurface::reconfigure/ ConfiguredSurface::resize touch a live device.

Device seam

This module speaks wgpu primitives directly — a &wgpu::Instance to create surfaces from, a &wgpu::Device to configure them against — rather than an owning context type. Anything that pools the instance/adapter/device sits above these entry points and passes its handles in, so nothing here needs to know how that pooling works.

Render-attachment only

The swapchain is configured with RENDER_ATTACHMENT and nothing else: the engine draws the frame through an ordinary render pass, in whichever of SURFACE_FORMATS the platform reports first. There is no compute-storage-write path here, so no surface has to carry STORAGE_BINDING and no surface is pinned to a single format to satisfy a compute target.

Structs

ConfiguredSurface

A configured swapchain surface: the surface itself, the configuration it was brought up with, and whether it actually came up translucent.

DetachedSurface

A created-but-not-yet-configured wgpu::Surface, produced by SurfaceFactory::create_detached_surface on the windowing thread and configured on the render thread.

SurfaceFactory

A cheap, cloneable handle to a wgpu::Instance used to create a surface on a different thread than the one that owns the renderer.

Enums

SurfaceAlphaRequest

What a caller wants of the surface’s alpha, expressed without naming a wgpu type — the public, platform-independent request a shell makes.

Constants

SURFACE_FORMATS

Every swapchain format select_surface_format will configure a surface with — a membership set, not a preference order.

Functions

alpha_mode_is_straight_translucent

Whether a resolved alpha mode means “translucent, and the swapchain stores STRAIGHT alpha” — the combination the engine’s premultiplied output cannot be presented into unconverted.

alpha_mode_is_translucent

Whether a resolved wgpu::CompositeAlphaMode actually composites the surface’s alpha against what is behind it — i.e. whether the surface really came up translucent, as opposed to what the caller requested.

alpha_mode_needs_premultiply

Whether a swapchain configured with this composite alpha mode expects the pixels it is handed to be premultiplied.

compositor_expects_premultiplied

Whether backend’s compositor actually composites mode premultiplied, despite alpha_mode_is_straight_translucent answering true for it — an upstream wgpu-hal truth bug specific to one backend/mode pair, not a property of the mode alone.

resolve_alpha_mode

Resolves a caller’s SurfaceAlphaRequest against the live surface’s reported alpha_modes, choosing the actual wgpu::CompositeAlphaMode to configure with.

select_surface_format

Picks the swapchain format to configure with: the first format the surface reports that is one of SURFACE_FORMATS.

surface_config

Builds the wgpu::SurfaceConfiguration a surface is brought up with.