Struct Canvas 

pub struct Canvas { /* private fields */ }

Builder for a single frame’s draw commands. Wraps Painter and adds canvas helpers.

Implementations

impl Canvas

pub fn viewport(&self) -> Viewport

pub fn current_transform(&self) -> Transform2D

Get the current transform from the painter’s transform stack.

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

Set the frame clear/background color (premultiplied linear RGBA).

pub fn fill_rect( &mut self, x: f32, y: f32, w: f32, h: f32, brush: Brush, z: i32, )

Fill a rectangle with a brush.

pub fn external_texture( &mut self, rect: Rect, texture_id: ExternalTextureId, z: i32, )

Composite an externally-rendered texture at the given rectangle.

The texture_id must be registered with the PassManager before the frame is submitted via register_external_texture.

pub fn fill_overlay_rect( &mut self, x: f32, y: f32, w: f32, h: f32, color: ColorLinPremul, )

Fill a rectangle as an overlay (no depth testing). Use this for modal scrims and other overlays that should blend over existing content without blocking text rendered at lower z-indices.

The rectangle coordinates are transformed by the current canvas transform, so they should be in local (viewport) coordinates.

pub fn fill_scrim_rect( &mut self, x: f32, y: f32, w: f32, h: f32, color: ColorLinPremul, )

Fill a rectangle as a scrim (blends over all existing content but allows subsequent z-ordered draws to render on top).

Unlike fill_overlay_rect, this uses a depth buffer attachment with:

• depth_compare = Always (always passes depth test)
• depth_write_enabled = false (doesn’t affect depth buffer)

This allows the scrim to dim background content while the modal panel (rendered at a higher z-index afterward) renders cleanly on top.

pub fn fill_scrim_with_cutout( &mut self, hole: RoundedRect, color: ColorLinPremul, )

Fill a fullscreen scrim that leaves a rounded-rect hole using stencil.

pub fn stroke_path( &mut self, path: Path, width: f32, color: ColorLinPremul, z: i32, )

Stroke a path with uniform width and solid color.

Paths that are not fully contained within the active clip are rejected because arbitrary path geometry cannot be CPU-clipped to a rectangle.

pub fn fill_path(&mut self, path: Path, color: ColorLinPremul, z: i32)

Fill a path with a solid color.

Paths that are fully outside the active clip are rejected.

pub fn ellipse( &mut self, center: [f32; 2], radii: [f32; 2], brush: Brush, z: i32, )

Draw an ellipse (y-down coordinates).

pub fn circle(&mut self, center: [f32; 2], radius: f32, brush: Brush, z: i32)

Draw a circle (y-down coordinates).

pub fn rounded_rect(&mut self, rrect: RoundedRect, brush: Brush, z: i32)

Draw a rounded rectangle fill.

pub fn stroke_rounded_rect( &mut self, rrect: RoundedRect, width: f32, brush: Brush, z: i32, )

Stroke a rounded rectangle.

pub fn draw_text_run( &mut self, origin: [f32; 2], text: String, size_px: f32, color: ColorLinPremul, z: i32, )

Draw text using direct rasterization (recommended).

This method rasterizes glyphs immediately using the text provider, bypassing complex display list paths. This is simpler and more reliable than deferred rendering.

Performance

• Glyphs are shaped and rasterized on each call
• Use TextLayoutCache to cache wrapping computations
• Debounce resize events to avoid excessive rasterization

Transform Stack

The current transform is applied to position text correctly within zones (viewport, toolbar, etc.).

DPI Scaling

Both position and size are automatically scaled by self.dpi_scale.

Example

canvas.draw_text_run(
    [10.0, 20.0],
    "Hello, world!".to_string(),
    16.0,
    ColorLinPremul::rgba(255, 255, 255, 255),
    10,  // z-index
);

pub fn draw_text_run_weighted( &mut self, origin: [f32; 2], text: String, size_px: f32, weight: f32, color: ColorLinPremul, z: i32, )

Draw a text run with an explicit font weight.

weight should follow CSS semantics (100–900; 400 = normal, 700 = bold).

pub fn draw_text_run_styled( &mut self, origin: [f32; 2], text: String, size_px: f32, weight: f32, style: FontStyle, family: Option<String>, color: ColorLinPremul, z: i32, )

Draw a text run with full styling options.

weight should follow CSS semantics (100–900; 400 = normal, 700 = bold). style specifies normal, italic, or oblique rendering. family optionally overrides the font family.

pub fn draw_text_run_gradient( &mut self, origin: [f32; 2], text: String, size_px: f32, weight: f32, style: FontStyle, family: Option<String>, brush: &Brush, text_width: f32, z: i32, )

Draw text with per-glyph gradient color sampling.

Works like draw_text_run_styled but instead of a single flat color, each glyph is tinted by sampling the provided Brush at the glyph’s normalised horizontal position (t = glyph_x / text_width). This implements CSS background-clip: text with gradient backgrounds.

