NAME

Term::Graille - Graphical Display in the terminal using UTF8 Braille characters

SYNOPSIS

my $canvas = Term::Graille->new(
  width  => 72,    # pixel width
  height => 64,    # pixel height
  top=>3,          # row position in terminal (optional,defaults to 1)
  left=>10,        # column position (optional,defaults to 1)
  borderStyle => "double",  # 
);

DESCRIPTION

Inspired by Drawille by asciimoo, which has many variants (including a perl variant Term::Drawille by RHOELZ), this is a clone with a few extras. The goal is to achieve performance and features. with built-in turtle-like graphics, line and curve drawing (Algorithm::Line::Bresenham), scrolling, border setting, and more in development.

FUNCTIONS

my $canvas=Term::Graille->new(%params)

Creates a new canavas; params are width The pixel width, required height the pixel height, required, top terminal row (optional,default 1) left terminal column ( optional,default 1) borderStyle border type (optional,one of 'simple', 'double', 'thin', 'thick' or 'shadow') borderColour border colour ( optional), title Title text for top border,(optional) titleColour Title colour (optional)

$canvas->draw() , $canvas->draw($row, $column)

Draws the canvas to the terminal window. Optional row and column parameters may be passed to position the displayed canvas. If borderStyle is specified, the border is drawn, If title is specified this is added to the top border

$canvas->as_string()

Returns the string containing the canvas of utf8 braille symbols, rows being separated by newline.

$canvas->set($x,$y,$pixelValue)

Sets a particular pixel on (default if $pixelValue not sent) or off.

$canvas->unset($x,$y)

Sets the pixel value at $x,$y to blank

$canvas->pixel($x,$y)

Gets the pixel value at $x,$y

$canvas->clear()

Re-initialises the canvas with blank braille characters

$canvas->line($x1,$y1,$x2,$y2,$value)

Uses Algorithm::Line::Bresenham to draw a line from $x1,$y1 to $x2,$y2. The optional value $value sets or unsets the pixels. If $value is a valid colour (see below) the line will be drawn with that colour.

$canvas->circle($x1,$y1,$radius,$value)

Uses Algorithm::Line::Bresenham to draw a circle centered at $x1,$y1 with radius $radius to $x2,$y2. The optional value $value sets or unsets the pixels. If $value is a valid colour (see below) the line will be drawn with that colour.

$canvas->ellipse_rect($x1,$y1,$x2,$y2,$value)

Uses Algorithm::Line::Bresenham to draw a rectangular ellipse, (an ellipse bounded by a rectangle defined by $x1,$y1,$x2,$y2). The optional value $value sets or unsets the pixels. If $value is a valid colour (see below) the line will be drawn with that colour.

$canvas->quad_bezier($x1,$y1,$x2,$y2,$x3,$y3,$value)

Uses Algorithm::Line::Bresenham to draw a quadratic bezier, defined by end points $x1,$y1,$x3,$y3) and control point $x2,$y2. The optional value $value sets or unsets the pixels. If $value is a valid colour (see below) the line will be drawn with that colour.

$canvas->thick_line($x1,$y1,$x2,$y2,$thickness,$value)

Uses Algorithm::Line::Bresenham to draw a thick line, defined by end points $x1,$y1,$x2,$y2) and thickness $thickness. The optional value $value sets or unsets the pixels. If $value is a valid colour (see below) the line will be drawn with that colour.

$canvas->varthick_line($x0,$y0,$x1,$y1, $left,$argL, $right,$argR, $value)=@_;

Uses Algorithm::Line::Bresenham to draw a variable thickness, defined by end points $x0,$y0,$x1,$y1) and thickness defined by two user defined functions, each function taking as arguments arg<L|R>, $pos, $len and returning thickness of the left and right sides of the line. The optional value $value sets or unsets the pixels. If $value is a valid colour (see below) the line will be drawn with that colour.

$canvas->polyline($x1,$y1,....,$xn,$yn,$value)

Uses Algorithm::Line::Bresenham to draw a poly line, form a sequences of points. The optional value $value sets or unsets the pixels. If $value is a valid colour (see below) the line will be drawn with that colour.

Character Level Functions;

$canvas->scroll($direction,$wrap)

Scrolls in $direction. $direction may be "l", "left", "r","right", "u","up","d", "down". Beacuse of the use of Braille characters, up/down scrolling is 4 pixels at a time, whereas left right scrolling is 2 pixels at a time. If $wrap is a true value, the screen wraps around.

$canvas->blockBlit($block,$gridX, $gridY)

Allows blitting a 2d arrays to a grid location in the canvas. Useful for printing using a Graille font.

$canvas->exportCanvas($filename) , $canvas->importCanvas($filename,[$toBuffer])

This allows the loading and unloading of a canvas from a file. There is no checking of the dimension of the canvas being imported at the moment. Import can be direct to the canvas, the function return the loaded data as an ArrayRef, the optional c<$toBuffer> parameter, if true prevents loading the data onto the canvas.

$canvas->textAt($x,$y,$text,$fmt)

Printing text on the $canvas. This is different fromthe exported printAt() function. the characters are printed on the $canvas and may be scrolled with the canvas and will overwrite or be over written othe $canvas drawing actions. The optional $fmt allows the setting of colour;

Enhancements

$canvas->logo($script)

Interface to Graille's built in Turtle interpreter. A string is taken and split by senicolons or newlines into instructions. The instructions are trimmed, and split by the first space character into command and parameters. Very simple in other words. No syntax checking is done

"fd distance" pen moves forward a certain distance. "lt angle", "rt angle" turns left or right. "bk distance" pen moves back a certain distance. "pu", "pd" Pen is up or down, up means no drawing takes place, and down means the turtle draws as it moves. "dir" set the direction at a specific angle in dgrees, with 0 being directly left. "mv"moves pen to specific coordinates without drawing. "ce" centers the turtle in the middle of a canvas "sp" allows animated drawing by specifiying the the number of centiseconds between instructions

Exported Routines

Graille exports some functions for additional console graphical manipulation This includes drawing of borders, printing characters at specific locations in the terminal window, and colouring the characters, clearing the screen, etc.

printAt($row,$column,@textRows); 

Prints text sent as a scalar, a list of scalars or a reference to list of scalars, at a specific location on the screen. Lists are printed from the same column but increasing row positions.

border($top,$left,$bottom,$right,$style,$colour);

Draws a border box.

paint($txt,$fmt)

Paints text the colour and background specified, $text may be a string, or ref to a list of strings. This is combined with printAt() abouve

clearScreen()

Guess what? clears the enire screen. This is different from $canvas->clear() which clears the Graille canvas.

block2braille($block)

Given a block of binary data (a 2D Array ref of 8-bit data), return a corresponding 2d Array ref of braille blocks. This is handy to convert, say, binary font data tinto Braille blocks for blittting into the canvas;

pixelAt($block,$px,$py)

Given a binary block of data e.g. a font or a sprite offered as a 2D Array ref find the pixel value at a certain coordinate in that block.

AUTHOR

Saif Ahmed

LICENSE

Artistic

INSTALLATION

Manual install:

$ perl Makefile.PL
$ make
$ make install

cpanm Term::Graille

perl -MCPAN -e shell
install Term::Graille