Doom Univers Paralleles

home *** CD-ROM | disk | FTP | other *** search

/ Doom Univers Paralleles / DoomUniversParalleles.iso / aawin / aapldev.doc < prev next >

Wrap

Text File | 1991-10-16 | 103KB | 2,295 lines

Autodesk Animator Windows Player AAPLAY.DLL - AA Play Library AAPLAY.DLL is a dynamic link library which will play Autodesk An- imator animation files and Windows device independent bitmap files. Using AAPLAY.DLL, applications can load, play and control anima- tions under windows. AAPLAY can use Autodesk Animator Files, or Windows Device Independent Bitmap Files. AAPLAY.DLL can play an animation inside of a window, or it will take over the entire screen for animation playing. AAPLAY.DLL can play MIDI music, digitized sound, or Compact Disk Redbook Audio with animations. AAPLAY.DLL can also manage animation scripts. Scripts are text files which contain animations to be played in a given order. AAPLAY.DLL can be used to create, edit and play animation scripts. When using full screen animations, the display can no longer be shared. AAPLAY.DLL will not allow any other animations to play while a full screen animation is playing. Their status will be playing, but no action will actually be taking place. When the current full screen animation is stopped, the next full screen animation is selected for playing. If there are no full screen animations to be played, AAPLAY.DLL will return the screen to windowed mode. The C language header file aaplay.h makes all of the declarations needed for using the AA Play Library. This document also includes the C language names, and the actual values of constants needed for the AA Play Library. In the following description, TRUE rep- resents a non-zero value, and FALSE is a zero value. A smaller version of the library is available with the sound and scripting features removed. A library call can be made to deter- mine the capabilities of the player. Features not in the limited version are indicated in this document. Windows Initialization - WIN.INI, and SYSTEM.INI The Windows player uses some entries in the Windows initializa- tion file, WIN.INI. These values are kept in the section named, [AAPLAY Animation]. The values are: FullScreen=driver Gives the driver used for full screen animation. Currently only the VGA is supported. The driver for the VGA is AAVGA.DLL. If this value is miss- ing, full screen animations can not be done. DualScreen=value Value indicates whether the full screen anima- tions are run on the same display as Windows. The player assumes the display is shared by Windows and full screen animation, unless this line is present and value is yes, true, on, or a non-zero number. If you are planning to run Windows on a display different from the VGA and run full screen animations, you must add the follow- ing line to the [386enh] section of the file SYSTEM.INI. This line will prevent Windows from attempting to place the VGA ad- dress space in the page frame for expanded memory. EMMExclude=A000-AFFF Special Considerations There are several differences between running animations in the Windows environment and the DOS environment. The following con- siderations should be made when authoring for Windows. Colors Under Windows The following discussion of color is not applicable when running animations in full screen mode under Windows. Colors must be considered for animations that are to be run in a window under the Windows Environment. Two color problems can arise. Windows on the standard VGA uses the 640 by 480 16 color mode. Animations that use many colors will not be displayed cor- rectly, in this case. If you are make animations to be played in a window on a standard VGA, you should limit your color selec- tion. The 640 by 480 16 color mode also does not support changing colors in an animation. For displays with more colors, a mechanism for managing color palettes was implemented in Windows 3.0. This mechanism is used by the player to display animations in a window. There are some unpleasant side effects that can occur when animation palettes do not conform to the Windows palette management. First, Windows reserves twenty colors for its own use, so only 236 colors are available for the animation. However, if the col- ors in an animation do not change, Windows will match colors in the animation and animations using 256 colors will display cor- rectly. Normally, when Windows changes the palette, a message is sent to every window begin displayed, informing the window that the palette has been changed. While these messages are being sent, other activity in the system is suspended, including playing other frames of the animation. So palette changes, either within an animation or between to successive animations in a script, can cause pauses while the animation is playing. When the palette is changed, Windows also may change the colors being used on the display. This means that the animation really needs to be re gen- erated in order to correctly display. If the color change is be- tween animation in a script, the first frame of the new animation will correct the colors. But, if the color change is within an animation, Windows can fix up the colors pretty well, but not completely accurately. So some colors in the animation may change. If color palette effects are desired, the player can reserve palette entries to be used for the effects. Three options are provided, no color entries are ever reserved, the color entries are reserved when the player finds that the colors are changing, or all of the color entries are reserved. When color palette en- tries are reserved, they are not available for color matching, and so if more then 236 colors are used, some colors will be lost. Windows reserves the color in the order they appear in the palette, so the twenty entries at the end of the palette are gen- erally the ones that are lost. To overcome these effects you should use color judiciously. If at all possible, don't use more than 236 colors in any frame and make these the first 236 colors in the palette. This limitation allows all of the palette entries to be reserved. Use a common palette for as many frames as possible. If animations are to be sequenced in a script, the palette of the last frame and the palette of the first frame of the following animation should be the same. Playback Speed Frame timing depends on whether the Multimedia extensions are in- stalled on a system. If these extensions are not installed, ani- mations can only be played at integral divisors of eighteen frames per second (18, 9, 6, 4.5, etc.). The player will round the speed so the playback time is as close as possible to the time desired (12 frames per second rounds to 9, 13 to 18). When the Multimedia extensions are installed, frame timing can be made to millisecond accuracy. When playing animations in a window, the player must convert the Animator format to Windows format and then generate the display from the converted image. This costs time. Animations can not be played in a window as quickly as on the full VGA screen. Playback speed can be improved, by loading the animation into memory before playing it. Of course, some amount of time is used in loading the animation, but it is possible to hide this by us- ing a still frame, or pre-loading the animation when the applica- tion begins. Sound With Animations The player can play sounds with animations, but the player cannot guarantee frame synchronization between the sounds and the anima- tion. The player will only begin sounds at the beginning of an animation, but in scripts sounds can play through more than one animation. Sounds can also be set to repeat after they have fin- ished. Repeating can be set to a specific number of times or un- til the animation ends. The animation can also be repeated until the sound is finished if you want to build a trailer. The player can not change the playing position within sounds, except to reposition the sound to the starting point. If an application uses aaSetParm, or aaSetParmIndirect to change the position of an animation, the sound position is not changed. When using the Test buttons in the user dialogs, sounds will start from the beginning of the sound. The player attempts to support any sound supported by the Media Control Interface. Sounds are divided into two classes, sounds which play from files on the computer, and sounds which play from independent media. The waveaudio and sequencer sounds are exam- ples of sounds that play from files, and cdaudio, videodisc, au- diotape, and videotape are examples of sounds that play through independent media. Sounds from files start at the beginning of the sound and con- tinue until the end of the sound. The player assumes a sound file contains exactly one sound that is played. Sounds for these de- vices are specified by giving the file name of the sound. The de- vice name can also be given, or if it is not given, the MCI ex- tensions section of system.ini is used to match the sound file to the proper device. For sounds from independent media this is not true. Additional parameters may be needed to indicate where the sound begins and ends on the media. Since these device do not require file names, the player will accept a string specifying the play command pa- rameters. These parameters are used each time the sound is played. The parameters allowed for specific devices are: cdaudio from pos to pos Pos gives the position on the compact disk in frames. If from is not given, the sound will start from its current position. Positions are given in minutes, seconds, and frames in the format t:m:s:f. The first frame is frame 1. So the first frame of a track is 0:0:1. So in order to play a song 4 minutes 63 seconds long on track 5 of a CDROM, the parameters used would be: from 5 to 5:4:63 videodisc from pos to pos Pos gives the position on the videodisc in frames. Always give the to argument to insure that the end of the sound is known. If from is not given, the sound starts from the current position. In this case, position is a time in hh:mm:ss format. Your videodisc player may display position in this format, or it may display position as a frame number. To convert from frame numbers to time, divide by 30 to get seconds, and then convert to hh:mm:ss format. The from position must be at least 1 second. For example, enter from 0:0:1 to 0:4:0 to play 4 minutes on the disc. User Dialogs The library has several dialogs that it will display when re- quested by an application. The library will also display some er- ror messages in message boxes. Prompts for File Names Dialogs are provided to ask the user for the names of animations or sounds. These dialogs are produced when the function aaGetFile is called and when a user saves a modified script that is begin unloaded using aaUnload. The limited version of the player will not present the dialog for sound names. If this dialog is re- quested, the player will indicate that CANCEL was pressed in the dialog. Both of these dialogs are like standard file open dialogs of most applications. An edit control is provided for entering a file name, and two list boxes list files matching the file specifica- tion, and directories. An additional list box is added when the name of a sound file is entered. This box contains a list of de- vices from the [MCI] section of system.ini, and is used to supply the device used to play the sound. When selecting a sound, the dialog recognizes device which re- quire a file name and devices that do not. If the device does not require a file name, the list boxes for the directory are dis- abled. The user can type in the play parameters string in the edit control. Edit Script Dialog This dialog is produced when aaPrompt is called for an animation script. It combines a file open dialog with a list box for dis- playing and editing the script itself. This dialog cannot appear in the limited version of the player, since animation scripts are not supported. The file open controls and list boxes are on the right side of the dialog. These are used to select animations or sounds to be entered in the script. To add an animation or sound to the script, the file is selected and then you can press the Insert button or double click on the file name in the file list box. This will insert the animation before the currently selected ani- mation in the script, or add the sound to the currently selected animation. You can also double click on an animation in the script list box which will insert the new animation before the selected animation. The list box on the left contains the lines of the script. Each line is identified by the name of the animation, followed by sev- eral characters indicating which animation parameters are changed from the default. These characters are: L - The number of loops is not 1. S - The speed is not the design speed. N - Sound has been added. R - The sound is to be repeated, if it finishes before the animation does. D - The sound does not start with the animation. C - Palette animation is inhibited. A - The entire palette is reserved for animation. M - The animation is loaded into memory before playing. F - The animation is to play in full screen mode. E - The last frame of the animation does not loop to the first frame. P - The animation is paused at its end. I - A transition has been added to the animation. Using the buttons at the bottom left you can Cut, Copy, and Paste lines in the script. Paste will paste text lines from other sources, if they are in the format of a script file. The Clear button deletes lines from the script without copying them to the Clipboard. The Undo button undoes the last change made to the script. The buttons at the lower right are used to exit the dialog, test the animation, save the script, change an animations parameters, and change the sound for an animation. Pressing the Done button will exit the dialog and leave the script as it was last changed. Pressing the Test button will test the animation script, begin- ning with the selected entry. If no entry is selected, the test will start at the beginning of the script. Pressing the Save but- ton will save the script as it is currently. When a single an- imation is selected in the script list box, the Parameters and Sound buttons are enabled. Pressing the parameters buttons will bring up the Animation Parameters Dialog, described below, and allow parameters for the animation to be changed in the script. Pressing the Sound button will change the mode of the dialog from adding animations to changing the sound for the selected anima- tion. When the sound button is pressed, the script list box is dis- abled, the edit buttons at the bottom left of the screen are dis- abled, and the parameters button is enabled. If the animation al- ready has a sound, the name of sound is displayed in the edit control, and the directory is displayed in the list boxes. At this point the user can either press the Flicks button which will return the dialog to the animation mode, or selects a sound and press the Insert button, which will add the sound to the anima- tion, or press the Off button at the bottom of the dialog, which will remove any sound from the animation, or press the Continue button at the dialog which will continue the sound from the pre- vious animation to this animation. When any of these actions take place, the dialog is returned to the animation mode. Animation Settings This dialog is produced when aaPrompt is called for a normal ani- mation, or the Parameters button is pressed for an animation in a script. It is used to adjust parameters of the animation such as speed and length of play. At the top right of the dialog, the speed, and length of one loop of the animation is displayed. Frames gives the length in frames of a single loop, Design Speed gives the speed of the animation as set in Animator, and Duration gives the duration of a single loop of the animation at the design speed in seconds. Also at the top of the dialog are five check boxes to control the mode of the animation: Load into Memory When set all of the animations frames are loaded from disk into memory when the animation is loaded. This can be used to improve playback speed of animation that have large average frame sizes. Full Screen This check box is only enabled if the FullScreen entry is present in the [AAPLAY Animation] sec- tion of win.ini. If it is checked, the animation will use the full screen to play, instead of playing in a window. Loop Frame This check box is only enabled for Windows Device Independent Bitmap Animations. It is used to in- dicate that the last frame of the animation is the deltas from the end of the animation to the beginning of the animation. Color Cycling OK This check box is used to inhibit palette anima- tions. It is usually checked which causes the player to reserve palette entries that change during an animation. If it is not checked, the player will not reserve any palette entries. Use All Colors This check box is only enabled if Animate Colors is checked. Checking this box will cause the player to reserve all palette entries for palette animation. The three edit controls and scroll bars in the middle of the dia- log labeled, Speed, Loops, and Duration are used to control the speed and length of an animation. Speed is given in frames per second, and defaults to the design speed. It can be changed using the scroll bar to its right, or by typing the desired speed in the field where the current value is displayed. It can range from 1.0 to 51.0 frames per second. Loops tells the player when to stop the animation. Its format is: loop:frame Loop gives the number of times to completely play the animation, and frame is the number of frames played after all of the loops are played. If frame is zero, it is not displayed and does not need to be entered. Loops can be changed using it's scroll bar, or by typing in the desired value. Loops can range from 1 frame to 999 Loops. It may also take on the value "Forever" which indi- cates that the animation can only by stopped by an external event. The number of whole loops can also be given the value "Sound" which indicates that the animation is to loop until the sound is finished playing. If no frame number is given, the ani- mation will end when the sound ends. If a frame number is given the animation will end immediately before the frame is played and after the sound has ended. Duration is the length of time the animation will play. It is calculated from the Speed and Loops values. Its format is: mm:ss.msec Mm is the number of minutes, ss the number of seconds and msec the number of milliseconds. It may range from the time of 1 frame to 49:59.999. It is when changing any of these three parameters, at least one of the other parameters must be changed to make the speed, length in loops and frame and duration in time consistent. The lock but- ton controls the parameter that is fixed in the calculation. The parameter that is not fixed is adjusted each time one of the other ones is changed. The Repeat Sound entry is used to change the number of times a sound is repeated. It can vary from 1 to 1000 times. It can also take on the value of "Forever" which indicates that the sound will repeat until the animation is stopped. This entry does not appear in the limited version of the player. The Delay Sound entry is used to delay sounds from the start of the animation. The number is given as a time in milliseconds and can range from -50:00.000 to 50:00.000. If the number is positive the sound start that length of time after the animation starts. If the number is negative the sound starts that length of time before the animation starts. The timing is directly tied to the speed of the animation, so the sound will be delayed longer than the time given if the animation cannot play at the requested speed. This entry does not appear in the limited version of the player. The Pause at End entry is used to length of time an animation is paused when it ends. It can vary from 0.000 to 50.000 seconds. If the animation loops is set to "Sound" with no frame given the an- imation is not paused if it is playing when the sound ends. If the animation has ended as is paused, in this case the ending of the sound will cause the animation end. The Test button will destroy the dialog, and run the animation with the currently selected values. Any key press, or mouse click in the animation window will stop the test and return to the dia- log. OK accepts the current values and CANCEL rejects the current val- ues. The Transitions button displays the Transition dialog described below. Transition Dialog The transition dialog is presented when the Transitions button is pressed in the Animation Settings dialog. This dialog is used to add fades to the beginning and end of animations. The duration of the fades can be set between .25 and 10.0 seconds. Function Summary The functions provided for frame animation are: aaOpen Opens the library. aaGetCaps Returns current capabilities of the animation player. aaClose Closes the library. aaLoad Loads a new animation. aaUnload Unloads a loaded animation. aaReLoad Loads an animation over a loaded animation. aaPlay Starts playing a loaded animation. aaPause Pauses a playing animation. aaStop Stops a playing animation. aaNotify Schedules frame synchronization messages. aaCancel Cancels frame synchronization mes- sages. aaPrompt Prompts for animation parameters using dialogs. aaGetParm Retrieves animation parameters. aaGetParmIndirect Retrieves animation parameters. aaSetParm Changes animation parameters. aaSetParmIndirect Changes animation parameters. aaShow Displays or hides the animation window. aaSound Places sound with an animation. aaGetFile Prompts for a file name using a dialog. aaSave Saves a loaded animation script. Using the Windows Animation Player There are three basic phases to using the player. During the first phase, an application must connect to the player. Once the connection is established, animations can be loaded and played. Finally the application must disconnect from the player before exiting. In order to connect to the player, the application must call the function aaOpen. This function has no arguments and returns a zero if the connection fails, or a non-zero value if the connec- tion succeeds. If the connection fails, no other call to the li- brary should be made. aaOpen should not be called again until af- ter a call to aaClose is made. The function aaGetCaps can be used to determine what player capabilities are available. Depending on the system and version, sound or scripting may not be available, and only reduced frame timing may be available. To disconnect from the player, the function aaClose is called. This function has no arguments or return value. The library should not be used after aaClose is called. In order to play animations they must first be loaded using aaLoad. aaLoad returns an unsigned integer which is used to ref- erence a loaded animation in other library functions. These func- tions can be used to begin play, stop or pause play, and reposi- tion the animation. When an application is finished with an ani- mation, it can be unloaded using aaUnload. After the library has been opened, an application can use aaGet- File to prompt for an animation or sound file name. Of course, an application can also use its own file name dialog, or some other mechanism to obtain the names of animations. Two primitives are supplied for frame synchronization. These primitives allow an application to request call backs from the animation player when certain frames are to be drawn. Using these call backs, the application can synchronize any other event with an animation frame. The primitives are aaNotify which schedules a call back, and aaCancel which cancels a call back. When a script is playing, call backs can only be scheduled for the currently playing animation. In order to facilitate synchronization in scripts, a call back is made at the start of each animation in the script. Call backs are provided for frame synchronization and state and error notification. The call back is made to the Window Procedure of the window set as the call back window. When an animation is loaded, the call back window is set to the hwnd parameter, but it may be changed by aaSetParm or aaSetParmIndirect. Two messages are used and the message number of these messages is determined using RegisterWindowMessage. The messages are identified by the following strings: "AAPLAY Notify" - Message string for frame syn- chronization messages. "AAPLAY Stop" - Message string for status and error messages. The call back function should be declared as follows: LONG FAR PASCAL CallBack(hwnd, msg, wparam, lparam); HWND hwnd; WORD msg; WORD wparam; DWORD lparam; The hwnd parameter always identifies the owner of the animation window. The msg parameter identifies the message, and is found by calling RegisterWindowMessage with the appropriate message string. The wparam parameter always identifies the animation that generated the message. It gives the value returned by aaLoad when the animation was loaded. For frame synchronization messages, lparam is the value requested by the application when the call back was requested, or zero for frame synchronization call backs generated at the beginning of an animation in a script. For status and error messages, lparam is an error code. If it is zero, the animation stopped at the end without an error. The fol- lowing error codes are defined: AA_BADPLAY - 1 An error occurred reading the animation. AA_BADNOTIFY - 2 A memory error occurred attempting a frame syn- chronization message. AA_BADSCRIPT - 3 An error occurred loading an animation or sound for a script. When processing a callback message from the player, you should not use aaUnload to unload the animation, or aaClose to close the library. You may used aaReLoad to reload an animation when a stop callback is recieved, but not when a frame callback is recieved. Several function are provided for retrieving and changing parame- ters of an animation. The application can provide a user inter- face or use the one provided in aaPrompt. For normal animations, the application should retrieve the values of an animations pa- rameters and save them for later use. Scripted animations will save the animation parameters in the script. Animation Scripts Animation scripts are text files containing an order list of ani- mations. Animation scripts can not be played by the limited ver- sion of the player. An error is returned if the limited player attempts to open an animation script. The animations are played in the order given in the list. Each animation is listed on a separate line. Any line listing an animation to be played can be continued by putting a back slash "\" at the end of the line. The last continuation line must not have a "\" at its end. any number of spaces, tabs, or the end of continued lines are treated as though it was just one space. Each line in the script starts with the name of the animation to be played, followed by optional entries giving parameters used in playing the animation. Each option begins with a minus sign, "-". If an option uses a parameter, you may put a space between the option and the parameter, or not. However a space must precede the minus sign for each option. For more information on each option, see the information in aaLoad, aaGetParm, and aaSound. The following options are sup- ported: -L loops[:frame] Sets the length of the animation. If set to 0 or "Forever", the animation will loop forever. De- faults to 1:0. The loops may also be set to the value "Sound", which indicates that the animation is to loop until the sound is finished playing. -S speed Sets the speed of the animation in frames per second. This value can be specified to a tenth of a frame per second. Defaults to the design speed of the animation. -N [sound [device]] Puts a sound with the animation. If the sound is missing, the sound, if any, of the previous ani- mation is used with this animation. If the device is missing, the [MCI Extensions] section of sys- tem.ini is used to locate the device used by the sound. An animation that does not have this op- tion will turn any sound off before playing. -R sound-repeats Sets the number of times a sound is to repeat. If set to 0 or "Forever", the sound will continue to play until the animation is finished, or another sound is played. Defaults to 1. The value is only checked, when the sound reaches the end of play. -D sound-delay Sets a delay from the start of the animation to the start of the sound. The time is given in min- utes and seconds, and can be given to one thou- sandth of a second. The time can range from 50:00.000 to -50:00.000. -P pause-time Sets a time which the script will pause after this animation has finished before starting the next animation. The time is given in seconds, and can be given to one thousandth of a second. -I [transition [duration]]... Sets transitions for animations in scripts. The transition may be on of cutfrom, fromblack, fromwhite, cutto, toblack, or towhite. Transitions default to cutto or cutfrom. The duration of the transition can be given from between .250 seconds and 10.000 seconds. The default time is .500 seconds. More than one transition may follow the -I. -C Inhibits palette animation. -A Reserves all palette entries for palette anima- tion. -M Loads the animation into memory. -F Plays the animation in full screen mode. -E Indicates that the last frame of the animation is not the deltas between the end of the animation and the beginning. Only valid for Windows DIB an- imations. The Dynamic Link Library Entry Points _________________________________________________________________ aaOpen Syntax BOOL aaOpen(void) aaOpen initializes the player for the application. TRUE is returned if the initialization succeeded. Otherwise FALSE is returned. An application must call aaOpen before making any other calls to the AA Play Library. aaOpen should not be called again before aaClose is called. Parameters None _________________________________________________________________ aaClose Syntax void aaClose(void) aaClose releases the player from the application. Any loaded animations used by the application are unloaded. Other calls to the AA Play Library should not be performed after this call is made. aaOpen should be called again to reopen the library, if necessary. Parameters None _________________________________________________________________ aaLoad Syntax HAA aaLoad(lpzFileName, hWnd, wMode, x, y, cx, cy, orgx, orgy) aaLoad loads an animation in preparation for play- ing. It returns a number between 1 and 65535, which is used to reference the loaded animation in other library calls. Once an animation is loaded, it can be played, and various parameters controlling its playing can be altered. If aaLoad is unable to load the animation, NULL (zero) is returned. Parameters LPSTR lpzFileName The name of the animation file to be opened or the contents of an animation script depending on the value of wMode. OpenFile is used to open ani- mation files and so the normal Windows file searching algorithm is used. This search algo- rithm will first search the current directory, then each directory in the PATH environment vari- able. If the wMode value indicates that lpzFileName is the contents of a script, the animation is opened as an untitled script. HWND hWnd The handle of a window that is to own this anima- tion. It must be supplied but may be null. Coordinates are given relative to this window and it is used to receive status and frame synchro- nization messages, when these are sent. The mes- sage numbers used for the status and notification messages are retrieved using RegisterWindowMes- sage. The following two messages are used by AAPLAY: AA_STOP - "AAPLAY Stop" The animation is being stopped. If lParam is non zero, the animation is being stopped because of an error. This message is not sent when the application stops the anima- tion using aaStop. AA_NOTIFY - "AAPLAY Notify" Sent because the user requested notifica- tion when a frame is drawn. See aaNotify and aaCancel. WORD wMode A word which indicates how the file is to be loaded. This value is found by adding the values desired below: AA_MEMORYLOAD - 1 Loads the entire animation into memory. This requires more time, and may fail be- cause of insufficient memory. AA_HIDEWINDOW - 2 Normally the frame at which the animation is stopped is displayed on the screen. If this value is added into the mode, the ani- mation is only displayed when it is play- ing. AA_NOPALETTE - 4 Inhibits palette animation. When palette animation is enabled, some colors may be lost if more that 236 colors are used. AA_RESERVEPALETTE - 8 If palette animation is not inhibited, this flag will reserve all of the palette en- tries for animation. Some colors may be lost if more that 236 colors are used. If the palette is changed without this flag being set, Windows will send a message to all windows on the screen informing them of the palette change. This can cause the ani- mation to stop momentarily. In order to prevent the palette change mes- sages when changing animations in scripts, or using aaReLoad, this flag must be set in the current animation and the following an- imation. AA_LOOPFRAME - 16 Indicates that the last frame of a Windows device independent bitmap animation is ac- tually the deltas between the last frame of the animation and the first. This value is not used for Autodesk Animator Animations. AA_FULLSCREEN - 32 Indicates that the animation is to be played on the full screen, not within the window hWnd. AA_STOPNOTIFY - 64 Prevents notification messages from being sent to the window identified by hWnd. AA_STOPSTATUS - 128 Prevents status messages from begin sent to the window identified by hWnd. AA_NOFAIL - 256 If a memory load fails due to memory limitations, the animation is loaded to play from disk. AA_BUILDSCRIPT - 1024 Indicates that an untitled script is to be built using the contents of the string ad- dressed by lpzFileName. If this mode is used for the limited version of the player, FALSE is returned. WORD x, y, cx, cy The coordinate of the upper left corner of the window used to display the animation, and the width (cx) and height (cy) of that window. X and y are relative to the upper left corner of the client are of the window hWnd. These values are modified to force the window to be contained in the window identified by hWnd. WORD orgx, orgy The coordinate of the animation displayed at the upper left corner of the window used to display the animation. _________________________________________________________________ aaUnload Syntax BOOL aaUnload(hAa) Unloads an animation loaded by aaLoad. If the anima- tion is playing, it is stopped. aaUnload will ask the user to save a modified script. This can be in- hibited by clearing the modified flag using aaSet- Parm. Parameters HAA hAa A handle returned by aaLoad. _________________________________________________________________ aaReLoad Syntax BOOL aaReLoad(hAa, lpzFileName, wMode, wMask) Loads another animation over an existing one. If the two animations use different colors, then setting AA_RESERVEPALETTE in both the existing animation and in wMode can improve the performance of this func- tion. The existing animation must be stopped, paused, or have finished playing in order to make this call. Parameters HAA hAa The handle of the animation returned by aaLoad. LPSTR lpzFileName The name of the animation file to be opened or the contents of an animation script depending on the value of wMode. OpenFile is used to open ani- mation files and so the normal Windows file searching algorithm is used. This search algo- rithm will first search the current directory, then each directory in the PATH environment vari- able. If the wMode value indicates that lpzFileName is the contents of a script, the animation is opened as an untitled script. WORD wMode This value is used exactly the same as in aaLoad. It uses the same value with the following addi- tional value: AA_DONTPAINT - 512 Inhibits painting of the initial frame un- til the animation begins playing. WORD wMask A mask used for setting the mode. Setting of spe- cific mode values can be inhibited by adding the value not to be set into this argument. _________________________________________________________________ aaPlay Syntax BOOL aaPlay(hAa) Plays the animation loaded by aaLoad. Play begins from the current position. aaPlay returns after the animation has begun playing. Returns TRUE if the an- imation is playing. Parameters HAA hAa A handle returned by aaLoad. _________________________________________________________________ aaNotify Syntax BOOL aaNotify(hAa, lPosition, lParam) Requests a frame synchronization message for the ap- plication using aaPlay. The message is sent immedi- ately before the frame at position lPosition is drawn. lParam is a parameter set by the user which is passed to the message handler. The word parameter to the message routine is always the handle hAa. If the position at the time of the call is needed, it can be retrieved using aaGetParm. This call is used to synchronize other events to an animation frame. The player will automatically generate frame syn- chronization messages whose lParam is zero, when an animation begins playing. If the application re- quests frame synchronization with lParam zero, it is the responsibility of the application to determine which synchronization message is begin sent. Parameters HAA hAa A handle returned by aaLoad. DWORD lPosition The position at which the notification is to take place. The high order word is the loop and the low order word is the frame. DWORD lParam A double word passed to the notification func- tion. _________________________________________________________________ aaCancel Syntax WORD aaCancel(hAa, lLowPos, lHighPos) Cancels frame synchronization messages. The number of messages canceled is returned. Parameters HAA hAa A handle returned by aaLoad DWORD lLowPos The lower loop and frame count where notification messages are canceled. DWORD lHighPos The upper loop and frame count where notification messages are canceled. _________________________________________________________________ aaStop Syntax BOOL aaStop(hAa) Stops the playing animation. Returns TRUE if the an- imation is stopped. Stopped animations begin with the first frame of the animation, when they are re- played. You may also use aaSetParm to start a stopped animation at a frame other than the first frame. Parameters HAA hAa A handle returned by aaLoad _________________________________________________________________ aaPause Syntax BOOL aaPause(hAa) Pauses a playing animation. Returns TRUE if the ani- mation is paused. A paused animation is still con- sidered playing, so no other full screen animations will play. Paused animations will continue playing from the current frame, when they are replayed by calling aaPlay. Parameters HAA hAa A handle returned by aaLoad. _________________________________________________________________ aaPrompt Syntax BOOL aaPrompt(hAa, lpName) Produces a dialog box that prompts the user for pa- rameters for playing the animation whose handle is hAa. This call acts differently for scripts and normal animations. For normal animations, the values en- tered by the user can be retrieved using aaGetParm or aaGetParmIndirect. Scripts can be saved in a file using aaSave, or the contents of the script can be retrieved using aaGetParm. Scripts are not available in the limited version of the player. If a script is modified, aaUnload will ask the user to save the script when it is unloaded. This can be prevented by setting the modified flag to zero, us- ing aaSetParm. Parameters HAA hAa A handle returned by aaLoad. LPSTR lpName The name of the animation. This name is used only to provide a caption for the dialog for normal animations. If it is NULL, no name is provided in the dialog caption in this case. _________________________________________________________________ aaGetParm Syntax LONG aaGetParm(hAa, wType) Gets current parameters for playing the animation. Parameters that are not valid are returned as zero. If the animation is a script, the parameters re- turned are for the currently visible animation. Parameters HAA hAa A handle returned by aaLoad. WORD wType The type of parameter to be retrieved: AA_STATUS - 1 Returns a word containing current status of the animation. The status of an animation can be: AA_STOPPED - 1 The animation is loaded and is not play- ing. AA_QUEUED - 2 The animation is loaded and aaPlay has been used to start the animation, but the animation cannot be started because either it is a full screen animation, or a full screen animation is playing, or both. The animation will be begun as soon as possible. AA_PLAYING - 3 The animation is playing. AA_PAUSED - 4 The animation has been paused using aa- Pause. AA_DONE - 5 A transitory state after an animation has finished playing, but before it has been stopped. The animation may be restarted from this state using aaPlay or reloaded using aaReLoad. AA_FILETYPE - 2 Returns a word containing the format of the animation on disk. The values returned are: AA_FLI - 1 Animator FLI format. AA_DIB - 2 Windows DIB format. AA_SCRIPT - 3 The animation is a script. This value will never be returned by the limited version of the player. AA_MODE - 3 Returns a word containing the current mode of the animation. The values are the same as the mode described in aaLoad, except AA_NOFAIL and AA_BUILDSCRIPT are never set. AA_WINDOW - 4 Returns a word containing the handle of the window that owns the animation. AA_SPEED - 5 Returns a word containing the speed of the animation, given in milliseconds per frame. This is the current speed of the animation. AA_DESIGNSPEED - 6 Returns a word containing the designed speed of the animation, given in millisec- onds per frame. AA_FRAMES - 7 Returns a word containing the number of frames in the animation. If the animation type is a DIB file, this number will be un- known, until the animation has been com- pletely played. If the number of frames is unknown, 0 is returned. AA_POSITION - 8 Returns a long containing the current posi- tion in the animation. The high order word is the current loop, the low order word is the current frame. The first loop is loop 0, and the first frame is frame 0. AA_LOOPS - 9 Returns a long returning the position of the frame at which the animation ends. A 0 indicates that the animation will not stop until an aaStop call is made. This number has the same format as AA_POSITION. If the value of the high order word of AA_LOOPS is AA_LOOPSOUND (which is 65535), then the animation loops until the sound finishes playing. If the low order word is also this value, the animation will end with the sound. Otherwise, the animation will stop on the frame number given by the low order word, after the sound has fin- ished. AA_X - 10 Returns the x coordinate of the upper left corner of the animation window. AA_Y - 11 Returns the y coordinate of the upper left corner of the animation window. AA_CX - 12 Returns the width of the animation window. AA_CY - 13 Returns the height of the animation window. AA_ORGX - 14 Returns the x coordinate in the animation, displayed at the upper left corner of the animation window. AA_ORGY - 15 Returns the y coordinate in the animation, display at the upper left corner of the an- imation window. AA_WIDTH - 16 Returns the width of the animation. AA_HEIGHT - 17 Returns the height of the animation. AA_RPTSOUND - 18 Returns the number of times the sound will repeat before stopping. Zero indicates that the sound will repeat until the animation ends. Zero is always returned in the lim- ited version of the player. AA_PAUSE - 19 Returns the length of time to pause this animation at the end in milliseconds. AA_DELAYSND - 20 Returns length of time to delay the sound from the start of the animation in mil- liseconds. The delay is negative if the sound is to start before the animation. Zero is always returned in the limited ver- sion of the player. AA_TRANSIN - 21 Returns the transition at the beginning of the animation. This transition may be: AA_CUT - 0 No transition is performed. AA_FADEBLACK - 1 Fade from black transition is performed. AA_FADEWHITE - 2 Fade from white transition is performed. AA_TRANSOUT - 22 Returns the transition at the end of the animation. The transition may be: AA_CUT - 0 No transition is performed. AA_FADEBLACK - 1 Fade to black transition is performed. AA_FADEWHITE - 2 Fade to white transition is performed. AA_TIMEIN - 23 Returns the duration of the transition at the beginning of the animation in milliseconds. This duration may be from .250 seconds to 10.000 seconds. AA_TIMEOUT -24 Returns the duration of the transition at the end of the animation in milliseconds. This duration may be from .250 seconds to 10.00 seconds. AA_MODFLAG - 100 Returns the modified flag for the script. Zero means the script is not modified and a non-zero value means the script is modi- fied. AA_CALLBACK - 25 Returns the handle of the window used to receive the status and notification messages. AA_ANIMWND - 26 Returns the handle of the window that actually contains the animation. AA_SCRIPTNAME - 101 Returns a global memory handle containing the name of the script. If the script is untitled, or the animation is not a script, zero is returned. AA_ANIMATION - 102 Returns the number of the currently visible animation in a script. Zero is the first animation of a script, or returned if the animation is not a script. AA_ANIMATIONCOUNT - 103 Returns the number of animations in a script. Zero is returned if the animation is not a script. AA_SCRIPTCONTENTS - 104 Returns a global memory handle containing the contents of the script. This handle contains the script as it would appear in a text file, and is terminated by a null character. If the script is empty, or the animation is not a script, zero is re- turned. AA_LASTERROR - 1001 Return the code for the last error detected by the player. This type should be used immediately after detecting an error to determine the error. If the animation handle is zero, the player will search for the last error for the calling application. If the animation handle is a valid handle, the player searches for the last error for the application owning the animation. The error codes are: AA_ERR_NOERROR - 0 No error was detected. AA_ERR_NOMEMORY - 256 An out of memory condition was detected. AA_ERR_BADHANDLE - 257 The handle used in the last call to the player was invalid. AA_ERR_NOTIMERS - 258 A system timer could not be allocated for the animation. AA_ERR_BADSOUND - 259 The sound could not be opened. AA_ERR_NOSCRIPT - 260 The operation in error requires a script. AA_ERR_WRITEERR - 261 An error occured while saving the script. AA_ERR_BADANIMATION - 262 The animation could no be opened. AA_ERR_BADWINDOWHANDLE - 512 An invalid window handle was given to the player. AA_ERR_WINDOWCREATE - 513 An error occured when creating the animation window. AA_ERR_DLGERROR - 514 An unexpected error occured while processing a dialog box. AA_ERR_INVALIDSTATUS 768 The function failed because the state of the animation did not allow it. AA_ERR_BADDIBFORMAT - 769 The Windows DIB file is corrupted. AA_ERR_BADFLIFORMAT - 770 The Autodesk Animator or Animator Pro file is corrupted. AA_ERR_UNRECOGNIZEDFORMAT 771 The file is in an unrecognized format. AA_ERR_NOSOUND - 772 Sound is not supported by the player. AA_ERR_NOTVALIDFORSCRIPTS 773 The request is not allowed for scripts, only for animations. AA_ERR_INVALIDFILE - 774 The file handle for the animation is invalid. AA_ERR_NOSCRIPTS - 775 Scripts are not supported by the player. AA_ERR_SPEED - 1024 The speed is invalid. The speed must be from 19 to 1000 milliseconds. AA_ERR_LOOPS - 1025 The loops are invalid. The number of loops may range from 0 to 999. AA_ERR_RPTSOUND - 1026 The number of sound repetitions are invalid. This value may range from 0 to 1000. AA_ERR_PAUSE - 1027 The time to pause at the end of the animation is invalid. This value may range from 0 to 50000 milliseconds. AA_ERR_TRANSIN - 1028 The starting transition is invalid. Transitions must be one of the codes described above. AA_ERR_TIMEIN - 1029 The duration of the starting transition is invalid. It ranges from 250 to 10000 milliseconds. AA_ERR_TRANSOUT - 1030 The ending transition is invalid. It must be one of the codes described above. AA_ERR_TIMEOUT - 1031 The time of the ending transition is invalid. It may rang from 250 to 10000 milliseconds. AA_ERR_DELAYSND - 1032 The delay of the sound from the start of the animation is invalid. It may range from -3000000 to 3000000 milliseconds. AA_ERR_INVALIDTYPE - 1033 The type parameter to aaGetParm aaSetParm or aaSetParmIndirect is invalid. AA_ERR_DUPLICATENOTIFY - 1280 An attempt was made to add a duplicate notification. AA_ERR_NOSWITCH - 1536 A script line is missing an option switch, or the switch is invalid. AA_ERR_PARSELOOPS - 1537 The number of loops on a script line is invalid. AA_ERR_PARSESPEED - 1538 The speed on a script line is invalid. AA_ERR_BADRPTSOUND - 1540 The number of sound repetitions on a script line is invalid. AA_ERR_PARSEPAUSE - 1541 The pause at the end of an animation on a script line is invalid. AA_ERR_PARSETRANS - 1542 A transition value is invalid. AA_ERR_PARSEDELAYSND - 1543 The delay of a sound from the beginning of the animation is invalid. AA_LASTERRORMESSAGE - 1002 A handle to a string containing text for the error code retrieved by AA_LASTERROR is returned. This string may be displayed in a message box. If the error is in a script, and the animation name of the line which caused the error is known, the name of the animation will be in the message. The player will also copy the message into a buffer, if aaSetParm is used. _________________________________________________________________ aaGetParmIndirect Syntax BOOL aaGetParmIndirect(hAa, lpAparm, wSize) Gets parameters for playing the animation into a structure. This allows an application to easily ob- tain all of an animations parameters. Parameters HAA hAa A handle returned by aaLoad. LPAAPARMS lpAparm A long pointer to the structure used to hold the parameters. The format of this structure is: struct { BYTE aa_status; /* offset 0 */ BYTE aa_filetype; /* offset 1 */ BYTE aa_mode; /* offset 2 */ BYTE aa_bitpix; /* offset 3 */ HWND aa_hwnd; /* offset 4 */ int aa_x, /* offset 6 */ aa_y, /* offset 8 */ aa_cx, /* offset 10 */ aa_cy; /* offset 12 */ int aa_orgx, /* offset 14 */ aa_orgy; /* offset 16 */ AASPEED aa_speed; /* offset 18 */ AASPEED aa_designspeed; /* offset 20 */ WORD aa_frames; /* offset 22 */ DWORD aa_position; /* offset 24 */ DWORD aa_loops; /* offset 28 */ WORD aa_rptsound; /* offset 30 */ WORD aa_pause; /* offset 32 */ LONG aa_delaysnd; /* offset 34 */ BYTE aa_transin; /* offset 36 */ BYTE aa_transout; /* offset 37 */ WORD aa_timein; /* offset 38 */ WORD aa_timeout; /* offset 40 */ HWND aa_callback; /* offset 42 */ HWND aa_animwnd; /* offset 44 */ }; The contents of each field is described in aaGet- Parm. WORD wSize The size of the parameter structure. _________________________________________________________________ aaSetParm Syntax HAA aaSetParm(hAa, wType, wValue1, lValue2) Sets parameters for playing the animation. The use of wValue1 and lValue2 depends on wType. The values of each field is described in aaGetParm. The handle of the animation with the new parameters is re- turned. If the value could not be set, NULL is re- turned. When NULL is returned, the original anima- tion handle is still valid. Parameters HAA hAa A handle returned by aaLoad. WORD wType The type of parameter to be set. The values of wValue1 and lValue2 vary depending on the parame- ter type. AA_MODE - 3 wValue1 is the current mode of the anima- tion. The low order word of lValue2 is a mask for setting the mode. Mode values which are not to be set can inhibited by adding the value into the mask. AA_WINDOW - 4 wValue1 is a the handle of a window in which the animation is to play. The call back window is changed if it has not been changed to another window handle. AA_SPEED - 5 wValue1 is the speed, in milliseconds per frame. AA_POSITION - 8 lValue2 is the number of frames and loops the frame position is to be moved. The high order word is the number of loops, the low order word is the number of frames. If the frames value wraps past the end of the ani- mation, it is carried into the loops value. wValue1 specifies the starting position. It is 0 if the starting position is the begin- ning of the animation, 1 if the starting position is the current frame, and 2 if the starting position is the end of the anima- tion. If the position is set while an animation is stopped, the animation will start from the given position, instead of from the be- ginning. In this case any sound associated with the animation is also started from its current position. AA_LOOPS - 9 lValue2 is the position of the frame at which the animation ends. If the value of the high order word of AA_LOOPS is AA_LOOPSOUND (which is 65535), then the animation loops until the sound finishes playing. If the low order word is also this value, the animation will end with the sound. Otherwise, the animation will stop on the frame number given by the low order word, after the sound has fin- ished. In the limited version of the player the value AA_LOOPSOUND is accepted, but it is interpreted as though the animation plays forever. AA_X - 10 wValue1 is the x coordinate of the upper left corner of the animation window. AA_Y - 11 wValue1 is the y coordinate of the upper left corner of the animation window. AA_CX - 12 wValue1 is the width of the animation win- dow. AA_CY - 13 wValue1 is the height of the animation win- dow. AA_ORGX - 14 wValue1 is the x coordinate in the anima- tion, displayed at the upper left corner of the animation window. AA_ORGY - 15 wValue1 is the y coordinate in the anima- tion, display at the upper left corner of the animation window. AA_RPTSOUND - 18 wValue1 is the number of times the sound is to repeat before stopping. The sound is al- ways stopped when the animation is stopped or paused. The limited version of the player ignore this parameter. AA_PAUSE - 19 wValue1 is the length of time to pause the animation at its end, in milliseconds. AA_DELAYSND - 20 lValue2 is the length of time to delay the sound from the start of the animation in milliseconds. The delay is negative if the sound is to start before the animation. The limited version of the player ignore this parameter. AA_TRANSIN - 21 wValue1 is the transition at the beginning of the animation. This transition may be: AA_CUT - 0 No transition is performed. AA_FADEBLACK - 1 Fade from black transition is performed. AA_FADEWHITE - 2 Fade from white transition is performed. AA_TRANSOUT - 22 wValue1 is the transition at the end of the animation. The transition may be: AA_CUT - 0 No transition is performed. AA_FADEBLACK - 1 Fade to black transition is performed. AA_FADEWHITE - 2 Fade to white transition is performed. AA_TIMEIN - 23 wValue1 is the duration of the transition at the beginning of the animation in milliseconds. This duration may be from .250 seconds to 10.000 seconds. AA_TIMEOUT -24 wValue1 is the duration of the transition at the end of the animation in milliseconds. This duration may be from .250 seconds to 10.00 seconds. AA_CALLBACK - 25 wValue1 is the handle of the window used to receive the status and notification messages. AA_ANIMWND - 26 wValue1 is the handle of the window that actually contains the animation. AA_MODFLAG - 100 wValue1 contains the modified flag for the script. Zero means the script is not modi- fied and a non-zero value means the script is modified. The limited version of the player ignore this parameter. AA_SCRIPTNAME - 101 lValue2 contains a pointer to the new name of the script. If lValue2 is zero, the script is untitled. The limited version of the player ignore this parameter. AA_ANIMATION - 102 lValue2 contains the number of the anima- tion in the script which is to become visi- ble. The limited version of the player ig- nore this parameter. wValue1 specifies the starting position. It is 0 if the starting position is the begin- ning of the animation, 1 if the starting position is the current frame, and 2 if the starting position is the end of the anima- tion. AA_LASTERRORMESSAGE - 1002 The string containing text for the error code retrieved by AA_LASTERROR is copied into a buffer. The buffer size is given in wValue1, and the address of the buffer is given in lValue2. This string may be displayed in a message box. If the error is in a script, and the animation name of the line which caused the error is known, the name of the animation will be in the message. The player will also return a handle to the message text, if aaGetParm is used. _________________________________________________________________ aaSetParmIndirect Syntax HAA aaSetParmIndirect(hAa, dwType, lpAparm, wMask) Sets the animation parameters from a structure. The handle of the animation with the new parameters is returned. If the value could not be set, NULL is re- turned. When NULL is returned, the original anima- tion handle is still valid. Parameters HAA hAa A handle returned by aaLoad. DWORD dwType A mask containing a bit for each parameter. Any parameter is set only when the corresponding mask bit is on. The following values define the mask bits: AA_SETMODE - 1 AA_SETWINDOW - 2 AA_SETSPEED - 4 AA_SETPOSITION - 8 AA_SETLOOPS - 16 AA_SETX - 32 AA_SETY - 64 AA_SETCX - 128 AA_SETCY - 256 AA_SETORGX - 512 AA_SETORGY - 1024 AA_SETRPTSOUND - 2048 AA_SETPAUSE - 4096 AA_SETDELAYSND - 8192 LPAAPARMS lpAparm A long pointer to the structure containing the parameters being set. See aaGetParmIndirect for a description of this structure. WORD wMask A mask used for setting the mode if AA_SETMODE is set in wType. Setting of specific mode values can be inhibited by adding the value not to be set into this argument. This argument is used only when AA_SETMODE is set in wType. _________________________________________________________________ aaShow Syntax BOOL aaShow(hAa, bShow) Shows or hides the animation window. This setting is independent of the mode value AA_HIDEWINDOW. This routine will hide playing animations and show hidden stopped animations. Parameters HAA hAa The handle of the animation returned by aaLoad. BOOL bShow The animation window is shown if bShow is TRUE, and hidden if bShow is FALSE. _________________________________________________________________ aaSound Syntax BOOL aaSound(hAa, lpszDevice, lpszSound, wMode) Associates a sound with an animation. The sound is begun with the animation and will end when the ani- mation ends, unless it is shorter than the anima- tion. If it is shorter than the animation, it can be looped using aaSetParm with AA_RPTSOUND. FALSE is always returned by the limited version of the player. If the appropriate flag is set in wMode, when the sound is associated, an alias for the sound is cre- ated. This alias is formed by concatenating the word "AAPLAY" and the decimal value of the handle, hAa. This alias can be used to alter the playing of the sound. Parameters HAA hAa The handle of the animation returned by aaLoad. LPSTR lpszDevice If AA_SNDDEVICEID is not set in wMode, this argu- ment contains the name of the device used to play the sound. If you have setup MCI extensions, this argument can be NULL. If AA_SNDDEVICEID is set in wMode, this argument contains the MultiMedia Con- trol Interface Type ID. LPSTR lpszSound Either the name of the file containing the sound to be played, or a string used to play the sound. The format of the file must be supported by the device used to play it. If the device specified by lpszDevice is not given, or requires a file to be played, this argument is the name of the file to play. If the device does not use files for playing (cdaudio, videodisc, videotape, etc), this argument contains the play arguments for an MCI Command string to the device. WORD wMode This argument gives the mode of the sound The following modes are valid: AA_SNDFREEZE - 1 Normally the animation continues to play when the sound is being prepared for playing. Setting this value prevents this from happen- ing. AA_SNDDEVICEID - 256 Indicates that the device value is not the name of a sound device, but is the MultiMedia Control Interface Type ID. _________________________________________________________________ aaGetCaps Syntax WORD aaGetCaps(type) Returns information on the current capabilities of the animation player. Parameters WORD type The type of information to be returned. This pa- rameter can take on the following values: AA_CAP_TIMER - 1 Returns the accuracy of the timer in millisec- onds. The time between successive frames is always an integral multiple of the value re- turned. The value returned is 55 milliseconds if the Multimedia extensions are not in- stalled, or 1 millisecond if the extensions are installed. AA_CAP_SOUND - 2 Returns zero if sound support is not available in the player. Otherwise a non-zero value is returned. Sound is not available in the lim- ited version of the player, when the Multi- media extensions are not installed, or when there are no drivers in the [MCI] section of system.ini. Some versions of the player may not support sound even when the Multimedia ex- tensions are installed and there are drivers in the [MCI] section of system.ini. AA_CAP_SCRIPT - 3 Returns zero if script support is not avail- able in the player. Otherwise a non-zero value is returned. Scripts are not available in the limited version of the player. _________________________________________________________________ aaGetFile Syntax int aaGetFile(wFlags, lpzFileName, wSizeFile, lpzDe- viceName, wSizeDevice) Prompts the user for the name of a file, and copies the name entered to the location addressed by lpz- FileName. If the file is the name of a sound file, the Sound device name is copied to the location ad- dressed by lpzDeviceName. The return value is 0, if the user presses the cancel button, -1 if the se- lected file does not exist, or a positive number if the selected file does exist. Parameters WORD wFlags Flags used to control the dialog box. It is formed by adding the following values: AA_GETFILE_MUSTEXIST - 1 If set the file entered must exist before aaGetFile will return. AA_GETFILE_NOSHOWSPEC- 2 If set the search specification is not dis- played in the file name edit control. AA_GETFILE_SAVE - 4 If set the OK button is changed to read "Save", and the caption reads "Save". Setting this value automatically sets the AA_GETFILE_USEFILE flag. This flag is ignored in the limited version of the player. AA_GETFILE_OPEN - 8 If set the OK button is changed to read "Open", and the caption reads "Open" AA_GETFILE_USEDIR - 16 If set the directory of the current contents of the string addressed by lpzFileName is used as the initial directory in the dialog. AA_GETFILE_USEFILE - 32 If set the file name of the current contents of the string addressed by lpzFileName is put in the file name edit control. AA_GETFILE_SOUND - 64 If set the file specification for sound files is used in the dialog, and the caption reads "Sound". If neither AA_GETFILE_SOUND nor AA_GETFILE_SCRIPT is set in wFlags, the file specification for animation and script files is used in the dialog, and the caption reads "Animation". Setting this flag will cause the limited version of the player to return 0, indicating the cancel button was pressed. AA_GETFILE_SCRIPT - 128 If set the file specification for script files is used in the dialog, and the caption reads "Script". If neither AA_GETFILE_SOUND nor AA_GETFILE_SCRIPT is set in wFlags, the file specification for animation and script files is used in the dialog, and the caption reads "Animation". Setting this flag will cause the limited version of the player to return 0, indicating the cancel button was pressed. LPSTR lpzFileName A pointer to a string used to hold the file name entered. WORD wSizeFile The maximum size of the file name which can be returned. LPSTR lpzDeviceName A pointer to a string used to hold the Sound De- vice name entered. This parameter is only used if AA_GETFILE_SOUND is set in wFlags. WORD wSizeDevice The maximum size of the Sound Device name which can be returned.. _________________________________________________________________ aaSave Syntax BOOL aaSave(hAa, wMode) Saves the script of the animation whose handle is hAa. Returns TRUE is the script is saved, otherwise FALSE is returned. False is always returned by the limited version of the player. Parameters HAA hAa The handle of the animation returned by aaLoad. WORD wMode The mode used to save the animation. It is formed by adding the following values: AA_SAVE_IFMODIFIED - 1 The script is only saved if it has been modi- fied. AA_SAVE_AS - 2 The user is prompted for a new file name to save the script. If the script is untitled, the used is always prompted for a file name, whether or not this flag is set. Error Dialogs The following error messages are presented in dialogs: The animation can The Test button was pressed in the Pa- not be tested with rameters dialog, but an error occurred the selected parame- when the animation was run. ters. The selected parame- The OK button was pressed in the Parame- ters can not be ters dialog, but an error prevented the changed in this ani- parameters from being changed. mation. The value for speed The speed entered was either not a num- is invalid. Please ber or was outside of the valid range. enter a value be- The valid range is displayed in the mes- tween nn.n and nn.n. sage. The value for loops The loops entered was either not in the is invalid. Please proper format or was outside of the enter a value be- valid range. The valid range is dis- tween nnnn:nnn and played in the message. nnnn:nnn. The value for dura- The duration entered was either not in tion is invalid. the proper format or was outside of the Please enter a value valid range. The valid range is dis- between mm:ss.sss played in the message. and mm:ss.sss. The number of times The repeat value for sound was either the sound is to be not a number or was outside of the valid repeated is invalid. range. The valid range is displayed in Please enter a value the message. between nnn and nnn. The value for paus- The pause at end value was either not a ing the animation is number or was outside of the valid invalid. Please en- range. The valid range is displayed in ter a value between the message. nn.nnn and nn.nnn. The value for delay The delay sound value was either not a sound is invalid. number or was outside of the valid Please enter a value range. The valid range is displayed in between mm:nn.nnn the message. and mm:nn.nnn. The number of frames The length of the animation changed af- found in the anima- ter the animation was loaded. tion was incorrect. Loops cannot be The value chosen for loops would require changed while Dura- that the duration be changed, but the tion is locked and duration is locked and can not be has the value changed. mm:ss.sss. Duration cannot be The value chosen for duration would re- changed while loops quire that the loops be changed, but the is locked and has loops are locked and can not be changed. the value nnnn:nnn. In the following messages the file name following Script: is the name of the script in which the error occurred. The file name following Line: is the name of the animation on which the error was found. Script: xxx\xxx\xxx A file error occurred while saving the An error occurred script. The disk is probably full, or while saving the the script may be read only. script. Script: xxx\xxx\xxx A memory allocation error occurred. Internal Error! In- sufficient memory for operation. Script: xxx\xxx\xxx While reading a script an option begin- Line: xxx\xxx\xxx ning with a '-' was expected. Instead Expected switch the characters displayed were found. found "xxxxx". Script: xxx\xxx\xxx The loop count entered on the script Line: xxx\xxx\xxx line was either not in the proper format Loop count, "xxxxx", or out of range. is invalid. Script: xxx\xxx\xxx The animation speed entered on the Line: xxx\xxx\xxx script line was either not a number or Animation speed, out of range. "xxxxx", is invalid. Script: xxx\xxx\xxx The number of sound repeats entered on Line: xxx\xxx\xxx the script line was either not a number Number of sound re- or out of range. peats, "xxxxx", is invalid. Script: xxx\xxx\xxx The length of pause at the animation end Line: xxx\xxx\xxx was either not a number or out of range. Animation pause time, "xxxxx", is invalid. Script: xxx\xxx\xxx The sound delay was either not a number Line: xxx\xxx\xxx or out of range. The sound delay, "xxxxx", is invalid. Script: xxx\xxx\xxx The options for the line are inconsis- Line: xxx\xxx\xxx tent and could not be set. An error occurred changing the parame- ters for this line. The following messages allow Yes or No responses from the user. Script: xxx\xxx\xxx Presented when a modified script is un- The animation script loaded using aaUnload. If the user has been modified. presses Yes, a file save dialog is pre- Do you want to save sented and the user can select a file to the script? save the script. If the user presses No, the modifications are lost. Script: xxx\xxx\xxx Presented when the user selects an ex- The script already isting file from the file save dialog. exists. Do you want This can happen when unloading a modi- to overwrite the fied script, or when using aaSave with current script? AA_SAVE_AS set. If Yes is pressed, the existing file is overwritten. If No is pressed, the user is prompted for an- other file name. If cancel is pressed, the save operation is canceled, which may cause modifications to be lost.