com.gif4j
Class GifImage

java.lang.Object
  com.gif4j.GifImage

public class GifImage

extends java.lang.Object

An instance of this java class is used to represent a gif image as a sequence of one or more frames (instances of GifFrame class) and to contain the next general gif image specific parameters:

Logical Screen Descriptor - The Logical Screen Descriptor contains the parameters necessary to define the area of the display device within which the images will be rendered. The coordinates in this block are given with respect to the top-left corner of the virtual screen; they do not necessarily refer to absolute coordinates on the display device. This implies that they could refer to window coordinates in a window-based environment or printer coordinates when a printer is used.
The logical screen area should be large enough to display all of your individual frames in it. If an image in the GIF file is larger than the logical screen or, by its positioning, extends beyond the screen, the portion that is off-screen will not be displayed.

Global Color Table (global palette, optional field) - This palette can have 2, 4, 8, 16, 32, 64, 128 , or 256 defined colors. Palettes are very important. Every color displayed in your GIF must come from a palette. The fewer colors used, the easier it will be for systems to display your images. The global palette is applied to all images in a GIF file. If an individual images differs greatly from that global palette, it may have a local palette that affects its color ONLY. However, no image can every reference more than one palette, so 256 colors per image is the max.
Gif4J doesn't calculate and use global color table by default. To receive better quality every added GifFrame has his own Local Color Table, but to optimize final image size (every Local Color Table takes up to 768 bytes) you can force Global Color Table usage (see GifEncoder.encode(GifImage gifImage, java.io.OutputStream outputStream, boolean forceGlobalColorTableUsage)). In this case local color tables will be union to global color table. This feature is recommended to use for images with a lot of GifFrames.

Loop Extension - gif image can have an Application Extension Block that tells Encoder to loop the entire GIF file.

Comments - gif image can have a plenty of embedded ASCII text comments.

To add new frame the next methods can be used:
addGifFrame(GifFrame frame),
addGifFrame(GifFrame frame, MorphingFilter filter),
addGifFrame(GifFrame frame, Watermark watermark),
addGifFrame(GifFrame frame, MorphingFilter filter, Watermark watermark)

GifImage is also used to control the next general parameters:

final image size by provided 'resize strategy' parameter:
RESIZE_STRATEGY_CROP_TO_FIT_IMAGE_SIZE,
RESIZE_STRATEGY_SCALE_TO_FIT_IMAGE_SIZE,
RESIZE_STRATEGY_EXTEND_TO_CURRENT
'resize strategy' parameter can be set by using the next constructors: GifImage(int resizeStrategy),
GifImage(int width, int height, int resizeStrategy)

general delay between image frames:
setDefaultDelay(int delay)

number of iterations the gif animation loop should be executed:
setLoopNumber(int number)

Hint: Use GifDecoder java class to load and decode GIF images into GifImage(-s) from input streams and files.
Use GifEncoder java class to encode and save GifImage(-s) into the GIF89a image file format to output streams and files.

Version:

2.0

Author:

Gif4J Software - Java GIF image processing solutions

See Also:

GifFrame, GifEncoder, GifDecoder

Field Summary

static int	RESIZE_STRATEGY_CROP_TO_FIT_IMAGE_SIZE Represents a resize strategy, when every subsequent image frame is necessarily resized by cropping to fit the fixed logical screen size.
static int	RESIZE_STRATEGY_EXTEND_TO_CURRENT Represents a resize strategy, when logical screen width and height are necessarily extended to support the adding frame's size.
static int	RESIZE_STRATEGY_SCALE_TO_FIT_IMAGE_SIZE Represents a resize strategy, when every subsequent image frame is necessarily resized by scaling to fit the fixed logical screen size.

Constructor Summary

GifImage()
Constructs GifImage with RESIZE_STRATEGY_EXTEND_TO_CURRENT resize strategy and indefinite general gif image width and height (these parameters will be taken from the first added GifFrame).

