com.day.image

Class Animation

java.lang.Object

com.day.image.Animation

public class Animation
extends java.lang.Object

The Animation class takes a series of Layers and puts them in a single output graphic stream adding animation code for the number of loops and the delay time and disposal method of the single patches.

What we do in this class is accept a series of layers, which will make up the single images. Currently layers are inserted into the animation in the succession of their addition. For each layer added, you may define the display time in 1/100th seconds and the disposal method used at the end of the display time.

In addition you may set global looping instruction, on how many times the sequence of images should be displayed. To disable setting the loop control value in the output file, set the global loop value to a negative value.

Properties

The Animation class supports the following properties, which are all backed by setter and getter methods :

loops		The number of loops to go through the animation. The default is not set byte the constructor or the setter is 0, which boils down to an endless loop.
defaultDisposal		The action the image decoder should take after the display time of an image has elapsed. This must be one of the defined DISPOSAL_* constants. The default if not set by a constructor or the setter is DISPOSAL_BACKGROUND.
backgroundColor		The background color of the animation. The default if not set by a constructor or the setter is to take the background color of the first image in the animation as the background color.

Supported Image Format

Currently the Animation class is solely implemented based on the GIF image file format, whose general structure is described here. You will also note, that the API of the Animation class is based on the functionality the GIF format offers for animated image files.

CompuServe Graphics Interchange Format (GIF)

The CompuServe Graphics Interchange Format (GIF) is a multi-image graphics format, which provides the capability for simple animations provided the image viewer is capable of interpreting the multi-image nature of the image file and the instructions for display.

Generally a GIF file is made up of the following structural elements :

• GIF89a Header
• Logical Screen Descriptor Block, with optional global color table
• optional Netscape Application Extension Block
• stream of graphics
  • optional Graphic Control Block
  • Image Descriptor or Plain Text Block with optional local color table
• GIF Trailer

For more details, look at the GIF89 Specification. Generally this page contains many interesting information on animated GIFs.

Since:

coati

Field Summary

Fields

Modifier and Type	Field and Description
static int	DISPOSAL_BACKGROUND Restore to background color.
static int	DISPOSAL_NO Do not dispose.
static int	DISPOSAL_NONE No disposal specifed.
static int	DISPOSAL_PREVIOUS Restore to previous.

Constructor Summary

Constructors

Constructor and Description
Animation() Creates the Animation object using the default values.
Animation(int loops) Creates the Animation object using the given properties.
Animation(int loops, int defaultDisposal, int bgColor) Creates the Animation object using the given properties.

Method Summary

Modifier and Type	Method and Description
void	addLayer(Layer layer, int delay) Add a layer for display during the indicated delay time after which the image is disposed of using the default disposal method.
void	addLayer(Layer layer, int delay, int disposal) Add a layer for display during the indicated delay time after which the image is disposed of using the disposal method.
int	getBackgroundColor() Returns the current desired background color, -1 if undefined.
int	getDefaultDisposal() Return the current default disposal method used for newly added Layers.
int	getLoops() Returns the number of iterations through the images currently set.
Layer	removeLayer(int idx) Remove the layer with the given index from the Animation.
Layer	removeLayer(Layer layer) Removes the first layer (in chronological order) matching the given layer from the animation.
void	setBackgroundColor(int bgColor) Sets the desired background color.
void	setDefaultDisposal(int defaultDisposal) Sets the default disposal method for newly added Layers.
void	setLoops(int loops) Change the number of iterations through the images to the new value.
java.lang.String	toString() Convert the Animation to some string representation for intelligent display.
void	write(java.lang.String mimeType, int numColors, java.io.OutputStream outs) Write the animation to the output indicated.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

DISPOSAL_NONE

public static int DISPOSAL_NONE

No disposal specifed. The decoder is not required to take any action.

DISPOSAL_NO

public static int DISPOSAL_NO

Do not dispose. The graphic is to be left in place.

DISPOSAL_BACKGROUND

public static int DISPOSAL_BACKGROUND

Restore to background color. The area used by the graphic must be restored to the background color.

DISPOSAL_PREVIOUS

public static int DISPOSAL_PREVIOUS

Restore to previous. The decoder is required to restore the area overwritten by the graphic with what was there prior to rendering the graphic.

Constructor Detail

Animation

public Animation(int loops,
                 int defaultDisposal,
                 int bgColor)

Creates the Animation object using the given properties.

Parameters:

loops - Number of times the application should loop through the images. Use a negative value to prevent looping at all.

