javax.media.jai
Class ImageLayout

java.lang.Object
  |
  +--javax.media.jai.ImageLayout
All Implemented Interfaces:
Cloneable, Serializable

public class ImageLayout
extends Object
implements Cloneable, Serializable

A class describing the desired layout of an OpImage.

The ImageLayout class encapsulates three types of information about an image:

Each of these parameters may be set individually, or left unset. An unset parameter will cause the corresponding value of a given RenderedImage to be used. For example, the code:

 ImageLayout layout;
 RenderedImage im;

 int width = layout.getTileWidth(im);
 
will return the tile width of the ImageLayout if it is set, or the tile width of the image im if it is not.

ImageLayout objects are primarily intended to be passed as part of the renderingHints argument of the create() method of RenderedImageFactory. The create() method may remove parameter settings that it cannot deal with, prior to passing the ImageLayout to any OpImage constructors. New OpImage subclasses are not required to accept an ImageLayout parameter, but most will at least need to synthesize one to be passed up the constructor chain.

Methods that modify the state of an ImageLayout return a reference to 'this' following the change. This allows multiple modifications to be made in a single expression. This provides a way of modifying an ImageLayout within a superclass constructor call.

See Also:
Serialized Form

Field Summary
static int COLOR_MODEL_MASK
          A bitmask to specify the validity of colorModel.
static int HEIGHT_MASK
          A bitmask to specify the validity of height.
static int MIN_X_MASK
          A bitmask to specify the validity of minX.
static int MIN_Y_MASK
          A bitmask to specify the validity of minY.
static int SAMPLE_MODEL_MASK
          A bitmask to specify the validity of sampleModel.
static int TILE_GRID_X_OFFSET_MASK
          A bitmask to specify the validity of tileGridXOffset.
static int TILE_GRID_Y_OFFSET_MASK
          A bitmask to specify the validity of tileGridYOffset.
static int TILE_HEIGHT_MASK
          A bitmask to specify the validity of tileHeight.
static int TILE_WIDTH_MASK
          A bitmask to specify the validity of tileWidth.
protected  int validMask
          The 'or'-ed together valid bitmasks.
static int WIDTH_MASK
          A bitmask to specify the validity of width.
 
Constructor Summary
ImageLayout()
          Constructs an ImageLayout with no parameters set.
ImageLayout(int minX, int minY, int width, int height)
          Constructs an ImageLayout with only the image dimension parameters set.
ImageLayout(int minX, int minY, int width, int height, int tileGridXOffset, int tileGridYOffset, int tileWidth, int tileHeight, SampleModel sampleModel, ColorModel colorModel)
          Constructs an ImageLayout with all its parameters set.
ImageLayout(int tileGridXOffset, int tileGridYOffset, int tileWidth, int tileHeight, SampleModel sampleModel, ColorModel colorModel)
          Constructs an ImageLayout with its tile grid layout, SampleModel, and ColorModel parameters set.
ImageLayout(RenderedImage im)
          Constructs an ImageLayout with all its parameters set to equal those of a given RenderedImage.
 
