SRANIMATOR(3)

NAME
SRanimator - XTANGO based animation package for SR

SYNOPSIS
(in SR program:)
	import SRanimator
(to build:)
	sr program.sr sranimator.o XTANGO/xtango.o -lXaw -lXmu -lXext -lXt -lX11
(with srm:)
	srm program.sr sranimator.o XTANGO/xtango.o -lXaw -lXmu -lXext -lXt -lX11
(to run:)
	xrdb -merge XTANGO/xtango.res
	a.out

DESCRIPTION
SRanimator provides a front-end to XTANGO, a library of algorithm animation routines. The SR application imports a global SRanimator and links with SR, XTANGO, and X library files. The library lists shown above assume that XTANGO was built using the Athena widget set.

RUNNING AN ANIMATION

Before running an XTANGO application you must run xrdb -merge XTANGO/xtango.res, where xtango.res is the application default file from the XTANGO distribution. Alternative methods of initialization are discussed in the XTANGO documentation.

To run an animation, compile and run the SR application containing the procedure calls described below. When the animation window appears, press the run animation button to begin the animation.

Animation parameters can be altered using other pushbuttons either before or after the animation has been started. The arrows and zoom pushbuttons on the left control the display, while the buttons at the bottom and the scrollbar at the right affect the animation behavior. An animation may be aborted at any time by selecting the quit pushbutton in the lower right-hand corner of the animation window.

Panning and Zooming

The pushbuttons along the left-hand edge of the animation screen affect what portions of an animation are displayed while an animation is running. To pan the animation window in a specific direction, select the appropriate arrow pushbutton. To zoom in on a section of the animation select the in pushbutton; select the out pushbutton to zoom back out.

Pausing a Running Animation

After initially selecting the run animation pushbutton to start the animation running, the run animation pushbutton changes its name to pause. An animation may be paused at any time by selecting the pause pushbutton which then pauses the animation and changes its name to unpause. To continue the animation, select the unpause pushbutton which then changes its name back to pause.

Changing the Animation Refresh Mode

When using Motif and HP widgets, XTANGO supports three different times to redraw all images displayed in an animation: between each frame, between each scene, and none. The default refresh mode is between each frame. (With Athena widgets, the mode setting has no effect.)

There is a direct trade-off between the frequency of redrawing and the speed of the animation. Refreshing by frame produces a smooth animation but runs the slowest. On the other hand, no refresh produces a quick animation possibly with many holes in the images (created when one image passes over another). Try the no refresh mode when initially building an animation. Then switch to by scene to iron out the minor bugs. Finally use the by frame mode when an animation is complete.

To change the refresh mode, select the mode pushbutton either before running an animation or during the animation. A menu will appear containing the three choices and the current choice will be indicated with a checkmark. After selecting the appropriate choice, the new refresh mode will take effect immediately.

Select the refresh pushbutton located next to the quit pushbutton to force a refresh at any time.

Slowing Down a Running Animation

Use the vertical scrollbar located along the right-hand edge of the animation window to control the amount of time between animation frames. The animation runs fastest when the scrollbar's “thumb” (the black, movable rectangle) is positioned at the top of the scrollbar; the animation becomes progressively slower as the thumb is moved towards the bottom of the scrollbar.

To change the position of the thumb, either select the thumb and drag it to a new location, select a location within the scrollbar (and the thumb will jump there), or select one of the arrows located at the ends of the scrollbar (and the thumb will step in the desired direction).

INTERFACE PROCEDURES

Animations operate on an infinite plane having a real-valued coordinate system. A rectangular portion of the plane, initially the area having x and y values between 0.0 and 1.0, is displayed on the screen. Graphical objects can be created and placed within the coordinate system, and then moved or altered to depict the operations and actions of a computer algorithm. The SR programmer specifies a unique integer id when creating an object, then uses this id to designate the object in subsequent operations.

The individual animation commands are described below. Most commands and parameters should be self-explanatory. Arguments named steps, centered, and steptime are of integer type. Arguments named xpos, ypos, xsize, ysize, radius, lx, by, rx, ty, ry are real or floating point numbers. The argument fillval should be one of the following strings: outline, light, half, heavy, or solid. The argument widthval should be one of the following strings: thin, medthick, or thick. The argument styleval should be one of the following strings: dotted, dashed, or solid. The argument arrows should be one of the following strings: none, forward, backward, or bidirectional. The parameter colorval can be any color specification acceptable to X. Note that the color command only supports a subset of all these possible colors: white, black, red, orange, yellow, green, blue, and maroon. The parameter fontname can be any font specification acceptable to X.

General Procedures

A_bg (colorval : string[*]) Change the background to the given color. The default background is white.

A_coords (lx, by, rx, ty : real) Change the displayed coordinates to the given values (left-bottom is (lx,by) and right-top is (rx,ty)). You can use repeated applications of this command to pan or zoom the animation view.

A_delay (steps : int) Generate the given number of animation frames with no changes in them.

A_zoom (id : int; rx, ry: real) Zoom in to (positive values of rx and ry) or out from (negative values) the object given by id. Values close to 0.0 zoom a little, absolute values close to 1.0 zoom a lot.

A_end () Terminate the animation.

Drawing Procedures

