Programming Wireless Devices with the Java2 Platform

12.3 Sprites

A Sprite is a basic visual element whose appearance is provided by one of several frames stored in an Image. The developer can control which frame is used to render the Sprite, thereby enabling animation effects. Several transforms such as flipping and rotation can also be applied to a Sprite to further vary its appearance. As with all Layer subclasses, a Sprite's location can be changed, and it can also be made visible or invisible.

12.3.1 Frames

The raw frames used to render a Sprite are provided in a single Image object, which may be mutable or immutable. If more than one frame is used, they are packed into the Image as a series of equally-sized frames. The frames are defined when the Sprite is instantiated; they can also be updated by calling the setImage method.

As shown in Figure 12.2, the same set of frames may be stored in several different arrangements depending on what is most convenient for the game developer. The implementation automatically determines how the frames are arranged based on the dimensions of the frames and those of the Image. The width of the Image must be an integer multiple of the frame width, and the height of the Image must be an integer multiple of the frame height.

The Image is divided into frames whose dimensions are dictated by the frameWidth and frameHeight parameters in the Sprite's constructor. Each frame within the Image is assigned a unique index number; the frame located in the upper-left corner of the Image is assigned an index of 0. (See Figure 12.3.) The remaining frames are then numbered consecutively in row-major order (indices are assigned across the first row, then the second row, and so on.) The getRawFrameCount method returns the total number of raw frames.

In following example, a Sprite is created by dividing an Image into 8 frames that are 16 pixels wide and 23 pixels high:

Image carFrames = Image.createImage("/carframes.png");
Sprite car = new Sprite(carFrames, 16, 23);

12.3.2 Frame Sequence

The frame sequence of a Sprite defines an ordered list of frames to be displayed. The default frame sequence mirrors the list of available frames, so there is a direct mapping between the sequence index and the corresponding frame index. This also means that the length of the default frame sequence is equal to the number of raw frames. For example, if a Sprite has 4 frames, its default frame sequence is {0, 1, 2, 3}.

The developer must explicitly switch the current frame in the frame sequence. This may be accomplished by calling the Sprite.setFrame, Sprite.prevFrame, or Sprite.nextFrame methods. The method Sprite.setFrame sets the current index in the sequence array. The method Sprite.prevFrame decrements the current index, wrapping around to the last sequence element if necessary. The method Sprite.nextFrame increments the current index, wrapping around to the first sequence element if necessary. Note that these methods always operate on the sequence index, not frame indices, although the sequence indices and the frame indices are interchangeable if the default frame sequence is used.

If desired, an arbitrary frame sequence may be defined for a Sprite. The frame sequence is defined using an array of integers whereby each element references a valid frame index. The array must contain at least one element, and each element must contain a valid frame index. The setFrameSequence method is used to set the frame sequence; passing this method null as the frame sequence restores the default frame sequence.

By defining a new frame sequence, the developer can conveniently display the Sprite's frames in any order desired; frames may be repeated, omitted, shown in reverse order, and so forth. For example, Figure 12.4 shows a special frame sequence that is used when the car explodes. Note that certain frames are repeated so that they are shown for a longer period of time.

int[] explosionSequence = {1, 2, 3, 4, 4, 5, 5, 5, 6, 6, 7, 7};
car.setFrameSequence(explosionSequence);

12.3.3 Reference Pixel

As a subclass of Layer, class Sprite inherits various methods for setting and retrieving object location such as the methods setPosition(x,y), getX(), and getY(). These methods all define position in terms of the upper-left corner of the Sprite's visual bounds; however, in some cases, it is more convenient to define the Sprite's position in terms of an arbitrary pixel within its frame, especially if transforms are applied to the Sprite.

Therefore, Sprite includes the concept of a reference pixel. The reference pixel is defined by specifying its location in the Sprite's untransformed frame using the defineReferencePixel method. By default, the reference pixel is defined to be the pixel at (0,0) in the frame. If desired, the reference pixel may be defined outside of the frame's bounds.

As shown in Figure 12.5, the reference pixel can be thought of as having a pushpin in its center. In this example, we define the reference pixel to be a pixel in the center of the car's front axle:

car.defineReferencePixel(8, 5);

Once defined, this pushpin may be used to set and query the location of the Sprite. The getRefPixelX and getRefPixelY methods can be used to query the location of the pushpin in the painter's coordinate system. The setRefPixelPosition method can be used to position the Sprite by specifying where the pushpin should be located in the painter's coordinate system.

12.3.4 Transforms

Various transforms can be applied to a Sprite. The available transforms include rotations in multiples of 90 degrees combined with mirroring about the vertical axis. The transforms are identical to those provided for Image rendering. (See Section 11.5.7, "Drawing Images.") A Sprite's transform is set by calling its setTransform method.

When a transform is applied, the Sprite is automatically positioned so that its reference pixel appears stationary in the painter's coordinate system. Thus, the reference pixel's pushpin effectively becomes the center of the transform operation. Since the reference pixel does not move, the values returned by getRefPixelX and getRefPixelY remain the same; however, the values returned by getX and getY may change to reflect the movement of the Sprite's upper left corner.

For the car example shown in Figure 12.5, the reference pixel is located closer to the front, which makes the rear of the car appear to slide as it is rotated by 90 degrees in Figure 12.6.