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 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 origin; drawing inside uses a reset local transform.

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

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)

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 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)

Draw text using the built-in AGG Glyph-Stroke-Vector font at size pixels. Useful before a proper font is loaded.

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>>, 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 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 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 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.