com.gif4j.light
Class GifEncoder

java.lang.Object
  com.gif4j.light.GifEncoder

public class GifEncoder

extends java.lang.Object

GifEncoder is a java class which takes as image(-s), encodes and saves it(them) out to a file or output stream using the GIF file format (GIF89a version). It can be used to save Image instances as non-animated GIF image files or prepared from the images sequence GifImage instances as animated GIF image files. If an encoding Image instance has more than 256 colors then before writing it as a GIF to the specified output stream it's automatically quantized to 256 unique colors. GifEncoder java class is thread safe and can be used without addittional synchronization.

The following 2 java examples demostrate common ways to use this java gif image encoder. Please peruse the API, tutorial and external examples for additional features.

Save an image as a commented GIF file using Java

 import com.gif4j.light.GifEncoder;
 import com.gif4j.light.GifFrame;
 import com.gif4j.light.GifImage;

 import java.awt.*;
 import java.io.File;
 import java.io.IOException;

     // ...

   public void saveImageAsGif(Image image, String comment, File fileToSave)
             throws IOException, InterruptedException {
         // create new GifImage
         GifImage gifImage = new GifImage();
         // create new GifFrame
         GifFrame gifFrame = new GifFrame(image);
         // add GifFrame to GifImage
         gifImage.addGifFrame(gifFrame);
         // add our comment
         gifImage.addComment(comment);
         // save gifImage
         GifEncoder.encode(gifImage, fileToSave);
     }

 

Save array of images as an animated GIF file using Java

 import com.gif4j.light.GifEncoder;
 import com.gif4j.light.GifFrame;
 import com.gif4j.light.GifImage;

 import java.awt.*;
 import java.io.File;
 import java.io.IOException;

    // ...

    public void saveImageArrayAsAnimatedGif(Image[] images, File fileToSave)
            throws IOException, InterruptedException {
        // create new GifImage instance
        GifImage gifImage = new GifImage();
        // set default delay between gif frames
        gifImage.setDefaultDelay(200);
        // set infinite looping (by default only 1 looping iteration is set)
        gifImage.setLoopNumber(0);
        // add comment to gif image
        gifImage.addComment("Animated GIF image example");
        // add images wrapped by GifFrame
        for (int i = 0; i < images.length; i++){
            GifFrame nextFrame = new GifFrame(images[i]);
            // clear logic screen after every frame
            nextFrame.setDisposalMethod(GifFrame.DISPOSAL_METHOD_RESTORE_TO_BACKGROUND_COLOR);
            gifImage.addGifFrame(nextFrame);
        }
        // save animated gif image
        GifEncoder.encode(gifImage, fileToSave);
    }
 

Note: After encoding a GifImage instance and its' internal GifFrame(-s) are disposed to free memory and can't be reused!

The following specification "GRAPHICS INTERCHANGE FORMAT(sm) Version 89a" was referenced for the development of this encoder.
Some of the naming conventions and clarification of some aspects of GIF file format and LZW compression were obtained from the following:
LZW.C
Copyright (c) 1989 Mark R. Nelson
LZW data compression/expansion demonstration program.
May 12, 1997

Version:

1.0

Author:

Gif4J Software - Java GIF image processing solutions

See Also:

GifImage, Image

Method Summary

static void	encode(GifImage gifImage, java.io.File output) Encode and write out the data contained in the GifImage to a File in the GIF output format ('89a' version).
static void	encode(GifImage gifImage, java.io.File output, boolean forceGlobalColorTableUsage) Encode and write out the data contained in the GifImage to a File in the GIF output format ('89a' version).
static void	encode(GifImage gifImage, java.io.OutputStream outputStream) Encode and write out the data contained in the GifImage to the specified output stream in the GIF image file format ('89a' version).
static void	encode(GifImage gifImage, java.io.OutputStream outputStream, boolean forceGlobalColorTableUsage) Encode and write out the data contained in the GifImage to the specified output stream in the GIF file format ('89a' version).
static void	encode(java.awt.Image image, java.io.DataOutput dataOutput) Encode and write out the data contained in the Image to the specified output in the GIF89a file format.
static void	encode(java.awt.Image image, java.io.File output) Encode and write out the data contained in the Image to a File in the GIF output format ('89a' version).
static void	encode(java.awt.Image image, java.io.OutputStream outputStream) Encode and write out the data contained in the Image to the output stream in the GIF89a file format.