pub fn draw_text_direct( &mut self, origin: [f32; 2], text: &str, size_px: f32, color: ColorLinPremul, provider: &dyn TextProvider, z: i32, )

Draw text directly by rasterizing immediately (simpler, bypasses display list). This is the recommended approach - it’s simpler and more reliable than draw_text_run.

pub fn set_text_provider( &mut self, provider: Arc<dyn TextProvider + Send + Sync>, )

Provide a text provider used for high-level text runs in this frame.

pub fn text_provider(&self) -> Option<&Arc<dyn TextProvider + Send + Sync>>

pub fn measure_text_width(&self, text: &str, size_px: f32) -> f32

Measure the width of a text run in logical pixels using the active text provider.

This is intended for layout/centering code that needs a more accurate width than simple character-count heuristics. When no provider is set, falls back to font_size * 0.55 * text.len() to match legacy behavior.

pub fn measure_text_width_styled( &self, text: &str, size_px: f32, weight: f32, style: FontStyle, family: Option<&str>, ) -> f32

Measure the width of a styled text run in logical pixels.

Unlike measure_text_width, this accounts for font weight, style, and family so that measurements match draw_text_run_styled rendering.

pub fn draw_text_glyphs( &mut self, origin: [f32; 2], glyphs: &[RasterizedGlyph], color: ColorLinPremul, z: i32, )

Draw pre-rasterized glyph masks at the given origin tinted with the color.

pub fn draw_hyperlink(&mut self, hyperlink: Hyperlink, z: i32)

Draw a hyperlink with text, optional underline, and URL target.

Example

let link = Hyperlink {
    text: "Click me".to_string(),
    pos: [10.0, 20.0],
    size: 16.0,
    color: ColorLinPremul::from_srgba_u8([0, 122, 255, 255]),
    url: "https://example.com".to_string(),
    weight: 400.0,
    measured_width: None,
    underline: true,
    underline_color: None,
    family: None,
    style: jag_draw::FontStyle::Normal,
};
canvas.draw_hyperlink(link, 10);

pub fn draw_svg<P: Into<PathBuf>>( &mut self, path: P, origin: [f32; 2], max_size: [f32; 2], z: i32, )

Queue an SVG to be rasterized and drawn at origin, scaled to fit within max_size. Captures the current transform from the painter’s transform stack. Optional style parameter allows overriding fill, stroke, and stroke-width.

pub fn draw_svg_styled<P: Into<PathBuf>>( &mut self, path: P, origin: [f32; 2], max_size: [f32; 2], style: SvgStyle, z: i32, )

Queue an SVG with style overrides to be rasterized and drawn.

pub fn draw_image<P: Into<PathBuf>>( &mut self, path: P, origin: [f32; 2], size: [f32; 2], fit: ImageFitMode, z: i32, )

Queue a raster image (PNG/JPEG/GIF/WebP) to be drawn at origin with the given size. The fit parameter controls how the image is scaled within the size bounds. Captures the current transform from the painter’s transform stack.

pub fn draw_raw_image( &mut self, pixels: Vec<u8>, src_width: u32, src_height: u32, origin: [f32; 2], dst_size: [f32; 2], z: i32, )

Queue raw pixel data to be drawn at origin with the given size. Pixels should be in BGRA format (4 bytes per pixel) to match CEF native output. Captures the current transform from the painter’s transform stack.

pub fn draw_raw_image_with_dirty_rects( &mut self, pixels: Vec<u8>, src_width: u32, src_height: u32, origin: [f32; 2], dst_size: [f32; 2], z: i32, dirty_rects: Vec<(u32, u32, u32, u32)>, )

Queue raw pixel data with dirty rects for partial update. Pixels should be in BGRA format (4 bytes per pixel) to match CEF native output. Only the dirty rectangles will be uploaded to the GPU texture.

pub fn push_clip_rect(&mut self, rect: Rect)

pub fn pop_clip(&mut self)

pub fn push_transform(&mut self, t: Transform2D)

pub fn pop_transform(&mut self)

pub fn push_opacity(&mut self, opacity: f32)

pub fn pop_opacity(&mut self)

pub fn hit_region_rect(&mut self, id: u32, rect: Rect, z: i32)

Add a hit-only region (invisible, used for interaction detection)

pub fn command_count(&self) -> usize

Return the current number of commands in the display list.

pub fn display_list(&self) -> &DisplayList

Get a reference to the display list for hit testing

pub fn snap_rect_logical_to_device(&self, rect: Rect) -> Rect

Snap a rectangle defined in logical coordinates so that, after applying the current transform and DPI scale, its edges land on physical pixel boundaries. This assumes the current transform is an axis-aligned translate/scale (no rotation/skew); for more complex transforms the original rect is returned unchanged.