Mojo struct 🡭

BoundsTarget

@memory_only
struct BoundsTarget

A DrawTarget that keeps the union of what it was asked to draw and draws nothing. See this module’s docstring for what the box means and where it is exact.

Construct with the page size, draw the scene through the trait, then read has_ink(), ink_bounds() or ink_pixels(). A target can be reused: reset() clears the union and every piece of state.

Fields

• width (Int)
• height (Int)

Implemented traits

AnyType, Deinitable, DrawTarget, Movable

Methods

__init__

fn def __init__(out self, width: Int, height: Int)

A measuring target the size of the page a scene will be drawn on.

Args:

• width (Int): Page width in pixels; ink past it does not count.
• height (Int): Page height in pixels.
• self (Self)

Returns:

Self

has_ink

fn def has_ink(self) -> Bool

Whether anything drawn so far had positive area inside the page and the clips in force when it was drawn.

Args:

• self (Self)

Returns:

Bool: True once any primitive contributed an extent.

ink_bounds

fn def ink_bounds(self) -> Tuple[Float64, Float64, Float64, Float64]

The geometric box around everything drawn, as (min_x, min_y, max_x, max_y) in this target’s coordinates, the convention of Path.bounds. All zeros with no ink; check has_ink() to tell that from a box at the origin.

Args:

• self (Self)

Returns:

Tuple[Float64, Float64, Float64, Float64]: (min_x, min_y, max_x, max_y).

ink_pixels

fn def ink_pixels(self) -> Tuple[Int, Int, Int, Int]

The whole-pixel box around everything drawn, as (x, y, width, height): every pixel whose square the geometry enters, which is every pixel an anti-aliased edge can touch. Zero size with no ink.

A crop is Canvas(width, height) drawn with translate(-x, -y), which lands the ink at the new origin.

Args:

• self (Self)

Returns:

Tuple[Int, Int, Int, Int]: (x, y, width, height), in pixels.

reset

fn def reset(mut self)

Forget every extent and every piece of state, so the target can measure another scene on the same page.

Args:

• self (Self)

fill_rect

fn def fill_rect(mut self, x: Int, y: Int, width: Int, height: Int, color: Color)

The pixels x through x + width - 1 by y through y + height - 1.

Args:

• self (Self)
• x (Int): First column.
• y (Int): First row.
• width (Int): Columns.
• height (Int): Rows.
• color (Color): Ignored.

fn def fill_rect(mut self, x: Float64, y: Float64, width: Float64, height: Float64, color: Color)

The geometric box from (x, y) spanning width x height, snapped the way fill_rect snaps it.

Args:

• self (Self)
• x (Float64): Left edge.
• y (Float64): Top edge.
• width (Float64): Width.
• height (Float64): Height.
• color (Color): Ignored.

fill_rect_gradient

fn def fill_rect_gradient(mut self, x: Int, y: Int, width: Int, height: Int, gradient: LinearGradient)

As fill_rect; the gradient does not change the extent.

Args:

• self (Self)
• x (Int): First column.
• y (Int): First row.
• width (Int): Columns.
• height (Int): Rows.
• gradient (LinearGradient): Ignored.

fn def fill_rect_gradient(mut self, x: Float64, y: Float64, width: Float64, height: Float64, gradient: LinearGradient)

As fill_rect; the gradient does not change the extent.

Args:

• self (Self)
• x (Float64): Left edge.
• y (Float64): Top edge.
• width (Float64): Width.
• height (Float64): Height.
• gradient (LinearGradient): Ignored.

draw_line_aa

fn def draw_line_aa(mut self, x0: Int, y0: Int, x1: Int, y1: Int, color: Color, width: Float64 = 1, dashes: List[Float64] = List(), dash_offset: Float64 = 0, cap: LineCap = LineCap.ROUND, join: LineJoin = LineJoin.ROUND, miter_limit: Float64 = 4)

A stroked segment between two pixel centers, with its caps.

Args:

