ch.reto_hoehener.japng
Interface Apng

public interface Apng

The central interface of the Japng library to create animated PNG's from a sequence of individual images (the animation frames).

The boundaries of the entire animation are determined by the width and height of the first frame, regardless of whether it is part of the animation or not. The first frame (or default image) should be appropriately padded with fully transparent pixels if extra space will be needed for later frames.

Japng tries to conserve the original PNG chunks of the input frames, but can only do so if all input frames are valid PNG's and have the same bit depth, color type, compression method, filter method, interlace method, and palette (if any). If any of these conditions are not met, Japng will automatically convert all frames to PNG with color type 6 (true color with alpha).

Until the status of firefox bug 441971 is more clear, the combination of color type 3 PNG's (indexed color) and BlendOp.OVER for any frame will also cause a conversion to true color!

Usage Example 1:

 Apng apng = ApngFactory.createApng();
 apng.addFrame(new File("test1_0.png"), 1000);
 apng.addFrame(new File("test1_1.png"), 1000);
 apng.assemble(new File("test1.png"));
 

Usage Example 2:

 Apng apng = ApngFactory.createApng();
 apng.setPlayCount(3);
 apng.setSkipFirstFrame(true);
 apng.addFrame(new File("test2_0.png"), 0);
 apng.addFrame(new File("test2_1.png"), 1500);
 apng.addFrame(new File("test2_2.png"), 1600, DisposeOp.PREVIOUS, BlendOp.OVER,   10, 10);
 apng.addFrame(new File("test2_3.png"), 1700, DisposeOp.NONE,     BlendOp.OVER,   40, 10);
 apng.addFrame(new File("test2_4.png"), 1800, DisposeOp.NONE,     BlendOp.OVER,   40, 40);
 apng.addFrame(new File("test2_5.png"), 4000, DisposeOp.NONE,     BlendOp.SOURCE, 10, 40);
 apng.assemble(new File("test2.png"));
 

Usage Example 3:

 Apng apng = ApngFactory.createApng();
 apng.addFrame(            new File("test3_0.jpg"), 1000);
 apng.addFrame( new FileInputStream("test3_1.bmp"), 1000);
 apng.addFrame(            new File("test3_2.gif"), 1000, DisposeOp.PREVIOUS, BlendOp.OVER);
 apng.addFrame( new FileInputStream("test3_3.png"), 1000, DisposeOp.NONE,     BlendOp.OVER);
 apng.assemble(new FileOutputStream("test3.png"));
 

Version:

$Id: Apng.java 44 2008-06-29 17:25:49Z reto $

Field Summary

static int

INFINITE_LOOPING Constant signifying infinite looping.

Method Summary

void	addFrame(java.awt.image.BufferedImage image, int displayMillis) BufferedImage variant of addFrame(File, int)
void	addFrame(java.awt.image.BufferedImage image, int displayMillis, DisposeOp disposeOp, BlendOp blendOp) BufferedImage variant of addFrame(File, int, DisposeOp, BlendOp)
void	addFrame(java.awt.image.BufferedImage image, int displayMillis, DisposeOp disposeOp, BlendOp blendOp, int x_offset, int y_offset) BufferedImage variant of addFrame(File, int, DisposeOp, BlendOp, int, int)
void	addFrame(java.io.File imageFile, int displayMillis) Same as calling addFrame(imageFile, displayMillis, DisposeOp.NONE, BlendOp.SOURCE, 0, 0).
void	addFrame(java.io.File imageFile, int displayMillis, DisposeOp disposeOp, BlendOp blendOp) Same as calling addFrame(imageFile, displayMillis, disposeOp, blendOp, 0, 0).
void	addFrame(java.io.File imageFile, int displayMillis, DisposeOp disposeOp, BlendOp blendOp, int x_offset, int y_offset) Adds a frame to the animation, at the specified x/y offset.
void	addFrame(java.io.InputStream imageStream, int displayMillis) InputStream variant of addFrame(File, int)
void	addFrame(java.io.InputStream imageStream, int displayMillis, DisposeOp disposeOp, BlendOp blendOp) InputStream variant of addFrame(File, int, DisposeOp, BlendOp)
void	addFrame(java.io.InputStream imageStream, int displayMillis, DisposeOp disposeOp, BlendOp blendOp, int x_offset, int y_offset) InputStream variant of addFrame(File, int, DisposeOp, BlendOp, int, int)
void	assemble(java.io.File outputFile) Assembles all the previously added frames to an animated PNG and writes it to the specified outputFile.
void	assemble(java.io.OutputStream outputStream) OutputStream variant of assemble(File)
void	reset() Resets this Apng object.
void	setPlayCount(int playCount) playCount indicates the number of times that this animation should play - if it is 0, the animation should play indefinitely.
void	setSkipFirstFrame(boolean skipFirstFrame) If true, the first frame will not be shown by APNG-aware viewers.

