Intel Animation for Java* Package Users Guide

• Introduction
• Overview
  • Sprites
  • AnimImages
  • Surface & AnimCanvas
  • Effects
• Getting Your Feet Wet
  • Working with Surface & AnimCanvas
  • Using StaticDataSprites
  • Moving Sprites
  • Animating Sprites
  • Using DynamicDataSprites
  • Applying Effects to Sprites

Introduction

The Intel Animation for Java* package is just what you've been looking for to make Java applets and applications come alive with high-speed animation and real-time effects.

The purpose of this document is to give the reader a thorough understanding of Intel Animation for Java. The first section will give an overview of the core elements of Intel Animation for Java. The second section will go into more detail, providing step-by-step examples of how to use the Intel Animation for Java package.

This document assumes the reader has a solid understanding of the Java programming language.

Overview

The basic components of the Intel Animation for Java package include the following: Sprites, AnimImages, the Surface & AnimCanvas, and Effects. This overview will give a high level discussion of these components.

Sprites

Sprites are visual objects in Intel Animation for Java. A sprite . . .

• has a home called a Surface.
• has a position on that Surface.
• can be moved to different positions on that Surface.
• has image data: a single image, or a sequence of images.
• can be animated with image sequence data.
• can have Effects applied to it, changing its appearance.
• can toggle its visibility on the Surface.

Sprites come in two types: StaticDataSprites and DynamicDataSprites. As these names suggest, a central feature of a Sprite is its data. A Sprite can have only one data source. We will talk more about data sources in the next section: AnimImages.

The image data in a StaticDataSprite is preprocessed. This means that a StaticDataSprite should have a data source that does not change. By preprocessing this data it can be displayed more quickly. The image data in a DynamicDataSprite is not preprocessed. This allows DynamicDataSprites to quickly change data sources without the overhead of preprocessing each data source.

AnimImages

Sprites get their data from AnimImages, of which there are two types: SingleImages and ImageSequences. A SingleImage is a 'wrapper' for a java.awt.Image (GIF or JPEG), and an ImageSequence is a container for multiple SingleImages. ImageSequences are used for flip book-style animation.

Surface & AnimCanvas

A Surface is where all the action takes place, and an AnimCanvas is what makes that action visible to the user.

A Surface gives Sprites a positional context. Sprites occupy space on a Surface, and can be moved from one position to another. It's a lot like arranging magnets on a whiteboard.

AnimCanvas is an extension of the java.awt.Canvas, and hence has all the capabilities of an AWT component. When all your work with a Surface is done, calling the repaint() method of the AnimCanvas makes your work visible to the Java applet or application.

Effects

One of the key features of the Intel Animation for Java package is the ability to apply real-time Effects to a Sprite. Multiple Effects can be applied to a Sprite, and Effects can be individually activated and deactivated at any time. Real-time means that Intel Animation for Java calculates a Sprite's new appearance as soon as an Effect is applied. This allows Effects to be highly responsive to user input.

The Intel Animation for Java package includes the following Effects: RotateXEffect, RotateYEffect, RotateZEffect, ScaleEffect, Affine2DEffect, HorizontalFlipEffect, and VerticalFlipEffect.

The RotateX, Y, and Z Effects rotate a Sprite around their respective axes. The ScaleEffect increases or decreases the size of a Sprite. The Affine2DEffect performs a shear, scale, and translation on a Sprite in one step. The Horizontal and Vertical FlipEffects flip a Sprite 180 degrees around their respective axes.

Getting Your Feet Wet

Now that you have an overview of the Intel Animation for Java package, the time has come to go into more detail. This section of the Intel Animation for Java Programmer's Guide will provide practical explanations for working with the Surface and AnimCanvas, using StaticDataSprites, moving Sprites, animating Sprites, using DynamicDataSprites, and applying Effects to Sprites.

Working with Surface & AnimCanvas

This section will cover the following topics: creating an AnimCanvas, adding an AnimCanvas to your applet or application, determining the dimensions of a Surface, ascertaining the color of a Surface, setting the color of a Surface, and painting the contents of a Surface to your applet or application.

Creating an AnimCanvas is a good place to start when using the Intel Animation for Java package.

AnimCanvas animcanvas = new AnimCanvas(SURFACE_HEIGHT, SURFACE_WIDTH);

The AnimCanvas can be placed in your applet or application like any other AWT component.

setLayout(new BorderLayout());

add("Center", animcanvas);

