Animator

About Animator

Animator is a program that allows you to draw simple animated 2D vector graphics without having to know the intricate APIs of more sophisticated vector libs. You don't have to link with anything: animator reads drawing commands from its STDIN.

Optionally, Animator can describe mouse and keyboard events on its STDOUT, so interactive graphics may be made.

Animator is written in C and uses SDL for graphics.

Animator might be useful together with software like Plumb.

Download

Source code is available from Subversion:

$ svn co svn://repo.hu/animator/trunk animator

i386 and amd64 Debian packages are available from the repo.hu Debian repository.

(There used to be a package for Arch Linux, thanks to AndreasBWagner.)

Command Line

Animator takes no file arguments, input is always read from STDIN.

The following command line arguments are accepted:

-h - display help

- display help -x N - set horizontal resolution (default 640)

- set horizontal resolution (default 640) -y N - set vertical resolution (default 480)

- set vertical resolution (default 480) -D bpp - force color depth (bits per pixel)

- force color depth (bits per pixel) -k - disable keepalive, exit on EOF on STDIN (keepalive is enabled by default)

- disable keepalive, exit on EOF on STDIN (keepalive is enabled by default) -e - enable event reporting (disabled by default)

- enable event reporting (disabled by default) -a - do not enforce aspect ratio (enforced by default)

- do not enforce aspect ratio (enforced by default) -d head - save all frames as head XXXX.png

- save all frames as XXXX.png -q - quit Animator when Q is pressed

- quit Animator when Q is pressed -C - don't clear screen on new frame

- don't clear screen on new frame -R - like -C , but allows resize

- like , but allows resize -H - headless mode (implies -k ). No display (useful with screenshot or -d ).

- headless mode (implies ). No display (useful with or ). -F N - specify output FD for screendump (default 1)

Input Syntax

Input is freeform, tokens are separated by whitespace.

Text starting with the ! character is ignored until EOL.

String constants can be given without quotes if they don't collide with keywords (and they're a single word); otherwise, they should be surrounded with double quotes ". Double quotes and backslashes can be escaped with backslash. Special characters

\t \r \b \f are supported.

General Commands

quit - shutdown program

- shutdown program keepalive on|off - control whether to keep processing events after EOF on STDIN. Enabled by default

on|off - control whether to keep processing events after EOF on STDIN. Enabled by default events on|off - control event reporting. Disabled by default. When enabled, the current transformation matrix is saved as the event transformation matrix. Subsequent event coordinates will be reported in this coordinate system.

on|off - control event reporting. Disabled by default. When enabled, the current transformation matrix is saved as the event transformation matrix. Subsequent event coordinates will be reported in this coordinate system. resize width height - resize drawing window to a specific resolution

- resize drawing window to a specific resolution warp X Y - move (warp) the mouse pointer to the specified position (given in the current coordinate system, not the event coordinate system). Will generate a MOTION event.

- move (warp) the mouse pointer to the specified position (given in the current coordinate system, the event coordinate system). Will generate a MOTION event. warp area name - move (warp) the mouse pointer to an arbitrary point of the given area. Will generate a MOTION event.

- move (warp) the mouse pointer to an arbitrary point of the given area. Will generate a MOTION event. echo string - write the string (plus a newline) to STDOUT

- write the string (plus a newline) to STDOUT echopt string [ x y ]* . - write the string, then all given points transformed to screen coordinates to STDOUT

[ ]* - write the string, then all given points transformed to screen coordinates to STDOUT title string - set window title

Frame Management

frame - use this at the beginning of a frame. Drawing color is set to black, line thickness is set to 1, dash pattern is set to 0xffff, but current transformations/matrices are preserved.

- use this at the beginning of a frame. Drawing color is set to black, line thickness is set to 1, dash pattern is set to 0xffff, but current transformations/matrices are preserved. flush - use this at the end of a frame. Draws current frame in the window. Can be invoked any time to refresh the window, even in the middle of frames.

- use this at the end of a frame. Draws current frame in the window. Can be invoked any time to refresh the window, even in the middle of frames. screenshot filename - equivalent to flush , but also saves the frame as filename (PNG format).