A_line (id : int; xpos, ypos, xsize, ysize : real; colorval, widthval, styleval, arrows : string[*]) Create a line with one endpoint at the given position and of the given size. The line can be dotted, dashed, or solid and can optionally have arrows on either or both ends. Note that lines are moved (move, jump, and exchange commands) relative to their centers.

A_rectangle (id : int; xpos, ypos, xsize, ysize : real; colorval, fillval : string[*]) Create a rectangle with lower left corner at the given position and of the given size (size must be positive).

A_circle (id : int; xpos, ypos, radius : real; colorval, fillval : string[*]) Create a circle centered at the given position.

A_triangle (id : int; v1x, v1y, v2x, v2y, v3x, v3y : real; colorval, fillval : string[*]) Create a triangle whose three vertices are located at the given three coordinates. Note that triangles are moved (move, jump, and exchange commands) relative to the centers of their bounding boxes.

A_text (id : int; xpos, ypos : real; centered : int; colorval, str : string[*]) Create text str with lower left corner at the given position if centered is 0. If centered is 1, the position arguments denote the place where the center of the text is put. The text string is allowed to have blank spaces included in it but you should make sure it includes at least one non-blank character.

A_bigtext (id : int; xpos, ypos : real; centered : int; colorval, str : string[*]) This works just like the text command except that this text is in a much larger font.

A_fonttext (id : int; xpos, ypos : real; centered : int; colorval, fontname, str : string[*]) This works just like the text command except that this text is in the specified font.

Image Manipulation Procedures

A_move (id : int; xpos, ypos : real) Smoothly move, via a sequence of intermediate steps, the object with the given id to the specified position.

A_moverelative (id : int; xdelta, ydelta : real) Smoothly move, via a sequence of intermediate steps, the object with the given id by the given relative distance.

A_moveto (id1, id2 : int) Smoothly move, via a sequence of intermediate steps, the object with the first id to the current position of the object with the second id.

A_jump (id : int; xpos, ypos : real) Move the object with the given id to the designated position in a one frame jump.

A_jumprelative (id : int; xdelta, ydelta : real) Move the object with the given id by the provided relative distance in one jump.

A_jumpto (id1, id2 : int) Move the object with the given id to the current position of the object with the second id in a one frame jump.

A_stepjump (id : int; xpos, ypos : real; steps, steptime : int) Move the object with the given id to the designated position in a multiple frame jump. The steps of the jump are done at the specified millisecond intervals.

A_stepjumpto (id1, id2 : int; steps, steptime : int) Move the object with the given id to the current position of the object with the second id in a multiple frame jump. The steps of the jump are done at the specified millisecond intervals.

A_color (id : int; colorval : string[*]) Change the color of the object with the given id to the specified color value. Only the colors white, black, red, green, blue, orange, maroon, and yellow are valid for this command.

A_delete (id : int) Permanently remove the object with the given id from the display, and remove any association of this id number with the object.

A_fill (id : int; fillval : string[*]) Change the object with the given id to the designated fill value. This has no effect on lines and text.

A_vis (id : int) Toggle the visibility of the object with the given id.

A_lower (id : int) Push the object with the given id backward to the viewing plane farthest from the viewer.

A_raise (id : int) Pop the object with the given id forward to the viewing plane closest to the viewer.

A_exchangepos (id1, id2 : int) Make the two objects specified by the given ids smoothly exchange positions.

A_switchpos (id1, id2 : int) Make the two objects specified by the given ids exchange positions in one instantaneous jump.

A_swapid (id1, id2 : int) Exchange the ids used to designate the two given objects.

A_resize (id : int; rx, ry: real) The circle, line, rectangle, or triangle is resized as follows. The radius of a circle has rx added to it, the endpoint of a line has (rx,ry) added to it, the lower-right corner of a rectangle is dragged by amount (rx,ry), and the first vertex of a triangle is dragged by amount (rx,ry).

FILES

SRanimator.sr    SR animator global resource
animator.o    compiled C language animator commands
xtango.o    compiled C language XTANGO library
xtango.res    XTANGO widget resources for X11 resources database

SEE ALSO

sr(1), srl(1)

Stephen J. Hartley, Animating Operating Systems Algorithms with XTANGO. ACM SIGCSE Bulletin 26, 1 (March, 1994).

Stephen J. Hartley, Integrating XTANGO's Animator into the SR Concurrent Programming Language. Submitted for publication, 1994; included in the SR distribution.

John T. Stasko, Tango: A Framework and System for Algorithm Animation. IEEE Computer 23, 9 (September, 1990), 27-39.

Doug Hayes, The XTANGO Environment and Differences from TANGO. John T. Stasko and Doug Hayes, XTANGO Algorithm Animation Designer's Package. These two papers are provided as part of the XTANGO package.

CAVEATS

Bracketing blocks of animation code with setpriority(1) and setpriority(0) may improve the animation.

The XTANGO package must be obtained and built separately in order to use the SR animator. XTANGO is available by anonymous FTP from par.cc.gatech.edu. The SR library must be built (or rebuilt) after installing XTANGO.

AUTHOR

Stephen J. Hartley

ACKNOWLEDGMENTS

SRanimator was inspired by SRWin, written by Qiang A. Zhao, and by the animator interpreter program, included with XTANGO, written by John T. Stasko and Doug Hayes.