API referencestd/graphics

std/graphics

Public declarations, types, methods, and source contracts for std/graphics.

On this page

Library guide · API index and notation

This page is generated from the bundled library in this checkout. Signatures and adjacent source comments are reproduced below; the linked guide explains usage, storage, failures, and platform support.

import "std/graphics"

Names used in signatures

Unqualified names denote this package’s types (including other source files in the same package), language built-ins, or generic parameters such as T. Qualified names use the import aliases below. These aliases belong to the library source; import a dependency yourself to use its alias in your program.

Alias Package Source file
bytes core/bytes graphics.dodo
mem core/mem graphics.dodo
num core/num graphics.dodo

Error

Enum · Source

pub enum Error {
    // An argument is outside what the operation accepts, such as a stride
    // shorter than one row or a dimension above MAX_DIMENSION.
    InvalidInput,
    // The pixel storage or output buffer is shorter than required.
    BufferTooSmall,
    // The pixel format, file variant or feature is not implemented.
    Unsupported,
    // A display or its bus failed while presenting.
    Device
}

error_name

Function · Source

pub fn error_name(error: Error) -> &str from(static)

PixelFormat

Enum · Source

Memory layout of one pixel.

pub enum PixelFormat {
    // Four bytes per pixel in the order red, green, blue, alpha.
    Rgba8888,
    // Four bytes per pixel in the order blue, green, red, alpha, the native
    // 32-bit layout of Windows DIBs, macOS bitmaps and X11 on little-endian.
    Bgra8888,
    // Two bytes per pixel, 5 bits red, 6 green, 5 blue, high byte first: the
    // order SPI panels such as the ST7789 and ILI9341 receive.
    Rgb565,
    // One luminance byte per pixel.
    Gray8,
    // One bit per pixel, eight pixels per byte with the leftmost in the most
    // significant bit; each row starts on a byte boundary. A set bit is on
    // (white).
    Mono1
}

MAX_DIMENSION

Constant · Source

The largest accepted width or height. Keeping both well inside i32 lets every edge computation use plain checked integer arithmetic.

pub const MAX_DIMENSION: u32 = 16777216

bits_per_pixel

Function · Source

Bits used by one pixel: 32, 16, 8 or 1.

pub fn bits_per_pixel(format: PixelFormat) -> u32

min_stride

Function · Source

Bytes in one tightly packed row, or the largest usize if it does not fit.

pub fn min_stride(width: u32, format: PixelFormat) -> usize

bytes_needed

Function · Source

Bytes a tightly packed width x height canvas needs, or the largest usize if the size does not fit in memory. Size static storage or an allocation with it.

pub fn bytes_needed(width: u32, height: u32, format: PixelFormat) -> usize

canvas

Function · Source

A canvas over pixels with tightly packed rows; see Canvas.new.

pub fn canvas(pixels: &mut[u8], width: u32, height: u32, format: PixelFormat) -> Canvas!Error from(pixels)

Color

Type alias · Source

A color as 0xAARRGGBB: alpha in the top byte, then red, green and blue. Colors are plain integers so they copy freely into every drawing call.

pub type Color = u32

TRANSPARENT

Constant · Source

pub const TRANSPARENT: Color = 0x00000000

BLACK

Constant · Source

pub const BLACK: Color = 0xff000000

WHITE

Constant · Source

pub const WHITE: Color = 0xffffffff

RED

Constant · Source

pub const RED: Color = 0xffff0000

GREEN

Constant · Source

pub const GREEN: Color = 0xff00ff00

BLUE

Constant · Source

pub const BLUE: Color = 0xff0000ff

YELLOW

Constant · Source

pub const YELLOW: Color = 0xffffff00

CYAN

Constant · Source

pub const CYAN: Color = 0xff00ffff

MAGENTA

Constant · Source

pub const MAGENTA: Color = 0xffff00ff

GRAY

Constant · Source

pub const GRAY: Color = 0xff808080

DARK_GRAY

Constant · Source

pub const DARK_GRAY: Color = 0xff404040

LIGHT_GRAY

Constant · Source

pub const LIGHT_GRAY: Color = 0xffc0c0c0

rgb

Function · Source

An opaque color from its channels.

pub fn rgb(red: u8, green: u8, blue: u8) -> Color

rgba

Function · Source

A color with an explicit alpha; 0 is fully transparent, 255 opaque.

pub fn rgba(red: u8, green: u8, blue: u8, alpha: u8) -> Color

hex

Function · Source

An opaque color from 0xRRGGBB, as written in CSS. Bits above the low 24 are ignored.

pub fn hex(value: u32) -> Color

red

Function · Source

pub fn red(color: Color) -> u8

green

Function · Source

pub fn green(color: Color) -> u8

blue

Function · Source

pub fn blue(color: Color) -> u8

alpha

Function · Source

pub fn alpha(color: Color) -> u8