The AnimCanvas constructor automatically creates a Surface. The Surface can be accessed using the getSurface() method. The dimensions of a Surface can be determined by calling:

Dimension surface_dimension = animcanvas.getSurface().size();

The color of a Surface can be retrieved and set with the following methods:

Color surface_color = animcanvas.getSurface().getColor();

animcanvas.getSurface().setColor(COLOR);

The contents of a Surface are painted to the screen by calling:

animcanvas.repaint();

Using StaticDataSprites

This section will demonstrate how a GIF file becomes a Sprite, introduce the concept of transparency, and show how to find the dimensions of an AnimImage.

Creating a Sprite

Creating a Sprite entails the following steps:

1. create a java.awt.Image.
2. create a SingleImage.
3. set the transparency color of the SingleImage.
4. create a StaticDataSprite.
5. assign the SingleImage to the StaticDataSprite.
6. assign the StaticDataSprite to a Surface.
7. set the position of the StaticDataSprite on the Surface.
8. call repaint() to make the StaticDataSprite visible.

Now let's look at each step in more detail.

1. Create an java.awt.Image.

Image image = getImage(getDocumentBase(), "file.gif");

2. Create a SingleImage.

SingleImage spriteSource = new SingleImage(image);

3. Set the transparency color of the SingleImage. (The topic of transparency will be covered in more detail below.)

spriteSource.setTransparency(COLOR);

4. Create the StaticDataSprite.

StaticDataSprite sprite = new StaticDataSprite();

5. Assign the SingleImage to the StaticDataSprite.

sprite.setData(spriteSource);

6. Assign the StaticDataSprite to a Surface.

sprite.setDestination(animCanvas.getSurface());

7. Position the StaticDataSprite on the Surface. (The coordinate system of a Sprite will be discussed in the next section: Moving Sprites.)

sprite.setPosition(new Point3D(x, y, z));

8. Call repaint() to make the StaticDataSprite visible.

animcanvas.repaint();

Using Transparency

As seen in step 3, SingleImages support transparency color, in which a user-defined color is displayed as transparent. The following methods are available to get and clear the transparency color of a SingleImage.

Color COLOR = spriteSource.getTransparencyColor();

spriteSource.clearTransparency();

If you do not know the transparency color of an image, the java.awt.image.PixelGrabber class can be used to get the color of one pixel of an image. Example code for using the java.awt.image.PixelGrabber class can be found in the source code for Lesson 2 of Intel Animation for Java Tutorial.

Finding the Dimensions of an AnimImage

The dimensions of an AnimImage can be found with the following method:

Dimension anim_image_size = spriteSource.size();

Although spriteSource in this example is a SingleImage, the size() method can also be used with an ImageSequence.

Moving Sprites

In this section we will learn how to move a Sprite.

Before introducing the methods useful for moving Sprites, it is important to understand the coordinate system of a Sprite. The coordinate systems in Intel Animation for Java have the following characteristics:

• the origin is at the top left corner.
• the x coordinate increases toward the right.
• the y coordinate increases downward.
• the z coordinate represents depth. Sprites that have a lower z are drawn last, or over the sprites with a higher z. For example, if Sprite A has z = 200 and Sprite B has a z = 300, Sprite A is drawn after Sprite B (Sprite A appears to have been drawn over Sprite B).
• x and y can have negative values. z CANNOT have a negative value.

A Sprite can be moved in four steps:

1. get the position of the Sprite.
2. adjust the position.
3. set the position of the Sprite.
4. call repaint() to make the Sprite's new position visible.

Now let's look at each step in more detail.

1. Get the position of the Sprite.

Point3D pos = sprite.getPosition(sprite);

2. Adjust the position.

pos.x = pos.x + DELTA_X;

3. Set the position of the Sprite.

sprite.setPosition(pos);

4. Call repaint() to make the Sprite's new position visible.

animcanvas.repaint();

Animating Sprites

This section will walk through how to create an animated sequence, demonstrate how to animate a Sprite with ImageSequence data, and introduce some useful methods for working with animated Sprites.

Building an Animation Sequence

Creating an animation sequence entails the following steps:

1. create an ImageSequence.
2. create a java.awt.Image for each frame of the animation.
3. create a SingleImage for each sequence of the animation.
4. set the transparency of each SingleImage in the animation sequence.
5. put the SingleImages in the ImageSequence.

Now let's look at each step in more detail.

1. Create a java.awt.Image for each sequence of the animation.

