Struct GfxCtx 

pub struct GfxCtx<'a> { /* private fields */ }

Cairo-style stateful 2D graphics context.

All widget painting goes through GfxCtx. Create one per frame from a Framebuffer, draw into it, then let it drop — the framebuffer retains the rendered pixels.

Layer compositing

Call push_layer(w, h) to redirect all subsequent drawing into an offscreen framebuffer. Call pop_layer() to SrcOver-composite that buffer back into the previous target (which may itself be a layer or the base framebuffer). Layers nest; each push must be matched by exactly one pop.

Implementations

impl GfxCtx<'_>

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

Begin an offscreen compositing layer of width × height logical pixels.

All draw calls until the matching pop_layer are redirected into a fresh transparent Framebuffer. The current CTM’s translation records the layer’s screen-space (physical) origin; the CTM’s scale is preserved so the subtree rasterises at physical resolution inside the layer buffer.

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

pub fn clip_path(&mut self)

Intersect the clip with the current path (canvas-2D clip()).

The path is rasterised — with the current CTM and fill rule — into an 8-bit anti-aliased coverage mask, and a clip layer of the path’s (clipped) device-space bounding box is pushed. Subsequent drawing goes into that layer in the same coordinate space (the CTM is only shifted by the layer origin, rotation and scale are preserved), and the matching restore() multiplies the layer by the mask before compositing it back.

reset_clip() inside a clip layer only clears the rectangular scissor; the path mask stays in force until the matching restore().

Like canvas clip() this does not clear the current path. Because drawing inside the clip layer may replace it, the path as of this call is snapshotted and put back when the layer pops, so the canvas-port idiom begin_path(); <outline>; fill(); save(); clip_path(); <interior>; restore(); stroke(); strokes the outline. (Canvas leaves whatever the interior built; restoring the outline is the more useful behaviour here and is what the wgpu backend does too.)

pub fn pop_layer(&mut self)

SrcOver-composite the current layer into the previous render target, then restore the graphics state that was active at the matching push_layer.

impl<'a> GfxCtx<'a>