• self (Self)
• x0 (Int): Start point x.
• y0 (Int): Start point y.
• x1 (Int): End point x.
• y1 (Int): End point y.
• color (Color): Ignored.
• width (Float64): Stroke width in pixels.
• dashes (List[Float64]): On/off segment lengths; a pattern ending short of the line ends the box short too.
• dash_offset (Float64): Distance into the dash pattern the line starts at.
• cap (LineCap): How the two ends are finished.
• join (LineJoin): Unused for a single segment.
• miter_limit (Float64): Unused for a single segment.

fn def draw_line_aa(mut self, x0: Float64, y0: Float64, x1: Float64, y1: Float64, color: Color, width: Float64 = 1, dashes: List[Float64] = List(), dash_offset: Float64 = 0, cap: LineCap = LineCap.ROUND, join: LineJoin = LineJoin.ROUND, miter_limit: Float64 = 4)

A stroked segment between sub-pixel endpoints, with its caps.

Args:

• self (Self)
• x0 (Float64): Start point x.
• y0 (Float64): Start point y.
• x1 (Float64): End point x.
• y1 (Float64): End point y.
• color (Color): Ignored.
• width (Float64): Stroke width in pixels.
• dashes (List[Float64]): On/off segment lengths.
• dash_offset (Float64): Distance into the dash pattern the line starts at.
• cap (LineCap): How the two ends are finished.
• join (LineJoin): Unused for a single segment.
• miter_limit (Float64): Unused for a single segment.

fill_circle_aa

fn def fill_circle_aa(mut self, cx: Int, cy: Int, radius: Int, color: Color)

A disk centered on a pixel center.

Args:

• self (Self)
• cx (Int): Center x.
• cy (Int): Center y.
• radius (Int): Radius in pixels.
• color (Color): Ignored.

fn def fill_circle_aa(mut self, cx: Float64, cy: Float64, radius: Float64, color: Color)

A disk at a sub-pixel center.

Args:

• self (Self)
• cx (Float64): Center x.
• cy (Float64): Center y.
• radius (Float64): Radius in pixels.
• color (Color): Ignored.

fill_circles_aa

fn def fill_circles_aa(mut self, centers: List[FPoint], radius: Float64, color: Color)

Every disk of a bulk marker call.

Args:

• self (Self)
• centers (List[FPoint]): Disk centers.
• radius (Float64): Shared radius.
• color (Color): Ignored.

Raises:

fn def fill_circles_aa(mut self, centers: List[FPoint], radius: Float64, colors: List[Color])

Every disk of a bulk marker call with a color per disk.

Args:

• self (Self)
• centers (List[FPoint]): Disk centers.
• radius (Float64): Shared radius.
• colors (List[Color]): Ignored.

Raises:

fill_mesh

fn def fill_mesh(mut self, points: List[FPoint], faces: List[Int], colors: List[Color])

The box around every vertex a face references.

Args:

• self (Self)
• points (List[FPoint]): Vertices.
• faces (List[Int]): Index triples.
• colors (List[Color]): Ignored.

Raises:

Error: A face index is out of range.

fill_mesh_shaded

fn def fill_mesh_shaded(mut self, points: List[FPoint], faces: List[Int], vertex_colors: List[Color])

The box around every vertex a face references.

Args:

• self (Self)
• points (List[FPoint]): Vertices.
• faces (List[Int]): Index triples.
• vertex_colors (List[Color]): Ignored.

Raises:

Error: A face index is out of range.

fill_ellipses_aa

fn def fill_ellipses_aa(mut self, centers: List[FPoint], rx: Float64, ry: Float64, color: Color)

Every ellipse of a bulk marker call.

Args:

• self (Self)
• centers (List[FPoint]): Ellipse centers.
• rx (Float64): Shared horizontal radius.
• ry (Float64): Shared vertical radius.
• color (Color): Ignored.

Raises:

fn def fill_ellipses_aa(mut self, centers: List[FPoint], rx: Float64, ry: Float64, colors: List[Color])

