Gif89Encoder

This is the central class of a JDK 1.1 compatible GIF encoder that, AFAIK, supports more features of the extended GIF spec than any other Java open source encoder. Some sections of the source are lifted or adapted from Jef Poskanzer's Acme GifEncoder (so please see the readme containing his notice), but much of it, including nearly all of the present class, is original code. My main motivation for writing a new encoder was to support animated GIFs, but the package also adds support for embedded textual comments.

There are still some limitations. For instance, animations are limited to a single global color table. But that is usually what you want anyway, so as to avoid irregularities on some displays. (So this is not really a limitation, but a "disciplinary feature" :) Another rather more serious restriction is that the total number of RGB colors in a given input-batch mustn't exceed 256. Obviously, there is an opening here for someone who would like to add a color-reducing preprocessor.

The encoder, though very usable in its present form, is at bottom only a partial implementation skewed toward my own particular needs. Hence a couple of caveats are in order. (1) During development it was in the back of my mind that an encoder object should be reusable - i.e., you should be able to make multiple calls to encode() on the same object, with or without intervening frame additions or changes to options. But I haven't reviewed the code with such usage in mind, much less tested it, so it's likely I overlooked something. (2) The encoder classes aren't thread safe, so use caution in a context where access is shared by multiple threads. (Better yet, finish the library and re-release it :)

There follow a couple of simple examples illustrating the most common way to use the encoder, i.e., to encode AWT Image objects created elsewhere in the program. Use of some of the most popular format options is also shown, though you will want to peruse the API for additional features.

Animated GIF Example

  import net.jmge.gif.Gif89Encoder;
  // ...
  void writeAnimatedGIF(Image[] still_images,
                        String annotation,
                        boolean looped,
                        double frames_per_second,
                        OutputStream out) throws IOException
  {
    Gif89Encoder gifenc = new Gif89Encoder();
    for (int i = 0; i < still_images.length; ++i)
      gifenc.addFrame(still_images[i]);
    gifenc.setComments(annotation);
    gifenc.setLoopCount(looped ? 0 : 1);
    gifenc.setUniformDelay((int) Math.round(100 / frames_per_second));
    gifenc.encode(out);
  }

Static GIF Example

  import net.jmge.gif.Gif89Encoder;
  // ...
  void writeNormalGIF(Image img,
                      String annotation,
                      int transparent_index,  // pass -1 for none
                      boolean interlaced,
                      OutputStream out) throws IOException
  {
    Gif89Encoder gifenc = new Gif89Encoder(img);
    gifenc.setComments(annotation);
    gifenc.setTransparentIndex(transparent_index);
    gifenc.getFrameAt(0).setInterlaced(interlaced);
    gifenc.encode(out);
  }

Constructor Summary
	Gif89Encoder() Use this default constructor if you'll be adding multiple frames constructed from RGB data (i.e., AWT Image objects or ARGB-pixel arrays).
	Gif89Encoder(Image static_image) Like the default except that it also adds a single frame, for conveniently encoding a static GIF from an image.
	Gif89Encoder(Color[] colors) This constructor installs a user color table, overriding the detection of of a palette from ARBG pixels.
	Gif89Encoder(Color[] colors, int width, int height, byte[] ci_pixels) Convenience constructor for encoding a static GIF from index-model data.

Method Summary
void	addFrame(Gif89Frame gf) Add a Gif89Frame frame to the end of the internal sequence.
void	addFrame(Image image) Convenience version of addFrame() that takes a Java Image, internally constructing the requisite DirectGif89Frame.
void	addFrame(int width, int height, byte[] ci_pixels) The index-model convenience version of addFrame().
void	encode(OutputStream out) After adding your frame(s) and setting your options, simply call this method to write the GIF to the passed stream.
Gif89Frame	getFrameAt(int index) Get a reference back to a Gif89Frame object by position.
int	getFrameCount() Get the number of frames that have been added so far.
void	insertFrame(int index, Gif89Frame gf) Like addFrame() except that the frame is inserted at a specific point in the sequence rather than appended.
static void	main(String[] args) A simple driver to test the installation and to demo usage.
void	setComments(String comments) Specify some textual comments to be embedded in GIF.
void	setLogicalDisplay(Dimension dim, int background) Sets attributes of the multi-image display area, if applicable.
void	setLoopCount(int count) Set animation looping parameter, if applicable.
void	setTransparentIndex(int index) Set the color table index for the transparent color, if any.
void	setUniformDelay(int interval) A convenience method for setting the "animation speed".

A simple driver to test the installation and to demo usage. Put the JAR on your classpath and run ala

java net.jmge.gif.Gif89Encoder {filename}

The filename must be either (1) a JPEG file with extension 'jpg', for conversion to a static GIF, or (2) a file containing a list of GIFs and/or JPEGs, one per line, to be combined into an animated GIF. The output will appear in the current directory as 'gif89out.gif'.

(N.B. This test program will abort if the input file(s) exceed(s) 256 total RGB colors, so in its present form it has no value as a generic JPEG to GIF converter. Also, when multiple files are input, you need to be wary of the total color count, regardless of file type.)

Parameters: args Command-line arguments, only the first of which is used, as mentioned above.

Class Gif89Encoder

Constructor Detail

Gif89Encoder

Gif89Encoder

Gif89Encoder

Gif89Encoder

Method Detail

addFrame

addFrame

addFrame

encode

getFrameAt

getFrameCount

insertFrame

main

setComments

setLogicalDisplay

setLoopCount

setTransparentIndex

setUniformDelay