Enum Canvas

pub enum Canvas {
    Software(SoftwareCanvas),
    Gles(GlesCanvas),
}

Per-frame rendering surface. Wraps a backend (software or GPU) behind an enum so widgets can stay backend-agnostic.

All drawing methods are dispatched by match self — no dyn indirection, so the backend branch stays predictable and inlinable in the hot path.

Variants

Software(SoftwareCanvas)

CPU rasterisation via tiny-skia + fontdue, written to a wl_shm buffer.

Gles(GlesCanvas)

GPU rasterisation via EGL + GLES 2/3. Presents via eglSwapBuffers; Canvas::write_to_wayland_buf is a no-op for this variant.

Implementations

impl Canvas

pub fn new(width: u32, height: u32) -> Self

Build a software canvas. The GPU backend requires an EGL context — see Canvas::new_gles.

pub fn new_gles( gl: Arc<Context>, version: GlesVersion, width: u32, height: u32, ) -> Self

Build a GPU canvas on an already-current EGL context.

pub fn size(&self) -> (u32, u32)

(width, height) of the underlying surface in physical pixels.

pub fn viewport_logical(&self) -> (f32, f32)

(width, height) of the surface in logical pixels (physical size divided by dpi_scale). This is the right viewport for resolving crate::Length values, which are themselves in logical units. Falls back to physical size if dpi_scale is 0 or negative so a misconfigured canvas still returns a usable non-zero viewport instead of NaN/inf.

let mut c = Canvas::new( 720, 1440 );
c.set_dpi_scale( 2.0 );
assert_eq!( c.viewport_logical(), ( 360.0, 720.0 ) );

pub fn viewport_layout(&self) -> (f32, f32)

(width, height) of the surface in physical pixels — the same space the layout tree is computed in (the root rect is pw × ph). This is the viewport that layout-affecting crate::Length values (widths, paddings, gaps, widget sizes) must resolve against so a Vw(100) fills the surface. Text font sizes are the exception: they resolve against Self::viewport_logical and are then scaled by dpi_scale at raster time, so they must NOT use this.

pub fn borrowed_gles_texture(&self) -> Option<BorrowedGlesTexture>

Borrow the GLES texture backing this canvas, when the canvas is GPU-backed.

pub fn read_gles_rgba_pixels(&self, out: &mut [u8]) -> Result<(), String>

Read a GLES canvas into tightly packed RGBA8, top-left row first. Intentionally unavailable for software canvases because the software backend’s canonical export path is Self::write_to_wayland_buf.

pub fn draw_external_texture( &mut self, texture: Texture, dest: Rect, opacity: f32, )

Composite an externally-owned GL texture into dest. No-op on the software backend (no GL state to sample from). Used by widgets that host content rendered by an external producer — the producer keeps ownership of the texture name; this call only samples it through the standard texture program.

pub fn dpi_scale(&self) -> f32

pub fn set_dpi_scale(&mut self, s: f32)

pub fn global_alpha(&self) -> f32

pub fn set_global_alpha(&mut self, a: f32)

pub fn font(&self) -> &Font

Shared font handle. Exposed so widgets that need raw fontdue access (e.g. Text for ascent/descent) do not have to go through wrappers for every metric they read.

pub fn set_font_registry(&mut self, registry: Arc<FontRegistry>)

Install a theme font registry on the active backend.

pub fn font_for(&self, family: &str, weight: u16, style: FontStyle) -> Arc<Font>

Resolve a specific font via the theme registry, falling back to the system-default Self::font when no registry is installed or the triple cannot be satisfied.

pub fn font_metrics(&self, ch: char, size: f32) -> Metrics

Convenience wrapper around font().metrics(...) already pre-scaled by dpi_scale. Most callers want this rather than the raw font handle.

pub fn font_line_metrics(&self, size: f32) -> Option<LineMetrics>

Convenience wrapper around font().horizontal_line_metrics(...).

pub fn resize(&mut self, width: u32, height: u32)

pub fn sub_canvas(&self, width: u32, height: u32) -> Canvas

pub fn blit(&mut self, src: &Canvas, dest_x: i32, dest_y: i32)

