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
pixelswith 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
topcomposited overbottom(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, eachglyph_heightrows 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
bitmapis 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
factortimes 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
textcovers: 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
pixelsis 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
stridebytes apart, for storage with padded rows such as a window system’s shared buffer. The stride must be at least min_stride(width, format);pixelsmust 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
colorover 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
sourcewith 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
regionofsource, 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
sourceover 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
textwith 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
outlinebyrulewithcolor.
pub fn fill_outline<O: Outline>(&mut self, outline: &O, rule: FillRule, color: Color)
Canvas.fill_path
Function · Source
Fill a stored path by
rulewithcolor.
pub fn fill_path(&mut self, path: &Path, rule: FillRule, color: Color)
Canvas.gradient_outline
Function · Source
Fill
outlinebyrulewith 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
outlinewithstyleincolor: 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
styleincolor.
pub fn stroke_path(&mut self, path: &Path, style: &Stroke, color: Color)
Canvas.gradient_stroke_outline
Function · Source
Stroke
outlinewithstyle, 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
widthpixels 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
radiuspixels, 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
colorover the canvas through a coverage mask:maskholdswidthxheightlevels, one byte per pixel in rows ofwidthbytes, 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 ofmaskare 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.
widthandheightare 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_heightpixels tall from row 0.
pub fn new(screen_height: u32) -> Bands
Bands.next
Function · Source
Move
canvasto 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
outlinemay 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
outlinebyruleinto a coverage mask instead of a canvas:maskreceives the coverage of the width x height pixels whose top-left pixel is (x, y), one byte per pixel in rows ofwidthbytes, from 0 to 255. Pixels the outline misses are set to 0, and rows past the end ofmaskare 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.
buffermust 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 whenbufferis 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
widthsubpixels 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:
patternalternates the lengths of dashes and gaps, starting with a dash, and repeats along each subpath fromoffsetinto 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
closejoins 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
startat pixel (x0, y0) toendat 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
innerat the centre of pixel (cx, cy) toouteratradiuspixels 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