- equivalent to , but also saves the frame as (PNG format). screendump - - equivalent to flush , but also dumps the frame buffer to (by default) stdout . Absolutely no conversion is done, so the result may depend on current color depth, byte ordering etc.

- equivalent to , but also dumps the frame buffer to (by default) . Absolutely no conversion is done, so the result may depend on current color depth, byte ordering etc. screendump filename - like screendump , but writes the dump into a file

- like , but writes the dump into a file sleep N - sleep N seconds (even event handling stops for this period...)

- sleep seconds (even event handling stops for this period...) flushdelay s - flush ; then sleep, as much as to keep an even frame rate of one frame per s seconds; then (if event reporting is enabled) emit a FLUSHDELAY dt event, where dt is the amount of time to advance your app state by, in seconds. Best used with small s values (such as 0.0166666 for 60 fps).

- ; then sleep, as much as to keep an even frame rate of one frame per seconds; then (if event reporting is enabled) emit a event, where is the amount of time to advance your app state by, in seconds. Best used with small values (such as 0.0166666 for 60 fps). aspect on|off - enable/disable enforcing aspect radio (enabled by default)

on|off - enable/disable enforcing aspect radio (enabled by default) bg color - set background color - the color is given in the same form as with the color command. The default background is white.

Transformations

rotate angle - apply rotation, angle degrees counter-clockwise

- apply rotation, degrees counter-clockwise scale x [ y ] - scale current matrix, by x factor horizontally and y factor vertically. Giving y is optional, it defaults to x if omitted.

[ ] - scale current matrix, by factor horizontally and factor vertically. Giving is optional, it defaults to if omitted. shift x y - apply a translation, by x horizontally and y vertically

- apply a translation, by horizontally and vertically viewport left bottom width height - a transformation that results in the desired viewport

- a transformation that results in the desired viewport viewport left bottom - right top - a variation on viewport

- a variation on viewport name - a transformation that would scale the named macro into the -1, -1 .. 1, 1 bounding box

- a transformation that would scale the named macro into the -1, -1 .. 1, 1 bounding box viewport aspect name - like above, but keep the aspect ratio of the macro

- like above, but keep the aspect ratio of the macro mult 9xN - multiply current matrix with an arbitrary matrix - 9 numbers given in row-major order

- multiply current matrix with an arbitrary matrix - 9 numbers given in row-major order push - create a copy of the current transformation matrix and push it on the stack.

- create a copy of the current transformation matrix and push it on the stack. pop - pop off the topmost element of the stack

- pop off the topmost element of the stack ident - load the identity matrix

Clipping

clip left bottom width height - set clipping rectangle. The bottom left and top right corners of the rectangle are calculated, then transformed according to the current coordinate system. Clipping will always be axis-aligned, regardless of any rotation in the current transformation!

- set clipping rectangle. The bottom left and top right corners of the rectangle are calculated, then transformed according to the current coordinate system. Clipping will always be axis-aligned, regardless of any rotation in the current transformation! clip left bottom - right top - a variation on clip

Drawing

color color - set drawing color - see color formatting

- set drawing color - see color formatting alpha alpha - set alpha (transparency); goes from 0 (invisible) to 1 (opaque)

- set alpha (transparency); goes from 0 (invisible) to 1 (opaque) thick number - set line thickness (applies to line , arrow , rect , lines , circle commands). Line thickness is given in pixels, and no transformations apply to it.

- set line thickness (applies to , , , , commands). Line thickness is given in pixels, and no transformations apply to it. dash 0xffff - set dash pattern (applies to the same commands as thick ). For each pixel, 1 bits are drawn, 0 bits are not

- set dash pattern (applies to the same commands as ). For each pixel, 1 bits are drawn, 0 bits are not dot x y - draw a single pixel

- draw a single pixel line x1 y1 x2 y2 - draw a line

- draw a line arrow x1 y1 x2 y2 - draw a line, with an arrowhead at x2,y2

- draw a line, with an arrowhead at rect x y width height - draw a rectangle of size width * height , between x, x+width; y, y+height

- draw a rectangle of size , between rect x1 y1 - x2 y2 - a variation on rect , draw rectangle between x1, x2; y1, y2

