CanDo: An Interactive Authoring Tool, Part 5: ANIMs, BrushANIMs, and Sound Sync and Part 6: Using AnimManager

by Randy Finch

In 1984, I first read (Compute!, August 1984) about a computer named Lorraine being developed by Amiga, a small computer company. At the time I owned a Commodore-64 and was considering buying a new computer. However, after reading the description of the Lorraine, I decided to save my money and prepare to purchase it when and if it ever came to market. I was not at all confident that this would become reality. Later, when I learned that Amiga had been purchased by Commodore, I became quite certain that the Lorraine computer would reach the marketplace.

About September or October 1985, the Lorraine, now called the Amiga 1000, hit the market. With money in hand I went to the nearest dealer, which was about 70 miles away, and began investigating this remarkable computer. The Amiga was quite expensive and I had to be sure it was worth it. After all, it was not compatible with my Commodore-64. I would have to purchase all new software, what little there was available at the time. There were three demos that really sold me on the power of the Amiga. One was the Robo-City animation. It was great! Robots walked a city street while a fire hydrant flexed it hose ports. Another demo was Boing. It was a big bouncing red and white beach ball that made a loud bong each time it hit a wall. The third demo was Music. It turned the computer keyboard into a musical keyboard. Various instruments were available for the sound. (By the way, Boing and Music still work on my accelerated Amiga 2000 running AmigaDOS 2.1. Alas, Robo-City does not.) I turned over my money and took my prize home. I have never regretted that decision. I still use that Amiga 1000 today.

The Amiga has come a long way. Many different models have come and gone. Also, with the increasing power of each generation has come more dramatic graphics and animation capabilities. (Who can forget the first time they saw the Juggler animation?) The Amiga's forte from the beginning has been its graphics, animation, and sound capabilities. It was these features that sold many people on the Amiga, including me.

One milestone in the history of the Amiga was the development of the ANIM file format. This brought standardization to animation files. Later came a variation of the ANIM format called the BrushANIM. This allowed brushes, or clips, to be animated. The ANIM format itself has evolved quite a bit. There have been many different compression schemes used with the most popular being the ANIM-5 format. Recently, ANIM-7 and ANIM-8 formats have been developed to allow high resolution animations to be played in real time on the Amiga 4000.

The 8SVX file format, which has been around since the beginning, helped standardize sound samples. It is still the standard for 8-bit sound samples on the Amiga.

CanDo Can Do Animations and Sound

CanDo has built-in support for BrushANIMs but not ANIMs. A utility program, AnimToBAnim, is included with CanDo. It allows ANIMs to be converted to BrushANIMs. Another included program called AnimManager can be used to play ANIM files. It can communicate with a CanDo deck via ARexx. CanDo allows other events, such as playing sounds, to be synchronized with an animation. CanDo also supports 8SVX sound samples. In this installment I will be discussing creating BrushANIMs from ANIMs, playing BrushANIMs and ANIMs, and synchronizing sound with an animation.

Converting ANIMs to BrushANIMs

If you want to convert an ANIM to a BrushANIM using a familiar yet timely method, you can load the ANIM into DeluxePaint and go through the procedure to grab the entire screen into a BrushANIM. A much easier way is to convert the ANIM file with the AnimToBAnim utility program included with CanDo. Unfortunately, the program only runs from the CLI. Fortunately, it is very easy to use. If you want to convert an ANIM file named myAnim to a BrushANIM file named myBAnim, simply type the following command in the CLI:

	AnimToBAnim myAnim myBAnim

This assumes that the directory in which AnimToBAnim resides, normally the CLIUtilities subdirectory of the CanDo directory, is on the path and that the current directory contains myAnim. The conversion is quite speedy. On my 68030/68882/28MHz accelerated Amiga 2000 using AmigaDOS 2.1, I was able to convert a 566,894-byte ANIM file (320x400, 32-color, 40 frames) to a 718,184-byte BrushANIM file in 35 seconds.

The AnimToBAnim utility also lets you extract just a portion of the ANIM file for conversion to a BrushANIM file. For instance, let's say you want to convert a 60x50 patch starting at an upper-left corner position of (130,175) to a BrushANIM file. You can type the following in the CLI:

	AnimToBAnim myAnim myBAnim 130 175 60 50

This procedure took 8 seconds on my Amiga using the same ANIM file mentioned earlier. The resulting BrushANIM file was 73,106 bytes long.

Preparing to Play a BrushANIM With Sound

