Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.flagstone.transform.util
Class FSImageConstructor

    java.lang.Object
      com.flagstone.transform.util.FSImageConstructor

    public class FSImageConstructor

extends java.lang.Object

The FSImageConstructor class is used to generate an image definition object from an image stored in a file. Currently PNG, BMP and JPEG encoded images are supported. The name of the file containing the image can be specified directly in the class constructor:

         FSImageConstructor imageConstructor = new FSImageConstructor(imageFile);

A single FSImageConstructor object can also be used to load a series of images:

         imageConstructor.setImageFromFile(imageFile);

If an error occurs each method will throw either a FileNotFoundException, IOException or DataFormatException depending on the error detected.

When an image is loaded the getFormat() method identifies the way the image is encoded:

Format | Description
--- | ---
JPEG | A JPEG encoded image.
IDX8 | An indexed image where each pixel specifies an index into a colour table containing up to 256 24-bit colours. Transparent colours are not supported.
IDXA | An indexed image where each pixel specifies an index into a colour table containing up to 256 32-bit colours - 8-bits for each colour channel and 8-bits for transparency.
RGB5 | An true colour image where each pixel specifies a 16-bit colour, with 5-bits per colour channel. Transparent colours are not supported.
RGB8 | An true colour image where each pixel specifies a 24-bit colour, with 8-bits per colour channel. Each pixel occupies 32-bits. Transparent colours are not supported so the first (most significant) byte is set to 255 by default.
RGBA | An true colour image where each pixel specifies a 32-bit colour, with 8-bits per colour channel and 8-bits for transparency. The first (most significant) byte contains the transparency information.

Once an image is loaded the definition required to add the image to a Flash file is generated using the defineImage() method:

         movie.add(imageConstructor.defineImage(movie.newIdentifier()));