ImageSequence seq = new ImageSequence(NUM_IMAGES_IN_SEQ, IMAGE_WIDTH, IMAGE_HEIGHT);

2. Create an awt.Image.

Image image1 = getImage(getDocumentBase(), "frame1.gif");

Image image2 = getImage(getDocumentBase(), "frame2.gif");

Image image3 = getImage(getDocumentBase(), "frame3.gif");

3. Create a SingleImage for each sequence of the animation.

SingleImage sequenceItem1 = new SingleImage(image1);

SingleImage sequenceItem2 = new SingleImage(image2);

SingleImage sequenceItem3 = new SingleImage(image3);

4. Set the transparency of each SingleImage in the animation sequence.

sequenceItem1.setTransparency(COLOR);

sequenceItem2.setTransparency(COLOR);

sequenceItem3.setTransparency(COLOR);

5. Put the SingleImages in the ImageSequence. Each SingleImage in an ImageSequence must have the same dimensions.

seq.setElementAt(sequenceItem1, 1);

seq.setElementAt(sequenceItem2, 2);

seq.setElementAt(sequenceItem3, 3);

Animating a Sprite with ImageSequence Data

This process includes the following steps:

1. create a StaticDataSprite.
2. assign the ImageSequence to the StaticDataSprite.
3. assign the StaticDataSprite to a Surface.
4. set the position of the StaticDataSprite on the Surface.
5. adjust the image number of the StaticDataSprite.
6. call repaint() to make the StaticDataSprite visible.

1. Create the sprite.

StaticDataSprite sprite = new StaticDataSprite();

2. Assign the ImageSequence to the StaticDataSprite.

sprite.setData(seq);

Steps 3 and 4 are the same as steps 6 and 7 in Using StaticDataSprites above.

5. Adjust the image number of the StaticDataSprite by 1.

sprite.adjustCurrentImageNumber(1);

6. Call repaint() to make the StaticDataSprite visible.

animcanvas.repaint();

By executing steps 5 and 6 in a loop, the Sprite becomes animated. The concept is analogous to flip-book animation. (When the image number reaches its maximum value, the next call to adjustCurrentImageNumber(1) will loop back to the first image number.)

Other Sprite Animation Methods

To get or set the current image number of a Sprite with ImageSequence data, use the following methods:

int image_num = sprite.getCurrentImageNumber();

sprite.setCurrentImageNumber(IMAGE_NUM);

This allows you to jump to a specific frame in the animation sequence.

Using DynamicDataSprites

This section will further clarify the differences between StaticDataSprites and DynamicDataSprites, introduce the concept of a Sprite's input and output view, and demonstrate how to change the input view of a DynamicDataSprite.

DynamicDataSprite Further Defined

A DynamicDataSprite is designed to be able to change its data source without the overhead of preprocessing each new set of data. For example, if you wanted to animate a character with different actions you would build an ImageSequence for each action. You might also have a SingleImage that represents the character when it is not moving. If the following DynamicDataSprite and AnimImages have been created:

DynamicDataSprite sprite;

ImageSequence walkSeq, runSeq, kickSeq;

SingleImage standImage;

Changing the data for a DynamicDataSprite is as simple as this:

sprite.setData(walkSeq);

sprite.setData(runSeq);

sprite.setData(kickSeq);

sprite.setData(standImage);

Over the lifetime of a StaticDataSprite, setData(AnimImage) should be called only once. Over the lifetime of a DynamicDataSprite, setData(AnimImage) can be called multiple times.

InputView and OutputView of a Sprite

Both the input and output view of a Sprite are packaged in a java.awt.Rectangle class. This means that both the input and output view have a position, as well as width and height.

The input view is on the coordinate system of the Sprite. The width and height of the input view is always the same as the width and height of a Sprite's data source. It is possible to modify a DynamicDataSprite's input view because its data is not preprocessed. This allows you to control how much of a DynamicDataSprite is visible. The procedure for changing the input view of a DynamicDataSprite will be covered below.

The output view is on the coordinate system of the Surface. The position, as well as the width and height, of the output view change when a Sprite's appearance is changed. The occurs when an Effect is applied to a Sprite. Effects will be discussed in the next section.

The input and output view of a Sprite (static or dynamic) can be retrieved by calling:

Rectangle sprite_inputview = sprite.getInputView();

Rectangle sprite_outputview = sprite.getOutputView();

Changing a DynamicDataSprite's InputView

