org.monte.media.image

Class BitmapImage

java.lang.Object

org.monte.media.image.BitmapImage

All Implemented Interfaces:

Cloneable

public class BitmapImage
extends Object
implements Cloneable

A BitmapImage is comprised of a ColorModel and an accessible byte array of image data.

The image data is expressed in several layers of rectangular regions called bit-planes. To determine the bits that form a single pixel one must combine all data-bits at the same x,y position in each bit-plane. This is known as a "planar" storage layout as it was used on Commodore Amiga Computers.

The bit-planes can be stored contiguously or can be interleaved at each scanline of the image.

Fig 1. A sample image:

 .+++..@...@.+..###...+++.     This sample uses 4 colors:
 +...+.@@.@@.+.#.....+...+     . = color 0 (all bits clear)
 +++++:@.@.@.+.#..##.+++++     + = color 1 (bit 0 set, bit 1 clear)
 +...+.@...@.+.#...#.+...+     @ = color 2 (bit 0 clear, bit 1 set)
 +...+.@...@.+..####.+...+     # = color 3 (all bits set)
 

Fig 2. Contiguous bit-plane storage layout.

 01110000 00001001 11000111 0.......     This is the first bit-plane.
 10001000 00001010 00001000 1.......     Each number represents a bit
 11111000 00001010 01101111 1.......     in the storage layout. Eight
 10001000 00001010 00101000 1.......     bits are grouped into one byte.
 10001000 00001001 11101000 1.......     Dots indicate unused bits.
 

 00000010 00100001 11000000 0.......     This is the second bit-plane.
 00000011 01100010 00000000 0.......
 00000010 10100010 01100000 0.......
 00000010 00100010 00100000 0.......
 00000010 00100001 11100000 0.......
 

Fig 3. Interleaved bit-plane storage layout.

 01110000 00001001 11000111 0.......     This is the first bit-plane.
 00000010 00100001 11000000 0.......     This is the second bit-plane.
 

 10001000 00001010 00001000 1.......     The bit-planes are interleaved
 00000011 01100010 00000000 0.......     at every scanline of the image.
 

 11111000 00001010 01101111 1.......
 00000010 10100010 01100000 0.......
 

 10001000 00001010 00101000 1.......
 00000010 00100010 00100000 0.......
 

 10001000 00001001 11101000 1.......
 00000010 00100001 11100000 0.......
 

For more details refer to "Amiga ROM Kernel Reference Manual: Libraries, Addison Wesley"

Responsibility

Gives clients direct access to the image data of the bitmap. Knows how to convert the bitmap into chunky image data according to the current color model. Supports indexed color model, direct color model, 6 and 8 bit HAM color model.

Version:

1.5 2011-01-05 Adds support for RGB555.
1.4 2011-01-03 Adds method setIntPixels().
1.3 2010-10-25 Removed suffixes in instance variable names.
1.2.1 2005-07-16 Setting a preferredColorModel is now better honoured.
1.2 2004-05-26 Improved performance of planar to chunky conversion routines.
1.1.1 2004-05-18 Fixed a bug, which caused an image to be all transparent, when it was of bitmap type indexed color, and when the desired bitmap type was true color, and the bitmap had a transparent color.
1.1 2003-04-01 BitmapImage can now convert bitmaps with IndexColorModel's into chunky pixels with DirectColorModel.
1.0 1999-10-19

Author:

Werner Randelshofer, Hausmatt 10, CH-6405 Goldau, Switzerland

Field Summary

Fields

Modifier and Type	Field and Description
static int	BYTE_PIXEL Tag for byte pixel data.
static int	INT_PIXEL Tag for integer pixel data.
static int	NO_PIXEL Tag indicating that no pixel data is available.
static int	SHORT_PIXEL Tag for short pixel data.

Constructor Summary

Constructors

Constructor and Description
BitmapImage(int width, int height, int depth, ColorModel colorModel) Construct an interleaved bitmap with the specified size, depth and color model.
BitmapImage(int width, int height, int depth, ColorModel colorModel, boolean isInterleaved) Construct a bitmap with the specified size, depth and color model and with optional interleave.
BitmapImage(int width, int height, int depth, ColorModel colorModel, int bitStride, int scanlineStride) Construct a bitmap with the specified size, depth, color model and interleave.

Method Summary

Methods