- a variation on , draw rectangle between fillrect x y width height - like rect , but fill it

- like , but fill it fillrect x1 y1 - x2 y2 - a variation on fillrect

- a variation on text [left|center|right bottom|center|top] x y text - draw text, at x,y ; alignment is optional, default is center center

[left|center|right bottom|center|top] - draw text, at ; alignment is optional, default is blit [left|center|right bottom|center|top] x y image - blit an image, at x,y ; alignment is optional, default is center center

[left|center|right bottom|center|top] - blit an image, at ; alignment is optional, default is lines x1 y1 x2 y2 [ x3 y3 ] ... - draw a line of multiple connected segments

[ ] - draw a line of multiple connected segments poly x1 y1 x2 y2 x3 y3 [ x4 y4 ] ... - draw a filled polygon

[ ] - draw a filled polygon circle x y r verts - draw a circle, with the given number of vertices, centered at x,y

- draw a circle, with the given number of vertices, centered at fillcircle x y r verts - like circle, but fill it

Images

Images have to be pre-loaded for drawing commands that use images (currently, blit, image_set, imgpoly). Each loaded image is associated with a name, and stored in a dictionary. Drawing commands look up images by the supplied name.

image name path - load an image file from path , store it as name . If an image is already loaded as the given name , it is unloaded first.

- load an image file from , store it as . If an image is already loaded as the given , it is unloaded first. image width height name - creates an empty image (filled with the current background color)

- creates an empty image (filled with the current background color) colormap ' c ' color - updates colormap used by image_set command

' ' - updates colormap used by command image_set image x y string - draws onto image , each character from string representing a pixel, looked up from the colormap , starting with image column x and row y , each subsequent character incrementing x

- draws onto , each character from representing a pixel, looked up from the , starting with image column and row , each subsequent character incrementing imgpoly ax ay ux uy vx vy image polygon... - draws a polygon using a stretched image as a texture. ax, ay specify the anchor point (point on output where the lower left corner of the texture is fixed) ux, uy specify the horizontal edge vector of one repeat of the texture vx, vy specify the vertical edge vector of one repeat of the texture

- draws a polygon using a stretched image as a texture. imgpoly ux uy vx vy image polygon... - draws a polygon using a stretched image as a texture. When ax, ay are skipped, the first point of the polygon is used as the anchor point.

- draws a polygon using a stretched image as a texture. imgpoly ux vy image polygon... - draws a polygon using a stretched image as a texture. uy and vx are 0 by default (resulting in axis-aligned texturing).

- draws a polygon using a stretched image as a texture. imgpoly image polygon... - draws a polygon using a stretched image as a texture. When both edge vectors are skipped, 1, 0 and 0, 1 are used (axis-aligned texturing where one repeat of the texture is 1 wide and tall).

- draws a polygon using a stretched image as a texture.

Colors

name - named colors (such as "black")

- named colors (such as "black") #rrggbb - hexadecimal form, 0-255

- hexadecimal form, 0-255 #rgb - hexadecimal form, each digit is duplicated

- hexadecimal form, each digit is duplicated #gg - grayscale hexadecimal, 0-255

- grayscale hexadecimal, 0-255 #g - grayscale hexadecimal, digit is duplicated

- grayscale hexadecimal, digit is duplicated red green blue - 3 floating point numbers, 0.0 - 1.0

- 3 floating point numbers, 0.0 - 1.0 gray - 1 floating point number (grayscale), 0.0 - 1.0

Areas

area name x1 y1 x2 y2 x3 y3 [ x4 y4 ] ... - defines a new Area, or redefines an existing one

[ ] - defines a new Area, or redefines an existing one delarea name - deletes an Area

- deletes an Area killareas - deletes all Areas

Having many Areas doesn't cause a slowdown when processing mouse events. However, defining and redefining Areas carries a performance penalty (comparable to rendering the corresponding polygon). Additionally, the definition penalty is repeated for all Areas when the screen is resized.

In short, moving/redefining lots of Areas often won't be particularly efficient.

Macros

macro [ push ] name - start recording macro

[ ] - start recording macro endmacro - end recording macro

