javax.media.jai.operator
Class FormatDescriptor

java.lang.Object
  javax.media.jai.OperationDescriptorImpl
      javax.media.jai.operator.FormatDescriptor

All Implemented Interfaces:

OperationDescriptor, RegistryElementDescriptor, Serializable

public class FormatDescriptor

extends OperationDescriptorImpl

An OperationDescriptor describing the "Format" operation.

The "Format" operation performs reformatting on an image. It is capable of casting the pixel values of an image to a given data type, replacing the SampleModel and ColorModel of an image, and restructuring the image's tile grid layout. The pixel values of the destination image are defined by the pseudocode:

dst[x][y][b] = cast(src[x][y][b], dataType)

where "dataType" is one of the constants TYPE_BYTE, TYPE_SHORT, TYPE_USHORT, TYPE_INT, TYPE_FLOAT, or TYPE_DOUBLE from java.awt.image.DataBuffer.

The output SampleModel, ColorModel and tile grid layout are specified by passing an ImageLayout object as a RenderingHint named "ImageLayout". The output image will have a SampleModel compatible with the one specified in the layout hint wherever possible; however, for output data types of float and double a ComponentSampleModel will be used regardless of the value of the hint parameter.

One of the common uses of the format operator is to cast the pixel values of an image to a given data type. In such a case, if the source image provided has an IndexColorModel, a RenderingHints object for JAI.KEY_REPLACE_INDEX_COLOR_MODEL with the value of Boolean.TRUE will automatically be added to the configuration Map for the operation. This addition will only take place if a value for the JAI.KEY_REPLACE_INDEX_COLOR_MODEL has not already been provided by the user. Note that the configuration Map is cloned before the new hint is added to it. Due to the addition of this new RenderingHint, using the "format" operation with source(s) that have an IndexColorModel will cause the destination to have an expanded non-IndexColorModel ColorModel. This expansion ensures that the conversion to a different data type, ColorModel or SampleModel happens correctly such that the indices into the color map (for IndexColorModel images) are not treated as pixel data. If the format operator is not being used to cast the pixel values of an image to a given data type, the expansion will not take place, the resultant image will still have an IndexColorModel.

The ImageLayout may also specify a tile grid origin and size which will be respected.

The typecasting performed by the Format function is defined by the following set of expressions, dependent on the data types of the source and destination. Casting an image to its current data type is a no-op. See The Java Language Specification for the definition of type conversions between primitive types.

In most cases, it is not necessary to explictly perform widening typecasts since they will be performed automatically by image operators when handed source images having different datatypes.

Source Type	Destination Type	Action
BYTE	SHORT	(short)(x & 0xff)
BYTE	USHORT	(short)(x & 0xff)
BYTE	INT	(int)(x & 0xff)
BYTE	FLOAT	(float)(x & 0xff)
BYTE	DOUBLE	(double)(x & 0xff)
SHORT	BYTE	(byte)clamp((int)x, 0, 255)
SHORT	USHORT	(short)clamp((int)x, 0, 32767)
SHORT	INT	(int)x
SHORT	FLOAT	(float)x
SHORT	DOUBLE	(double)x
USHORT	BYTE	(byte)clamp((int)x & 0xffff, 0, 255)
USHORT	SHORT	(short)clamp((int)x & 0xffff, 0, 32767)
USHORT	INT	(int)(x & 0xffff)
USHORT	FLOAT	(float)(x & 0xffff)
USHORT	DOUBLE	(double)(x & 0xffff)
INT	BYTE	(byte)clamp(x, 0, 255)
INT	SHORT	(short)clamp(x, -32768, 32767)
INT	USHORT	(short)clamp(x, 0, 65535)
INT	FLOAT	(float)x
INT	DOUBLE	(double)x
FLOAT	BYTE	(byte)clamp((int)x, 0, 255)
FLOAT	SHORT	(short)clamp((int)x, -32768, 32767)
FLOAT	USHORT	(short)clamp((int)x, 0, 65535)
FLOAT	INT	(int)x
FLOAT	DOUBLE	(double)x
DOUBLE	BYTE	(byte)clamp((int)x, 0, 255)
DOUBLE	SHORT	(short)clamp((int)x, -32768, 32767)
DOUBLE	USHORT	(short)clamp((int)x, 0, 65535)
DOUBLE	INT	(int)x
DOUBLE	FLOAT	(float)x

The clamp function may be defined as:

 int clamp(int x, int low, int high) {
     return (x < low) ? low : ((x > high) ? high : x);
 }
 

Resource List

Name	Value
GlobalName	Format
LocalName	Format
Vendor	com.sun.media.jai
Description	Reformats an image.
DocURL	http://java.sun.com/products/java-media/jai/forDevelopers/jai-apidocs/javax/media/jai/operator/FormatDescriptor.html
Version	1.0
arg0Desc	The output data type (from java.awt.image.DataBuffer).