Modifier and Type	Method and Description
BitmapImage	clone() Creates a clone.
void	convertFromChunky(BufferedImage image) Converts the indicated area of the bitmap data into pixel data.
int	convertToChunky() Converts the planar image data into chunky pixel data.
int	convertToChunky(int top, int left, int bottom, int right) Converts the indicated area of the bitmap data into pixel data.
void	flushPixels() Frees the memory allocated for the pixel data.
byte[]	getBitmap() Gives you direct access to the bitmap data array.
int	getBitplaneStride() Returns the number of bytes that you must add to a bitmap address to advance to the next bit of a scanline.
byte[]	getBytePixels() Returns a reference to the byte pixel data that has been generated by a previous call to #converToChunky.
ColorModel	getChunkyColorModel() Returns the current color model of the chunky image in this bitmap.
int	getDepth() Returns the depth of the image.
int	getHeight() Returns the height of the image.
int[]	getIntPixels() Returns a reference to the integer pixel data that has been generated by a previous call to #converToChunky.
int	getPixelType() Returns the available type of pixel data.
ColorModel	getPlanarColorModel() Returns the current color model of the planar image in this bitmap.
int	getScanlineStride() Returns the numer of bytes you must add to a given address in the bitmap to advance to the next scanline of the image.
short[]	getShortPixels() Returns a reference to the byte pixel data that has been generated by a previous call to #converToChunky.
int	getWidth() Returns the width of the image.
boolean	isEnforceDirectColors() If this returns true, then convertToChunky always generates chunky pixels using a DirectColorModel.
void	setBytePixels(byte[] buf)
void	setEnforceDirectColors(boolean b) If you set this to true, then convertToChunky always generates chunky pixels using a DirectColorModel.
void	setIntPixels(int[] buf)
void	setPlanarColorModel(ColorModel colorModel) Replaces the color model used for conversions from/to chunky pixels.
void	setPreferredChunkyColorModel(ColorModel colorModel) Sets the preferred color model used for to chunky pixels.
void	setShortPixels(short[] buf)

Methods inherited from class java.lang.Object

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

Field Detail

BYTE_PIXEL

public static final int BYTE_PIXEL

Tag for byte pixel data.

See Also:

Constant Field Values

INT_PIXEL

public static final int INT_PIXEL

Tag for integer pixel data.

See Also:

Constant Field Values

SHORT_PIXEL

public static final int SHORT_PIXEL

Tag for short pixel data.

See Also:

Constant Field Values

NO_PIXEL

public static final int NO_PIXEL

Tag indicating that no pixel data is available.

See Also:

Constant Field Values

Constructor Detail

BitmapImage

public BitmapImage(int width,
           int height,
           int depth,
           ColorModel colorModel)

Construct an interleaved bitmap with the specified size, depth and color model. BitplaneStride and ScanlineStride are rounded up to the next even number of bytes.

Pre condition: -

Post condition: Interleaved bitmap constructed.

Obligation: -

Parameters:

width - Width in pixels.

height - Height in pixels.

depth - Number of bits per pixel.

colorModel - Color model to be used for conversions from/to chunky pixels.

BitmapImage

public BitmapImage(int width,
           int height,
           int depth,
           ColorModel colorModel,
           boolean isInterleaved)

Construct a bitmap with the specified size, depth and color model and with optional interleave. BitplaneStride and ScanlineStride are rounded up to the next even number of bytes.

Pre condition: -

Post condition: BitmapImage constructed.

Obligation: -

Parameters:

width - Width in pixels.

height - Height in pixels.

depth - Number of bits per pixel.

colorModel - Color model to be used for conversions from/to chunky pixels.

isInterleaved - Indicator for contiguous or interleaved bit-planes.

BitmapImage

public BitmapImage(int width,
           int height,
           int depth,
           ColorModel colorModel,
           int bitStride,
           int scanlineStride)

Construct a bitmap with the specified size, depth, color model and interleave.

Pre condition: ScanlineStride must be a multiple of BitplaneStride or vice versa.

Post condition: BitmapImage constructed.

Obligation: -

Parameters:

width - Width in pixels.

height - Height in pixels.

depth - Number of bits per pixel.

colorModel - Color model to be used for conversions from/to chunky pixels.

bitStride - Number of data array elements between two bits of the same image pixel.

scanlineStride - Number of data array elements between a given pixel and the pixel in the same column of the next scanline.

Method Detail

setEnforceDirectColors

public void setEnforceDirectColors(boolean b)

If you set this to true, then convertToChunky always generates chunky pixels using a DirectColorModel.

isEnforceDirectColors

public boolean isEnforceDirectColors()

If this returns true, then convertToChunky always generates chunky pixels using a DirectColorModel.

getWidth

public int getWidth()

Returns the width of the image.

Pre condition: -

Post condition: -

Obligation: -

Returns:

The width in pixels.

getHeight

public int getHeight()

Returns the height of the image.

Pre condition: -

Post condition: -

Obligation: -

Returns:

The height in pixels.

getDepth

public int getDepth()

Returns the depth of the image.

The depth indicates how many bits are used to form a single pixel.

Pre condition: -

Post condition: -

Obligation: -

Returns:

The number of bitplanes used to form a single pixel.

getScanlineStride

public int getScanlineStride()

Returns the numer of bytes you must add to a given address in the bitmap to advance to the next scanline of the image.

Pre condition: -

Post condition: -

Obligation: -

Returns:

The scansize.

getBitplaneStride

public int getBitplaneStride()

Returns the number of bytes that you must add to a bitmap address to advance to the next bit of a scanline.

Pre condition: -

Post condition: -

Obligation: -

Returns:

