Animay Programmers Guide

1.0 Introduction

2.0 Source Code

2.1 Header Files

2.2 C Files - Standard

2.2.1 natural.c

2.2.2 animay.c

2.2.3 files.c

2.3 C Files - Motif Editor

1.0 Introduction

This document contains descriptions of which module is in what file, and a brief description of the purpose and role of each function. It is designed to be an aide to anyone trying to understand this code, not a complete reference.

2.0 Source Code

2.1 Header Files

2.1.1 natural.h

Contains the typedef of the structure Vector2d, and of splinedata. Also contains the headers of the functions from natural.c which animay.c calls.

2.1.2 animay.h

Contains the code-specific configuration defines; MOSAIC_CMD, POV_CMD, DISPLAY_CMD/_POST, DEF_OUT_FILE and ENV_VAR_NAME. Of less importance to the user are the defines for the date and version number.

This file contains the typedef for the keyframes struct, which was created as a complement to the splinedata typedef in natural.h. The main variables holding the spline data and other animation data are declared as external.

2.1.3 xheaders.h

Contains all the include files for Xlib and Motif, as well as defines for the graphics layout, such as the window size. The define's to convert between screen co-ordinates and values are in this file, along with the callback functions external declarations, and the global variables which involve the editor, and not the spline data directly.

2.1.4 help.h

Contains the text for the about message, plus all the context sensitive help messages.

2.2 C Files - Standard

2.2.1 natural.c

The natural interpolation library was introduced to me in the unit Graphics Systems 303, of which Brian Von Konsky was the supervisor & lecturer.

2.2.2 animay.c

Contains the startup functions, process command line arguments and environment variable, act as interface between natural.c and the other files, and call the main process functions.

CalcInterp(): Calls two functions from natural.c to sort the knots and calculate the coefficients, from which the spline is calculated.
AddKnot(): Adds a knot to the spline structure. If a knot already exists at that point, it is overwritten with the new one, else the knot is inserted.
QueryValue(): Calls the function Function in natural.c to calculate a value at a certain place along a spline.
nest_bug_check(): Checks the nesting when reading an ".anp" file, and reports an error if required.
is_a_num(): Returns true (positive) if the string passed is a number. ie; contains only the characters '0' to '9', '.', and possibly a leading '-' for negative numbers.
BarGraph(): Draws a row of a given character a certain way between a minimum & maximum value. Used for displaying the splines for the standard version of Animay.
CalcFrame(): Given a time value, returns the new POVray for that time. Substitutes all the variables with the correct value based on the time value passed to it.
ConcatArgs(): Takes argc and argv, and returns a string made of each argv separated by a space.
DoAnimation(): If preview/edit mode is selected, then it starts the Motif editor for the Motif version, or prints the text bar representation of the splines for the standard version. If it's not in preview/edit mode, then it pauses, then calls GenerateAnimation() in files.c.
ProcessArgs(): Takes argc and argv, and checks for valid command line or environment variable options.
CheckEnvVar(): Checks the Animay environment variable, and if it has a value, converts the string to argc and argv format, and passes this to ProcessArgs().
main(): Calls the main functions to initialise and process the data.

2.2.3 files.c

Contains functions for loading and saving splines and animations, and also executes POVray when generating frames.

SetAllArgs(): Set the allargs variable.
SetOutFile(): Set the outfile variable.
explode(): Convert a string into an array of smaller strings, split at the specified character passed to the function.
GenerateFrame(): Given a time or frame number, get the temporary POVray file, and run POVray to generate the new frame image.
LoadAnimation(): Read in a ".anp" file, storing the scenery information separately, and converting the animation block into the data structures required.
indent(): Space a string to the right a specified amount.
SaveAnimation(): Rewrite scene and animation data to an ".anp" file.
LoadSpline(): Load spline information from disk, overwriting the current spline.
SaveSpline(): Reverse of LoadSpline(). Save the current spline's data to disk.

2.3 C Files - Motif Editor

2.3.1 xwin.c

Contains miscellaneous X-windows functions, such as opening the graphics windows, keeping track of mouse events, etc ...

