Struct WgpuGfxCtx 

pub struct WgpuGfxCtx { /* private fields */ }

A DrawCtx that renders via wgpu (Vulkan / DX12 / Metal / WebGL2).

Create with WgpuGfxCtx::new, passing a wgpu::Device and wgpu::Queue that were obtained by the platform shell. Each frame: call render_app_frame (which calls reset and app.paint(ctx)), then call end_frame with the current surface texture view to flush all deferred draw commands.

Implementations

impl WgpuGfxCtx

pub fn set_surface_texture(&mut self, tex: Texture)

Stash a handle to the current frame’s surface texture so a later Self::read_screenshot / capture_screenshot call can copy from it. Called from the platform shell with frame.texture.clone() BEFORE begin_frame. wgpu::Texture is internally ref-counted, so the clone is cheap — but it is a live reference to the swap-chain back buffer, so the frame MUST then be presented through Self::present (or the stash dropped with Self::release_frame_texture), never via a bare SurfaceTexture::present().

If the previous frame’s texture is still stashed (the shell never released it), this logs a one-time log::warn! per ctx, since that is the pattern that breaks DX12 swap-chain resize.

pub fn release_frame_texture(&mut self)

Release the ctx’s per-frame handles: the Self::set_surface_texture stash and the begin_frame view if end_frame did not already consume it.

Self::present calls this for you — including when the stash is an SSAA / scene texture rather than the surface itself. Call it directly only from shells that do not present a frame at all (e.g. a frame abandoned mid-way or an offscreen-only render). Screenshot read-back must happen before this — afterwards Self::read_screenshot returns an empty buffer.

pub fn present(&mut self, frame: SurfaceTexture)

Present frame, first releasing the ctx’s per-frame handles (see Self::release_frame_texture).

This is THE way to present whenever the ctx was given the frame’s surface texture (via Self::set_surface_texture or begin_frame). On Windows/DX12 a clone of the back buffer that outlives present() keeps the swap chain referenced, so the next Surface::configure (DXGI ResizeBuffers) fails with “Invalid surface” and recreating the swap chain fails with E_ACCESSDENIED. Do any Self::read_screenshot before calling.

pub fn set_pending_screenshot(&mut self, captured: (Vec<u8>, u32, u32))

Stash captured screenshot pixels for the read-back closure to pick up. See Self::take_pending_screenshot.

pub fn take_pending_screenshot(&mut self) -> (Vec<u8>, u32, u32)

Consume the pending screenshot pixels — returns (Vec::new(), 0, 0) when none are stashed (typical non-capture frames). Called by the agg_gui::screenshot::run_frame_with_capture read-back closure.

pub fn read_screenshot(&self) -> (Vec<u8>, u32, u32)

Read the current frame’s rendered pixels back to CPU memory as a top-down RGBA8 buffer. Returns (pixels, width, height). The first width * 4 bytes are the TOP row (Y-down image order).

Must be called AFTER Self::end_frame has submitted the render and BEFORE the platform shell calls Self::present (which releases the stashed texture). Requires the platform shell to have called Self::set_surface_texture earlier in the frame so we hold a handle into the surface that’s still valid post-render.

Returns an empty buffer if no surface texture is currently stashed (including after Self::present / Self::release_frame_texture).

impl WgpuGfxCtx

pub fn has_pending_readback(&self) -> bool

Whether a capture readback is already in flight.

pub fn begin_capture_readback(&mut self) -> bool

Kick off an async readback of the current capture texture. Returns false if nothing is captured or a readback is already in flight. Pure GPU submit + map_async; never blocks.

pub fn poll_capture_readback(&mut self) -> Option<(Vec<u8>, u32, u32)>

Harvest a completed readback’s pixels, or None if still pending / none in flight. Never blocks: on the web the map resolves on a later event loop turn; the cheap non-blocking poll keeps native progressing too.

impl WgpuGfxCtx

pub fn has_pending_scaled_readback(&self) -> bool