The interleave of the bitmap.

setPlanarColorModel

public void setPlanarColorModel(ColorModel colorModel)

Replaces the color model used for conversions from/to chunky pixels.

Pre condition: The new color model must correspond with the depth of the bitmap.

Post condition: Color model changed.

Obligation: -

Parameters:

colorModel - The new color model.

getPlanarColorModel

public ColorModel getPlanarColorModel()

Returns the current color model of the planar image in this bitmap.

Pre condition: -

Post condition: -

Obligation: -

Returns:

The color model.

setPreferredChunkyColorModel

public void setPreferredChunkyColorModel(ColorModel colorModel)

Sets the preferred color model used for to chunky pixels.

Pre condition: -

Post condition: Color model changed.

Obligation: -

Parameters:

colorModel - The new color model.

getChunkyColorModel

public ColorModel getChunkyColorModel()

Returns the current color model of the chunky image in this bitmap.

Pre condition: -

Post condition: -

Obligation: -

Returns:

The color model.

getBitmap

public byte[] getBitmap()

Gives you direct access to the bitmap data array.

Pre condition: -.

Post condition: -

Obligation: The bitmap data array remains property of the BitmapImage and will be used at the next conversion to chunky. You can access it as you like (even during conversion) since this class does never change the contents of the bitmap.

Returns:

A reference to the bitmap data.

getBytePixels

public byte[] getBytePixels()

Returns a reference to the byte pixel data that has been generated by a previous call to #converToChunky.

Pre condition: -

Post condition: -

Obligation: You may modify the contents of the array as you like to get some nice effects for the next call to #convertToChunky. Note whovewer that #convertToChunky will not reuse this array when the colorModel has been changed to a color format that requires pixels in integer format.

Returns:

byte array or NULL when no byte pixels have been generated by #convertToChunky.

getShortPixels

public short[] getShortPixels()

Returns a reference to the byte pixel data that has been generated by a previous call to #converToChunky.

Pre condition: -

Post condition: -

Obligation: You may modify the contents of the array as you like to get some nice effects for the next call to #convertToChunky. Note whovewer that #convertToChunky will not reuse this array when the colorModel has been changed to a color format that requires pixels in integer format.

Returns:

byte array or NULL when no byte pixels have been generated by #convertToChunky.

getIntPixels

public int[] getIntPixels()

Returns a reference to the integer pixel data that has been generated by a previous call to #converToChunky.

Pre condition: -

Post condition: -

Obligation: You may modify the contents of the array as you like to get some nice effects for the next call to #convertToChunky. Note however that #convertToChunky will not reuse this array when the colorModel has been changed to a color format that requires pixels in byte format.

Returns:

byte array or NULL when no int pixels have been generated by #convertToChunky.

getPixelType

public int getPixelType()

Returns the available type of pixel data.

Pre condition: -

Post condition: -

Obligation: -

Returns:

A constant that specifies the current type of pixel data.

clone

public BitmapImage clone()

Creates a clone.

Pre condition: -

Post condition: Clone created.

Overrides:

clone in class Object

Returns:

A clone.

convertToChunky

public int convertToChunky()

Converts the planar image data into chunky pixel data.

This method will either generate byte pixel data or integer pixel data (depending on the color model).

The pixel array that resulted to a prior call to this method will be reused when the image dimension and the color model allows for it.

Pre condition: -

Post condition: Chunky pixels generated.

Obligation: -

Returns:

The type of generated pixel data.

convertToChunky

public int convertToChunky(int top,
                  int left,
                  int bottom,
                  int right)

Converts the indicated area of the bitmap data into pixel data.

This method will either generate byte pixel data or integer pixel data (depending on the color model).

Note that the size of the generated pixel data always corresponds to the size of the complete image. You do only specify a subset of the image to be converted not a subset to be extracted. Note also that the pixel data that resulted from prior calls to this method will be reused when the generated pixel array was of the same size and type.

Pre condition: -

Post condition: The indicated part of the bitmap has been converted into chunky pixels.

Obligation: -

Returns:

The type of generated pixel data.

convertFromChunky

public void convertFromChunky(BufferedImage image)

Converts the indicated area of the bitmap data into pixel data.

This method will either generate byte pixel data or integer pixel data (depending on the color model).

Note that the size of the generated pixel data always corresponds to the size of the complete image. You do only specify a subset of the image to be converted not a subset to be extracted. Note also that the pixel data that resulted from prior calls to this method will be reused when the generated pixel array was of the same size and type.

Pre condition: -

Post condition: The indicated part of the bitmap has been converted into chunky pixels.

Obligation: -

flushPixels

public void flushPixels()

Frees the memory allocated for the pixel data.

Pre condition: -

Post condition: The bitmap has given up all its references to the pixel data.

Obligation: The pixel data will not be reused at the next call to #convertToChunky.

setIntPixels

public void setIntPixels(int[] buf)

setBytePixels

public void setBytePixels(byte[] buf)

setShortPixels

public void setShortPixels(short[] buf)