Method Summary
 Object clone()
          Returns a clone of the ImageLayout as an Object.
 boolean equals(Object obj)
          Tests if the specified Object equals this ImageLayout.
 ColorModel getColorModel(RenderedImage fallback)
          Returns the value of colorModel if it is valid, and otherwise returns the value from the supplied RenderedImage.
 int getHeight(RenderedImage fallback)
          Returns the value of height if it is valid, and otherwise returns the value from the supplied RenderedImage.
 int getMinX(RenderedImage fallback)
          Returns the value of minX if it is valid, and otherwise returns the value from the supplied RenderedImage.
 int getMinY(RenderedImage fallback)
          Returns the value of minY if it is valid, and otherwise returns the value from the supplied RenderedImage.
 SampleModel getSampleModel(RenderedImage fallback)
          Returns the value of sampleModel if it is valid, and otherwise returns the value from the supplied RenderedImage.
 int getTileGridXOffset(RenderedImage fallback)
          Returns the value of tileGridXOffset if it is valid, and otherwise returns the value from the supplied RenderedImage.
 int getTileGridYOffset(RenderedImage fallback)
          Returns the value of tileGridYOffset if it is valid, and otherwise returns the value from the supplied RenderedImage.
 int getTileHeight(RenderedImage fallback)
          Returns the value of tileHeight if it is valid, and otherwise returns the value from the supplied RenderedImage.
 int getTileWidth(RenderedImage fallback)
          Returns the value of tileWidth if it is valid, and otherwise returns the value from the supplied RenderedImage.
 int getValidMask()
          Returns the 'or'-ed together bitmask indicating parameter validity.
 int getWidth(RenderedImage fallback)
          Returns the value of width if it is valid, and otherwise returns the value from the supplied RenderedImage.
 int hashCode()
          Returns the hash code for this ImageLayout.
 boolean isValid(int mask)
          Returns true if all the parameters specified by the argument are set.
 ImageLayout setColorModel(ColorModel colorModel)
          Sets colorModel to the supplied value and marks it as valid.
 ImageLayout setHeight(int height)
          Sets height to the supplied value and marks it as valid.
 ImageLayout setMinX(int minX)
          Sets minX to the supplied value and marks it as valid.
 ImageLayout setMinY(int minY)
          Sets minY to the supplied value and marks it as valid.
 ImageLayout setSampleModel(SampleModel sampleModel)
          Sets sampleModel to the supplied value and marks it as valid.
 ImageLayout setTileGridXOffset(int tileGridXOffset)
          Sets tileGridXOffset to the supplied value and marks it as valid.
 ImageLayout setTileGridYOffset(int tileGridYOffset)
          Sets tileGridYOffset to the supplied value and marks it as valid.
 ImageLayout setTileHeight(int tileHeight)
          Sets tileHeight to the supplied value and marks it as valid.
 ImageLayout setTileWidth(int tileWidth)
          Sets tileWidth to the supplied value and marks it as valid.
 ImageLayout setValid(int mask)
          Sets selected bits of the valid bitmask.
 ImageLayout setWidth(int width)
          Sets width to the supplied value and marks it as valid.
 String toString()
          Returns a String containing the values of all valid fields.
 ImageLayout unsetImageBounds()
          Marks the parameters dealing with the image bounds (minX, minY, width, and height) as being invalid.
 ImageLayout unsetTileLayout()
          Marks the parameters dealing with the tile layout (tileGridXOffset, tileGridYOffset, tileWidth, and tileHeight) as being invalid.
 ImageLayout unsetValid(int mask)
          Clears selected bits of the valid bitmask.
 
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

MIN_X_MASK

public static final int MIN_X_MASK
A bitmask to specify the validity of minX.

MIN_Y_MASK

public static final int MIN_Y_MASK
A bitmask to specify the validity of minY.

WIDTH_MASK

public static final int WIDTH_MASK
A bitmask to specify the validity of width.

HEIGHT_MASK

public static final int HEIGHT_MASK
A bitmask to specify the validity of height.

TILE_GRID_X_OFFSET_MASK

public static final int TILE_GRID_X_OFFSET_MASK
A bitmask to specify the validity of tileGridXOffset.

TILE_GRID_Y_OFFSET_MASK

public static final int TILE_GRID_Y_OFFSET_MASK
A bitmask to specify the validity of tileGridYOffset.

TILE_WIDTH_MASK

public static final int TILE_WIDTH_MASK
A bitmask to specify the validity of tileWidth.

TILE_HEIGHT_MASK

public static final int TILE_HEIGHT_MASK
A bitmask to specify the validity of tileHeight.

SAMPLE_MODEL_MASK

public static final int SAMPLE_MODEL_MASK
A bitmask to specify the validity of sampleModel.

COLOR_MODEL_MASK

public static final int COLOR_MODEL_MASK
A bitmask to specify the validity of colorModel.

validMask

protected int validMask
The 'or'-ed together valid bitmasks.
Constructor Detail

ImageLayout

public ImageLayout()
Constructs an ImageLayout with no parameters set.

ImageLayout

public ImageLayout(int minX,
                   int minY,
                   int width,
                   int height,
                   int tileGridXOffset,
                   int tileGridYOffset,
                   int tileWidth,
                   int tileHeight,
                   SampleModel sampleModel,
                   ColorModel colorModel)
Constructs an ImageLayout with all its parameters set. The sampleModel and colorModel parameters are ignored if null.
Parameters:
minX - the image's minimum X coordinate.
minY - the image's minimum Y coordinate.
width - the image's width.
height - the image's height.
tileGridXOffset - the X coordinate of tile (0, 0).
tileGridYOffset - the Y coordinate of tile (0, 0).
tileWidth - the width of a tile.
tileHeight - the height of a tile.
sampleModel - the image's SampleModel.
colorModel - the image's ColorModel.

ImageLayout

public ImageLayout(int minX,
                   int minY,
                   int width,
                   int height)
Constructs an ImageLayout with only the image dimension parameters set.
Parameters:
minX - the image's minimum X coordinate.
minY - the image's minimum Y coordinate.
width - the image's width.
height - the image's height.