Methods inherited from class java.lang.Object

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

Method Detail

encode

public static final void encode(GifImage gifImage,
                                java.io.OutputStream outputStream)
                         throws java.io.IOException

Encode and write out the data contained in the GifImage to the specified output stream in the GIF image file format ('89a' version).

Parameters:

gifImage - GifImage to encode and write out

outputStream - the specified stream to output

Throws:

java.io.IOException - If write operation fails

java.lang.NullPointerException - If gifImage is null

java.lang.NullPointerException - If output stream is null

encode

public static final void encode(GifImage gifImage,
                                java.io.OutputStream outputStream,
                                boolean forceGlobalColorTableUsage)
                         throws java.io.IOException

Encode and write out the data contained in the GifImage to the specified output stream in the GIF file format ('89a' version).

Parameters:

gifImage - GifImage to encode and write out

outputStream - the specified stream to output

forceGlobalColorTableUsage - force Global Color Table usage. If true local color tables from all frames will be union to one global color table. It's useful to optimize final image size (every Local Color Table takes up to 768 bytes).

Throws:

java.io.IOException - If write operation fails

java.lang.NullPointerException - If GifImage is null

java.lang.NullPointerException - If output stream is null

encode

public static final void encode(GifImage gifImage,
                                java.io.File output)
                         throws java.io.IOException

Encode and write out the data contained in the GifImage to a File in the GIF output format ('89a' version). If there is already a File present, its contents are discarded.

Parameters:

gifImage - GifImage to encode and write out

output - a File to be written to.

Throws:

java.io.IOException - If write operation fails

java.lang.NullPointerException - If GifImage is null

java.lang.NullPointerException - If output is null

Since:

2.0

encode

public static final void encode(GifImage gifImage,
                                java.io.File output,
                                boolean forceGlobalColorTableUsage)
                         throws java.io.IOException

Encode and write out the data contained in the GifImage to a File in the GIF output format ('89a' version). If there is already a File present, its contents are discarded.

Parameters:

gifImage - GifImage to encode and write out

output - a File to be written to.

forceGlobalColorTableUsage - force Global Color Table usage. If true local color tables from all frames will be union to one global color table. It's useful to optimize final image size (every Local Color Table takes up to 768 bytes).

Throws:

java.io.IOException - If write operation fails

java.lang.NullPointerException - If GifImage is null

java.lang.NullPointerException - If output is null

Since:

2.0

encode

public static final void encode(java.awt.Image image,
                                java.io.OutputStream outputStream)
                         throws java.io.IOException

Encode and write out the data contained in the Image to the output stream in the GIF89a file format. Running this method is equal to running encode(com.gif4j.light.GifImage gifImage, java.io.OutputStream outputStream) where GifImage instance contains the only one GifFrame instance wrapped the specified image.

Parameters:

image - image to encode

outputStream - the specified stream to output

Throws:

java.io.IOException - If write operation fails

java.lang.NullPointerException - If image is null

java.lang.NullPointerException - If output stream is null

encode

public static final void encode(java.awt.Image image,
                                java.io.DataOutput dataOutput)
                         throws java.io.IOException

Encode and write out the data contained in the Image to the specified output in the GIF89a file format.

Parameters:

image - image to encode

dataOutput - the specified output to write

Throws:

java.io.IOException - If write operation fails

java.lang.NullPointerException - If image is null

java.lang.NullPointerException - If output is null

encode

public static final void encode(java.awt.Image image,
                                java.io.File output)
                         throws java.io.IOException

Encode and write out the data contained in the Image to a File in the GIF output format ('89a' version). If there is already a File present, its contents are discarded.

Parameters:

image - image to encode and write out

output - a File to be written to.

Throws:

java.io.IOException - If write operation fails

java.lang.NullPointerException - If GifImage is null

java.lang.NullPointerException - If output is null

Since:

2.0