Every ellipse of a bulk marker call with a color per ellipse.

Args:

• self (Self)
• centers (List[FPoint]): Ellipse centers.
• rx (Float64): Shared horizontal radius.
• ry (Float64): Shared vertical radius.
• colors (List[Color]): Ignored.

Raises:

draw_circle_aa

fn def draw_circle_aa(mut self, cx: Float64, cy: Float64, radius: Float64, color: Color, width: Float64 = 1)

A ring: the disk out to the stroke’s outer edge, which is the radius plus half the width.

Args:

• self (Self)
• cx (Float64): Center x.
• cy (Float64): Center y.
• radius (Float64): Radius to the middle of the stroke.
• color (Color): Ignored.
• width (Float64): Stroke width.

fill_ellipse_aa

fn def fill_ellipse_aa(mut self, cx: Int, cy: Int, rx: Int, ry: Int, color: Color)

An ellipse centered on a pixel center.

Args:

• self (Self)
• cx (Int): Center x.
• cy (Int): Center y.
• rx (Int): Horizontal radius.
• ry (Int): Vertical radius.
• color (Color): Ignored.

fn def fill_ellipse_aa(mut self, cx: Float64, cy: Float64, rx: Float64, ry: Float64, color: Color)

An ellipse at a sub-pixel center.

Args:

• self (Self)
• cx (Float64): Center x.
• cy (Float64): Center y.
• rx (Float64): Horizontal radius.
• ry (Float64): Vertical radius.
• color (Color): Ignored.

draw_ellipse_aa

fn def draw_ellipse_aa(mut self, cx: Int, cy: Int, rx: Int, ry: Int, color: Color)

A one-pixel ellipse outline centered on a pixel center.

Args:

• self (Self)
• cx (Int): Center x.
• cy (Int): Center y.
• rx (Int): Horizontal radius to the middle of the stroke.
• ry (Int): Vertical radius to the middle of the stroke.
• color (Color): Ignored.

fn def draw_ellipse_aa(mut self, cx: Float64, cy: Float64, rx: Float64, ry: Float64, color: Color, width: Float64 = 1)

An ellipse outline: the ellipse out to the stroke’s outer edge.

Args:

• self (Self)
• cx (Float64): Center x.
• cy (Float64): Center y.
• rx (Float64): Horizontal radius to the middle of the stroke.
• ry (Float64): Vertical radius to the middle of the stroke.
• color (Color): Ignored.
• width (Float64): Stroke width.

fill_arc_aa

fn def fill_arc_aa(mut self, cx: Float64, cy: Float64, radius: Float64, start_angle: Float64, end_angle: Float64, color: Color)

A pie wedge, flattened the way the fill flattens it.

Args:

• self (Self)
• cx (Float64): Center x.
• cy (Float64): Center y.
• radius (Float64): Wedge radius.
• start_angle (Float64): Sweep start, radians.
• end_angle (Float64): Sweep end, radians.
• color (Color): Ignored.

fill_arcs_aa

fn def fill_arcs_aa(mut self, centers: List[FPoint], radius: Float64, start_angle: Float64, end_angle: Float64, color: Color)

Every wedge of a bulk call.

Args:

• self (Self)
• centers (List[FPoint]): Wedge centers.
• radius (Float64): Shared radius.
• start_angle (Float64): Shared sweep start, radians.
• end_angle (Float64): Shared sweep end, radians.
• color (Color): Ignored.

Raises:

fn def fill_arcs_aa(mut self, centers: List[FPoint], radius: Float64, start_angle: Float64, end_angle: Float64, colors: List[Color])

Every wedge of a bulk call with a color per wedge.

Args:

• self (Self)
• centers (List[FPoint]): Wedge centers.
• radius (Float64): Shared radius.
• start_angle (Float64): Shared sweep start, radians.
• end_angle (Float64): Shared sweep end, radians.
• colors (List[Color]): Ignored.