- end recording macro invoke name - execute macro

- execute macro invoke X Y name - equivalent to: push; shift by X , Y ; execute macro; pop

- equivalent to: push; shift by , ; execute macro; pop forget - forget all macros

If macro push is used, an existing macro of the same name is extended, not replaced.

Not all commands are allowed inside macro bodies; basically only drawing and matrix commands are allowed. This is the full list:

color alpha thick dash dot line arrow rect fillrect text blit lines poly circle fillcircle push pop mult rotate scale shift viewport ident invoke area delarea clip

Empty macro bodies are not allowed.

Executing a macro is equivalent to executing the instructions in it. Recording a macro doesn't execute the instructions in it right away; the macro has to be invoked for that.

Macros can be redefined by recording a new macro of the same name. Macros are looked up each time they're invoked, so if a macro is redefined, its meaning will change in any other macro that invokes it.

Recursive macros will do exactly what you expect - crash animator, that is.

Mouse Cursors

defcursor name data mask hot_col hot_row - define a new mouse cursor

- define a new mouse cursor setcursor name - set mouse cursor to a previously defined cursor

These commands allow you to override the default mouse cursor on the system.

Both data and mask are 32x32 monochrome bitmaps, given as a hexadecimal string from top to down and left to right (each row consists of 8 nybbles, leftmost bit being MSB). Both data and mask must be 32*32/4 = 256 characters long.

Data bit Mask bit Color 0 0 Transparent 1 0 Black (inverted on some systems) 0 1 White 1 1 Black

hot_col and hot_row specify the hot point of the cursor (both 0 based integers, origin is the top left corner).

For example:

defcursor "earth" "000000000007f00000388e0000e1d38001dd9bc003fd8fe007f119700ff000380fe03c381fc07ffc1c207fd41800ffe42c007ffa24003ff222c003f221e003e223f801e223fc01ca21fc03d210f803d410f0038410700304086000080820000804200010021000200100004000c98180003ffe000007f0000000000000000000" "000000000007f000003ffe0000ffff8001ffffc003ffffe007fffff00ffffff80ffffff81ffffffc1ffffffc1ffffffc3ffffffe3ffffffe3ffffffe3ffffffe3ffffffe3ffffffe3ffffffe1ffffffc1ffffffc1ffffffc0ffffff80ffffff807fffff003ffffe001ffffc000ffff80003ffe000007f0000000000000000000" 16 15 setcursor "earth"

Event Output

When event reporting is turned on, a description of each event is written to STDOUT, one per line. Coordinates in events are written in the current coordinate system seen at the time of the last events on command.

Reported Event Types

PRESS button_number X Y [ area ...] Mouse button pressed.

[ ...] RELEASE button_number X Y [ area ...] Mouse button released.

[ ...] MOTION button_mask X Y [ area ...] Mouse moved.

[ ...] KEYDOWN mod_mask unicode keyname Key pressed.

KEYUP mod_mask keyname Key released.

RESIZE width height left bottom right top Screen resized. The new width and height are reported in pixels; then the new boundaries of the root coordinate system are printed.

FLUSHDELAY dt Only after the flushdelay command is used.

For PRESS, RELEASE, and MOTION, the names of the Areas that contain the mouse pointer are printed, separated by spaces.

mod_mask is a bitmask integer, describing which modifier keys are currently pressed. Here's the value table:

NONE = 0x0000, LSHIFT= 0x0001, RSHIFT= 0x0002, LCTRL = 0x0040, RCTRL = 0x0080, LALT = 0x0100, RALT = 0x0200, LMETA = 0x0400, RMETA = 0x0800, NUM = 0x1000, CAPS = 0x2000, MODE = 0x4000

unicode is an integer: the unicode character the current keypress represents (might be 0 if no character can be associated)

keyname is the name of the pressed key, as reported by SDL_GetKeyName . A list may be seen here (the Common name column). Note that the names may contain spaces.

Author

Copyright (C) 2009-2011 Máté Nagy <mnagy AT port70.net>

Animator is licensed under the GNU General Public License Version 2 (available in the file COPYING) or any later version.

Home page: http://repo.hu/projects/animator