The defineImage()method returns an FSDefineObject (the abstract base class for all objects used to define shapes etc. in a Flash file. The exact class of the object generated depends of the format of the image loaded.

Class | Generated when...
--- | ---
FSDefineJPEGImage2 | A JPEG encoded image is loaded. The getFormat() method returns the class constant JPEG.
FSDefineImage | An indexed BMP or PNG image contains a colour table without transparent colours or when a true colour image contains 16-bit or 24-bit colours is loaded. The getFormat() method returns the class constants IDX8, RGB5 or RGB8.
FSDefineImage2 | A BMP or PNG indexed image contains a colour table with transparent colours is loaded or when a true colour image contains 32-bit bit colours. The getFormat() method returns the class constants IDXA or RGBA.

Images are displayed in Flash by filling a shape with the image bitmap. The defineEnclosingShape() method generates a rectangular shape object which wraps the image:

         int imageId = movie.newIdentifier();
         int shapeId = movie.newIdentifier();

         int xOrigin = imageConstructor.getWidth()/2;
         int yOrigin = imageConstructor.getHeight()/2;

         boolean border = false;

         movie.add(imageConstructor.defineImage(imageId));
         movie.add(imageConstructor.defineEnclosingShape(shapeId, imageId, xOrigin, yOrigin, border));

Here the origin, used when placing the shape on the screen, is defined as the centre of the shape. Other points may be defined to suit the alignment of the shape when it is placed on the display list.

## Post Processing

Once an image has been loaded, FSImageConstructor supports a range of methods to access the colour table or image data - depending on the image format. This allows the image data to be processed before the objects used to add the image to a Flash file are defined.

         imageConstructor.getColorTable();
         imageConstructor.getIndexedImage();
         imageConstructor.setColorImage();
         imageConstructor.getJPEGImage();

The information returned will depend on the image format. If an indexed image is loaded then the getColourTable() and getIndexedImage() will return the arrays of bytes for the colour table and image respectively. If getColorImage() or getJPEGImage() are used on an indexed image then they will return null objects.

Once the image data has been processed separate set methods are available depending on the type of image:

         imageConstructor.setIndexedImage(format, imageWidth, imageHeight, colourTable, image);
         imageConstructor.setColorImage(format, imageWidth, imageHeight, image);
         imageConstructor.setJPEGImage(imageWidth, imageHeight, image);

Field Summary
`static int` | `IDX8` Format for indexed images containing a colour table with 24-bit colours.
`static int` | `IDXA` Format for indexed images containing a colour table with 32-bit colours.
`static int` | `JPEG` Format for JPEG encoded images
`static int` | `RGB5` Format for true colour images containing 16-bit colours, 5-bits for each colour channel.
`static int` | `RGB8` Format for true colour images containing 24-bit colours, 8-bits for each colour channel.
`static int` | `RGBA` Format for true colour images containing 32-bit colours, 8-bits for each colour channel plus transparency.

Constructor Summary
`FSImageConstructor()` Constructs an FSImageConstructor object with no image.
`FSImageConstructor(byte[] bytes)` Constructs and FSImageConstructor object and loads the encoded image data.
`FSImageConstructor(java.lang.String filename)` Constructs and FSImageConstructor object and loads the image from the specified file.

Method Summary
`FSDefineShape3` | `defineEnclosingShape(int shapeIdentifier, int imageIdentifier, int xOrigin, int yOrigin, FSSolidLine borderStyle)` Generates the shape definition object that is required to display an image in a Flash movie.
`FSDefineObject` | `defineImage(int identifier)` Generates an object used to define an image in a Flash file.
`byte[][][]` | `getColorImage()` Returns a copy of the image data decoded from a true colour file.
`byte[][]` | `getColorTable()` Returns a copy of the colour table used in an indexed image.
`int` | `getFormat()` Returns a constant identifying the format for the way the pixels are encoded.
`int` | `getHeight()` Returns the height of the image in pixels.
`java.util.ArrayList` | `getImageAsBlocks(int blockWidth, int blockHeight)` Return the image as an array of FSImageBlock objects that can be used when creating ScreenVideo streams.
`byte[][]` | `getIndexedImage()` Returns a copy of the image data decoded from an indexed image.
`byte[]` | `getJPEGImage()` Returns a copy of the encoded data decoded from a JPEG image file.
`int` | `getWidth()` Returns the width of the image in pixels.
`void` | `setColorImage(int encoding, int imageWidth, int imageHeight, byte[][][] image)` Sets the image data for a true colour image.
`void` | `setImage(byte[] bytes)` Initialises the FSImageConstructor object with the image data.
`void` | `setImageFromFile(java.lang.String filename)` Initialises the FSImageConstructor object with the image in the specified file.
`void` | `setIndexedImage(int encoding, int imageWidth, int imageHeight, byte[][] table, byte[][] image)` Sets the image data for an indexed image.
`void` | `setJPEGImage(int imageWidth, int imageHeight, byte[] image)` Sets the image data for a JPEG encoded image.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### JPEG

    public static final int JPEG

  Format for JPEG encoded images

  See Also:
    Constant Field Values

### IDX8

    public static final int IDX8

  Format for indexed images containing a colour table with 24-bit colours.

  See Also:
    Constant Field Values

### IDXA

    public static final int IDXA

  Format for indexed images containing a colour table with 32-bit colours.

  See Also:
    Constant Field Values

### RGB5

    public static final int RGB5

  Format for true colour images containing 16-bit colours, 5-bits for each colour channel.

  See Also:
    Constant Field Values

### RGB8

    public static final int RGB8

  Format for true colour images containing 24-bit colours, 8-bits for each colour channel.

  See Also:
    Constant Field Values

### RGBA

    public static final int RGBA

  Format for true colour images containing 32-bit colours, 8-bits for each colour channel plus transparency.

  See Also:
    Constant Field Values

Constructor Detail

### FSImageConstructor

    public FSImageConstructor()

  Constructs an FSImageConstructor object with no image.

### FSImageConstructor

    public FSImageConstructor(java.lang.String filename)
                       throws java.io.IOException,
                              java.util.zip.DataFormatException

  Constructs and FSImageConstructor object and loads the image from the specified file. The FSImageConstructor class support Windows bitmap (BMP), Portable Network Graphics (PNG) or JPEG encoded images.

  Parameters:
    `filename` - the name of the file containing the image.
  Throws:
    `java.io.FileNotFoundException` - is the file cannot be found.
    `java.io.IOException` - if an error occurs while reading the file.
    `java.util.zip.DataFormatException` - if the file contains an unsupported image format or if an error occurs while decoding the image in the file.

### FSImageConstructor

    public FSImageConstructor(byte[] bytes)
                       throws java.util.zip.DataFormatException

  Constructs and FSImageConstructor object and loads the encoded image data. The FSImageConstructor class support Windows bitmap (BMP), Portable Network Graphics (PNG) or JPEG encoded images.

  Parameters:
    `bytes` - an array of bytes containing the encoded image.
  Throws:
    `java.util.zip.DataFormatException` - if the data contains an unsupported image format or if an error occurs while decoding the image.

Method Detail

### setImageFromFile

    public void setImageFromFile(java.lang.String filename)
                          throws java.io.IOException,
                                 java.util.zip.DataFormatException

  Initialises the FSImageConstructor object with the image in the specified file. This method can be used to generate the image definition objects for a Flash movie using the same FSImageConstructor object.

  Parameters:
    `filename` - the name of the file containing the image.
  Throws:
    `java.io.FileNotFoundException` - is the file cannot be found.
    `java.io.IOException` - if an error occurs while reading the file.
    `java.util.zip.DataFormatException` - if the file contains an unsupported image format or if an error occurs while decoding the image in the file.

### setImage

    public void setImage(byte[] bytes)
                  throws java.util.zip.DataFormatException

  Initialises the FSImageConstructor object with the image data.

  Parameters:
    `bytes` - an array of bytes containing the encoded image.
  Throws:
    `java.util.zip.DataFormatException` - if the data contains an unsupported image format or if an error occurs while decoding the image.

### getFormat

    public int getFormat()

  Returns a constant identifying the format for the way the pixels are encoded.

  Returns:
    the image format.

### getWidth

    public int getWidth()

  Returns the width of the image in pixels.

  Returns:
    the image width in pixels.

### getHeight

    public int getHeight()

  Returns the height of the image in pixels.

  Returns:
    the image height in pixels.

### getColorTable

    public byte[][] getColorTable()

  Returns a copy of the colour table used in an indexed image. Each entry in the colour table contains 4 bytes with one byte for the alpha channel and each of the three colour channels, red, green and blue. The alpha channel occupied the most significant byte (3) followed by red, green and blue (the least significant byte). For images in IDX8 format the alpha channel defaults to 255 (completely opaque). If the image format is JPEG or one of the true colour formats (RGB5, RGB8, RGBA) then the colour table returned is null.

  Returns:
    a two-dimensional array of bytes containing the colours used in an indexed image.

### getIndexedImage

    public byte[][] getIndexedImage()

  Returns a copy of the image data decoded from an indexed image. A two dimensional array is returned, byte[height][width] with each entry containing an index into the colour table. If the image format is JPEG or one of the true colour formats (RGB5, RGB8, RGBA) then the indexed image returned is null.

  Returns:
    a two-dimensional array of bytes (height x width) with each entry containing an index into the colour table.

### getColorImage

    public byte[][][] getColorImage()

  Returns a copy of the image data decoded from a true colour file. A three dimensional array is returned with four bytes for each pixel in the image, byte[height][width][4] - one byte for the red [0], green [1], blue [2] and alpha [3] channels. If the image format is JPEG or an indexed image (IDX8, IDXA) then the image data returned is null.

  Returns:
    an array of bytes containing the colour channels for each pixel in the image.

### getJPEGImage

    public byte[] getJPEGImage()

  Returns a copy of the encoded data decoded from a JPEG image file. If the image format is an indexed or true colour image (IDX8, IDXA, RGB5, RGB8, RGBA) then the indexed image returned is null.

  Returns:
    an array of bytes containing the JPEG encoded image.

### getImageAsBlocks

    public java.util.ArrayList getImageAsBlocks(int blockWidth,
                                                int blockHeight)

  Return the image as an array of FSImageBlock objects that can be used when creating ScreenVideo streams. The image is divided by tiling blocks of the specified width and height across the image. For blocks at the right and bottom edges the size of the block may be reduced so that it fits the image exactly. In other words the blocks are not padded with extra pixel information.

  Parameters:
    `blockWidth` - the width of a block in pixels.
    `blockHeight` - the height of a block in pixels
  Returns:
    an array of FMImageBlock objects.

### setIndexedImage

    public void setIndexedImage(int encoding,
                                int imageWidth,
                                int imageHeight,
                                byte[][] table,
                                byte[][] image)

  Sets the image data for an indexed image.

  Parameters:
    `encoding` - the format for the encoded image, either IDX8, or IDXA.
    `imageWidth` - the width of the image in pixels.
    `imageHeight` - the height of the image in pixels.
    `table` - a two-dimensional array containing four bytes for each colour, [n][4]. For each entry [n][3] contains alpha, [n][2] red, [n][1] green and [n][0] blue.
    `image` - a two-dimensional array of bytes, [imageHeight][imageWidth] containing the index into the colour table for each pixel in the image.

### setColorImage

    public void setColorImage(int encoding,
                              int imageWidth,
                              int imageHeight,
                              byte[][][] image)

  Sets the image data for a true colour image.

  Parameters:
    `encoding` - the format for the encoded image, either RGB5, RGB8 or RGBA.
    `imageWidth` - the width of the image in pixels.
    `imageHeight` - the height of the image in pixels.
    `image` - a three-dimensional array of bytes, [imageHeight][imageWidth][4] containing the colours for each pixel in the image. Four bytes are used to specify the colour. The order of the colour information from the most significant [3] to the least [0] is alpha, red, green and blue.

### setJPEGImage

    public void setJPEGImage(int imageWidth,
                             int imageHeight,
                             byte[] image)

  Sets the image data for a JPEG encoded image.

  Parameters:
    `imageWidth` - the width of the image in pixels.
    `imageHeight` - the height of the image in pixels.
    `image` - an array of bytes containing the JPEG encoded image.

### defineImage

    public FSDefineObject defineImage(int identifier)

  Generates an object used to define an image in a Flash file. The class of the object returned is determined by the format of the image data:

  Class | Generated when...
  --- | ---
  FSDefineJPEGImage2 | The image format is JPEG and the level of transparency is not defined.
  FSDefineImage | The image format is IDX8, RGB5 or RGB8.
  FSDefineImage2 | The image format is IDXA, RGBA.

  Parameters:
    `identifier` - an unique identifier that is used to reference the image definition in a Flash movie.

### defineEnclosingShape

    public FSDefineShape3 defineEnclosingShape(int shapeIdentifier,
                                               int imageIdentifier,
                                               int xOrigin,
                                               int yOrigin,
                                               FSSolidLine borderStyle)

  Generates the shape definition object that is required to display an image in a Flash movie. The shape is generated with a single fill style (FSBitmapFill object). The origin of the shape is specified relative to the top left corner of the image. The borderStyle argument specifies a border that will be drawn around the image. The style may be set to null is no border is drawn.

  Parameters:
    `shapeIdentifier` - an unique identifier that is used to reference the shape definition in a Flash movie.
    `imageIdentifier` - the unique identifier of the image generated using the defineImage() method.
    `xOrigin` - the offset in pixels along the x-axis, relative to the top left corner of the image, where the origin (0,0) of the shape will be located.
    `yOrigin` - the offset in pixels along the y-axis, relative to the top left corner of the image, where the origin (0,0) of the shape will be located.
    `borderStyle` - the style drawn around the border of the image. May be null if no border is drawn.

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD