Struct WgpuBackend 

pub struct WgpuBackend { /* private fields */ }

GPU-based rendering backend.

Creates a wgpu device and surface from a platform-provided Metal layer (macOS) or window handle. Implements RenderBackend by accumulating geometry per frame, then flushing it in present().

Implementations

impl WgpuBackend

pub fn from_surface( instance: &Instance, surface: Surface<'static>, logical_w: u32, logical_h: u32, scale: f32, ) -> Option<Self>

Create a GPU backend from a pre-created wgpu surface.

logical_w and logical_h are in logical points. scale is the display scale factor (2.0 on Retina). The surface is configured at logical × scale physical pixels.

Panics

Panics if the embedded font fails to parse (a bug in the bundled font asset, never user input).

pub fn pump_init( adapter: &Adapter, surface: &Surface<'static>, logical_w: u32, logical_h: u32, scale: f32, ) -> Option<(Self, Device, SurfaceConfiguration)>

Device + surface-configuration selection given an adapter, for a surface the backend does NOT take ownership of. Used by Self::from_surface (which then attaches the surface) and by crate::pump::SurfacePump init closures, where the surface stays with the pump: acquire / configure / present route through the pump’s client, which on Windows runs them on the pump thread instead of the host’s GUI thread. Pump users call Self::set_pump with the pump’s client after adopting the backend. Does not configure the surface.

pub fn set_pump(&mut self, client: PumpClient)

Attach the pump client the backend’s acquire / configure / present calls route through. Pair of Self::pump_init.

pub fn new( device: Arc<Device>, queue: Arc<Queue>, target_format: TextureFormat, max_logical_w: u32, max_logical_h: u32, scale: f32, ) -> Option<Self>

Build a standalone WgpuBackend that records into encoders supplied per-frame by the caller.

Unlike Self::from_surface / from_metal_layer / the pump path (Self::pump_init), this constructor does not own or reach a wgpu::Surface or manage frame acquisition. The caller is expected to have its own render loop, allocate command encoders, and present - this backend only supplies the 2D widget pipeline, glyph atlas, and lyon-tessellated primitive recording.

Usage:

let mut backend = WgpuBackend::new(
    device.clone(), queue.clone(),
    target_format, max_w, max_h,
).expect("backend init");

// per-frame, after the caller has drawn its own content into `view`:
backend.begin_frame(w, h);
truce_gui::widgets::draw(&mut backend, &layout, &theme, &snap, &mut state);
backend.finish(&mut encoder, &view);
// caller submits encoder + presents.

max_logical_w / max_logical_h are in logical points; scale is the display scale factor (2.0 on Retina, 1.0 otherwise). The MSAA texture is seeded at logical × scale physical pixels; if a subsequent begin_frame(logical_w, logical_h) exceeds the seed, the MSAA texture is reallocated transparently.

Matches the coordinate contract of Self::from_surface: draw calls and event coordinates are logical points; the backend multiplies by scale internally when rasterizing.

Panics

Panics if the embedded font fails to parse (bundled-asset bug, never user input).

pub fn begin_frame(&mut self, logical_w: u32, logical_h: u32)

Prepare for recording a frame of logical_w × logical_h logical points. The MSAA target and ortho matrix are sized at logical × self.scale() physical pixels; widget draw calls use logical coordinates.

Resets accumulated geometry and the clear flag. Rebuilds the MSAA texture if the physical size differs from the previous frame.

Only meaningful when the backend was built via Self::new; the surface-owning constructors drive their own frame lifecycle.

pub fn scale(&self) -> f32

Display scale factor: logical × scale = physical. Callers sizing sibling GPU resources (e.g. an intermediate texture that the backend will resolve into) should use this to stay consistent with the backend’s raster dimensions.

pub fn set_scale(&mut self, scale: f32)

Update the display scale factor. The next Self::resize (or Self::begin_frame in headless mode) recomputes physical dimensions and reconfigures the surface / MSAA target. Callers driving a windowed surface should follow with a resize so the surface_config picks up the new size on the same frame; the short-circuit in resize doesn’t trigger because the scale change makes the new physical dims differ from the old.

pub fn finish(&mut self, encoder: &mut CommandEncoder, view: &TextureView)

Flush accumulated geometry into a single render pass on view, recorded into encoder. The caller retains ownership of both - this method neither submits the encoder nor calls present().

If clear() was called since the last begin_frame, the pass uses LoadOp::Clear(clear_color); otherwise LoadOp::Load so any prior content in view is preserved (the common case when widgets overlay a custom render).

pub fn acquire_wait(&self) -> Duration

How long the last present blocked in the swapchain acquire waiting for the compositor to free a frame slot.

pub fn resize(&mut self, logical_w: u32, logical_h: u32) -> bool

Resize the wgpu surface, MSAA texture, and viewport projection.

logical_w and logical_h are in logical points (same coordinate space as BuiltinEditor::size()). Returns true if the surface was actually reconfigured.

impl WgpuBackend

pub fn headless(width: u32, height: u32, scale: f32) -> Option<Self>

Create a headless GPU backend (no window or surface). Used for snapshot testing.

Panics

Panics if the embedded font fails to parse (bundled-asset bug, never user input).

pub fn read_pixels(&mut self) -> Vec<u8>

Render to an offscreen texture and read back RGBA pixels. Only works for headless backends (no surface).

Panics

Panics if wgpu::Buffer::map_async reports failure when reading back the GPU readback buffer - that indicates an adapter / driver fault rather than a recoverable runtime condition, so the snapshot path bubbles it up rather than papering over it.

Trait Implementations

impl RenderBackend for WgpuBackend

All RenderBackend methods accept coordinates in logical points. The backend multiplies by self.scale to get physical pixel positions. Font glyphs are rasterized at physical resolution for sharp text.

fn clear(&mut self, color: Color)

Clear the entire surface with a solid color.

fn fill_rect(&mut self, x: f32, y: f32, w: f32, h: f32, color: Color)

Fill a rectangle.

fn fill_circle(&mut self, cx: f32, cy: f32, radius: f32, color: Color)

Fill a circle.

fn stroke_circle( &mut self, cx: f32, cy: f32, radius: f32, color: Color, width: f32, )

Stroke a circle outline.

fn stroke_arc( &mut self, cx: f32, cy: f32, radius: f32, start_angle: f32, end_angle: f32, color: Color, width: f32, )

Stroke an arc (portion of a circle).

fn draw_line( &mut self, x1: f32, y1: f32, x2: f32, y2: f32, color: Color, width: f32, )

Draw a line between two points.

fn draw_text(&mut self, text: &str, x: f32, y: f32, size: f32, color: Color)

Draw text using the embedded TrueType font (skrifa, via truce_font::raster).

fn text_width(&self, text: &str, size: f32) -> f32

Measure the width of a text string in logical points, at the given logical-point font size.

fn register_image(&mut self, rgba: &[u8], width: u32, height: u32) -> ImageId

Register an RGBA8 image (premultiplied alpha, row-major, tightly packed).

fn unregister_image(&mut self, id: ImageId)

Remove a previously-registered image. No-op if the id is invalid or already unregistered.

fn draw_image(&mut self, id: ImageId, x: f32, y: f32, w: f32, h: f32)

Draw a previously-registered image at (x, y) sized w × h.

fn present(&mut self)

Flush rendering to the display surface.