javax.imageio

Class IIOParam

public abstract class IIOParam extends Object

An IIOParam stores parameters used when encoding or decoding image streams. ImageReadParam and ImageWriteParam extend this abstract base class. IIOParams allow control over how source pixels converted into destination pixels. This conversion can take place between a stream and in-memory image data, when an image reader is doing the conversion, or a writer can be doing the conversion from an in-memory source to a stream destination. An image reader can be restricted to only read from a given region; likewise a writer can be restricted to only write output to a given region. For image readers and writers, IIOParam supports image pixelation -- where the input image is approximated by the output image using larger-sized pixel blocks. For example: FIXME IIOParams can control how pixels are combined into larger blocks using sub-sampling matrices. For example: FIXME They can also control which source bands are read and written; this example reads the RGBA (red, green, blue, transparency) data from a PNG image and outputs just the red and transparency bands: FIXME

Field Summary
protected IIOParamController	controller The controller called by this IIOParam to retrieve parameters.
protected IIOParamController	defaultController The default controller called by this IIOParam to retrieve parameters.
protected Point	destinationOffset The offset in the destination where the upper-left decoded/encoded pixel should be located.
protected ImageTypeSpecifier	destinationType Sets the output colour type when writing or the destination image type when reading.
protected int[]	sourceBands An array indicating which source bands will be used or null.
protected Rectangle	sourceRegion The source pixel region or null.
protected int	sourceXSubsampling Sample every sourceXSubsampling'th pixel in the source image when pixelating the destination image in the horizontal direction.
protected int	sourceYSubsampling Sample every sourceYSubsampling'th pixel in the source image when pixelating the destination image in the vertical direction.
protected int	subsamplingXOffset Start sampling at this horizontal offset within the source region when pixelating the destination image in the horizontal direction.
protected int	subsamplingYOffset Start sampling at this vertical offset within the source region when pixelating the destination image in the vertical direction.

Constructor Summary
protected	IIOParam() Constructs an IIOParam object.

Method Summary
boolean	activateController() Activates the parameter controller by calling its activate method and passing it this IIOParam.
IIOParamController	getController() Retrieve the currently set controller if one has been set, or the default controller, or null if the controller has been explicitly set to null.
IIOParamController	getDefaultController() Retrieve the default controller regardless of whether or not a non-default controller has been set.
Point	getDestinationOffset() Retrieve the offset in the destination where the upper-left decoded/encoded pixel should be located.
ImageTypeSpecifier	getDestinationType() Retrieve the currently set image-type specifier or null if none has been set.
int[]	getSourceBands() Retrieve the current source band values or null if source band values have not been set.
Rectangle	getSourceRegion() Retrieve the source rectangle from which pixels should be read or null if no source region has been set.
int	getSourceXSubsampling() Retrieve the number of pixel columns to advance before taking a pixel sample.
int	getSourceYSubsampling() Retrieve the number of pixel rows to advance before taking a pixel sample.
int	getSubsamplingXOffset() Retrieve the number of pixel columns to advance before taking any pixel samples.
int	getSubsamplingYOffset() Retrieve the number of pixel rows to advance before taking any pixel samples.
boolean	hasController() Check if a non-null controller is currently available.
void	setController(IIOParamController controller) Sets the controller for this IIOParam.
void	setDestinationOffset(Point destinationOffset) Specify the destination pixel offset.
void	setDestinationType(ImageTypeSpecifier destinationType) Set the destination image type.
void	setSourceBands(int[] sourceBands) Set the indices of the source bands to be used.
void	setSourceRegion(Rectangle sourceRegion) Set the source region from which to read.
void	setSourceSubsampling(int sourceXSubsampling, int sourceYSubsampling, int subsamplingXOffset, int subsamplingYOffset) Set the source sampling intervals and offsets.

Field Detail

controller

protected IIOParamController controller

The controller called by this IIOParam to retrieve parameters.

defaultController

protected IIOParamController defaultController

The default controller called by this IIOParam to retrieve parameters.

destinationOffset

protected Point destinationOffset

The offset in the destination where the upper-left decoded/encoded pixel should be located.

destinationType

protected ImageTypeSpecifier destinationType

Sets the output colour type when writing or the destination image type when reading.

sourceBands

protected int[] sourceBands

An array indicating which source bands will be used or null.

sourceRegion

protected Rectangle sourceRegion

The source pixel region or null.

sourceXSubsampling

protected int sourceXSubsampling

Sample every sourceXSubsampling'th pixel in the source image when pixelating the destination image in the horizontal direction.

sourceYSubsampling

protected int sourceYSubsampling

Sample every sourceYSubsampling'th pixel in the source image when pixelating the destination image in the vertical direction.

subsamplingXOffset

protected int subsamplingXOffset

Start sampling at this horizontal offset within the source region when pixelating the destination image in the horizontal direction.

subsamplingYOffset

protected int subsamplingYOffset

Start sampling at this vertical offset within the source region when pixelating the destination image in the vertical direction.

Constructor Detail

IIOParam

protected IIOParam()

Constructs an IIOParam object.

Method Detail

activateController

public boolean activateController()

Activates the parameter controller by calling its activate method and passing it this IIOParam. A true return value indicates that this IIOParam's values are ready for the next read or write operation. A return value of false means that this IIOParam's values have not been affected because the controller operations were cancelled.