with_alpha

Function · Source

The same color with its alpha replaced.

pub fn with_alpha(color: Color, alpha: u8) -> Color

luma

Function · Source

Perceived brightness, 0 to 255, using integer BT.601 weights. Gray8 and Mono1 canvases store this value (Mono1 lights pixels from 128 up).

pub fn luma(color: Color) -> u8

over

Function · Source

top composited over bottom (source-over). Both are straight, not premultiplied, colors.

pub fn over(top: Color, bottom: Color) -> Color

Point

Struct · Source

pub struct Point {
    pub x: i32
    pub y: i32
}

Point.new

Function · Source

pub fn new(x: i32, y: i32) -> Point

Point.clone

Function · Source

pub fn clone(&self) -> Point

Point.equals

Function · Source

pub fn equals(&self, other: &Point) -> bool

Size

Struct · Source

pub struct Size {
    pub width: u32
    pub height: u32
}

Size.new

Function · Source

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

Size.clone

Function · Source

pub fn clone(&self) -> Size

Size.equals

Function · Source

pub fn equals(&self, other: &Size) -> bool

Size.is_empty

Function · Source

pub fn is_empty(&self) -> bool

Rect

Struct · Source

An axis-aligned rectangle covering columns x..x+width and rows y..y+height, end exclusive. A rectangle with zero width or height is empty.

pub struct Rect {
    pub x: i32
    pub y: i32
    pub width: u32
    pub height: u32
}

Rect.new

Function · Source

pub fn new(x: i32, y: i32, width: u32, height: u32) -> Rect

Rect.empty

Function · Source

pub fn empty() -> Rect

Rect.clone

Function · Source

pub fn clone(&self) -> Rect

Rect.equals

Function · Source

Field-wise equality; two differently placed empty rectangles differ.

pub fn equals(&self, other: &Rect) -> bool

Rect.is_empty

Function · Source

pub fn is_empty(&self) -> bool

Rect.size

Function · Source

pub fn size(&self) -> Size

Rect.right

Function · Source

One past the last column, which may exceed the i32 range.

pub fn right(&self) -> i64

Rect.bottom

Function · Source

One past the last row, which may exceed the i32 range.

pub fn bottom(&self) -> i64

Rect.contains

Function · Source

pub fn contains(&self, x: i32, y: i32) -> bool

Rect.intersect

Function · Source

The overlap of both rectangles, or Rect.empty() if they do not overlap.

pub fn intersect(&self, other: &Rect) -> Rect

Rect.union

Function · Source

The smallest rectangle containing both. An empty operand is ignored; a result wider than u32 saturates.

pub fn union(&self, other: &Rect) -> Rect

Rect.offset

Function · Source

The same rectangle moved by (dx, dy), saturating at the i32 range.

pub fn offset(&self, dx: i32, dy: i32) -> Rect

Font

Struct · Source

A fixed-width bitmap font. Glyphs are stored for consecutive code points starting at first, each glyph_height rows of ceil(glyph_width / 8) bytes, leftmost pixel in the most significant bit. The cell includes any spacing, so text advances by exactly glyph_width * scale per character. Characters outside the font draw as an outlined replacement box.

pub struct Font {
    // Private implementation fields omitted.
}

Font.new

Function · Source

Fails with InvalidInput for a zero or above-256 glyph dimension or a zero count, and BufferTooSmall when bitmap is shorter than count * glyph_height * ceil(glyph_width / 8) bytes.

pub fn new(glyph_width: u32, glyph_height: u32, first: u32, count: u32, bitmap: &[u8]) -> Font!Error from(bitmap)

Font.scaled

Function · Source

The same font drawn factor times larger in both directions. Factors are limited to 1 through 64; 0 is treated as 1.

pub fn scaled(self, factor: u32) -> Font

Font.scale

Function · Source

pub fn scale(&self) -> u32

Font.advance

Function · Source

Horizontal distance between characters, in canvas pixels.

pub fn advance(&self) -> u32

Font.line_height

Function · Source

Vertical distance between lines, in canvas pixels.

pub fn line_height(&self) -> u32

Font.has_glyph

Function · Source

pub fn has_glyph(&self, code_point: u32) -> bool

Font.measure

Function · Source

The size text covers: the longest line times the advance, and the line count times the line height. “\n” starts a line; “\r” is ignored.

pub fn measure(&self, text: &str) -> Size

Canvas

Struct · Source

A drawing surface over borrowed pixel storage. Row y starts at byte y * stride. Every drawing call is limited to the clip rectangle, which starts as the whole canvas, and grows the dirty rectangle to cover the pixels it wrote. Displays present only the dirty part; take_dirty() reads and resets it.

A canvas normally covers a surface from (0, 0). set_origin places it at another point of a larger surface, such as one band of a screen: drawing, clip, dirty and color_at coordinates are then surface coordinates, and the canvas stores only its width x height pixels from the origin.