Whether a scaled capture readback is already in flight. Independent of Self::has_pending_readback, which tracks the full-surface one.

pub fn begin_capture_readback_scaled( &mut self, src_region: Option<RectInPixels>, dst_w: u32, dst_h: u32, ) -> bool

Kick off an async readback of a scaled (and optionally cropped) copy of the current capture texture.

src_region is in framebuffer pixels (top-down, see RectInPixels) and is clamped to the surface; None means the whole surface. The result is resampled to dst_w x dst_h with linear filtering, so the caller controls the readback cost directly: only dst_w * dst_h * 4 bytes ever cross back to the CPU.

Returns false — queueing nothing — when there is nothing to capture: no capture texture (call DrawCtx::capture_screenshot first), a zero-sized output, an empty or entirely off-surface region, or a scaled readback already in flight. Same “nothing captured” signal as Self::begin_capture_readback.

Pure GPU submit + map_async; never blocks. Harvest with Self::poll_capture_readback_scaled.

pub fn poll_capture_readback_scaled(&mut self) -> Option<(Vec<u8>, u32, u32)>

Harvest a completed scaled readback’s pixels as tight top-row-first RGBA8, or None if still pending / none in flight. Never blocks.

Unlike Self::poll_capture_readback there is no per-pixel swizzle here — the blit already produced RGBA in the surface’s own byte encoding — so the only CPU work is stripping the row padding.

impl WgpuGfxCtx

pub fn new( device: Arc<Device>, queue: Arc<Queue>, surface_format: TextureFormat, width: f32, height: f32, ) -> Self

Create a new WgpuGfxCtx.

device and queue must come from a wgpu::Adapter whose surface is already configured with surface_format. The caller retains ownership of the surface; this struct only receives Arc refs to the device and queue so both it and the platform shell can drive buffer writes and texture uploads on the same queue.

pub fn last_end_frame_stats(&self) -> LastEndFrameStats

Wall-clock breakdown of the most recent end_frame flush. Returns zeroes until the first frame has been flushed. Designed for live perf HUDs in platform shells — see atomartist’s record_frame_timings for an example consumer.

pub fn reset(&mut self, width: f32, height: f32)

Reset drawing state for a new frame. Preserves GPU resources.

pub fn set_lcd_mode(&mut self, on: bool)

Enable / disable LCD subpixel text for this context. Called each frame from render_app_frame with font_settings::lcd_enabled().

pub fn begin_frame(&mut self, view: TextureView)

Start a frame: take ownership of this frame’s render target and queue the clear.

view is the wgpu::TextureView for the surface texture (or any other target) being painted this frame. It is stashed on the context so that mid-frame GPU work — custom render passes, layer compositing — targets the same attachment as the deferred 2-D pipeline without the caller plumbing it through every method; Self::end_frame consumes it.

The clear itself happens inside end_frame, when the leading DrawCommand::Clear is flushed into the first render pass; this method only pushes the current theme’s background colour onto the command list so the frame starts from a clean framebuffer.

pub fn end_frame(&mut self)

Flush all deferred draw commands into a single wgpu command submission.

Must be called after the frame’s painting and before Self::present. The render target was stashed by Self::begin_frame — the platform shell does not need to pass it again here.

pub fn pipelines(&self) -> &WgpuPipelines

Borrow the shared 2-D pipeline collection. Exposed so platform shells (currently demo-wasm) can drive a SsaaFramebuffer::blit_to when they need to composite an intermediate scene texture onto the real swap-chain surface — see the comment on SsaaFramebuffer::resolve_texture for the WebGL2 scene-buffer pattern. The returned &WgpuPipelines only exposes the fields pub(crate) library code already uses; external callers can pass it back into other library APIs but cannot reach in directly.

pub fn device(&self) -> &Arc<Device>

Borrow a clone-able handle to the wgpu device used for resource allocation. Exposed alongside Self::pipelines so platform shells driving an external blit pass (currently demo-wasm’s scene-buffer → surface composite) don’t need to hold a duplicate Arc<wgpu::Device> themselves.