Returns: true if parameters were successfully set, false if parameters were not changed

getController

public IIOParamController getController()

Retrieve the currently set controller if one has been set, or the default controller, or null if the controller has been explicitly set to null.

Returns: the currently used controller or null

getDefaultController

public IIOParamController getDefaultController()

Retrieve the default controller regardless of whether or not a non-default controller has been set. The default controller may be null.

Returns: the default controller or null

getDestinationOffset

public Point getDestinationOffset()

Retrieve the offset in the destination where the upper-left decoded/encoded pixel should be located. (0, 0) by default.

Returns: the destination offset

getDestinationType

public ImageTypeSpecifier getDestinationType()

Retrieve the currently set image-type specifier or null if none has been set.

Returns: the current image-type specifier or null

getSourceBands

public int[] getSourceBands()

Retrieve the current source band values or null if source band values have not been set. The returned array is a copy of this IIOParam's source band array.

Returns: the current set of source band values or null

getSourceRegion

public Rectangle getSourceRegion()

Retrieve the source rectangle from which pixels should be read or null if no source region has been set.

Returns: the current source region or null

getSourceXSubsampling

public int getSourceXSubsampling()

Retrieve the number of pixel columns to advance before taking a pixel sample.

Returns: the horizontal sub-sampling interval

getSourceYSubsampling

public int getSourceYSubsampling()

Retrieve the number of pixel rows to advance before taking a pixel sample.

Returns: the vertical sub-sampling interval

getSubsamplingXOffset

public int getSubsamplingXOffset()

Retrieve the number of pixel columns to advance before taking any pixel samples.

Returns: the horizontal sub-sampling offset

getSubsamplingYOffset

public int getSubsamplingYOffset()

Retrieve the number of pixel rows to advance before taking any pixel samples.

Returns: the vertical sub-sampling offset

hasController

public boolean hasController()

Check if a non-null controller is currently available.

Returns: true if getController returns a non-null value, false if getController returns null

setController

public void setController(IIOParamController controller)

Sets the controller for this IIOParam. This is the controller that will be activated when activateController is called. The argument controller overrides this IIOParam's default controller. If the argument is null then no controller will be set, not even the default one. To reset the default controller call setController(getDefaultController()).

Parameters: controller the controller to set or null

setDestinationOffset

public void setDestinationOffset(Point destinationOffset)

Specify the destination pixel offset. Image writers are only affected by this setting when ImageWriter.replacePixels is called in which case the offset is into the region of pixels being changed.

Parameters: destinationOffset the offset where pixel writing should begin

setDestinationType

public void setDestinationType(ImageTypeSpecifier destinationType)

Set the destination image type. If this value is set on an image reader then its read method will return a new BufferedImage of the specified destination type. In this case any destination image set using setDestination() is ignored. If this is set on an image writer then the destination type affects only the colour model of the destination image. The destination type's SampleModel is ignored. The destination type's ColorModel will override the source image's colour model.

Parameters: destinationType the sample and colour models of the destination image

setSourceBands

public void setSourceBands(int[] sourceBands)

Set the indices of the source bands to be used. Duplicate indices are not allowed. A value of null means use all source bands. The argument array is copied and stored, so subsequent updates to it will not be reflected in this IIOParam.

Parameters: sourceBands the array of source bands to use

setSourceRegion

public void setSourceRegion(Rectangle sourceRegion)

Set the source region from which to read. The number of pixels sampled from the source region depends on the source sub-sampling settings. If the combination of this sourceRegion and the current sub-sampling settings would result in no pixels being sampled then an IllegalStateException will be thrown. The source region is specified in the source image coordinate system which has point (0, 0) at the top-left and increases down and to the right. The argument source region is clipped to the image boundaries at read-time. A null argument sets the source region to null meaning that the whole image should be read.

Parameters: sourceRegion the rectangular source region

Throws: IllegalArgumentException if sourceRegion has width or height <= 0 or x or y < 0 IllegalStateException if the given sourceRegion and the current sampling settings would produce zero samples

setSourceSubsampling

public void setSourceSubsampling(int sourceXSubsampling, int sourceYSubsampling, int subsamplingXOffset, int subsamplingYOffset)

Set the source sampling intervals and offsets. Every sourceXSubsampling'th pixel horizontally and sourceYSubsampling'th pixel vertically will be sampled. Sampling will being a the subsamplingXOffset'th column and the subsamplingYOffset'th row. Horizontally, the number of sampled pixels will be: floor((width - subsamplingXOffset + sourceXSubsampling - 1) / sourceXSubsampling) Vertically: floor((height - subsamplingYOffset + sourceYSubsampling - 1) / sourceYSubsampling) If the current source region setting is such that the given sub-sampling arguments would produce zero pixel samples, an IllegalStateException is thrown. The offset parameters can be used to make source regions overlap when tiling across an image. This can eliminate seams and better-tile images whose width or height is not a multiple of the sampling interval.

Parameters: sourceXSubsampling the horizontal sampling interval sourceYSubsampling the vertical sampling interval subsamplingXOffset the horizontal offset of the initial sample subsamplingYOffset the vertical offset of the initial sample

Throws: IllegalArgumentException if either subsamplingXOffset or subsamplingYOffset is < 0 IllegalStateException if the current source region combined with the given sub-sampling parameters would produce zero pixel samples