pub struct Canvas {
    // Private implementation fields omitted.
}

Canvas.new

Function · Source

A canvas with tightly packed rows. Fails with InvalidInput when a dimension exceeds MAX_DIMENSION and BufferTooSmall when pixels is shorter than bytes_needed(width, height, format). Extra bytes are unused. The pixels keep their contents and the dirty rectangle starts empty.

pub fn new(pixels: &mut[u8], width: u32, height: u32, format: PixelFormat) -> Canvas!Error from(pixels)

Canvas.with_stride

Function · Source

A canvas whose rows are stride bytes apart, for storage with padded rows such as a window system’s shared buffer. The stride must be at least min_stride(width, format); pixels must hold stride * height bytes.

pub fn with_stride(pixels: &mut[u8], width: u32, height: u32, stride: usize, format: PixelFormat) -> Canvas!Error from(pixels)

Canvas.width

Function · Source

pub fn width(&self) -> u32

Canvas.height

Function · Source

pub fn height(&self) -> u32

Canvas.size

Function · Source

pub fn size(&self) -> Size

Canvas.bounds

Function · Source

The area of the surface the canvas covers: its size at its origin.

pub fn bounds(&self) -> Rect

Canvas.set_origin

Function · Source

Place the canvas’s top-left pixel at (x, y) of the surface, each clamped to +/-2^28. The pixels keep their contents, the clip resets to the new bounds and the dirty rectangle to empty.

pub fn set_origin(&mut self, x: i32, y: i32)

Canvas.format

Function · Source

pub fn format(&self) -> PixelFormat

Canvas.stride

Function · Source

Bytes from the start of one row to the next.

pub fn stride(&self) -> usize

Canvas.pixels

Function · Source

The canvas bytes, stride * height of them, for presenting or encoding. Byte offsets count from the canvas’s top-left pixel, wherever its origin is.

pub fn pixels(&self) -> &[u8] from(self)

Canvas.row

Function · Source

The bytes of the canvas’s row y, counted from its top edge (surface row y + bounds().y), exactly min_stride(width, format) long. Panics when y >= height.

pub fn row(&self, y: u32) -> &[u8] from(self)

Canvas.clip

Function · Source

pub fn clip(&self) -> Rect

Canvas.set_clip

Function · Source

Limit drawing to rect, intersected with the canvas.

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

Canvas.reset_clip

Function · Source

pub fn reset_clip(&mut self)

Canvas.dirty

Function · Source

The smallest rectangle covering every pixel drawn since the last take_dirty(), or an empty rectangle.

pub fn dirty(&self) -> Rect

Canvas.take_dirty

Function · Source

Return the dirty rectangle and reset it to empty.

pub fn take_dirty(&mut self) -> Rect

Canvas.mark_dirty

Function · Source

Add rect, limited to the canvas, to the dirty rectangle: for pixels changed through other means, or to retry a failed present.

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

Canvas.mark_all_dirty

Function · Source

Mark the whole canvas dirty.

pub fn mark_all_dirty(&mut self)

Canvas.color_at

Function · Source

The color at (x, y), or none outside the canvas. Formats without alpha read as opaque; Rgb565 channels are widened by repeating their high bits.

pub fn color_at(&self, x: i32, y: i32) -> Option<Color>

Canvas.clear

Function · Source

Fill the clip rectangle (the whole canvas unless set_clip was called).

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

Canvas.pixel

Function · Source

Set one pixel. Colors are stored, not blended; see blend_rect.

pub fn pixel(&mut self, x: i32, y: i32, color: Color)

Canvas.line

Function · Source

A one pixel wide line including both end points. Pixel rows (or columns, for steep lines) follow the exact line, rounding half up.

pub fn line(&mut self, x0: i32, y0: i32, x1: i32, y1: i32, color: Color)

Canvas.rect

Function · Source

The one pixel wide outline of a width x height rectangle.

pub fn rect(&mut self, x: i32, y: i32, width: u32, height: u32, color: Color)

Canvas.fill_rect

Function · Source

pub fn fill_rect(&mut self, x: i32, y: i32, width: u32, height: u32, color: Color)

Canvas.fill

Function · Source

fill_rect for a Rect value, such as the bounds text() returned.

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

Canvas.blend_rect

Function · Source

Composite color over the pixels of a rectangle using its alpha.

pub fn blend_rect(&mut self, x: i32, y: i32, width: u32, height: u32, color: Color)

Canvas.round_rect

Function · Source

A rectangle outline with corners rounded to radius, limited to half the shorter side.

pub fn round_rect(&mut self, x: i32, y: i32, width: u32, height: u32, radius: u32, color: Color)

Canvas.fill_round_rect

Function · Source

pub fn fill_round_rect(&mut self, x: i32, y: i32, width: u32, height: u32, radius: u32, color: Color)

