Struct Canvas 

pub struct Canvas {
    pub width: usize,
    pub height: usize,
    pub final_width: usize,
    pub final_height: usize,
    pub default_color: Color,
    /* private fields */
}

A canvas for drawing to the terminal, like a digital picasso.

The Canvas represents a 3D grid of TerminalPixels that can be drawn to. Each terminal character cell is composed of two half-block pixels (top and bottom). The z coordinate in set_pixel determines the layering (depth). It uses a differential rendering approach to only update the parts of the screen that have changed.

Fields

width: usize

The width of the canvas in terminal character columns.

height: usize

The height of the canvas in terminal character rows.

final_width: usize

The final width of the canvas in terminal character columns.

final_height: usize

The final height of the canvas in terminal character rows.

default_color: Color

The default color used for clearing the canvas and for transparent pixels.

Implementations

impl Canvas

pub fn new(width: usize, height: usize, default_color: Color) -> Canvas

Creates a new Canvas with the given width, height, and default color.

Arguments

• width - The width of the canvas in terminal character columns.
• height - The height of the canvas in terminal character rows.
• default_color - The default background color for the canvas.

Returns

A new Canvas instance.

pub fn clear(&mut self)

Clears the entire canvas to the default_color. All half-block pixels across all z-layers are reset to the default_color.

pub fn set_pixel(&mut self, x: usize, y: usize, z: usize, color: Color)

Sets a half-block pixel at the specified (x, y) coordinate and z-layer with the given color.

Arguments

• x - The terminal column coordinate (0-indexed).
• y - The half-block row coordinate (0-indexed). - y = 0 corresponds to the top half of the first terminal cell row. - y = 1 corresponds to the bottom half of the first terminal cell row. - y = 2 corresponds to the top half of the second terminal cell row, and so on.
• z - The z-layer (depth) of the pixel. Higher z values are drawn on top of lower z values.
• color - The Color to set for the pixel.

pub fn render(&mut self) -> String

Renders the current state of the canvas to a string containing ANSI escape codes.

This function composites all z-layers for each terminal character cell to determine the final top and bottom half-block colors. It then compares this composited state with the previous frame’s state and returns a string containing only the necessary ANSI escape codes to update the terminal, optimizing for minimal output.

Returns

A String containing ANSI escape codes to update the terminal.