Package COM.INFORMATIMAGO.COMMON-LISP.PICTURE.PICTURE

This package exports functions to draw ASCII-ART pictures.

ASCII-ART primitives.

A picture is a matrix of characters.
There are primitives to draw points, lines, rectangles,
circles and ellipses, and strings.

The coordinate system is the direct one:
- x increases toward the right,
- y increases toward the top. Bottom left is (0,0).

License:

    AGPL3

    Copyright Pascal J. Bourguignon 2002 - 2012

    This program is free software: you can redistribute it and/or modify
    it under the terms of the GNU Affero General Public License as published by
    the Free Software Foundation, either version 3 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU Affero General Public License for more details.

    You should have received a copy of the GNU Affero General Public License
    along with this program.
    If not, see <http://www.gnu.org/licenses/>

(draw-arrow pict x y w h &key tail)
generic-function
DO:      Draw a line between (x,y) and (x+w-1,y+h-1) and end it with
         with an arrow tip. If TAIL is specified, draw it at the
         start.
RETURN:  PICT
(draw-line pict x y w h &key foreground)
generic-function
DO:      Draw a line between (x,y) and (x+w-1,y+h-1)
         with the foreground character.
RETURN:  PICT
(draw-on-picture sprite pict x y &optional frame)
generic-function
DO:      Draws the frame FRAME of the SPRITE on the picture PICT,
         placing the spot of the sprite at coordinates (X,Y).
         Transparent pixels are not drawn.
(draw-point pict x y foreground)
generic-function
PRE:    inside = (AND (<= 0 X) (<= 0 Y) (< Y (HEIGHT PICT)) (< X (WIDTH PICT)))
        old-point = (POINT-AT PICT X Y)
POST:   inside       ==> (EQ FOREGROUND (POINT-AT PICT X Y))
        (NOT inside) ==> (EQ old-point (POINT-AT PICT X Y))
RETURN: PICT
(draw-string pict x y string &key direction)
generic-function
PRE:     (MEMBER DIRECTION '(:E :W :N :S :NE :NW :SE :SW
                           :NNE :NNW :SSE :SSW :ENE :ESE :WNW :WSW
                           :LEFT :RIGHT :UP :DOWN NIL) :TEST (FUNCTION 'EQ))
DO:      Draws the STRING in the given DIRECTION (default :RIGHT = :E).
         STRING may be anything, it will be formated with ~A.
         If it contains *NEW-LINE* characters then it's split and
         each line is written ''under'' the other, according to the DIRECTION.
RETURN:  PICT
(erase-rect pict x y w h)
generic-function
DO:      Fills the specified rectangle with (PICTURE-BACKGROUND PICT).
RETURN:  PICT
(fill-rect pict x y w h &key foreground)
generic-function
DO:      Fills the specified rectangle with FOREGROUND.
RETURN:  PICT
(frame-rect pict x y w h &key top-left top-right bottom-left bottom-right top bottom left right)
generic-function
DO:      Draws the frame of a rect parallel to the axis
         whose diagonal is [(x,y),(x+w-1,y+h-1)].
RETURN:  PICT
(frames sprite)
generic-function
RETURN:  The number of frames in the SPRITE.
(height object)
generic-function
RETURN:  The height of the object.
picture
class
A picture is a bi-dimentional (y,x) array of characters.
Class precedence list: PICTURE STANDARD-OBJECT T
Class init args: PICTURE-DATA PICTURE-BACKGROUND
(picture-background picture)
generic-function
The background character of the picture.

PICTURE-DATA

(point-at pict x y)
generic-function
PRE:     inside = (AND (<= 0 X) (< X (WIDTH PICT)) (<= 0 Y) (< Y (HEIGHT PICT)))
RETURN:  inside       ==> The character at coordinate (X,Y).
         (NOT inside) ==> (PICTURE-BACKGROUND PICT)
(set-sprite-data sprite data)
generic-function
DATA may be either:
       - a single string with frames separated by FF and lines separated by LF,
       - a list of string frames with lines separated by LF,
       - a list of list of string lines.
       - a list of list of list of single character strings or symbols
         or characters or character codes.
       - a tri-dimentional array of characters.
RETURN: SPRITE
(size-string pict string &key direction)
generic-function
RETURN:  left bottom width height of the rectangle in which the
         STRING will be drawn by DRAW-STRING, relative to the point
         where it'll drawn.
sprite
class
A sprite is a tri-dimentional (time,y,x) array of characters.
Class precedence list: SPRITE STANDARD-OBJECT T
Class init args: SPRITE-NAME SPRITE-DATA SPRITE-SPOT-X SPRITE-SPOT-Y SPRITE-TRANSPARENT-CHARACTER

SPRITE-DATA

(sprite-name sprite)
generic-function
Name of this sprite.
(sprite-spot-x sprite)
generic-function
X coordinate of the spot of the sprite.
(sprite-spot-y sprite)
generic-function
Y coordinate of the spot of the sprite
(sprite-transparent-character sprite)
generic-function
The transparent character of the sprite.
(to-string pict)
generic-function
RETURN:  A string containing the picture characters, (pict height) lines
         of (pict width) characters.
(width object)
generic-function
RETURN:  The width of the object.