Parameter List

Name	Class Type	Default Value
dataType	java.lang.Integer	DataBuffer.TYPE_BYTE

See Also:

DataBuffer, ImageLayout, OperationDescriptor, Serialized Form

Field Summary

Fields inherited from class javax.media.jai.OperationDescriptorImpl

sourceNames, supportedModes

Fields inherited from interface javax.media.jai.OperationDescriptor

NO_PARAMETER_DEFAULT

Constructor Summary

FormatDescriptor()
Constructor.

Method Summary

static RenderedOp	create(RenderedImage source0, Integer dataType, RenderingHints hints) Reformats an image.
static RenderableOp	createRenderable(RenderableImage source0, Integer dataType, RenderingHints hints) Reformats an image.
Number	getParamMaxValue(int index) Returns the maximum legal value of a specified numeric parameter for this operation.
Number	getParamMinValue(int index) Returns the minimum legal value of a specified numeric parameter for this operation.
boolean	isRenderableSupported() Returns true since renderable operation is supported.

Methods inherited from class javax.media.jai.OperationDescriptorImpl

arePropertiesSupported, getDefaultSourceClass, getDestClass, getDestClass, getInvalidRegion, getName, getNumParameters, getNumSources, getParamClasses, getParamDefaults, getParamDefaultValue, getParameterListDescriptor, getParamNames, getPropertyGenerators, getPropertyGenerators, getRenderableDestClass, getRenderableSourceClasses, getResourceBundle, getResources, getSourceClasses, getSourceClasses, getSourceNames, getSupportedModes, isImmediate, isModeSupported, isRenderedSupported, makeDefaultSourceClassList, validateArguments, validateArguments, validateParameters, validateParameters, validateRenderableArguments, validateRenderableSources, validateSources, validateSources

Methods inherited from class java.lang.Object

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

Constructor Detail

FormatDescriptor

public FormatDescriptor()

Constructor.

Method Detail

isRenderableSupported

public boolean isRenderableSupported()

Returns true since renderable operation is supported.

Specified by:

isRenderableSupported in interface OperationDescriptor

Overrides:

isRenderableSupported in class OperationDescriptorImpl

See Also:

OperationDescriptorImpl.isModeSupported(java.lang.String)

getParamMinValue

public Number getParamMinValue(int index)

Returns the minimum legal value of a specified numeric parameter for this operation.

Specified by:

getParamMinValue in interface OperationDescriptor

Overrides:

getParamMinValue in class OperationDescriptorImpl

Parameters:

index - The index of the parameter to be queried.

Returns:

A Number representing the minimum legal value, or null if the specified parameter is not numeric.

See Also:

ParameterListDescriptor.getParamValueRange(java.lang.String), ParameterListDescriptor.getEnumeratedParameterValues(java.lang.String), ParameterListDescriptor.isParameterValueValid(java.lang.String, java.lang.Object)

getParamMaxValue

public Number getParamMaxValue(int index)

Returns the maximum legal value of a specified numeric parameter for this operation.

Specified by:

getParamMaxValue in interface OperationDescriptor

Overrides:

getParamMaxValue in class OperationDescriptorImpl

Parameters:

index - The index of the parameter to be queried.

Returns:

A Number representing the maximum legal value, or null if the specified parameter is not numeric.

See Also:

ParameterListDescriptor.getParamValueRange(java.lang.String), ParameterListDescriptor.getEnumeratedParameterValues(java.lang.String), ParameterListDescriptor.isParameterValueValid(java.lang.String, java.lang.Object)

create

public static RenderedOp create(RenderedImage source0,
                                Integer dataType,
                                RenderingHints hints)

Reformats an image.

Creates a ParameterBlockJAI from all supplied arguments except hints and invokes JAI.create(String,ParameterBlock,RenderingHints).

Parameters:

source0 - RenderedImage source 0.

dataType - The output data type (from java.awt.image.DataBuffer). May be null.

hints - The RenderingHints to use. May be null.

Returns:

The RenderedOp destination.

Throws:

IllegalArgumentException - if source0 is null.

See Also:

JAI, ParameterBlockJAI, RenderedOp

createRenderable

public static RenderableOp createRenderable(RenderableImage source0,
                                            Integer dataType,
                                            RenderingHints hints)

Reformats an image.

Creates a ParameterBlockJAI from all supplied arguments except hints and invokes JAI.createRenderable(String,ParameterBlock,RenderingHints).

Parameters:

source0 - RenderableImage source 0.

dataType - The output data type (from java.awt.image.DataBuffer). May be null.

hints - The RenderingHints to use. May be null.

Returns:

The RenderableOp destination.

Throws:

IllegalArgumentException - if source0 is null.

See Also:

JAI, ParameterBlockJAI, RenderableOp