ImageLayout

public ImageLayout(int tileGridXOffset,
                   int tileGridYOffset,
                   int tileWidth,
                   int tileHeight,
                   SampleModel sampleModel,
                   ColorModel colorModel)
Constructs an ImageLayout with its tile grid layout, SampleModel, and ColorModel parameters set. The sampleModel and colorModel parameters are ignored if null.
Parameters:
tileGridXOffset - the X coordinate of tile (0, 0).
tileGridYOffset - the Y coordinate of tile (0, 0).
tileWidth - the width of a tile.
tileHeight - the height of a tile.
sampleModel - the image's SampleModel.
colorModel - the image's ColorModel.

ImageLayout

public ImageLayout(RenderedImage im)
Constructs an ImageLayout with all its parameters set to equal those of a given RenderedImage.
Parameters:
im - a RenderedImage whose layout will be copied.
Method Detail

getValidMask

public int getValidMask()
Returns the 'or'-ed together bitmask indicating parameter validity. To determine the validity of a particular parameter, say tile width, test getValidMask() & ImageLayout.TILE_WIDTH_MASK against 0.

To test a single mask value or set of mask values, the convenience method isValid() may be used.

Returns:
an int that is the logical 'or' of the valid mask values, with a '1' bit representing the setting of a value.

isValid

public final boolean isValid(int mask)
Returns true if all the parameters specified by the argument are set.
Parameters:
mask - a bitmask.
Returns:
a boolean truth value.

setValid

public ImageLayout setValid(int mask)
Sets selected bits of the valid bitmask. The valid bitmask is set to the logical 'or' of its prior value and a new value.
Parameters:
mask - the new mask value to be 'or'-ed with the prior value.
Returns:
a reference to this ImageLayout following the change.

unsetValid

public ImageLayout unsetValid(int mask)
Clears selected bits of the valid bitmask. The valid bitmask is set to the logical 'and' of its prior value and the negation of the new mask value. This effectively subtracts from the set of valid parameters.
Parameters:
mask - the new mask value to be negated and 'and'-ed with the prior value.
Returns:
a reference to this ImageLayout following the change.

unsetImageBounds

public ImageLayout unsetImageBounds()
Marks the parameters dealing with the image bounds (minX, minY, width, and height) as being invalid.
Returns:
a reference to this ImageLayout following the change.

unsetTileLayout

public ImageLayout unsetTileLayout()
Marks the parameters dealing with the tile layout (tileGridXOffset, tileGridYOffset, tileWidth, and tileHeight) as being invalid.
Returns:
a reference to this ImageLayout following the change.

getMinX

public int getMinX(RenderedImage fallback)
Returns the value of minX if it is valid, and otherwise returns the value from the supplied RenderedImage. If minX is not valid and fallback is null, 0 is returned.
Parameters:
fallback - the RenderedImage fallback.
Returns:
the appropriate value of minX.

setMinX

public ImageLayout setMinX(int minX)
Sets minX to the supplied value and marks it as valid.
Parameters:
minX - the minimum X coordinate of the image, as an int.
Returns:
a reference to this ImageLayout following the change.

getMinY

public int getMinY(RenderedImage fallback)
Returns the value of minY if it is valid, and otherwise returns the value from the supplied RenderedImage. If minY is not valid and fallback is null, 0 is returned.
Parameters:
fallback - the RenderedImage fallback.
Returns:
the appropriate value of minY.

setMinY

public ImageLayout setMinY(int minY)
Sets minY to the supplied value and marks it as valid.
Parameters:
minY - the minimum Y coordinate of the image, as an int.
Returns:
a reference to this ImageLayout following the change.

getWidth

public int getWidth(RenderedImage fallback)
Returns the value of width if it is valid, and otherwise returns the value from the supplied RenderedImage. If width is not valid and fallback is null, 0 is returned.
Parameters:
fallback - the RenderedImage fallback.
Returns:
the appropriate value of width.

setWidth

public ImageLayout setWidth(int width)
Sets width to the supplied value and marks it as valid.
Parameters:
width - the width of the image, as an int.
Returns:
a reference to this ImageLayout following the change.
Throws:
IllegalArgumentException - if width is non-positive.

getHeight

public int getHeight(RenderedImage fallback)
Returns the value of height if it is valid, and otherwise returns the value from the supplied RenderedImage. If height is not valid and fallback is null, 0 is returned.
Parameters:
fallback - the RenderedImage fallback.
Returns:
the appropriate value of height.

setHeight