The following code sample will change the input view of a DynamicDataSprite to display the upper right quadrant of the Sprite's AnimImage.

DynamicDataSprite sprite;

Rectangle new_input_view = new Rectangle();

new_input_view.x = SPRITE_WIDTH/2;

new_input_view.y = 0;

new_input_view.width = SPRITE_WIDTH/2;

new_input_view.height = SPRITE_HEIGHT/2;

sprite.setInputView(new_input_view);

Applying Effects to Sprites

This section will describe the Effects introduced in the overview in more detail, and give a step-by-step example using the RotateXEffect.

Each effect, except the Horizontal and Vertical FlipEffects, have Effect parameters. By explaining the parameters of each Effect, the function of each Effect will be made clear.

RotateXEffect, RotateYEffect

When rotating a Sprite around the x- or y-axis you must specify the x or y position of the axis. For example, this would allow you to rotate a Sprite around its center or its edge.

RotateXParam rotate_x_param = new RotateXParam(ANGLE, AXIS);

RotateYParam rotate_y_param = new RotateYParam(ANGLE, AXIS);

See RotateXParam in the JavaDocs.

RotateZEffect

When using the RotateZEffect you must specify the (x,y) coordinate of the z-axis, which is perpendicular to the screen. The position of the z-axis can be at any point on the Sprite. The (0,0) point of a Sprite is in the upper-left hand corner.

RotateZParam rotate_z_param = new RotateZParam(ANGLE, X_ORIGIN, Y_POSITION);

See RotateZParam in the JavaDocs.

ScaleEffect

ScaleEffect can change the size of a Sprite, create stretching Effects, and relocate the origin of a Sprite. If you do not apply ScaleEffect, the Sprite will be the same size as the original image. If you set Xscale at 2 and Yscale at 2, the Sprite will be twice as big. Setting Xscale and Yscale at 0.5 will make it half as big. If you set Xscale at 1 and Yscale at 2, the Sprite will stretch, becoming tall and skinny.

You can specify the origin that the Sprite will scale from by choosing (x,y) coordinates on the Sprite. The default origin is (0,0) or the upper-left corner. The origin determines how a sprite will expand when it is enlarged. At default (0,0) the sprite will begin at the upper-left corner and extend to the right and down. If the origin is at the center, (0.5,0.5) for a 1-by-1 sprite, the sprite will extend outwards in all directions.

ScaleParam scale_param = new ScaleParam(X_SCALE, Y_SCALE, X_POSITION, Y_POSITION);

See ScaleParam in the JavaDocs.

Affine2DEffect

An Affine2DEffect performs a shear, scale, and translation in one step. A shear deforms a Sprite by causing it to "lean" to one side or the other, depending on the parameters of an Affine2DEffect. The scale step of an Affine2DEffect is the same as the ScaleEffect. The final step of an Affine2DEffect, translation, adjusts the position of a Sprite in the x-y plane.

Affine2DParam affine_2D_param = new Affine2DParam(X_SCALE, Y_SCALE, X_SHEAR, Y_SHEAR, X_TRANS, Y_TRANS, X_POSITION, Y_POSITION);

See Affine2DParam in the JavaDocs.

Using the RotateXEffect

The following steps demonstrate how to apply a RotateXEffect to a Sprite. (This process is the same for other Effects.)

1. create an Effect parameter.
2. create an Effect.
3. apply the Effect to a Sprite.

Now let's look at each step in more detail.

1. Create an Effect parameter.

RotateXParam rotate_x_param = new RotateXParam(ANGLE, X_AXIS_OFFSET);

2. Create an Effect.

RotateXEffect rotate_x_effect = new RotateXEffect(rotate_x_param);

3. Apply the Effect to a Sprite.

sprite.applyEffect(rotate_x_effect);

After applyEffect() is called, the Effect is automatically activated (the Effect is performed). An Effect can be activated and deactivated by calling:

rotate_x_effect.activate(boolean)

An Effect's parameters can be retrieved and set with the following methods:

rotate_x_param = rotate_x_effect.getParams();

rotate_x_param.Angle = rotate_x_param.Angle + 5;

rotate_x_effect.setParams(rotate_x_param);

Call the repaint() method to update a Sprite's appearance.

animcanvas.repaint();

The Effect can be removed from the Sprite with

sprite.removeEffect(rotate_x_effect);

This page was last updated on Feb 11th, 1997.

Legal Stuff