Raises:

fill_ring_sector_aa

fn def fill_ring_sector_aa(mut self, cx: Float64, cy: Float64, inner_radius: Float64, outer_radius: Float64, start_angle: Float64, end_angle: Float64, color: Color)

A ring segment: along the outer arc, in to the inner arc and back along it, flattened the way the fill flattens it.

Args:

• self (Self)
• cx (Float64): Center x.
• cy (Float64): Center y.
• inner_radius (Float64): Radius of the hole.
• outer_radius (Float64): Outer radius.
• start_angle (Float64): Sweep start, radians.
• end_angle (Float64): Sweep end, radians.
• color (Color): Ignored.

stroke_path_aa

fn def stroke_path_aa(mut self, path: Path, color: Color, width: Float64 = 1, dashes: List[Float64] = List(), dash_offset: Float64 = 0, cap: LineCap = LineCap.ROUND, join: LineJoin = LineJoin.ROUND, miter_limit: Float64 = 4)

A stroke’s outline with its caps and joins: Path.stroke_bounds with the same style.

Args:

• self (Self)
• path (Path): The path to stroke.
• color (Color): Ignored.
• width (Float64): Stroke width in pixels.
• dashes (List[Float64]): On/off segment lengths.
• dash_offset (Float64): Distance into the dash pattern the stroke starts at.
• cap (LineCap): How open sub-paths end.
• join (LineJoin): How corners are turned; a MITER spike counts.
• miter_limit (Float64): Ratio past which MITER falls back to BEVEL.

fill_path_aa

fn def fill_path_aa(mut self, path: Path, color: Color, fill_rule: FillRule = FillRule.EVEN_ODD)

A filled path’s flattened outline. The fill rule cannot change the outer box, so it is ignored.

Args:

• self (Self)
• path (Path): The path to fill.
• color (Color): Ignored.
• fill_rule (FillRule): Ignored.

draw_image

fn def draw_image(mut self, image: Canvas, x: Float64, y: Float64, width: Float64 = 0, height: Float64 = 0)

The box the image is scaled to, placed as a fill_rect at the same coordinates would be.

Args:

• self (Self)
• image (Canvas): The pixels; only its size is read.
• x (Float64): Left edge in user space.
• y (Float64): Top edge in user space.
• width (Float64): Drawn width, or 0 for image.width.
• height (Float64): Drawn height, or 0 for image.height.

Raises:

draw_text

fn def draw_text(mut self, x: Float64, y: Float64, text: String, color: Color, size: Float64, family: String = "Sans", slant: FontSlant = FontSlant.NORMAL, weight: FontWeight = FontWeight.NORMAL, rotation: Float64 = 0, align: TextAlign = TextAlign.LEFT, *, mut cache: FontCache)

The block draw_text would lay out, from measure_text_block with the same font, alignment and rotation, then mapped through the transform. Exact up to a canvas rotation, which maps the block’s box corner by corner.

Args:

• self (Self)
• x (Float64): Anchor x.
• y (Float64): Anchor y.
• text (String): The text, newline-separated lines.
• color (Color): Ignored.
• size (Float64): Font size in points.
• family (String): Font family name or generic alias.
• slant (FontSlant): Requested style.
• weight (FontWeight): Requested weight.
• rotation (Float64): Radians about the anchor.
• align (TextAlign): Horizontal alignment of each line.
• cache (FontCache): Font cache to resolve and measure through.

Raises:

Error: No font resolves for family.

draw_text_runs

fn def draw_text_runs(mut self, x: Float64, y: Float64, runs: List[TextRun], color: Color, family: String = "Sans", weight: FontWeight = FontWeight.NORMAL, rotation: Float64 = 0, align: TextAlign = TextAlign.LEFT, *, mut cache: FontCache)

The union of the blocks draw_text would lay out for each run at the anchor canvas.text.render.text_run_anchors computes for it: what Canvas.draw_text_runs inks, since it draws exactly those calls.