Canvas.circle

Function · Source

A one pixel wide circle outline. Radius r spans 2r + 1 pixels centred on (cx, cy) and covers the pixel centres within r + 1/2 of it.

pub fn circle(&mut self, cx: i32, cy: i32, radius: u32, color: Color)

Canvas.fill_circle

Function · Source

pub fn fill_circle(&mut self, cx: i32, cy: i32, radius: u32, color: Color)

Canvas.ellipse

Function · Source

An axis-aligned ellipse outline spanning 2rx + 1 by 2ry + 1 pixels. Radii above 16383 are clamped.

pub fn ellipse(&mut self, cx: i32, cy: i32, rx: u32, ry: u32, color: Color)

Canvas.fill_ellipse

Function · Source

pub fn fill_ellipse(&mut self, cx: i32, cy: i32, rx: u32, ry: u32, color: Color)

Canvas.polygon

Function · Source

The closed outline through the vertices in coordinates, given as x, y pairs (x0, y0, x1, y1, …): a line from each vertex to the next and from the last back to the first. A trailing unpaired value is ignored.

pub fn polygon(&mut self, coordinates: &[i32], color: Color)

Canvas.fill_polygon

Function · Source

Fill the inside of the polygon through coordinates (x, y pairs) by the even-odd rule: a pixel is filled when its centre is enclosed by an odd number of edges. Self-intersecting outlines and holes traced in either direction work. Needs at least three vertices.

pub fn fill_polygon(&mut self, coordinates: &[i32], color: Color)

Canvas.blit

Function · Source

Copy all of source with its top-left corner at (x, y), converting the pixel format if needed. Alpha is copied, not blended.

pub fn blit(&mut self, source: &Canvas, x: i32, y: i32)

Canvas.blit_region

Function · Source

Copy region of source, in the source’s coordinates, with its top-left corner at (x, y).

pub fn blit_region(&mut self, source: &Canvas, region: Rect, x: i32, y: i32)

Canvas.blend

Function · Source

Composite all of source over this canvas at (x, y) using the source alpha (source-over). Sources without alpha are opaque, like blit.

pub fn blend(&mut self, source: &Canvas, x: i32, y: i32)

Canvas.blend_region

Function · Source

pub fn blend_region(&mut self, source: &Canvas, region: Rect, x: i32, y: i32)

Canvas.text

Function · Source

Draw text with its top-left corner at (x, y) and return the area its character cells cover, the same size font.measure(text) reports, even where clipping hid them. Only set glyph pixels are drawn; fill the returned bounds first for an opaque background. “\n” returns to x on the next line and “\r” is ignored.

pub fn text(&mut self, font: &Font, x: i32, y: i32, text: &str, color: Color) -> Rect

Canvas.fill_outline

Function · Source

Fill outline by rule with color.

pub fn fill_outline<O: Outline>(&mut self, outline: &O, rule: FillRule, color: Color)

Canvas.fill_path

Function · Source

Fill a stored path by rule with color.

pub fn fill_path(&mut self, path: &Path, rule: FillRule, color: Color)

Canvas.gradient_outline

Function · Source

Fill outline by rule with a gradient.

pub fn gradient_outline<O: Outline>(&mut self, outline: &O, rule: FillRule, gradient: &Gradient)

Canvas.gradient_path

Function · Source

pub fn gradient_path(&mut self, path: &Path, rule: FillRule, gradient: &Gradient)

Canvas.stroke_outline

Function · Source

Stroke outline with style in color: paint the band of the stroke’s width along it, with the style’s joins, caps and dashes.

pub fn stroke_outline<O: Outline>(&mut self, outline: &O, style: &Stroke, color: Color)

Canvas.stroke_path

Function · Source

Stroke a stored path with style in color.

pub fn stroke_path(&mut self, path: &Path, style: &Stroke, color: Color)

Canvas.gradient_stroke_outline

Function · Source

Stroke outline with style, painted with a gradient.

pub fn gradient_stroke_outline<O: Outline>(&mut self, outline: &O, style: &Stroke, gradient: &Gradient)

Canvas.gradient_stroke_path

Function · Source

pub fn gradient_stroke_path(&mut self, path: &Path, style: &Stroke, gradient: &Gradient)

Canvas.gradient_rect

Function · Source

Fill a width x height rectangle with a gradient.

pub fn gradient_rect(&mut self, x: i32, y: i32, width: u32, height: u32, gradient: &Gradient)

Canvas.aa_line

Function · Source

A one pixel wide line between the centres of pixels (x0, y0) and (x1, y1), with square ends reaching the outer edges of both pixels. Horizontal and vertical lines cover exactly the pixels line() draws.

pub fn aa_line(&mut self, x0: i32, y0: i32, x1: i32, y1: i32, color: Color)

Canvas.aa_thick_line