GetMenuBar(): Return the menubar widget.
SetMenuBar(): Store the menubar widget in the variable menubar.
open_window(): Create the graphics window for the drawing area widget.
refreshWindow(): Redraw the current contents of the spline display.
UpdYdata(): Update the data concerning the "Y" or value axis.
UpdXdata(): Update the data concerning the "X" or time axis.
UpdMdata(): Update the data concerning the marked point.
redraw(): Callback for resizing & exposing the window. Calls refreshWindow().
UpdVarLabel(): Updates the label on the toolbar saying what the primary variable is, and what (if any) the secondary variables are.
UpdOfsBar(): Callback for the time offset scrollbar.
UpdOfsXBar(): Callback for the value offset scrollbar.
UpdZoomBar(): Returns a rescaled value for either zoom scroll bar.
UpdZoomXBar(): Callback for the value zoom scroll bar.
UpdZoomYBar(): Callback for the time zoom scroll bar.
InsertAtCoord(): Insert a knot/keyframe at the specified coordinate.
DeleteKnot(): Deletes the keyframe specified by the knot number.
DragPointCB(): Callback for when the mouse is dragged within the window.
SelectPointCB(): Callback for when a mouse button is set or released within the window.
ChildProcessFinished(): Like a callback; triggered using signal when a child process finishes.
init_splineinfo(): Check for variables with names like "camx", "camy", and "camz", and group them together.
init_toolbar(): Initialises all the widgets in the toolbar.
initpanel(): The main function, called from animay.c. Initialises the application, and all the widgets which it's made up of.

2.3.2 menus.c

Contains the functions and data for creating the menu structure.

CreateMenuButtons(): A recursive function to create the menu structure.
InitMenus(): Adds the dynamic data to the predefined static menu data, which is then passed to CreateMenuButtons() to create the menu structure. The dynamic data involves the list of variables under the Variables menu, and a similar list under Options.Group Variables.
GetGroupLabel(): Returns a requested widget from the Options.Group Variables menu. The menu contains all variables except the current one, and this is achieved by including all variables, but keeping the current variable unmanaged.

2.3.3 menucbs.c

Contains all the functions associated with the menus. All the call-backs, and dialog-oriented routines.

OptionStr(): Returns a string based on the POVray options selected under the Options menu.
TogglePOVOp(): Callback for the Options menu to toggle the POVray options.
TogglearButton(): Callback for the Options.Group Variables menu. Handles removing and adding a variable to a group.
SelectVarButton(): Callback for the Variables menu. This selects a new variable as the primary variable.
ToggleEditMode(): Callback for the Toolbar. Depending on which button was toggled, a different bit in editmode is toggled.
CancelCB(): A basic cancel callback; destroys the widget.
ChangeVarVal(): Callback from the editing dialogs which sets the new values.
AlreadyError(): General "error" dialog box, with no different OK callbacks. It's just to tell you "Something screwed up".
OpenVarDialog(): Callback from the Edit menu buttons. Opens a dialog box with the old value, so you can keep the old value, or change it.
DOITSaveAnimation(): Callback which saves the animation, then destroys the widget.
DOITSaveSpline(): Similar to DOITSaveAnimation().
FileSelectionCB(): Callback from the file selection box for loading/saving a spline/animation.
FileMenuCB(): Callback from the first 4 file menu buttons. Opens a file selection box.
QuitAppCB(): Callback from File.Exit. Kills any POVray processes before quitting, but leaves any display or HTML processes going.
CancelWotcherCB(): Callback from dialog box when generating a frame or animation when Cancel is pressed.
SkipFrameCB(): Callback from dialog box when generating an animation. Kills the current POVray child, which then automatically goes on to the next frame.
DisplaySoFar(): Tries to spawn a viewer application to view part or all of a frame.
DisplaySoFarCB(): Callback from generating dialog box giving the go-ahead to display the frame.
GenerateOKCB(): Callback from confirmation box giving the go-ahead to generate the full animation.
GenerateFrameCB(): Similar to GenerateOKCB(), but not as critical, as it will only generate one frame, not hundreds.
GenerateAnimationCB(): Callback from File.Generate* which opens a dialog box and asks for confirmation.
FinishedAnimationCB(): Called when the very last POVray process has finished.
FinishedFrameCB(): Called when a one-frame generation finishes. Opens a dialog box prompting to continue, or display the frame.
DoingNextFrameCB(): Callback called when a POVray child finishes, but it isn't the end of the animation. Updates the message in the Generating box to give the current frame being calculated.

2.3.4 help.c

Contains the routines for diplaying context-sensitive help, loading a HTML browser with the documentation, and generating the "About" panel.

ContinueCB(): Standard continue/cancel button. Will destruct an alternate widget if passed it.
HelpWindow(): Opens up a dialog shell with a scrollable view of the specified help text. Has one button; "Continue".
AboutAnimayCB(): Callback from Help.About, which opens up a HelpWindow with the "About" text in it.
MosaicHelpCB(): Forks off another process to run Mosaic, or some other HTML reader, to browse the Animay documentation.
OnlineHelpCB(): Callback from Help.Online.* which opens a HelpWindow and displays help on the desired topic.

Trevor Phillips

phillips@guri.cage.curtin.edu.au