pub fn queue(&self) -> &Arc<Queue>

Borrow a clone-able handle to the wgpu queue. Same rationale as Self::device — the shell submits the scene-blit encoder through this queue.

pub fn surface_format(&self) -> TextureFormat

Format of the render target this context was configured for. Custom renderers need it to build pipelines whose ColorTargetState matches the surface they will be composited onto.

pub fn push_custom_render( &mut self, renderer: SharedCustomRenderer, screen_rect: Rect, )

Queue a custom wgpu render pass to run at the current point in the frame’s draw order. The user-supplied WgpuCustomRender is invoked from end_frame after the active 2-D pass closes; subsequent 2-D content reopens with LoadOp::Load so it composites on top.

screen_rect is the widget’s logical-pixel rect in agg-gui Y-up coords. The implementor receives it via WgpuCustomRenderCtx::screen_rect and is responsible for any scissor / viewport conversions to wgpu’s Y-down convention.

Trait Implementations

impl DrawCtx for WgpuGfxCtx

fn as_any_mut(&mut self) -> Option<&mut dyn Any>

Optional escape hatch for widgets that need direct access to a backend-specific concrete context (e.g. to push a custom GPU draw command into the deferred command stream).

fn set_fill_color(&mut self, c: Color)

fn set_fill_linear_gradient(&mut self, gradient: LinearGradientPaint)

fn supports_fill_linear_gradient(&self) -> bool

fn set_fill_radial_gradient(&mut self, gradient: RadialGradientPaint)

fn supports_fill_radial_gradient(&self) -> bool

fn set_stroke_color(&mut self, c: Color)

fn set_stroke_linear_gradient(&mut self, gradient: LinearGradientPaint)

fn supports_stroke_linear_gradient(&self) -> bool

fn set_stroke_radial_gradient(&mut self, gradient: RadialGradientPaint)

fn supports_stroke_radial_gradient(&self) -> bool

fn set_line_width(&mut self, w: f64)

fn set_line_join(&mut self, j: LineJoin)

fn set_line_cap(&mut self, c: LineCap)

fn set_miter_limit(&mut self, limit: f64)

fn set_line_dash(&mut self, dashes: &[f64], offset: f64)

fn set_blend_mode(&mut self, _mode: CompOp)

fn set_global_alpha(&mut self, a: f64)

fn set_fill_rule(&mut self, rule: FillRule)

fn set_font(&mut self, font: Arc<Font>)

fn set_font_size(&mut self, size: f64)

fn clip_rect(&mut self, x: f64, y: f64, w: f64, h: f64)

fn reset_clip(&mut self)

fn clip_path(&mut self)

Intersect the clip with the current path (canvas-2D clip()), using the current fill rule.

fn supports_clip_path(&self) -> bool

True when DrawCtx::clip_path actually masks by the current path. false means the call is a no-op on this backend.

fn clear(&mut self, color: Color)

Fill the entire render target with color, ignoring the current clip.

fn begin_path(&mut self)

fn move_to(&mut self, x: f64, y: f64)

fn line_to(&mut self, x: f64, y: f64)

fn cubic_to(&mut self, cx1: f64, cy1: f64, cx2: f64, cy2: f64, x: f64, y: f64)

fn quad_to(&mut self, cx: f64, cy: f64, x: f64, y: f64)

fn arc_to( &mut self, cx: f64, cy: f64, r: f64, start_angle: f64, end_angle: f64, ccw: bool, )

fn circle(&mut self, cx: f64, cy: f64, r: f64)

Add a full circle contour to the current path.

fn rect(&mut self, x: f64, y: f64, w: f64, h: f64)

Add an axis-aligned rectangle contour to the current path.

fn rounded_rect(&mut self, x: f64, y: f64, w: f64, h: f64, r: f64)

Add a rounded-rectangle contour to the current path.

fn close_path(&mut self)

fn fill(&mut self)

fn stroke(&mut self)

fn fill_and_stroke(&mut self)

