Canvas class

A 2D canvas widget for drawing high-resolution pixel graphics in a terminal.

Sub-pixel 2x4 Dot Masks Rendering

  • Each cell in the terminal grid represents a 2x4 sub-pixel block.
  • It uses a bitmask mapping system (_dotMasks) to target individual sub-pixels (bits 0 to 7 of a byte).
  • Depending on renderMode, sub-pixels are rasterized as Braille patterns (using the Unicode Braille block starting at 0x2800), dense shade blocks (░, ▒, ▓, █), or quadrant characters (▘, ▝, etc.).

Background Snapshot Cache (saveBackground)

  • Calling saveBackground copies the active state of the pixel grid, anti-aliasing attributes, and style overrides into background snapshot arrays.
  • When clear is invoked, the canvas is restored to this snapshotted state instead of blanking out entirely, allowing static backgrounds (e.g. axes, borders) to be cached for fast redraws.

Example Usage

final canvas = Canvas(40, 20, renderMode: CanvasRenderMode.braille);
canvas.drawLine(0, 0, 80, 80, value: true);

// Save as background:
canvas.saveBackground();

// Draw dynamic elements:
canvas.setPixel(10, 10, true);

// Restore background later:
canvas.clear();

Properties and Settings

Property Type Description
width int Canvas width in terminal grid columns.
height int Canvas height in terminal grid rows.
style Style Base style for the canvas cell blocks.
renderMode CanvasRenderMode Pixel mapping mode (braille, density, quadrants).
Inheritance

Constructors

Canvas(int width, int height, {Style style = Style.empty, bool isOccluded(int col, int row)?, CanvasRenderMode renderMode = CanvasRenderMode.braille})
Creates a canvas widget of given width and height.

Properties

hashCode → int
The hash code for this object.
no setterinherited
height → int
Canvas height in terminal grid rows.
final
isOccluded ↔ bool Function(int col, int row)?
Optional callback to check if a specific cell (col, row) is occluded by overlapping elements.
getter/setter pair
key → Key?
The optional key for this widget.
finalinherited
renderMode ↔ CanvasRenderMode
Pixel mapping mode (braille, density, quadrants).
getter/setter pair
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
style → Style
Base style for the canvas cell blocks.
final
width → int
Canvas width in terminal grid columns.
final

Methods

clear() → void
Clears the canvas pixels and runtime anti-aliasing flags. Restores the background snapshot if it exists.
createElement() → Element
Creates an Element to manage this widget's location in the tree.
inherited
drawBox(int x, int y, int width, int height, {bool value = true, bool antiAliased = false, Style? cellStyle}) → void
Draws a box outline in sub-pixel coordinates.
drawCircle(int centerX, int centerY, int radius, {bool value = true, bool antiAliased = false, Style? cellStyle}) → void
Draws a circle outline at (centerX, centerY) with radius in sub-pixel coordinates.
drawEllipse(int centerX, int centerY, int radiusX, int radiusY, {bool value = true, bool antiAliased = false, Style? cellStyle}) → void
Draws an ellipse outline at (centerX, centerY) with radiusX and radiusY in sub-pixel coordinates.
drawLine(int x0, int y0, int x1, int y1, {bool value = true, bool antiAliased = false, Style? cellStyle}) → void
Draws a line from (x0, y0) to (x1, y1) in sub-pixel coordinates.
drawLineColored(int x0, int y0, int x1, int y1, Color c0, Color c1, {bool value = true, bool antiAliased = false}) → void
Draws a line with color interpolated from c0 to c1 in sub-pixel coordinates.
drawLineColoredPacked(int x0, int y0, int x1, int y1, int c0argb, int c1argb, {bool value = true, bool antiAliased = false}) → void
Draws a line with packed ARGB colors interpolated in sub-pixel coordinates.
fillBox(int x, int y, int width, int height, {bool value = true, bool antiAliased = true, Style? cellStyle}) → void
Fills a rectangular box in sub-pixel coordinates.
fillCircle(int centerX, int centerY, int radius, {bool value = true, bool antiAliased = true, Style? cellStyle}) → void
Fills a circle at (centerX, centerY) with radius in sub-pixel coordinates.
fillQuadColored(int x0, int y0, int x1, int y1, int x2, int y2, int x3, int y3, Color c0, Color c1, Color c2, Color c3, {bool value = true, bool antiAliased = false}) → void
Fills a quadrilateral with vertices p0, p1, p2, p3 (ordered around perimeter) and interpolates colors. Splits the quad into two triangles and uses the gap-free scanline triangle rasterizer.
fillTriangleColored(int x0, int y0, int x1, int y1, int x2, int y2, Color c0, Color c1, Color c2, {bool value = true, bool antiAliased = false}) → void
Fills a triangle with vertices (x0, y0), (x1, y1), (x2, y2) and interpolates colors. Uses a scanline fill algorithm to ensure there are no gaps inside the triangle.
getIntrinsicHeight(int width) → int
Computes the intrinsic height of this widget under the given width constraint.
inherited
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
render(Buffer buffer, Rect area) → void
Renders the widget onto the provided buffer within the specified area.
override
saveBackground() → void
Saves the current canvas state as a background snapshot.
setPixel(int px, int py, bool value, {bool antiAliased = false, Style? cellStyle}) → void
Sets pixel at (px, py) relative to canvas coordinates.
toString() → String
A string representation of this object.
inherited

Operators

operator ==(Object other) → bool
The equality operator.
inherited