com.flagstone.transform.util
Class FSImageConstructor

java.lang.Object
  extended by 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:

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

ClassGenerated 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:
ClassGenerated 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.