Class ui.Canvas

A canvas using Unicode Braille characters for TUI pixel graphics.

Each cell is 2 pixels wide, 4 pixels tall (8 dots per braille character).

Pixel coordinates are 0-based. The origin (0, 0) is at the top-left corner, with x increasing to the right and y increasing downward. Drawing outside the canvas bounds is ignored (no error).

Example usage:

local Canvas = require "terminal.ui.canvas"
local c = Canvas({
  width = 60,
  height = 30,
})
c:set(10, 5)  -- set a pixel at (10, 5)
print(c:render({ print = true }))  -- render the canvas for printing

Methods

ui.canvas:arc (opts) Draw an arc (a portion of an ellipse outline).
ui.canvas:circle (opts) Draw a circle.
ui.canvas:clear () Clear the entire canvas.
ui.canvas:clone () Return a copy of this canvas with identical dimensions and pixel state.
ui.canvas:ellipse (opts) Draw an ellipse.
ui.canvas:get_pixels () Returns the canvas size in pixels.
ui.canvas:get_size () Returns the canvas size in display rows and columns.
ui.canvas:init (opts) Create a new canvas.
ui.canvas:line (opts) Draw a line between two pixels.
ui.canvas:polygon (opts) Draw a polygon from an array of {x, y} points.
ui.canvas:render ([opts={}]) Render the canvas to a single string.
ui.canvas:resize ([rows[, cols]]) Resize the canvas to the given dimensions.
ui.canvas:roll ([rows=0[, cols=0]]) Shift canvas content, wrapping pixels that move beyond one edge onto the opposite edge.
ui.canvas:scroll ([rows=0[, cols=0]]) Shift canvas content, dropping pixels that move beyond the edges.
ui.canvas:set (x, y) Set (illuminate) a pixel.
ui.canvas:unset (x, y) Clear (extinguish) a pixel.


Methods

ui.canvas:arc (opts)
Draw an arc (a portion of an ellipse outline). Walks the ellipse parametrically from angle_start to angle_end (both in radians), always in the direction of increasing angle.

Angle convention: Because the canvas origin is top-left and y increases downward, positive angles go clockwise on screen: 0 points right, pi/2 points down, pi points left, 3*pi/2 points up. This is the opposite of the standard mathematical convention.

Range: angle_end must be >= angle_start. For a full ellipse use angle_end = angle_start + 2*math.pi. Ranges larger than 2*pi are accepted but cause the arc to be traced more than once; since set/unset are idempotent this produces the correct pixels but wastes proportional compute time.

Parameters:

  • opts
    • x integer centre pixel column, 0-based
    • y integer centre pixel row, 0-based
    • rx integer horizontal radius in pixels
    • ry integer vertical radius in pixels
    • angle_start number start angle in radians
    • angle_end number end angle in radians (must be >= angle_start)
    • erase boolean if truthy, unset pixels instead of setting them (default false)
ui.canvas:circle (opts)
Draw a circle. Convenience wrapper around ellipse with equal horizontal and vertical radii.

Parameters:

  • opts
    • x integer centre pixel column, 0-based
    • y integer centre pixel row, 0-based
    • r integer radius in pixels
    • fill boolean if truthy, fill the interior (default false)
    • erase boolean if truthy, unset pixels instead of setting them (default false)
ui.canvas:clear ()
Clear the entire canvas. Fills all cells with the blank state (respects the invert option passed upon instantiation).
ui.canvas:clone ()
Return a copy of this canvas with identical dimensions and pixel state.

Returns:

    Canvas Copy of the canvas
ui.canvas:ellipse (opts)
Draw an ellipse.

Parameters:

  • opts
    • x integer centre pixel column, 0-based
    • y integer centre pixel row, 0-based
    • rx integer horizontal radius in pixels
    • ry integer vertical radius in pixels
    • fill boolean if truthy, fill the interior (default false)
    • erase boolean if truthy, unset pixels instead of setting them (default false)
ui.canvas:get_pixels ()
Returns the canvas size in pixels.

Returns:

  1. number pixel height
  2. number pixel width
ui.canvas:get_size ()
Returns the canvas size in display rows and columns.

Returns:

  1. number rows
  2. number columns
ui.canvas:init (opts)
Create a new canvas. Do not call this method directly, call on the class instead.