Function · Source

A line width pixels wide between the centres of pixels (x0, y0) and (x1, y1), with round ends centred on them.

pub fn aa_thick_line(&mut self, x0: i32, y0: i32, x1: i32, y1: i32, width: u32, color: Color)

Canvas.aa_fill_circle

Function · Source

A disk of radius + 1/2 pixels around the centre of pixel (cx, cy), the area fill_circle approximates with whole pixels.

pub fn aa_fill_circle(&mut self, cx: i32, cy: i32, radius: u32, color: Color)

Canvas.aa_circle

Function · Source

The one pixel wide ring between radius - 1/2 and radius + 1/2, the area circle() approximates.

pub fn aa_circle(&mut self, cx: i32, cy: i32, radius: u32, color: Color)

Canvas.aa_fill_ellipse

Function · Source

pub fn aa_fill_ellipse(&mut self, cx: i32, cy: i32, rx: u32, ry: u32, color: Color)

Canvas.aa_ellipse

Function · Source

pub fn aa_ellipse(&mut self, cx: i32, cy: i32, rx: u32, ry: u32, color: Color)

Canvas.aa_fill_round_rect

Function · Source

A width x height rectangle with exactly round corners of radius pixels, limited to half the shorter side.

pub fn aa_fill_round_rect(&mut self, x: i32, y: i32, width: u32, height: u32, radius: u32, color: Color)

Canvas.aa_round_rect

Function · Source

The one pixel wide outline along the inside of aa_fill_round_rect.

pub fn aa_round_rect(&mut self, x: i32, y: i32, width: u32, height: u32, radius: u32, color: Color)

Canvas.aa_fill_polygon

Function · Source

The polygon through coordinates (x, y pairs of pixel corners, as for fill_polygon), filled by the even-odd rule. Vertices are clamped to +/-2^21. Needs at least three vertices.

pub fn aa_fill_polygon(&mut self, coordinates: &[i32], color: Color)

Canvas.fill_mask

Function · Source

Composite color over the canvas through a coverage mask: mask holds width x height levels, one byte per pixel in rows of width bytes, from 0 (untouched) to 255 (fully covered), as coverage_mask writes them. The mask’s top-left pixel lands on (x, y). Each pixel is blended exactly as fill_outline blends one with that coverage, so filling an outline and filling its mask draw the same pixels. Rows past the end of mask are skipped.

pub fn fill_mask(&mut self, mask: &[u8], width: u32, height: u32, x: i32, y: i32, color: Color)

Canvas.fill_spans

Function · Source

fill_mask for spans from coverage_spans: the same pixels, drawn faster. width and height are the area the spans were made for.

pub fn fill_spans(&mut self, spans: &[u8], width: u32, height: u32, x: i32, y: i32, color: Color)

Canvas.gradient_spans

Function · Source

gradient_mask for spans from coverage_spans.

pub fn gradient_spans(&mut self, spans: &[u8], width: u32, height: u32, x: i32, y: i32, gradient: &Gradient)

Canvas.gradient_mask

Function · Source

fill_mask with a gradient instead of a color, blended as gradient_outline blends.

pub fn gradient_mask(&mut self, mask: &[u8], width: u32, height: u32, x: i32, y: i32, gradient: &Gradient)

Canvas.equals

Function · Source

True when both canvases have the same size and every pixel decodes to the same color. Formats and origins may differ; padding bytes are ignored.

pub fn equals(&self, other: &Canvas) -> bool

Canvas.diff_bounds

Function · Source

The smallest rectangle covering every pixel whose color differs, or an empty rectangle. Pixels present in only one canvas count as different. Origins are ignored: both canvases are compared from their top-left pixels, and the rectangle is relative to them.

pub fn diff_bounds(&self, other: &Canvas) -> Rect

Display

Interface · Source

Anything that can show a canvas: a window, an SPI or I2C panel, or the in-memory std/graphics/fake display. Drawing code generic over Display runs unchanged on all of them.

Display coordinates are surface coordinates: a canvas covers canvas.bounds() of the display, the whole display when it has the display’s size and no origin, or one part of it, such as a band from Bands. Only the part of a presented rectangle inside both the canvas and the display is shown; the rest is ignored, as drawing ignores pixels outside a canvas.

pub interface Display {
    // Pixel size of the whole display.
    fn size(&self) -> Size
    // The pixel format it reads most efficiently. Others are converted.
    fn format(&self) -> PixelFormat
    // Show `dirty` from `canvas`. Pixels outside it may or may not be
    // transferred.
    fn present(&mut self, canvas: &Canvas, dirty: Rect) -> void!Error
}

present

Function · Source

Present the canvas’s dirty rectangle, if any, and reset it. On failure the rectangle is marked dirty again so the next call retries it.

pub fn present<D: Display>(display: &mut D, canvas: &mut Canvas) -> void!Error