When I first started to play around with animations and sound using CanDo, I decided that an appropriate animation to start with was one I created for a presention in my wife's Calculus class. I had written a C program entitled 3DPlot that draws user-defined 3-dimensional math functions (see Fred Fish Disk #440). I had created 20 pictures of the function N*SIN(X*Y) where N varied smoothly from 2 to -2. By converting these 20 frames to an animation (using DeluxePaint) and then tacking on the same pictures again in reverse order, I was able to create a 40-frame animation showing how the shape of the function's surface changed as the function's coefficient changed (Figure 1). I converted the resulting ANIM file to a BrushANIM using AnimToBAnim. In fact, this is the file I discussed converting earlier.

One of the sound samples that comes with CanDo is a file named Boing, which of course makes a boing sound. I thought it would be appropriate to add this sound to my animation playback at the two points of maximum expansion of the function's surface just before beginning its contraction. I also wanted to play around with the MoveBrushAnim command that allows a velocity and an acceleration to be set for a BrushANIM. The result is the ZPlayBAnim deck shown in Listing 1. Its interface is shown in Figure 2.

One of the first things I discovered when playing the BrushANIM with CanDo is that you need to set the resolution of the card's window to the resolution of the BrushANIM. My BrushANIM has a resolution of 320x400 while the card I first played it on had a resolution of 320x200. It played just fine except it was elongated and the bottom half was missing. This is not a bad thing, though. Sometimes you might want to play a BrushANIM at a different resolution. CanDo allows it. Once I adjusted the card's resolution to 320x400, the BrushANIM looked fine except ...

The second thing I discovered was that the screen colors of the card do not automatically change to match the BrushANIM's colors. They must be set before displaying the BrushANIM. Again, this is not a bad thing. By requiring the card's colors to be set in the deck, you can easily play back animations with altered colors. Fortunately, for those who want to play BrushANIMs in their original colors, there is a quick way to set the colors. Load the BrushANIM into DeluxePaint. Choose the menu item Color / Palette / Use Brush Palette. This will change the screen's color palette to that of the BrushANIM. Now save the blank DeluxePaint page to disk. From the Window requester in CanDo (Figure 3), make the card a Picture Window rather than a Normal Window. Select the DeluxePaint file that you saved earlier as the Picture to use for the card (see Listing 1, PictureWindow Definition section). Now when you run your application, the card will have the same colors as your BrushANIM.

Playing the BrushANIM

The program interface (Figure 2) has two buttons labeled "Play BAnim" and "Stop BAnim". I believe you can guess the function of each. Please refer to the appropriate sections of the code in Listing 1 during the following discussion.

When the "Play BAnim" button is pressed, the first command to execute is the ShowBrushAnim command. It specifies that the BrushANIM named sin(x*y)-40.banim in the CanDo:anims directory should be displayed in the window. The two zeroes at the end of the command indicate that the initial position of the BrushANIM should be at (0,0) relative to the window (upper left corner). If the BrushANIM is not already loaded, the ShowBrushAnim command will load it. If you want to load the BrushANIM without displaying it, use the LoadBrushAnim command. It has the following syntax:

	LoadBrushAnim filename, pseudoname, loadflags

One nice feature of this command is the use of the pseudoname. This allows you to refer to the animation later using the pseudoname rather than the filename. If you have a long path and filename, this can save a lot of typing. However, there is one caveat. If you want to use the Animation object on the Main Control Panel (see below), you cannot give the BrushANIM a pseudoname because the Animation object only accepts filenames. As you can see in Listing 1, I use the filename throughout.

The code following the ShowBrushAnim command is a loop that executes five times. The loop consists of four MoveBrushAnim commands. The MoveBrushAnim command specifies how a BrushANIM should move around on the screen. A velocity and/or acceleration can be specified. The first two numbers after the filename set the X and Y velocities, respectively. These values specify the number of pixels the BrushANIM should move in each direction from one frame to the next. The next two numbers, which are both set to zero in my program, specify the X and Y accelerations, respectively. These numbers will be added to their corresponding velocities from one frame to the next. The last value specifies the number of frames that should be displayed for this one MoveBrushAnim command. Finally, the keyword QUEUE is used. This tells CanDo that each MoveBrushAnim command should be put in a queue and played individually. Without the QUEUE keyword, the four MoveBrushAnim commands would be added together before actually moving the BrushANIM. Notice that the four MoveBrushAnim commands in Listing 1 cause the BrushANIM to move around the edges of a box. If the QUEUE keyword is removed from each command, then the four commands added together is NOTHING. The BrushANIM will not move at all. Finally, the BrushAnims ON command is issued to get the BrushANIM moving. If other BrushANIMs have been loaded and displayed, the BrushAnims ON command would start all of them.

Stopping the BrushANIM

The "Stop BAnim" button simply causes the command BrushAnims OFF to be executed. This stops the BrushANIM, but it will still be displayed on the screen. Since the BrushANIM that is displayed is full screen, the "Stop BAnim" button will be erased when it is displayed. However, the button is still active, and, if you can guess where to click, you can stop the animation. One way to avoid this is to display the BrushANIM on a separate card from the interface. A KeyInput object could be added to the card displaying the animation that allows a particular key press to display the interface card, whereupon the "Stop BAnim" button could be pressed with no guesswork. I leave this exercise to the reader.