GifImage(int resizeStrategy)
Constructs GifImage of one of the predefined resize strategies and indefinite logical screen width and height (these parameters will be taken from the first added GifFrame).

GifImage(int width, int height)
Constructs GifImage with RESIZE_STRATEGY_SCALE_TO_FIT_IMAGE_SIZE resize strategy and the specified general logical screen width and height.

GifImage(int width, int height, int resizeStrategy)
Constructs GifImage of one of the predefined resize strategies and general logical screen width and height.

Method Summary

void	addComment(java.lang.String comment) Add ASCII textual comment to be embedded in this GIF image.
GifImage	addGifFrame(GifFrame frame) Add the specified frame to the end of the internal sequence.
GifImage	addGifFrame(GifFrame frame, MorphingFilter filter) Add the specified frame to the end of the internal sequence and set the specified morphing filter which will be applied to adding frame before the encoding process starts.
GifImage	addGifFrame(GifFrame frame, MorphingFilter filter, Watermark watermark) Add the specified frame to the end of the internal sequence, set the specified morphing filter and watermark which will be applied to adding frame before the encoding process starts.
GifImage	addGifFrame(GifFrame frame, Watermark watermark) Add the specified frame to the end of the internal sequence and set the specified watermark which will be applied to adding frame before the encoding process starts.
java.util.Iterator	comments() Returns an iterator over the elements in the comments array or null if comments array is empty.
java.util.Iterator	frames() Returns an iterator over the frames (GifFrame instances) in the current frames sequence.
java.lang.String	getComment(int index) Returns ASCII textual comment as a String from comments array at the specified index.
int	getCurrentLogicHeight() Returns current logic screen height
int	getCurrentLogicWidth() Returns current logic screen width
GifFrame	getFrame(int index) Returns GifFrame at the specified index in the current frames sequence.
GifFrame	getLastFrame() Returns the last GifFrame in the current frames sequence
int	getLoopNumber() Returns number of animated gif image loop iterations
int	getNumberOfComments() Returns the number of text comments in the comments array.
int	getNumberOfFrames() Returns the number of frames in the current frames sequence.
int	getScreenHeight() Returns gif image logic screen height
int	getScreenWidth() Returns gif image logic screen width
java.awt.Color	getTransparentColor() Returns the transparent color set by setTransparentColor(java.awt.Color) method.
java.lang.String	getVersion() Get GIF image format version number.
void	removeComment(int index) Remove ASCII textual comment from comments array at the specified index.
void	setDefaultDelay(int delay) Set default delay between frames.
void	setLoopNumber(int number) Set number of iterations the loop should be executed.
void	setTransparentColor(java.awt.Color color) Set the transparent color to replace a source transparent color in GIF image palette

Methods inherited from class java.lang.Object

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

Field Detail

RESIZE_STRATEGY_CROP_TO_FIT_IMAGE_SIZE

public static final int RESIZE_STRATEGY_CROP_TO_FIT_IMAGE_SIZE

Represents a resize strategy, when every subsequent image frame is necessarily resized by cropping to fit the fixed logical screen size.

See Also:

Constant Field Values

RESIZE_STRATEGY_EXTEND_TO_CURRENT

public static final int RESIZE_STRATEGY_EXTEND_TO_CURRENT

Represents a resize strategy, when logical screen width and height are necessarily extended to support the adding frame's size.

This strategy is used by default.

See Also:

Constant Field Values

RESIZE_STRATEGY_SCALE_TO_FIT_IMAGE_SIZE

public static final int RESIZE_STRATEGY_SCALE_TO_FIT_IMAGE_SIZE

Represents a resize strategy, when every subsequent image frame is necessarily resized by scaling to fit the fixed logical screen size.

See Also:

Constant Field Values

Constructor Detail

GifImage

public GifImage()

Constructs GifImage with RESIZE_STRATEGY_EXTEND_TO_CURRENT resize strategy and indefinite general gif image width and height (these parameters will be taken from the first added GifFrame).

GifImage

public GifImage(int resizeStrategy)

Constructs GifImage of one of the predefined resize strategies and indefinite logical screen width and height (these parameters will be taken from the first added GifFrame).

Parameters:

resizeStrategy - one of the predefined resize strategies:
RESIZE_STRATEGY_CROP_TO_FIT_IMAGE_SIZE,
RESIZE_STRATEGY_SCALE_TO_FIT_IMAGE_SIZE,
RESIZE_STRATEGY_EXTEND_TO_CURRENT

GifImage

public GifImage(int width,
                int height)

Constructs GifImage with RESIZE_STRATEGY_SCALE_TO_FIT_IMAGE_SIZE resize strategy and the specified general logical screen width and height. All added frames will be validated and resized if need to fit these width and height.

Parameters:

width - logical screen width (in pixels)

height - logical screen height (in pixels)

Throws:

java.lang.IllegalArgumentException - If width and/or height parameter less than 1.

GifImage

public GifImage(int width,
                int height,
                int resizeStrategy)

Constructs GifImage of one of the predefined resize strategies and general logical screen width and height. All added frames will be validated and resized if need to fit these width and height.

Parameters:

width - logical screen width (in pixels)

height - logical screen height (in pixels)

resizeStrategy - one of the predefined resize strategies:
RESIZE_STRATEGY_CROP_TO_FIT_IMAGE_SIZE,
RESIZE_STRATEGY_SCALE_TO_FIT_IMAGE_SIZE,
RESIZE_STRATEGY_EXTEND_TO_CURRENT

Throws:

java.lang.IllegalArgumentException - If width and/or height parameter less than 1.

Method Detail

addComment

public void addComment(java.lang.String comment)

Add ASCII textual comment to be embedded in this GIF image.

Parameters:

comment - string containing ASCII text comment

Throws:

java.lang.NullPointerException - If comment string is null

Since:

2.0

See Also:

getComment(int), getNumberOfComments()

addGifFrame

public GifImage addGifFrame(GifFrame frame)

Add the specified frame to the end of the internal sequence.

Parameters:

frame - GifFrame to add

Returns:

this GifImage instance

Throws:

java.lang.NullPointerException - If frame to add is null.

See Also:

GifFrame

addGifFrame

public GifImage addGifFrame(GifFrame frame,
                            MorphingFilter filter)

Add the specified frame to the end of the internal sequence and set the specified morphing filter which will be applied to adding frame before the encoding process starts.

Parameters:

frame - GifFrame to add

filter - MorphingFilter to apply

Returns:

this GifImage instance

Throws:

java.lang.NullPointerException - If frame to add is null.

See Also:

MorphingFilter, GifFrame

addGifFrame

public GifImage addGifFrame(GifFrame frame,
                            MorphingFilter filter,
                            Watermark watermark)

Add the specified frame to the end of the internal sequence, set the specified morphing filter and watermark which will be applied to adding frame before the encoding process starts.

Parameters:

frame - GifFrame to add

filter - MorphingFilter to apply

watermark - Watermark to apply

Returns:

this GifImage instance

Throws:

java.lang.NullPointerException - If frame to add is null.

See Also:

GifFrame, Watermark, MorphingFilter

addGifFrame

public GifImage addGifFrame(GifFrame frame,
                            Watermark watermark)

Add the specified frame to the end of the internal sequence and set the specified watermark which will be applied to adding frame before the encoding process starts.

Parameters:

frame - GifFrame to add

watermark - Watermark to apply

Returns:

this GifImage instance

Throws:

java.lang.NullPointerException - If frame to add is null.

See Also:

Watermark, GifFrame

comments

public java.util.Iterator comments()

Returns an iterator over the elements in the comments array or null if comments array is empty.

Returns:

an iterator over the elements in the comments array

Since:

2.0

See Also:

addComment(java.lang.String), getComment(int), getNumberOfComments()

frames

public java.util.Iterator frames()

Returns an iterator over the frames (GifFrame instances) in the current frames sequence.

Returns:

an iterator over the frames

Since:

2.0

See Also:

getNumberOfFrames()

getComment

public java.lang.String getComment(int index)

Returns ASCII textual comment as a String from comments array at the specified index.

Parameters:

index - the index of the comment to be retrieved

Returns:

the comment string at the specified index

Throws:

java.lang.IllegalArgumentException - if comments array is empty or the specified index is invalid (less than 0 or more than or equal to the size of comments array)

Since:

2.0

See Also:

addComment(java.lang.String), getNumberOfComments()

getCurrentLogicHeight

public int getCurrentLogicHeight()

Returns current logic screen height

Returns:

current logic screen height

getCurrentLogicWidth

public int getCurrentLogicWidth()

Returns current logic screen width

Returns:

current logic screen width

getFrame

public GifFrame getFrame(int index)

Returns GifFrame at the specified index in the current frames sequence.

Parameters:

index - the index of the GifFrame to be retrieved

Returns:

GifFrame at the specified index.

Throws:

java.lang.IllegalArgumentException - if frames sequence is empty or the specified index is invalid (less than 0 or more than or equal to the size of frames sequence)

Since:

2.0

See Also:

getNumberOfFrames()

getLastFrame

public GifFrame getLastFrame()

Returns the last GifFrame in the current frames sequence

Returns:

the last GifFrame in the current frames sequence

getLoopNumber

public int getLoopNumber()

Returns number of animated gif image loop iterations

Returns:

number of animated gif image loop iterations

getNumberOfComments

public int getNumberOfComments()

Returns the number of text comments in the comments array.

Returns:

number of comments in the comments array

Since:

2.0

See Also:

addComment(java.lang.String), getComment(int)

getNumberOfFrames

public int getNumberOfFrames()

Returns the number of frames in the current frames sequence.

Returns:

number of frames

Since:

2.0

See Also:

frames(), getFrame(int), getLastFrame()

getScreenHeight

public int getScreenHeight()

Returns gif image logic screen height

Returns:

current logic screen height

getScreenWidth

public int getScreenWidth()

Returns gif image logic screen width

Returns:

gif image logic screen width

getTransparentColor

public java.awt.Color getTransparentColor()

Returns the transparent color set by setTransparentColor(java.awt.Color) method. If not set before returns NULL.

Returns:

the transparent color set by setTransparentColor(java.awt.Color) method. If not set before returns NULL.

Since:

2.3

getVersion

public java.lang.String getVersion()

Get GIF image format version number. Returns one of the following values: "87a", "89a"

Returns:

GIF image format version

removeComment

public void removeComment(int index)

Remove ASCII textual comment from comments array at the specified index.

Parameters:

index - the index of the comment to be removed

Throws:

java.lang.IllegalArgumentException - if comments array is empty or the specified index is invalid (less than 0 or more than or equal to the size of comments array)

Since:

2.0

See Also:

addComment(java.lang.String), getNumberOfComments()

setDefaultDelay

public void setDefaultDelay(int delay)

Set default delay between frames. This delay is automatically applied to adding frames without delay set. If not set - value of 200 (2 seconds) is used.

Parameters:

delay - delay time in 1/100 (centiseconds) - value 100 means delay in 1 second.

Throws:

java.lang.IllegalArgumentException - If delay less than 1.

setLoopNumber

public void setLoopNumber(int number)

Set number of iterations the loop should be executed.

Parameters:

number - Number of iterations the loop should be executed: value of 0 set indefinite looping (is set by default). Maximum iterations number (excluding indefinite looping) is 65535.

Throws:

java.lang.IllegalArgumentException - If number less than 0.

setTransparentColor

public void setTransparentColor(java.awt.Color color)

Set the transparent color to replace a source transparent color in GIF image palette

Parameters:

color - transparent color to set

Since:

2.3