Visual Effects for o Images

Displaying Image Sequences

ImagesPlayer is aimed at displaying the sequence of images making up an n, s, or g set of images.

The ImagesPlayer constructor takes the image's name, an animPeriod value, a seqDuration value, a Boolean indicating if the sequence should repeat, and a reference to the ImagesLoader:

     ImagesPlayer player = new ImagesPlayer(imagesName, animPeriod, seqDuration,                                                    isRepeating, imsLoader);

seqDuration is the total time required to show the entire sequence. Internally, this is used to calculate showPeriod, the amount of time each image will be the current one before the next image takes its place. animPeriod states how often ImagesPlayer's updateTick( ) method will be called (the animation period). updateTick( ) will be called periodically by the update( ) method in the top-level animation framework.

The current time is calculated when updateTick( ) is called and used to calculate imPosition, which specifies which image should be returned when getCurrentImage( ) is called. This process is illustrated in Figure 6-5.

This approach relies on the animation loop calling updateTick( ) regularly at a fixed time interval, which is true for ImagesTests. Another implicit assumption is that the showPeriod time duration will be larger than animPeriod. For example, showPeriod might be in tenths of seconds even though animPeriod may be in milliseconds. If showPeriod is less than animPeriod, then rendering progresses too slowly to display all

Figure 6-5. ImagesPlayer in use

the images within the required seqDuration time, and images (frames) will be skipped.

When the sequence finishes, a callback, sequenceEnded( ), can be invoked on a specified object implementing the ImagesPlayerWatcher interface. This is done for the n numbers images:

     numbersPlayer =  new ImagesPlayer("numbers", PERIOD, 1, false, imsLoader);     numbersPlayer.setWatcher(this);         // report sequence's finish to ImagesTests

In the case of numbers, animPeriod is PERIOD (0.1 seconds), seqDuration is one second, and the sequence will not repeat. Since there are six numbers files, showPeriod will be about 0.17 seconds and, therefore, (just) greater than the animPeriod.

Though ImagesPlayer is principally aimed at supporting regularly repeating animations, it also includes public methods for stopping, resuming, and restarting an animation at a given image position.

Implementation Details

The ImagesPlayer object maintains an animTotalTime variable, which holds the current time (in milliseconds) since the object was created. It is incremented when updateTick( ) is called:

     public void updateTick( )     // I assume that this method is called every animPeriod ms     {       if (!ticksIgnored) {         // update total animation time, modulo seq duration         animTotalTime = (animTotalTime + animPeriod) %                                    (long)(1000 * seqDuration);         // calculate current displayable image position         imPosition = (int) (animTotalTime / showPeriod);         if ((imPosition == numImages-1) && (!isRepeating)) {  //seq end           ticksIgnored = true;   // stop at this image           if (watcher != null)             watcher.sequenceEnded(imName);   // call callback         }       }     }

imPosition holds the index into the sequence of images. showPeriod is defined as:

     showPeriod = (int) (1000 * seqDuration / numImages);

This means that imPosition can only be a value between 0 and numImages-1.

getCurrentImage( ) uses imPosition to access the relevant image in the loader:

     public BufferedImage getCurrentImage( )     { if (numImages != 0)         return imsLoader.getImage(imName, imPosition);       else         return null;     }

getCurrentImage( )'s test of numImages is used to detect problems which may have arisen when the ImagesPlayer was created, for example, when the image name (imName) is unknown to the loader.

The ticksIgnored Boolean is employed to stop the progression of a sequence. In updateTick( ), if ticksIgnored is true, then the internal time counter, animTotalTime, will not be incremented. It is controlled by the stop( ), resume( ), and restartAt( ) methods. stop( ) sets the ticksIgnored Boolean:

     public void stop( )     {  ticksIgnored = true;  }