Adding Sound

CanDo allows scripts to be executed for each frame of an animation, or for when it reaches its destination, or for any specified frame in the animation. This is done though the Animation object (Figure 4). When using the Animation object, make sure that the BrushANIM path and filename combination is not longer than 32 characters. If it is, the Animation object will not work properly.

I wanted to add the Boing sound to the function plot BrushANIM at its two points of maximum expansion. These occur at frames 20 and 40. By specifying that a script should execute at these frames, I was able to add the sounds I needed. Only one command is executed for each of these scripts, the PlaySound command. It simply specifies the name of the file containing the sound. There are several options available for the PlaySound command, but they were not needed in my program.

One Final Problem

There was one additional problem I encountered when playing my full screen BrushANIM. Double imaging. Most ANIM players use double buffering, which displays one frame of the animation while the next frame is being generated on an unseen screen. Once the next frame is generated, it is displayed. The next frame is then generated on the other screen which is now hidden, and so on. BrushANIMs are not displayed this way in CanDo. Each frame is generated on the same screen. Thus, if the screen is refreshed during the middle of generating the next frame of the animation, part of one frame can be mingled with the next frame causing double imaging. This is particularly true of interlaced screens. Also, the larger the BrushANIM, the greater the probability that double imaging will occur.

I used AnimToBAnim to create a 50x50 BrushANIM from my original ANIM file. I then animated it in a similar way to the full screen BrushANIM. The double imaging was not noticeable.

Yet Another Final Problem

Sometimes the Boing sound would be muffled to a "putt" sound as if there was not enough time to play the complete sound. I noticed that this occurred more frequently when the mouse was being moved at the time the sound was supposed to play. I am not positive about what causes this, but it seems that if there is enough other activity occurring on the computer then it interferes with the sound playback. I am using a 68030 28MHz accelerated Amiga 2000. Perhaps on an Amiga 4000, this would not be a problem.

Using AnimManager

If you have an ANIM file that you would like to play from within CanDo and you do not need to move it around on the screen as you can a BrushANIM, then AnimManager is the ticket. AnimManager is an AmigaDOS program included with CanDo that plays an ANIM file with full double-buffering so there is no double imaging problem. AnimManager has an ARexx interface that allows CanDo to communicate with it and control it via commands. Listing 2 is a CanDo deck, entitled ZPlayAnim, that uses AnimManager to play the original ANIM file of the math function stretching and contracting. The first thing that has to be done in the program is to establish ARexx communications with AnimManager. This is accomplished in a global routine called Communicate.

Establishing Communications

The first thing that the Communicate routine does is set up an ARexx port that the ZPlayAnim deck will listen to in order to receive information from AnimManager. I named this port ANIMFrameEvent. Next, the program tries to find AnimManager's ARexx port named AnimRexxPort. If this port cannot be found, then AnimManager is not currently executing and an error condition ensues. The IfError statement traps the error and then attempts to load AnimManager with the Dos command. Notice the -t option on the command line. This parameter tells AnimManager the name of the ARexx port it should speak to. A loop then executes wherein attempts are made to locate AnimRexxPort. If it is not found, the CanDo program is stopped. If it is found, the program continues.

Your Wish Is My ARexx Command

The first command sent to AnimManager is QuickLoadAnim. This command directs AnimManager to load an ANIM file. The filename is a parameter of the QuickLoadAnim command. QuickLoadAnim loads an ANIM file in such a way that it can only be played in a forward direction. If you want to load an ANIM file such that it can be played forwards and backwards, the LoadAnim command must be used. However, the loading time is longer since the format of the file has to be converted as it is loaded.

Next, the string variable Q is equated with a quotation mark. Note that the first quote indicates that a string constant follows. The next two consecutive quotes indicate that a literal quote is part of the string. Finally, the fourth quote indicates the end of the string constant. Q is used to embed a quotation mark in ARexx command strings. Two additional string variables are assigned; then two more commands are sent to AnimManager. Each is a SetFrameMark command. This command tells AnimManager to pass a message back to the CanDo deck when a particular frame of the animation is displayed. The first parameter of the SetFrameMark specifies the message to be sent back; the second parameter specifies the frame number at which to send the message. My program needs to know when frames 20 and 40 are reached in order to play the Boing sound. The message to be sent back at frame 20 is "Frame 20". The message to be sent back at frame 40 is, you guessed it, "Frame 40". In each of these messages the word Frame is the message, while the 20 and the 40 are parameters.

Executing the ZPlayAnim Deck

