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.

Rotating rectangle demo Metaball demo Lander demo

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 is now 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:

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 \n \t \r \b \f are supported.

General Commands

Frame Management

Transformations

Initial coordinate system is left edge to right edge -1 .. 1, bottom edge to top edge -1 .. 1. Transformation matrices are kept on a stack; the top matrix of the stack is the active one.

Clipping

At the beginning of each frame, the clipping rectangle is reset to contain the entire window area of Animator.

Drawing

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.

Colors

Colors can be specified in multiple ways:

Areas

Areas are used for event reporting. These are named polygon boundaries, the names of which are printed when events occur within their bounds.

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

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

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

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