Package com.day.image

Class Animation

  • public class Animation
extends java.lang.Object
    The Animation class takes a series of Layers and puts them in a single output graphic stream adding animation code for the number of loops and the delay time and disposal method of the single patches.

    What we do in this class is accept a series of layers, which will make up the single images. Currently layers are inserted into the animation in the succession of their addition. For each layer added, you may define the display time in 1/100th seconds and the disposal method used at the end of the display time.

    In addition you may set global looping instruction, on how many times the sequence of images should be displayed. To disable setting the loop control value in the output file, set the global loop value to a negative value.

    Properties

    The Animation class supports the following properties, which are all backed by setter and getter methods :

    loops   The number of loops to go through the animation. The default is not set byte the constructor or the setter is 0, which boils down to an endless loop.
    defaultDisposal   The action the image decoder should take after the display time of an image has elapsed. This must be one of the defined DISPOSAL_* constants. The default if not set by a constructor or the setter is DISPOSAL_BACKGROUND.
    backgroundColor   The background color of the animation. The default if not set by a constructor or the setter is to take the background color of the first image in the animation as the background color.

    Supported Image Format

    Currently the Animation class is solely implemented based on the GIF image file format, whose general structure is described here. You will also note, that the API of the Animation class is based on the functionality the GIF format offers for animated image files.

    CompuServe Graphics Interchange Format (GIF)

    The CompuServe Graphics Interchange Format (GIF) is a multi-image graphics format, which provides the capability for simple animations provided the image viewer is capable of interpreting the multi-image nature of the image file and the instructions for display.

    Generally a GIF file is made up of the following structural elements :

    • GIF89a Header
    • Logical Screen Descriptor Block, with optional global color table
    • optional Netscape Application Extension Block
    • stream of graphics
      • optional Graphic Control Block
      • Image Descriptor or Plain Text Block with optional local color table
    • GIF Trailer

    For more details, look at the GIF89 Specification. Generally this page contains many interesting information on animated GIFs.

    Since:
    coati

    • Constructor Summary

      Constructors 
      Constructor Description
      Animation()
      Creates the Animation object using the default values.
      Animation​(int loops)
      Creates the Animation object using the given properties.
      Animation​(int loops, int defaultDisposal, int bgColor)
      Creates the Animation object using the given properties.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void addLayer​(Layer layer, int delay)
      Add a layer for display during the indicated delay time after which the image is disposed of using the default disposal method.
      void addLayer​(Layer layer, int delay, int disposal)
      Add a layer for display during the indicated delay time after which the image is disposed of using the disposal method.
      int getBackgroundColor()
      Returns the current desired background color, -1 if undefined.
      int getDefaultDisposal()
      Return the current default disposal method used for newly added Layers.
      int getLoops()
      Returns the number of iterations through the images currently set.
      Layer removeLayer​(int idx)
      Remove the layer with the given index from the Animation.
      Layer removeLayer​(Layer layer)
      Removes the first layer (in chronological order) matching the given layer from the animation.
      void setBackgroundColor​(int bgColor)
      Sets the desired background color.
      void setDefaultDisposal​(int defaultDisposal)
      Sets the default disposal method for newly added Layers.
      void setLoops​(int loops)
      Change the number of iterations through the images to the new value.
      java.lang.String toString()
      Convert the Animation to some string representation for intelligent display.
      void write​(java.lang.String mimeType, int numColors, java.io.OutputStream outs)
      Write the animation to the output indicated.

      • Methods inherited from class java.lang.Object

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

    • Field Detail

      • DISPOSAL_NONE

        public static int DISPOSAL_NONE
        No disposal specifed. The decoder is not required to take any action.

      • DISPOSAL_NO

        public static int DISPOSAL_NO
        Do not dispose. The graphic is to be left in place.

      • DISPOSAL_BACKGROUND

        public static int DISPOSAL_BACKGROUND
        Restore to background color. The area used by the graphic must be restored to the background color.

      • DISPOSAL_PREVIOUS

        public static int DISPOSAL_PREVIOUS
        Restore to previous. The decoder is required to restore the area overwritten by the graphic with what was there prior to rendering the graphic.

    • Constructor Detail

      • Animation

        public Animation​(int loops,
                 int defaultDisposal,
                 int bgColor)
        Creates the Animation object using the given properties.
        Parameters:
        loops - Number of times the application should loop through the images. Use a negative value to prevent looping at all.
        defaultDisposal - default disposal method for images after the delay time has elapsed
        bgColor - The background color to set on the animated GIF. Only the red, green and blue values are used, the alpha value is ignored as GIF does not support alpha values.

      • Animation

        public Animation​(int loops)
        Creates the Animation object using the given properties. The background color is taken from the first image in the animation while the default disposal method is set to DISPOSAL_BACKGROUND.
        Parameters:
        loops - Number of times the application should loop through the images. Use a negative value to prevent looping at all.

      • Animation

        public Animation()
        Creates the Animation object using the default values. The background color is taken from the first image in the animation while the default disposal method is set to DISPOSAL_BACKGROUND. The loop counter is initialized to 0, which means endless loop.

    • Method Detail

      • setLoops

        public void setLoops​(int loops)
        Change the number of iterations through the images to the new value.
        Parameters:
        loops - Number of times the application should loop through the images. Use a negative value to prevent looping at all or set to 0 for endless looping.

      • getLoops

        public int getLoops()
        Returns the number of iterations through the images currently set.
        Returns:
        Number of iterations through the images.

      • setDefaultDisposal

        public void setDefaultDisposal​(int defaultDisposal)
        Sets the default disposal method for newly added Layers. This setting does not affect Layers already added to the animation object !
        Parameters:
        defaultDisposal - The disposal method to use. This must be one of DISPOSAL_* constants defined above.
        Throws:
        java.lang.IllegalArgumentException - if the disposal value is illegal.
        See Also:
        DISPOSAL_NONE, DISPOSAL_NO, DISPOSAL_BACKGROUND, DISPOSAL_PREVIOUS

      • getDefaultDisposal

        public int getDefaultDisposal()
        Return the current default disposal method used for newly added Layers.
        Returns:
        current default disposal method used

      • setBackgroundColor

        public void setBackgroundColor​(int bgColor)
        Sets the desired background color. If the desired color is -1, the background color of the first layer in the animation is taken as the animations background color.
        Parameters:
        bgColor - The new background color to set. Only the red, green and blue values are used, the alpha value is ignored as GIF does not support alpha values.

      • getBackgroundColor

        public int getBackgroundColor()
        Returns the current desired background color, -1 if undefined.
        Returns:
        the current desired background color, -1 if undefined.

      • addLayer

        public void addLayer​(Layer layer,
                     int delay)
        Add a layer for display during the indicated delay time after which the image is disposed of using the default disposal method.
        Parameters:
        layer - the Layer object to add
        delay - the display time of the image in 1/100 sec.
        Throws:
        java.lang.NullPointerException - if the layer is null.

      • addLayer

        public void addLayer​(Layer layer,
                     int delay,
                     int disposal)
        Add a layer for display during the indicated delay time after which the image is disposed of using the disposal method.
        Parameters:
        layer - the Layer object to add
        delay - the display time of the image in 1/100 sec.
        disposal - the disposal method for the object. This must be one of the predefined DISPOSAL_* constants.
        Throws:
        java.lang.NullPointerException - if the layer is null.
        java.lang.IllegalArgumentException - if the disposal value is not one of the predefined DISPOSAL_* constants.
        See Also:
        DISPOSAL_NONE, DISPOSAL_NO, DISPOSAL_BACKGROUND, DISPOSAL_PREVIOUS

      • removeLayer

        public Layer removeLayer​(int idx)
        Remove the layer with the given index from the Animation.
        Parameters:
        idx - index of the Layer in the list
        Returns:
        the layer removed from the Animation
        Throws:
        java.lang.IndexOutOfBoundsException - if the index is less than zero or bigger than the number of layers in the animation.
        java.lang.NullPointerException - if no layer is present at the given position.

      • removeLayer

        public Layer removeLayer​(Layer layer)
        Removes the first layer (in chronological order) matching the given layer from the animation. If a layer is contained more than once within the animation, you must use multiple calls to removeLayer.
        Parameters:
        layer - Layer object to remove from the animation
        Returns:
        the layer removed from the animation or null if the layer was not part of the animation.

      • write

        public void write​(java.lang.String mimeType,
                  int numColors,
                  java.io.OutputStream outs)
           throws java.io.IOException
        Write the animation to the output indicated.
        Parameters:
        mimeType - MIME type indicating the graphics output file format to use. Currently only image/gif is supported.
        numColors - The number of colors to generate in the animated GIF, if not in the range [2 .. 256], 256 is taken as the default.
        outs - the OutputStream used for output
        Throws:
        java.io.IOException - got from called write methods
        java.lang.IllegalArgumentException - or if the mimeType is not image/gif or if the OutputStream is null.

      • toString

        public java.lang.String toString()
        Convert the Animation to some string representation for intelligent display.
        Overrides:
        toString in class java.lang.Object
        Returns:
        the string representation of the Animation object.