present_all

Function · Source

Present the whole canvas regardless of its dirty rectangle, then reset it.

pub fn present_all<D: Display>(display: &mut D, canvas: &mut Canvas) -> void!Error

Bands

Struct · Source

Draws a screen taller than the memory for its pixels one horizontal band at a time. A 320x240 RGB565 frame needs 153,600 bytes, more than half an RP2040’s RAM; a 320x40 band needs 25,600. Each call to next moves a canvas one band down the screen with set_origin, so drawing code keeps using screen coordinates and the canvas keeps only what falls inside the band:

pixels := [0u8; 320 * 40 * 2] band := graphics.canvas(&mut pixels, 320, 40, graphics.PixelFormat.Rgb565)? bands := graphics.Bands.new(240) for bands.next(&mut band) { draw_screen(&mut band, &state) graphics.present_all(&mut lcd, &mut band)? }

The scene is drawn once per band, so the work grows with the band count; pick the tallest band the memory allows. Displays ignore the part of a last band that hangs below the screen.

pub struct Bands {
    // Private implementation fields omitted.
}

Bands.new

Function · Source

Bands covering a screen screen_height pixels tall from row 0.

pub fn new(screen_height: u32) -> Bands

Bands.next

Function · Source

Move canvas to the left edge of the next band, resetting its clip and dirty rectangle, and return true; after the last band, return false and start over, so the same Bands draws the next frame. A canvas with no rows covers nothing and returns false.

pub fn next(&mut self, canvas: &mut Canvas) -> bool

Bands.restart

Function · Source

Start the next frame from the top even if this one was cut short.

pub fn restart(&mut self)

SUBPIXEL

Constant · Source

Path, Pen and Outline coordinates are fixed point with SUBPIXEL units to the pixel: 256 is one pixel, 128 half a pixel. The pixel (x, y) covers x * 256 .. (x + 1) * 256 horizontally, so its centre is x * 256 + 128.

pub const SUBPIXEL: i32 = 256

FillRule

Enum · Source

Which parts of a self-overlapping outline are inside.

pub enum FillRule {
    // Inside where the outline winds around a point at least once in either
    // direction; overlapping contours merge. TrueType glyphs use this rule.
    NonZero,
    // Inside where a ray from the point crosses the outline an odd number of
    // times, so a contour inside another cuts a hole whatever its direction.
    EvenOdd
}

Outline

Interface · Source

A shape that can describe itself to a Pen. The rasterizer calls trace several times per drawing call: once to find the bounds, then once per band of rows (one band unless more than 256 edges cross the visible rows), and once per 256 columns of a row crossed by more than 256 edges. trace must describe the same outline every time. Implement it to draw procedural shapes without storing them; a Path stores commands for shapes built up front.

pub interface Outline {
    fn trace(&self, pen: &mut Pen)
}

Pen

Struct · Source

Receives an outline as move, line, curve and close commands in subpixel coordinates. Contours close themselves: move_to and the end of a trace close an open contour with a straight line to its start. Inside a Stroked outline the commands trace the centre line of a stroke instead, and open contours stay open.

A pen works in one of three modes. Measuring finds the bounds from the points and control points alone. Collecting flattens the outline once into the straight edges that cross a band of rows, which the canvas then sweeps row by row, computing coverage only next to edges. Dense rasterizes one pass of one row straight into the cells; it is the fallback for a row crossed by more edges than a band holds.

pub struct Pen {
    // Private implementation fields omitted.
}

Pen.move_to

Function · Source

Start a new contour at (x, y), closing the current one.

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

Pen.line_to

Function · Source

A straight edge from the current point to (x, y). Without a preceding move_to, the contour starts at the current point, initially (0, 0).

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

Pen.quad_to

Function · Source

A quadratic Bezier curve through control point (cx, cy) to (x, y).

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

Pen.cubic_to

Function · Source

A cubic Bezier curve through control points (c1x, c1y) and (c2x, c2y) to (x, y).

pub fn cubic_to(&mut self, c1x: i32, c1y: i32, c2x: i32, c2y: i32, x: i32, y: i32)

Pen.close

Function · Source

Close the current contour with a straight edge back to its start.

pub fn close(&mut self)

outline_bounds

Function · Source

The pixels outline may cover: the smallest rectangle of whole pixels around every point it passes through, or an empty rectangle for an outline with no points. Size a mask for coverage_mask with it.

pub fn outline_bounds<O: Outline>(outline: &O) -> Rect

coverage_mask

Function · Source

Rasterize outline by rule into a coverage mask instead of a canvas: mask receives the coverage of the width x height pixels whose top-left pixel is (x, y), one byte per pixel in rows of width bytes, from 0 to 255. Pixels the outline misses are set to 0, and rows past the end of mask are skipped. The levels are the ones fill_outline blends with, so a mask drawn with Canvas.fill_mask matches filling the outline. Because coverage depends only on where the outline lies relative to the pixel grid, a mask made once can be drawn again anywhere the outline would be moved by whole pixels.

