com.gif4j.light
Class GifImage

java.lang.Object
  extended bycom.gif4j.light.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 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(com.gif4j.light.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 method should be used:
    addGifFrame(com.gif4j.light.GifFrame frame)

    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 GifEncoder java class to encode and save GifImage(-s) into the GIF89a image file format to output streams and files.

    Version:
    1.0
    Author:
    Gif4J Software - Java GIF image processing solutions
    See Also:
    Image, GifFrame, GifEncoder

    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.
     int getCurrentLogicHeight()
              get current logic screen height
     int getCurrentLogicWidth()
              get current logic screen width
     GifFrame getLastFrame()
              Returns the last added frame
     void setDefaultDelay(int delay)
              Set default delay between frames.
     void setLoopNumber(int number)
              Set number of iterations the loop should be executed.
     
    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_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

    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
    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

    addGifFrame

    public GifImage addGifFrame(GifFrame frame)
                         throws java.lang.InterruptedException
    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.
    java.lang.InterruptedException
    See Also:
    GifFrame

    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.

    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.

    getCurrentLogicWidth

    public int getCurrentLogicWidth()
    get current logic screen width

    Returns:
    current logic screen width

    getCurrentLogicHeight

    public int getCurrentLogicHeight()
    get current logic screen height

    Returns:
    current logic screen height

    getLastFrame

    public GifFrame getLastFrame()
    Returns the last added frame

    Returns:
    the last added frame

    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