Args:

• self (Self)
• x (Float64): Anchor x.
• y (Float64): Anchor y, the label’s baseline.
• runs (List[TextRun]): The label’s runs, in reading order.
• color (Color): Ignored.
• family (String): Font family name or generic alias.
• weight (FontWeight): Requested weight.
• rotation (Float64): Radians about the anchor.
• align (TextAlign): Horizontal alignment of the whole label.
• cache (FontCache): Font cache to resolve and measure through.

Raises:

Error: No font resolves for family.

push_clip

fn def push_clip(mut self, x: Int, y: Int, width: Int, height: Int)

Confine what follows to a rectangle of pixels, under the transform, intersected with the clip already in force. A shape wholly outside contributes nothing until pop_clip.

Args:

• self (Self)
• x (Int): First column.
• y (Int): First row.
• width (Int): Columns.
• height (Int): Rows.

pop_clip

fn def pop_clip(mut self)

Undo the innermost push_clip; a no-op with none pushed.

Args:

• self (Self)

begin_annotated_group

fn def begin_annotated_group(mut self, title: String)

A label, which draws nothing here.

Args:

• self (Self)
• title (String): Ignored.

end_annotated_group

fn def end_annotated_group(mut self)

Ends a label; nothing to do.

Args:

• self (Self)

begin_batch

fn def begin_batch(mut self)

Nothing is deferred here, so nothing to begin.

Args:

• self (Self)

end_batch

fn def end_batch(mut self)

Nothing was deferred, so nothing to draw.

Args:

• self (Self)

save

fn def save(mut self)

Record the transform, blend mode, color space and clip depth for restore.

Args:

• self (Self)

restore

fn def restore(mut self)

Put back what the matching save recorded, popping any clip pushed since. A no-op with nothing saved.

Args:

• self (Self)

translate

fn def translate(mut self, tx: Float64, ty: Float64)

Shift user space.

Args:

• self (Self)
• tx (Float64): Horizontal shift.
• ty (Float64): Vertical shift.

rotate

fn def rotate(mut self, angle: Float64)

Rotate user space about its origin.

Args:

• self (Self)
• angle (Float64): Radians.

scale

fn def scale(mut self, sx: Float64, sy: Float64)

Scale user space.

Args:

• self (Self)
• sx (Float64): Horizontal factor.
• sy (Float64): Vertical factor.

transform

fn def transform(mut self, matrix: Matrix2D)

Compose matrix before the current transform, the order Canvas.transform composes in.

Args:

• self (Self)
• matrix (Matrix2D): The map to apply first.

set_transform

fn def set_transform(mut self, matrix: Matrix2D)

Replace the transform.

Args:

• self (Self)
• matrix (Matrix2D): The new map from user space to page pixels.

reset_transform

fn def reset_transform(mut self)

Back to the identity.

Args:

• self (Self)

current_transform

fn def current_transform(self) -> Matrix2D

The transform in force.

Args:

• self (Self)

Returns:

Matrix2D: The current transform; the identity if none is set.

has_transform

fn def has_transform(self) -> Bool

Whether the transform is anything but the identity.

Args:

• self (Self)

Returns:

Bool: True if a transform is in force.

set_blend_mode

fn def set_blend_mode(mut self, mode: BlendMode)

Carried for save/restore; every mode counts as ink.

Args:

• self (Self)
• mode (BlendMode): The mode to record.

blend_mode

fn def blend_mode(self) -> BlendMode

The recorded blend mode.

Args:

• self (Self)

Returns:

BlendMode: The mode last set, SOURCE_OVER by default.

set_color_space

fn def set_color_space(mut self, space: ColorSpace)

Carried for save/restore; the space changes no extent.

Args:

• self (Self)
• space (ColorSpace): The space to record.

color_space

fn def color_space(self) -> ColorSpace

The recorded color space.

Args:

• self (Self)

Returns:

ColorSpace: The space last set, SRGB by default.