pub fn blit_fade_bottom( &mut self, src: &Canvas, dest_x: i32, dest_y: i32, fade_bottom_px: f32, )

Like Self::blit but feathers the last fade_bottom_px source rows so the bottom edge fades to transparent. The software backend currently ignores fade_bottom_px, so the dissolve is GLES-only.

pub fn set_clip_rects(&mut self, rects: &[Rect])

pub fn clip_bounds(&self) -> Vec<Rect>

Snapshot the currently installed clip bounds (empty when no clip is active). Used by widgets that need to install a tighter clip for a single primitive and then restore whatever the outer partial-redraw or sub-canvas clip was — there is no stack internally, so round-tripping through Self::set_clip_rects with the snapshot is how to compose.

pub fn clear_clip(&mut self)

pub fn clear(&mut self)

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

pub fn fill_rect( &mut self, rect: Rect, color: Color, corners: impl Into<Corners>, )

pub fn fill_paint_rect( &mut self, rect: Rect, paint: &ThemePaint, corners: impl Into<Corners>, )

Paint-driven rectangle fill.

Dispatches on the crate::theme::Paint variant. Solid fills go straight through Self::fill_rect. Gradients (linear and radial) are routed to dedicated shaders on the GPU backend; on the Software backend they still collapse to a flat fill from the first stop — tiny-skia can render gradients natively, but wiring that up is left for a follow-up.

pub fn stroke_rect( &mut self, rect: Rect, color: Color, width: f32, corners: impl Into<Corners>, )

pub fn fill_shadow_outer( &mut self, target: Rect, shadow: &Shadow, corners: impl Into<Corners>, )

Paint an outer drop shadow behind the rounded rect target.

On the GPU backend this runs an analytic soft-shadow shader in one draw call — no FBO, no cache, no readback. On the Software backend it is a no-op today.

pub fn fill_shadow_inset( &mut self, target: Rect, shadow: &InsetShadow, corners: impl Into<Corners>, )

Paint an inner (inset) shadow inside the rounded rect target.

On the GPU backend, uses a dedicated shader whose inner SDF encodes shadow.offset and shadow.spread. The blend state is switched per-call to honour shadow.blend: Normal, PlusLighter, Multiply and Screen map to fixed-function blend modes; Overlay routes through a dedicated shader that snapshots the FBO and computes the CSS Overlay formula in-shader.

On the Software backend this is a no-op today.

pub fn fill_surface( &mut self, rect: Rect, fill: &ThemePaint, outer_shadows: &[Shadow], inset_shadows: &[InsetShadow], corners: impl Into<Corners>, )

Unified surface painter. Composes a themed surface in the canonical paint order: outer shadows → fill → insets.

pub fn draw_line( &mut self, x0: f32, y0: f32, x1: f32, y1: f32, color: Color, width: f32, )

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

pub fn draw_text_with_font( &mut self, text: &str, x: f32, y: f32, size: f32, color: Color, font: &Arc<Font>, )

Draw text with an explicitly supplied font instead of the canvas default. Use Self::font_for to resolve a (family, weight, style) triple from the active theme registry first.

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

pub fn measure_text_with_font( &self, text: &str, size: f32, font: &Arc<Font>, ) -> f32

Width of text rendered with font. Mirrors Self::measure_text but bypasses the canvas default font so text laid out at one weight and drawn at another stays aligned.

pub fn draw_image_data( &mut self, rgba_data: &[u8], img_w: u32, img_h: u32, dest: Rect, opacity: f32, )

pub fn clear_rects_transparent(&mut self, rects: &[Rect])

Zero pixels inside each rect — used by the partial-redraw path when the surface background is fully transparent.

pub fn write_to_wayland_buf(&self, buf: &mut [u8], swap_rb: bool)

Copy / present the rendered frame. For software this fills a wl_shm buffer (with optional R/B swap for Argb8888). For GPU the commit happens via eglSwapBuffers elsewhere — this call is a no-op.

pub fn present(&mut self)

Publish the in-progress GPU frame: blit the FBO onto the EGL window’s default framebuffer. The follow-up eglSwapBuffers (done outside the canvas) is what actually commits to the compositor. No-op on software, where presentation is the SHM attach_to/commit pair.