pub fn new(fb: &'a mut Framebuffer) -> Self

Create a new graphics context for the given framebuffer.

pub fn save(&mut self)

pub fn restore(&mut self)

Pop the graphics state pushed by the matching save().

Any clip layers opened by clip_path() since that save() are composited (and their masks applied) first — a clip layer’s lifetime ends at the restore() matching the save() that preceded it, which is exactly canvas-2D clip() semantics.

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

Append a translation. Uses pre-multiply (Cairo semantics).

pub fn rotate(&mut self, radians: f64)

Append a CCW rotation in radians. Uses pre-multiply semantics.

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

Append a scale. Uses pre-multiply semantics.

pub fn set_transform(&mut self, m: TransAffine)

pub fn reset_transform(&mut self)

pub fn transform(&self) -> TransAffine

Return the current accumulated transform (cumulative translation + scale from all parent save/translate/restore calls). The tx/ty fields give the widget’s bottom-left corner in framebuffer (Y-up) coordinates.

pub fn set_fill_color(&mut self, color: Color)

pub fn set_fill_linear_gradient(&mut self, gradient: LinearGradientPaint)

pub fn set_fill_radial_gradient(&mut self, gradient: RadialGradientPaint)

pub fn set_fill_pattern(&mut self, pattern: PatternPaint)

pub fn set_stroke_color(&mut self, color: Color)

pub fn set_stroke_linear_gradient(&mut self, gradient: LinearGradientPaint)

pub fn set_stroke_radial_gradient(&mut self, gradient: RadialGradientPaint)

pub fn set_stroke_pattern(&mut self, pattern: PatternPaint)

pub fn set_line_width(&mut self, w: f64)

pub fn set_line_join(&mut self, join: LineJoin)

pub fn set_line_cap(&mut self, cap: LineCap)

pub fn set_miter_limit(&mut self, limit: f64)

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

pub fn set_fill_rule(&mut self, rule: FillRule)

pub fn set_blend_mode(&mut self, mode: CompOp)

Set the Porter-Duff compositing mode. Default: SrcOver.

pub fn set_global_alpha(&mut self, alpha: f64)

Global alpha multiplier (0.0–1.0) applied on top of each color’s alpha.

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

Set the current font. Shared via Arc — cheap to clone across widgets.

pub fn set_font_size(&mut self, size: f64)

Set the font size in pixels (distance from baseline to cap height).

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

Enable/disable LCD subpixel rendering on this ctx. When true, fill_text uses the per-channel coverage pipeline; when false grayscale AA. Set by paint_subtree_backbuffered for LcdCoverage widget buffers, and by the main render loop for direct-to-screen text.

pub fn lcd_mode(&self) -> bool

Read the ctx’s current LCD mode.

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

Intersect the current clip with a rectangle in the current local coordinate space (i.e. after all accumulated translate / scale calls). The four corners are mapped through the current transform to produce an axis-aligned screen-space bounding box, which is then intersected with any existing clip.

For the common case of pure translations this is equivalent to the old “screen-space rectangle” API, but it now works correctly when called from inside a paint() method that runs after the framework has already translated the context to the widget’s origin.

pub fn reset_clip(&mut self)

pub fn clear(&mut self, color: Color)

Fill the entire active framebuffer with color, ignoring transform and clip.

pub fn begin_path(&mut self)

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

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

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

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

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

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

Full circle at (cx, cy) with radius r.

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

Axis-aligned rectangle — bottom-left (x, y), size w × h.

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

Rounded rectangle — bottom-left (x, y), size w × h, corner radius r.

pub fn close_path(&mut self)

pub fn fill(&mut self)

Fill the accumulated path.

pub fn stroke(&mut self)

Stroke the accumulated path.

pub fn fill_and_stroke(&mut self)

Fill then stroke the accumulated path in one call.

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

Draw text at position (x, y) using the current font and fill color.

(x, y) is the baseline-left position in Y-up screen coordinates. Glyphs extend upward (higher Y) for ascenders and downward (lower Y) for descenders — correct for Y-up rendering with no Y-flip.

Requires a font to be set via set_font. Does nothing if no font has been set.

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

Measure the advance width and metrics of text in the current font.

Returns None if no font has been set.

pub fn fill_text_gsv(&mut self, text: &str, x: f64, y: f64, size: f64)

Draw text using AGG’s built-in vector font (no external font needed).

Useful for labels before a full font is loaded.

Trait Implementations

impl DrawCtx for GfxCtx<'_>

fn set_fill_color(&mut self, c: Color)

fn set_fill_linear_gradient(&mut self, gradient: LinearGradientPaint)

fn set_fill_radial_gradient(&mut self, gradient: RadialGradientPaint)

fn set_fill_pattern(&mut self, pattern: PatternPaint)

fn supports_fill_linear_gradient(&self) -> bool

fn supports_fill_radial_gradient(&self) -> bool

fn supports_fill_pattern(&self) -> bool

fn set_stroke_color(&mut self, c: Color)

fn set_stroke_linear_gradient(&mut self, gradient: LinearGradientPaint)

fn set_stroke_radial_gradient(&mut self, gradient: RadialGradientPaint)

fn set_stroke_pattern(&mut self, pattern: PatternPaint)

fn supports_stroke_linear_gradient(&self) -> bool

fn supports_stroke_radial_gradient(&self) -> bool

fn supports_stroke_pattern(&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_fill_rule(&mut self, rule: FillRule)

fn set_blend_mode(&mut self, m: CompOp)

fn set_global_alpha(&mut self, a: f64)

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

fn set_font_size(&mut self, s: 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, c: 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, a1: f64, a2: 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, t: &str, x: f64, y: f64)

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

fn fill_text_gsv(&mut self, t: &str, x: f64, y: f64, s: f64)

Do not call this from application code, ever.

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

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

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, r: f64)

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

fn set_transform(&mut self, m: TransAffine)

fn reset_transform(&mut self)

fn push_layer(&mut self, w: f64, h: f64)

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

fn supports_compositing_layers(&self) -> bool

Whether this backend implements real offscreen compositing layers.

fn push_layer_with_alpha(&mut self, w: f64, h: 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 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_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_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 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_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 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 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 supports_retained_layers(&self) -> bool

Whether this backend can retain named offscreen layers across frames.

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 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_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 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 visuals(&self) -> Visuals

Return the currently-active Visuals palette.