Field Detail

INFINITE_LOOPING

static final int INFINITE_LOOPING

Constant signifying infinite looping.

See Also:

Constant Field Values

Method Detail

setPlayCount

void setPlayCount(int playCount)

playCount indicates the number of times that this animation should play - if it is 0, the animation should play indefinitely. If nonzero, the animation should come to rest on the final frame at the end of the last play.

(quoted from the APNG specification)

The default is 0 (Apng.INFINITE_LOOPING).

setSkipFirstFrame

void setSkipFirstFrame(boolean skipFirstFrame)

If true, the first frame will not be shown by APNG-aware viewers.

Set to true if the first frame does not belong to the animation and should only be displayed by viewers which do not support APNG.

The default value is false.

addFrame

void addFrame(java.io.File imageFile,
              int displayMillis)

Same as calling addFrame(imageFile, displayMillis, DisposeOp.NONE, BlendOp.SOURCE, 0, 0).

addFrame

void addFrame(java.io.File imageFile,
              int displayMillis,
              DisposeOp disposeOp,
              BlendOp blendOp)

Same as calling addFrame(imageFile, displayMillis, disposeOp, blendOp, 0, 0).

addFrame

void addFrame(java.io.File imageFile,
              int displayMillis,
              DisposeOp disposeOp,
              BlendOp blendOp,
              int x_offset,
              int y_offset)

Adds a frame to the animation, at the specified x/y offset.

Frame boundary constraints:

 x_offset >= 0
 y_offset >= 0
 x_offset + frame width  <= animation width
 y_offset + frame height <= animation height
 

Parameters:

imageFile - The file containing the frame image.

displayMillis - The number of milliseconds to display this frame. Valid range: [0, Short.MAX_VALUE].

disposeOp - Specifies how the output buffer should be changed at the end of this frame.

blendOp - Specifies how this frame is to be blended into the current output buffer.

x_offset - X position at which to render this frame (relative to default frame).

y_offset - Y position at which to render this frame (relative to default frame).

See Also:

DisposeOp, BlendOp

addFrame

void addFrame(java.io.InputStream imageStream,
              int displayMillis)

InputStream variant of addFrame(File, int)

addFrame

void addFrame(java.io.InputStream imageStream,
              int displayMillis,
              DisposeOp disposeOp,
              BlendOp blendOp)

InputStream variant of addFrame(File, int, DisposeOp, BlendOp)

addFrame

void addFrame(java.io.InputStream imageStream,
              int displayMillis,
              DisposeOp disposeOp,
              BlendOp blendOp,
              int x_offset,
              int y_offset)

InputStream variant of addFrame(File, int, DisposeOp, BlendOp, int, int)

addFrame

void addFrame(java.awt.image.BufferedImage image,
              int displayMillis)

BufferedImage variant of addFrame(File, int)

addFrame

void addFrame(java.awt.image.BufferedImage image,
              int displayMillis,
              DisposeOp disposeOp,
              BlendOp blendOp)

BufferedImage variant of addFrame(File, int, DisposeOp, BlendOp)

addFrame

void addFrame(java.awt.image.BufferedImage image,
              int displayMillis,
              DisposeOp disposeOp,
              BlendOp blendOp,
              int x_offset,
              int y_offset)

BufferedImage variant of addFrame(File, int, DisposeOp, BlendOp, int, int)

assemble

void assemble(java.io.File outputFile)
              throws JapngException

Assembles all the previously added frames to an animated PNG and writes it to the specified outputFile.

Throws:

JapngException

assemble

void assemble(java.io.OutputStream outputStream)
              throws JapngException

OutputStream variant of assemble(File)

Throws:

JapngException

reset

void reset()

Resets this Apng object. Discards all frame information and reverts playCount and skipFirstFrame to their default values.