pub fn coverage_mask<O: Outline>(outline: &O, rule: FillRule, mask: &mut[u8], x: i32, y: i32, width: u32, height: u32)

spans_bound

Function · Source

The bytes coverage_spans needs for a width x height area: room for the mask itself and for its spans, which may be larger than the mask.

pub fn spans_bound(width: u32, height: u32) -> usize

coverage_spans

Function · Source

coverage_mask stored as spans for Canvas.fill_spans and gradient_spans. buffer must hold spans_bound(width, height) bytes; the coverage is rasterized into its end and encoded in place at its start. Returns the length of the spans, or 0 when buffer is too small or the area is empty. A typical glyph’s spans are a fraction of its mask.

pub fn coverage_spans<O: Outline>(outline: &O, rule: FillRule, buffer: &mut[u8], x: i32, y: i32, width: u32, height: u32) -> usize

Path

Struct · Source

An outline stored as commands in caller-owned i32 words, in subpixel coordinates. A move or line takes 3 words, a quadratic curve 5, a cubic 7, a close 1; the shape helpers add whole closed contours. Building a path cannot fail: when a command does not fit, the path is marked overflowed, keeps no further commands, and draws nothing.

storage := [0i32; 256] path := graphics.Path.new(&mut storage) path.move_to(10 * graphics.SUBPIXEL, 0) path.quad_to(20 * graphics.SUBPIXEL, 20 * graphics.SUBPIXEL, 0, 20 * graphics.SUBPIXEL) path.close() canvas.fill_path(&path, graphics.FillRule.NonZero, graphics.WHITE)

pub struct Path {
    // Private implementation fields omitted.
}

Path.new

Function · Source

pub fn new(storage: &mut[i32]) -> Path from(storage)

Path.clear

Function · Source

Remove every command and the overflow mark.

pub fn clear(&mut self)

Path.len

Function · Source

Storage words in use.

pub fn len(&self) -> usize

Path.is_empty

Function · Source

pub fn is_empty(&self) -> bool

Path.overflowed

Function · Source

True when a command did not fit; the path then draws nothing.

pub fn overflowed(&self) -> bool

Path.move_to

Function · Source

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

Path.line_to

Function · Source

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

Path.quad_to

Function · Source

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

Path.cubic_to

Function · Source

pub fn cubic_to(&mut self, c1x: i32, c1y: i32, c2x: i32, c2y: i32, x: i32, y: i32)

Path.close

Function · Source

pub fn close(&mut self)

Path.rect

Function · Source

A closed rectangle contour with its top-left corner at (x, y).

pub fn rect(&mut self, x: i32, y: i32, width: i32, height: i32)

Path.round_rect

Function · Source

A closed rectangle contour with corners rounded to radius, limited to half the shorter side.

pub fn round_rect(&mut self, x: i32, y: i32, width: i32, height: i32, radius: i32)

Path.ellipse

Function · Source

A closed ellipse contour centred on (cx, cy).

pub fn ellipse(&mut self, cx: i32, cy: i32, rx: i32, ry: i32)

Path.circle

Function · Source

pub fn circle(&mut self, cx: i32, cy: i32, radius: i32)

Path.trace

Function · Source

Describe the stored commands to pen; nothing once overflowed.

pub fn trace(&self, pen: &mut Pen)

LineJoin

Enum · Source

How a stroke turns a corner between two segments.

pub enum LineJoin {
    // Extend the outer edges until they meet, or bevel the corner where
    // that would reach further than the miter limit.
    Miter,
    // An arc of the half width around the corner.
    Round,
    // A straight edge across the corner.
    Bevel
}

LineCap

Enum · Source

How a stroke ends at each end of an open subpath and of every dash.

pub enum LineCap {
    // Flat, at the end point.
    Butt,
    // A half disk of the half width around the end point.
    Round,
    // Flat, half the width beyond the end point.
    Square
}

STROKE_DASHES

Constant · Source

The most dash lengths a stroke holds; set_dashes ignores more.

pub const STROKE_DASHES: usize = 16

Stroke

Struct · Source

How to stroke an outline: its width, joins, caps and dash pattern. Lengths are in subpixels, like path coordinates. The defaults are those of SVG and HTML canvas: miter joins with a limit of 4, butt caps, solid.

style := graphics.Stroke.new(3 * graphics.SUBPIXEL) style.set_join(graphics.LineJoin.Round) dashes := [6 * graphics.SUBPIXEL, 3 * graphics.SUBPIXEL] style.set_dashes(&dashes, 0) canvas.stroke_path(&path, &style, graphics.WHITE)

pub struct Stroke {
    // Private implementation fields omitted.
}

Stroke.new

Function · Source