defaultDisposal - default disposal method for images after the delay time has elapsed

bgColor - The background color to set on the animated GIF. Only the red, green and blue values are used, the alpha value is ignored as GIF does not support alpha values.

Animation

public Animation(int loops)

Creates the Animation object using the given properties. The background color is taken from the first image in the animation while the default disposal method is set to DISPOSAL_BACKGROUND.

Parameters:

loops - Number of times the application should loop through the images. Use a negative value to prevent looping at all.

Animation

public Animation()

Creates the Animation object using the default values. The background color is taken from the first image in the animation while the default disposal method is set to DISPOSAL_BACKGROUND. The loop counter is initialized to 0, which means endless loop.

Method Detail

setLoops

public void setLoops(int loops)

Change the number of iterations through the images to the new value.

Parameters:

loops - Number of times the application should loop through the images. Use a negative value to prevent looping at all or set to 0 for endless looping.

getLoops

public int getLoops()

Returns the number of iterations through the images currently set.

Returns:

Number of iterations through the images.

setDefaultDisposal

public void setDefaultDisposal(int defaultDisposal)

Sets the default disposal method for newly added Layers. This setting does not affect Layers already added to the animation object !

Parameters:

defaultDisposal - The disposal method to use. This must be one of DISPOSAL_* constants defined above.

Throws:

java.lang.IllegalArgumentException - if the disposal value is illegal.

See Also:

DISPOSAL_NONE, DISPOSAL_NO, DISPOSAL_BACKGROUND, DISPOSAL_PREVIOUS

getDefaultDisposal

public int getDefaultDisposal()

Return the current default disposal method used for newly added Layers.

Returns:

current default disposal method used

setBackgroundColor

public void setBackgroundColor(int bgColor)

Sets the desired background color. If the desired color is -1, the background color of the first layer in the animation is taken as the animations background color.

Parameters:

bgColor - The new background color to set. Only the red, green and blue values are used, the alpha value is ignored as GIF does not support alpha values.

getBackgroundColor

public int getBackgroundColor()

Returns the current desired background color, -1 if undefined.

Returns:

the current desired background color, -1 if undefined.

addLayer

public void addLayer(Layer layer,
                     int delay)

Add a layer for display during the indicated delay time after which the image is disposed of using the default disposal method.

Parameters:

layer - the Layer object to add

delay - the display time of the image in 1/100 sec.

Throws:

java.lang.NullPointerException - if the layer is null.

addLayer

public void addLayer(Layer layer,
                     int delay,
                     int disposal)

Add a layer for display during the indicated delay time after which the image is disposed of using the disposal method.

Parameters:

layer - the Layer object to add

delay - the display time of the image in 1/100 sec.

disposal - the disposal method for the object. This must be one of the predefined DISPOSAL_* constants.

Throws:

java.lang.NullPointerException - if the layer is null.

java.lang.IllegalArgumentException - if the disposal value is not one of the predefined DISPOSAL_* constants.

See Also:

DISPOSAL_NONE, DISPOSAL_NO, DISPOSAL_BACKGROUND, DISPOSAL_PREVIOUS

removeLayer

public Layer removeLayer(int idx)

Remove the layer with the given index from the Animation.

Parameters:

idx - index of the Layer in the list

Returns:

the layer removed from the Animation

Throws:

java.lang.IndexOutOfBoundsException - if the index is less than zero or bigger than the number of layers in the animation.

java.lang.NullPointerException - if no layer is present at the given position.

removeLayer

public Layer removeLayer(Layer layer)

Removes the first layer (in chronological order) matching the given layer from the animation. If a layer is contained more than once within the animation, you must use multiple calls to removeLayer.

Parameters:

layer - Layer object to remove from the animation

Returns:

the layer removed from the animation or null if the layer was not part of the animation.

write

public void write(java.lang.String mimeType,
                  int numColors,
                  java.io.OutputStream outs)
           throws java.io.IOException

Write the animation to the output indicated.

Parameters:

mimeType - MIME type indicating the graphics output file format to use. Currently only image/gif is supported.

numColors - The number of colors to generate in the animated GIF, if not in the range [2 .. 256], 256 is taken as the default.

outs - the OutputStream used for output

Throws:

java.io.IOException - got from called write methods

java.lang.IllegalArgumentException - or if the mimeType is not image/gif or if the OutputStream is null.

toString

public java.lang.String toString()

Convert the Animation to some string representation for intelligent display.

Overrides:

toString in class java.lang.Object

Returns:

the string representation of the Animation object.