fn draw_triangles_aa( &mut self, vertices: &[[f32; 3]], indices: &[u32], color: Color, )

Submit pre-tessellated AA triangles with per-vertex coverage (x, y, alpha) and triangle indices.

fn fill_text(&mut self, text: &str, x: f64, y: f64)

Draw text with the bottom of the baseline at (x, y).

fn fill_text_gsv(&mut self, _text: &str, _x: f64, _y: f64, _size: f64)

Do not call this from application code, ever.

fn measure_text(&self, text: &str) -> Option<TextMetrics>

Measure text with the current font and font-size settings.

fn has_image_blit(&self) -> bool

Returns true if this context implements draw_image_rgba with actual pixel blitting. Label (and any other widget that uses a software backbuffer) gates its cache path on this method so it can fall back to direct fill_text() on render targets that don’t support blitting (e.g. the GL path).

fn draw_image_rgba( &mut self, data: &[u8], img_w: u32, img_h: u32, dst_x: f64, dst_y: f64, dst_w: f64, dst_h: f64, )

Draw raw RGBA pixel data into dst_rect (Y-up local coordinates).

fn draw_image_rgba_arc( &mut self, data: &Arc<Vec<u8>>, img_w: u32, img_h: u32, dst_x: f64, dst_y: f64, dst_w: f64, dst_h: f64, )

Same as [draw_image_rgba] but accepts an Arc<Vec<u8>> so the GL backend can key its texture cache on the Arc’s pointer identity and hold a Weak ref for automatic cleanup when the underlying buffer is dropped — the pattern MatterCAD implements with C# ConditionalWeakTable.

fn draw_image_rgba_corners( &mut self, data: &Arc<Vec<u8>>, img_w: u32, img_h: u32, corners: [(f64, f64); 4], )

Blit data as a textured quad whose four destination corners are supplied explicitly. Caller is responsible for choosing the corners (typically the projection of a 3-D rotated card onto the 2-D viewport). corners is ordered bottom-left, bottom-right, top-right, top-left in agg-gui’s Y-up local coordinate space, and is fed through the current CTM the same way axis-aligned blits are.

fn has_lcd_mask_composite(&self) -> bool

Returns true if this backend supports [draw_lcd_mask] — i.e. it can composite per-channel LCD coverage onto the active target. Label queries this to decide between the LCD and grayscale AA paths; a backend that returns false will never see LCD text.

fn draw_lcd_mask( &mut self, mask: &[u8], mask_w: u32, mask_h: u32, src_color: Color, dst_x: f64, dst_y: f64, )

Composite a pre-rasterized LCD subpixel mask onto the current render target, mixing src_color into the destination through per-channel coverage.

fn draw_lcd_mask_arc( &mut self, mask: &Arc<Vec<u8>>, mask_w: u32, mask_h: u32, src_color: Color, dst_x: f64, dst_y: f64, )

Arc-keyed variant so GL backends can cache the uploaded texture on the Arc’s pointer identity — one glTexImage2D per unique raster, lifetime tied to the mask’s strong-ref count. Software backends fall through to the slice path.

fn draw_lcd_backbuffer_arc( &mut self, color: &Arc<Vec<u8>>, alpha: &Arc<Vec<u8>>, content_version: u64, w: u32, h: u32, dst_x: f64, dst_y: f64, dst_w: f64, dst_h: f64, )

Composite a two-plane LcdCoverage-mode backbuffer onto the active render target at (dst_x, dst_y) with size (dst_w, dst_h) (in local coords). Inputs are two Arc<Vec<u8>>, each 3 bytes per pixel, top-row-first:

fn transform(&self) -> TransAffine

Current accumulated transform (CTM).

fn root_transform(&self) -> TransAffine

Current transform expressed in the root render target’s coordinate space, even when drawing inside an offscreen layer whose local CTM was reset to identity. Global overlays use this to submit app-level bounds.

fn save(&mut self)

fn restore(&mut self)

fn translate(&mut self, tx: f64, ty: f64)