Parameters:

  • opts
    • width integer Width in display columns (each column is 2 pixels wide)
    • height integer Height in display rows (each row is 4 pixels tall)
    • invert boolean If true, cleared cells are fully lit instead of empty (default false)

Usage:

    local Canvas = require "terminal.ui.canvas"
local c = Canvas({
  width = 60,
  height = 30,
  invert = false,      -- optional, default is false
})
print(c:get_pixels())  --> 120, 120 (each cell is 2x4 pixels)
ui.canvas:line (opts)
Draw a line between two pixels.

Parameters:

  • opts
    • x1 integer start pixel column, 0-based
    • y1 integer start pixel row, 0-based
    • x2 integer end pixel column, 0-based
    • y2 integer end pixel row, 0-based
    • erase boolean if truthy, unset pixels instead of setting them (default false)
ui.canvas:polygon (opts)
Draw a polygon from an array of {x, y} points. 1 point draws a dot, 2 points draw a line, 3+ points draw a closed polygon by default.

Parameters:

  • opts
    • points table array of {x, y} pixel coordinate pairs (integer), 0-based
    • open boolean if truthy, do not close the path back to the first point (default false)
    • fill boolean if truthy, fill the interior of the polygon (default false)
    • erase boolean if truthy, unset pixels instead of setting them (default false)
ui.canvas:render ([opts={}])
Render the canvas to a single string. Use opts.print = true when writing to a plain terminal or file (e.g. with print or io.write) where cursor positioning is not needed. Omit opts.print (or set it to false) when rendering into a TUI layout where the cursor must return to the top-left of the canvas area after rendering.

Parameters:

  • opts
    • print boolean if truthy, use newline separators with no return sequence (default false)
    • row number first cell row of the viewport (1-based), must be valid (default 1)
    • col number first cell column of the viewport (1-based), must be valid (default 1)
    • rows number number of rows to render (defaults to all rows from opts.row to the bottom) (optional)
    • cols number number of columns to render (defaults to all columns from opts.col to the right) (optional)

Returns:

    string
ui.canvas:resize ([rows[, cols]])
Resize the canvas to the given dimensions. Columns are added or removed on the right; rows are added or removed at the bottom. New cells are filled with the blank state. Existing content within the new bounds is preserved. Dimensions are in display cells: each row is 4 pixels tall, each column is 2 pixels wide.

Parameters:

  • rows integer new height in display rows (1 row = 4 pixels) (optional)
  • cols integer new width in display columns (1 column = 2 pixels) (optional)
ui.canvas:roll ([rows=0[, cols=0]])
Shift canvas content, wrapping pixels that move beyond one edge onto the opposite edge. Positive rows rolls content downward; positive cols rolls content to the right. Offsets are in display cells: each row is 4 pixels tall, each column is 2 pixels wide.

Parameters:

  • rows integer cell rows to roll (negative = up, positive = down; 1 row = 4 pixels) (default 0)
  • cols integer cell columns to roll (negative = left, positive = right; 1 column = 2 pixels) (default 0)
ui.canvas:scroll ([rows=0[, cols=0]])
Shift canvas content, dropping pixels that move beyond the edges. Positive rows shifts content downward; positive cols shifts content to the right. Vacated cells are filled with the blank state. Offsets are in display cells: each row is 4 pixels tall, each column is 2 pixels wide.

Parameters:

  • rows integer cell rows to shift (negative = up, positive = down; 1 row = 4 pixels) (default 0)
  • cols integer cell columns to shift (negative = left, positive = right; 1 column = 2 pixels) (default 0)
ui.canvas:set (x, y)
Set (illuminate) a pixel. Coordinates are 0-based; origin (0, 0) is at the top-left. Out-of-bounds coordinates are ignored (no error).

Parameters:

  • x integer pixel column, 0-based, left to right
  • y integer pixel row, 0-based, top to bottom
ui.canvas:unset (x, y)
Clear (extinguish) a pixel. Coordinates are 0-based; origin (0, 0) is at the top-left. Out-of-bounds coordinates are ignored (no error).

Parameters:

  • x integer pixel column, 0-based, left to right
  • y integer pixel row, 0-based, top to bottom
generated by LDoc 1.5.0