| 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: java.awt.image.DataBuffer
See Also: javax.media.jai.ImageLayout
See Also: javax.media.jai.OperationDescriptor |