fn rotate(&mut self, radians: f64)

fn scale(&mut self, sx: f64, sy: f64)

fn set_transform(&mut self, m: TransAffine)

fn reset_transform(&mut self)

fn supports_compositing_layers(&self) -> bool

Whether this backend implements real offscreen compositing layers.

fn supports_retained_layers(&self) -> bool

Whether this backend can retain named offscreen layers across frames.

fn push_layer(&mut self, width: f64, height: f64)

Begin a new transparent compositing layer of the given pixel dimensions.

fn push_layer_with_alpha(&mut self, width: f64, height: f64, alpha: f64)

Begin a new transparent compositing layer that will be multiplied by alpha when composited back into the parent target.

fn pop_layer(&mut self)

Composite the current layer back into the previous render target using SrcOver alpha blending, then discard the layer.

fn set_layer_rounded_clip(&mut self, x: f64, y: f64, w: f64, h: f64, r: f64)

Constrain subsequent drawing in the current layer to a rounded-rect mask. Used by window layers after shadows are drawn so chrome/content cannot write into rounded transparent corners.

fn set_layer_opaque_backdrop(&mut self, opaque: bool)

Declare that the current layer is now covered by opaque content, so text drawn into it lands on destination alpha 1.

fn composite_retained_layer( &mut self, key: u64, width: f64, height: f64, alpha: f64, ) -> bool

Composite a previously retained backend layer. Returns true when the backend had a retained surface for key and drew it.

fn push_retained_layer_with_alpha( &mut self, key: u64, width: f64, height: f64, alpha: f64, )

Begin rendering into a retained backend layer identified by key. Backends that do not retain layers may fall back to a transient layer.

fn gl_paint(&mut self, _screen_rect: Rect, _painter: &mut dyn GlPaint)

Render GPU content (3-D scene, video frame, etc.) inline at the correct painter-order position.

fn capture_screenshot(&mut self) -> bool

Snapshot the current frame’s surface into the backend’s internal screenshot texture (allocating / resizing as needed). Must be called inside the active frame, after end_frame has flushed the 2-D render but before the platform shell calls present.

fn has_captured_screenshot(&self) -> bool

True if a previously-captured screenshot is held by the backend and available for Self::draw_captured_screenshot.

fn captured_screenshot_size(&self) -> Option<(u32, u32)>

Dimensions of the held capture, or None when no capture exists.

fn draw_captured_screenshot( &mut self, dst_x: f64, dst_y: f64, dst_w: f64, dst_h: f64, ) -> bool

Draw the held capture into (dst_x, dst_y, dst_w, dst_h) using the backend’s preferred filtered sampling. Returns true if the capture exists and was drawn.

fn read_captured_screenshot(&mut self) -> (Vec<u8>, u32, u32)

Read the held capture’s pixels back to CPU memory as Y-down RGBA8 — for Save / Copy. This is intentionally a single-shot synchronous readback; widgets should NOT call this every frame. Returns (empty, 0, 0) on backends without a capture or without GPU readback support.

fn set_fill_pattern(&mut self, _pattern: PatternPaint)

fn set_stroke_pattern(&mut self, _pattern: PatternPaint)

fn supports_fill_pattern(&self) -> bool

fn supports_stroke_pattern(&self) -> bool

fn ellipse( &mut self, cx: f64, cy: f64, rx: f64, ry: f64, rotation: f64, start_angle: f64, end_angle: f64, ccw: bool, )

Append an elliptical arc to the current path, mirroring canvas-2D ellipse(cx, cy, rx, ry, rotation, start_angle, end_angle, ccw).

fn snap_to_pixel(&mut self)

Opt-in pixel snapping. Strips the fractional part of the current CTM translation so subsequent integer-coordinate rect / fill / stroke / draw_image_rgba* calls land exactly on the physical pixel grid — no AA fringe on edges, no LINEAR-filter blur on 1:1 texture blits.

fn visuals(&self) -> Visuals

Return the currently-active Visuals palette.