public ImageLayout setHeight(int height)
Sets height to the supplied value and marks it as valid.
Parameters:
height - the height of the image, as an int.
Returns:
a reference to this ImageLayout following the change.
Throws:
IllegalArgumentException - if height is non-positive.

getTileGridXOffset

public int getTileGridXOffset(RenderedImage fallback)
Returns the value of tileGridXOffset if it is valid, and otherwise returns the value from the supplied RenderedImage. If tileGridXOffset is not valid and fallback is null, 0 is returned.
Parameters:
fallback - the RenderedImage fallback.
Returns:
the appropriate value of tileGridXOffset.

setTileGridXOffset

public ImageLayout setTileGridXOffset(int tileGridXOffset)
Sets tileGridXOffset to the supplied value and marks it as valid.
Parameters:
tileGridXOffset - the X coordinate of tile (0, 0), as an int.
Returns:
a reference to this ImageLayout following the change.

getTileGridYOffset

public int getTileGridYOffset(RenderedImage fallback)
Returns the value of tileGridYOffset if it is valid, and otherwise returns the value from the supplied RenderedImage. If tileGridYOffset is not valid and fallback is null, 0 is returned.
Parameters:
fallback - the RenderedImage fallback.
Returns:
the appropriate value of tileGridYOffset.

setTileGridYOffset

public ImageLayout setTileGridYOffset(int tileGridYOffset)
Sets tileGridYOffset to the supplied value and marks it as valid.
Parameters:
tileGridYOffset - the Y coordinate of tile (0, 0), as an int.
Returns:
a reference to this ImageLayout following the change.

getTileWidth

public int getTileWidth(RenderedImage fallback)
Returns the value of tileWidth if it is valid, and otherwise returns the value from the supplied RenderedImage. If tileWidth is not valid and fallback is null, 0 is returned.
Parameters:
fallback - the RenderedImage fallback.
Returns:
the appropriate value of tileWidth.

setTileWidth

public ImageLayout setTileWidth(int tileWidth)
Sets tileWidth to the supplied value and marks it as valid.
Parameters:
tileWidth - the width of a tile, as an int.
Returns:
a reference to this ImageLayout following the change.
Throws:
IllegalArgumentException - if tileWidth is non-positive.

getTileHeight

public int getTileHeight(RenderedImage fallback)
Returns the value of tileHeight if it is valid, and otherwise returns the value from the supplied RenderedImage. If tileHeight is not valid and fallback is null, 0 is returned.
Parameters:
fallback - the RenderedImage fallback.
Returns:
the appropriate value of tileHeight.

setTileHeight

public ImageLayout setTileHeight(int tileHeight)
Sets tileHeight to the supplied value and marks it as valid.
Parameters:
tileHeight - the height of a tile, as an int.
Returns:
a reference to this ImageLayout following the change.
Throws:
IllegalArgumentException - if tileHeight is non-positive.

getSampleModel

public SampleModel getSampleModel(RenderedImage fallback)
Returns the value of sampleModel if it is valid, and otherwise returns the value from the supplied RenderedImage. If sampleModel is not valid and fallback is null, null is returned.
Parameters:
fallback - the RenderedImage fallback.
Returns:
the appropriate value of sampleModel.

setSampleModel

public ImageLayout setSampleModel(SampleModel sampleModel)
Sets sampleModel to the supplied value and marks it as valid.
Parameters:
sampleModel - the new SampleModel.
Returns:
a reference to this ImageLayout following the change.

getColorModel

public ColorModel getColorModel(RenderedImage fallback)
Returns the value of colorModel if it is valid, and otherwise returns the value from the supplied RenderedImage. If colorModel is not valid and fallback is null, null is returned.
Parameters:
fallback - the RenderedImage fallback.
Returns:
the appropriate value of colorModel.

setColorModel

public ImageLayout setColorModel(ColorModel colorModel)
Sets colorModel to the supplied value and marks it as valid.
Parameters:
colorModel - the new ColorModel.
Returns:
a reference to this ImageLayout following the change.

toString

public String toString()
Returns a String containing the values of all valid fields.
Overrides:
toString in class Object

clone

public Object clone()
Returns a clone of the ImageLayout as an Object.
Overrides:
clone in class Object

equals

public boolean equals(Object obj)
Tests if the specified Object equals this ImageLayout.
Overrides:
equals in class Object
Parameters:
obj - the Object to test for equality
Returns:
true if the specified Object is an instance of ImageLayout and equals this ImageLayout; false otherwise.
Since:
JAI 1.1

hashCode

public int hashCode()
Returns the hash code for this ImageLayout.
Overrides:
hashCode in class Object
Returns:
a hash code for this ImageLayout.
Since:
JAI 1.1