When the ZPlayAnim deck runs, the BeforeAttachment routine for the card PlayAnim executes. This routine simply calls the Communicate global routine. The PlayAnim card looks identical to the card used in the ZPlayBAnim deck described earlier except it uses a Normal Window rather than a Picture Window. The latter is not needed in this deck since AnimManager will display the animation on its own screen.

When the button labeled "Play Anim" is pressed, the Communicate routine is executed just in case AnimManager is no longer running. Next, the command "KeyControls On" is sent to AnimManager. This tells AnimManager to allow the user to control the animation playback using the computer keyboard. There are keys available for changing the speed of playback, pausing, stepping through the animation one frame at a time, and playing the animation in reverse order or in ping-pong mode. The latter two commands are only available when the ANIM file is loaded with LoadAnim rather than QuickLoadAnim. Be prepared to click on the animation screen before you press any control keys because even though the animation screen appears on top of all other screens, it is not the active screen until you click on it. Also, I discovered that if you press the key to play an animation in ping-pong mode when QuickLoadAnim is used to load it, then no other control keys will function except the ESCAPE key which exits the program.

Next, an AddButton command is sent to AnimManager. This command specifies that an invisible button should be added to the animation screen. AnimManager is told to send the message ClickButton to the CanDo deck when the user clicks within the region of the button. The button begins at the upper left hand corner of the screen (0,0) and is 50 pixels wide and 50 pixels tall. This button lets the user quickly exit AnimManager. (Really it is for instructional purposes since the ESCAPE key works just as well.)

Finally, the "Play Forward" command is issued to get the animation started and a flag variable AnimButton is set to FALSE. More about AnimButton later.

Synchronizing Sound

Because AnimManager was instructed to send the message FRAME back to the CanDo deck whenever frames 20 and 40 are displayed, an ARexx object needs to added to the card (Figure 5). This object is named PlaySound. Since the same sound is played at both frames 20 and 40, the parameter that is passed along with the FRAME message does not need to be checked. If different sounds were to be played for the two frames, then the frame number parameter would have to be checked to determine which sound to play. The ARexx object added to the PlayAnim card simply waits for an ARexx message of FRAME and then executes the PlaySound command. What could be simpler?

Quitting AnimManager

There are several ways to exit AnimManager. One is to press the ESCAPE key. This will only work if the "KeyControls On" command has been issued to AnimManager.

Another way to exit AnimManager is to switch to the CanDo card and press the "Stop Anim" button. This causes the OnRelease event script for the button to execute. It sends a "Quit" command to AnimManager.

The third way to exit AnimManager is to press the invisible button created with the AddButton command. This causes AnimManager to send a ClickButton message to the CanDo deck. This message is detected by another ARexx object named CheckQuit. When the message is received, the AnimButton flag is set to TRUE. "Why not just send a 'Quit' command to AnimManager at this point?" I hear you asking. Good question. This is the way I originally tried it. Whenever I clicked on the invisible button, the animation froze, and I could not do anything else. CanDo was frozen, also. However, other applications continued to work fine. It seemed as though ARexx communications had fouled up somehow. But what good does just setting a flag variable to TRUE do? Well, none unless you have a routine checking for AnimButton to be set to TRUE. Therefore, I added a Timer object (Figure 6) set to execute once a second. Each second, the value of AnimButton is checked. When it becomes equal to TRUE, AnimManager is sent messages telling it to push its screen to the back of other screens and then quit. The screen must be sent to the back before quitting or the program will freeze up as described earlier. Occasionally, AnimManager would freeze up using the technique shown in Listing 2; however, it was rare. The others methods caused a freeze-up 100 percent of the time.

Closing Comments

I hope you have learned a lot from the previous exercises. I know I have. Animation and sound can be a lot a fun. It is always exciting to see an image you have created moving about on the computer screen while sounds emanate from the speakers. There is much more that CanDo can do with animations and sound, but it would take too much space to cover it all in one article.

If you have any applications created with CanDo that you would like to share, please send them to me care of Amazing Computing. I will be interested in looking at them.

In the last installment, I mentioned that CanDo 2.51 requires commercial developers to have a license to distribute a custom runtime system provided by INOVAtronics. I have received more information about this. The yearly license fee is $50 to $200 depending on the type of applications distributed. The license can apply to single or multiple software titles.

I plan to discuss creating AmigaGuide help files in the next installment. Also, I have just received a copy of Helm, a new authoring tool from Eagle Tree Software. It appears that some of the capabilities I wanted to see in CanDo are available in Helm. Of course, there are probably other features that CanDo has that are missing in Helm. I plan to compare CanDo with Helm in a future installment.

Happy authoring.


Back to list of articles
Back to Randy Finch's Home Page
Last modified on April 1, 1996
Randy Finch at webmaster@rcfinch.com