A solid stroke width subpixels wide, centred on the outline. A width of zero or less draws nothing; widths are limited to 2^30.

pub fn new(width: i32) -> Stroke

Stroke.width

Function · Source

pub fn width(&self) -> i32

Stroke.set_join

Function · Source

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

Stroke.set_cap

Function · Source

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

Stroke.set_miter_limit

Function · Source

The longest a miter may reach from its corner, as a ratio of the miter’s length to the stroke width in SUBPIXEL units: 1024 (the default) is 4, which bevels corners sharper than about 29 degrees. Clamped to 256 (1, always bevel) to 16384 (64).

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

Stroke.set_dashes

Function · Source

Dash the stroke: pattern alternates the lengths of dashes and gaps, starting with a dash, and repeats along each subpath from offset into it. An odd count is repeated to make it even, as in SVG, and at most STROKE_DASHES lengths are kept. Zero-length dashes draw only their caps, dots with round caps. A pattern shorter than a quarter pixel in all is scaled up to that, keeping its proportions. A pattern with a negative length, or no positive one, leaves the stroke solid, as do gaps under 1/4096 of the width with round or square caps, which the caps close.

pub fn set_dashes(&mut self, pattern: &[i32], offset: i32)

Stroke.clear_dashes

Function · Source

Make the stroke solid again.

pub fn clear_dashes(&mut self)

Stroke.dash_count

Function · Source

Lengths in the dash pattern, 0 for a solid stroke.

pub fn dash_count(&self) -> usize

Stroked

Struct · Source

An outline’s stroke as an outline of its own, for coverage masks and spans or to combine with other shapes. Fill it by FillRule.NonZero: strokes overlap themselves at every join, and the even-odd rule would cut holes there. Contours are not closed for stroking: an open contour gets caps, and only close joins its end to its start. An outline that is stroked again inside a Stroked is stroked once, by the outer style.

shape := graphics.Stroked.new(&path, &style) graphics.coverage_mask(&shape, graphics.FillRule.NonZero, &mut mask, x, y, w, h)

pub struct Stroked<O: Outline> {
    // Private implementation fields omitted.
}

Stroked.new

Function · Source

pub fn new(outline: &O, style: &Stroke) -> Stroked<O> from(outline, style)

Stroked.trace

Function · Source

pub fn trace(&self, pen: &mut Pen)

GRADIENT_STOPS

Constant · Source

The most color stops a gradient holds; add_stop ignores more.

pub const GRADIENT_STOPS: usize = 8

Spread

Enum · Source

What a gradient paints beyond its end points.

pub enum Spread {
    // Extend the first and last colors.
    Pad,
    // Start again from the first color.
    Repeat,
    // Run back and forth.
    Reflect
}

Gradient

Struct · Source

A linear or radial color gradient for gradient_rect, gradient_path and gradient_outline. Colors are sampled at pixel centres and interpolated in premultiplied alpha, so fading to TRANSPARENT does not darken. Stops sit at offsets from 0 (the start point or centre) to 255 (the end point or radius); two stops at one offset make a hard edge.

sky := graphics.Gradient.linear(0, 0, 0, 99, graphics.hex(0x203a5c), graphics.hex(0xf4a259)) sky.add_stop(160, graphics.hex(0xbc4b51)) canvas.gradient_rect(0, 0, 160, 100, &sky)

pub struct Gradient {
    // Private implementation fields omitted.
}

Gradient.linear

Function · Source

From start at pixel (x0, y0) to end at pixel (x1, y1), constant along lines perpendicular to that direction. If both points are the same pixel, the gradient paints its last stop’s color.

pub fn linear(x0: i32, y0: i32, x1: i32, y1: i32, start: Color, end: Color) -> Gradient

Gradient.radial

Function · Source

From inner at the centre of pixel (cx, cy) to outer at radius pixels from it, constant along circles. A zero radius paints the last stop’s color.

pub fn radial(cx: i32, cy: i32, radius: u32, inner: Color, outer: Color) -> Gradient

Gradient.add_stop

Function · Source

Insert a stop at offset (0 to 255), after any stops already there. A gradient holds at most GRADIENT_STOPS stops; further ones are ignored.

pub fn add_stop(&mut self, offset: u8, color: Color)

Gradient.stop_count

Function · Source

pub fn stop_count(&self) -> usize

Gradient.set_spread

Function · Source

pub fn set_spread(&mut self, spread: Spread)

Gradient.set_dither

Function · Source

Ordered (4x4 Bayer) dithering when drawing on Rgb565 and Mono1 canvases, which trades banding for a fine regular pattern. Other formats store 8 bits per channel and are unaffected.

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

Gradient.color_at

Function · Source

The undithered color at the centre of pixel (x, y).

pub fn color_at(&self, x: i32, y: i32) -> Color

Search every guide, reference page, and API declaration.