A
ColorModel
class that works with pixel values that
represent color and alpha information as separate samples and that
store each sample in a separate data element. This class can be
used with an arbitrary
ColorSpace
. The number of
color samples in the pixel values must be same as the number of
color components in the
ColorSpace
. There may be a
single alpha sample.
For those methods that use
a primitive array pixel representation of type transferType
,
the array length is the same as the number of color and alpha samples.
Color samples are stored first in the array followed by the alpha
sample, if present. The order of the color samples is specified
by the ColorSpace
. Typically, this order reflects the
name of the color space type. For example, for TYPE_RGB
,
index 0 corresponds to red, index 1 to green, and index 2 to blue.
The translation from pixel sample values to color/alpha components for
display or processing purposes is based on a one-to-one correspondence of
samples to components.
Depending on the transfer type used to create an instance of
ComponentColorModel
, the pixel sample values
represented by that instance may be signed or unsigned and may
be of integral type or float or double (see below for details).
The translation from sample values to normalized color/alpha components
must follow certain rules. For float and double samples, the translation
is an identity, i.e. normalized component values are equal to the
corresponding sample values. For integral samples, the translation
should be only a simple scale and offset, where the scale and offset
constants may be different for each component. The result of
applying the scale and offset constants is a set of color/alpha
component values, which are guaranteed to fall within a certain
range. Typically, the range for a color component will be the range
defined by the getMinValue
and getMaxValue
methods of the ColorSpace
class. The range for an
alpha component should be 0.0 to 1.0.
Instances of ComponentColorModel
created with transfer types
DataBuffer.TYPE_BYTE
, DataBuffer.TYPE_USHORT
,
and DataBuffer.TYPE_INT
have pixel sample values which
are treated as unsigned integral values.
The number of bits in a color or alpha sample of a pixel value might not
be the same as the number of bits for the corresponding color or alpha
sample passed to the
ComponentColorModel(ColorSpace, int[], boolean, boolean, int, int)
constructor. In
that case, this class assumes that the least significant n bits of a sample
value hold the component value, where n is the number of significant bits
for the component passed to the constructor. It also assumes that
any higher-order bits in a sample value are zero. Thus, sample values
range from 0 to 2n - 1. This class maps these sample values
to normalized color component values such that 0 maps to the value
obtained from the ColorSpace's
getMinValue
method for each component and 2n - 1 maps to the value
obtained from getMaxValue
. To create a
ComponentColorModel
with a different color sample mapping
requires subclassing this class and overriding the
getNormalizedComponents(Object, float[], int)
method.
The mapping for an alpha sample always maps 0 to 0.0 and
2n - 1 to 1.0.
For instances with unsigned sample values,
the unnormalized color/alpha component representation is only
supported if two conditions hold. First, sample value value 0 must
map to normalized component value 0.0 and sample value 2n - 1
to 1.0. Second the min/max range of all color components of the
ColorSpace
must be 0.0 to 1.0. In this case, the
component representation is the n least
significant bits of the corresponding sample. Thus each component is
an unsigned integral value between 0 and 2n - 1, where
n is the number of significant bits for a particular component.
If these conditions are not met, any method taking an unnormalized
component argument will throw an IllegalArgumentException
.
Instances of ComponentColorModel
created with transfer types
DataBuffer.TYPE_SHORT
, DataBuffer.TYPE_FLOAT
, and
DataBuffer.TYPE_DOUBLE
have pixel sample values which
are treated as signed short, float, or double values.
Such instances do not support the unnormalized color/alpha component
representation, so any methods taking such a representation as an argument
will throw an IllegalArgumentException
when called on one
of these instances. The normalized component values of instances
of this class have a range which depends on the transfer
type as follows: for float samples, the full range of the float data
type; for double samples, the full range of the float data type
(resulting from casting double to float); for short samples,
from approximately -maxVal to +maxVal, where maxVal is the per
component maximum value for the ColorSpace
(-32767 maps to -maxVal, 0 maps to 0.0, and 32767 maps
to +maxVal). A subclass may override the scaling for short sample
values to normalized component values by overriding the
getNormalizedComponents(Object, float[], int)
method.
For float and double samples, the normalized component values are
taken to be equal to the corresponding sample values, and subclasses
should not attempt to add any non-identity scaling for these transfer
types.
Instances of ComponentColorModel
created with transfer types
DataBuffer.TYPE_SHORT
, DataBuffer.TYPE_FLOAT
, and
DataBuffer.TYPE_DOUBLE
use all the bits of all sample values. Thus all color/alpha components
have 16 bits when using DataBuffer.TYPE_SHORT
, 32 bits when
using DataBuffer.TYPE_FLOAT
, and 64 bits when using
DataBuffer.TYPE_DOUBLE
. When the
ComponentColorModel(ColorSpace, int[], boolean, boolean, int, int)
form of constructor is used with one of these transfer types, the
bits array argument is ignored.
It is possible to have color/alpha sample values
which cannot be reasonably interpreted as component values for rendering.
This can happen when ComponentColorModel
is subclassed to
override the mapping of unsigned sample values to normalized color
component values or when signed sample values outside a certain range
are used. (As an example, specifying an alpha component as a signed
short value outside the range 0 to 32767, normalized range 0.0 to 1.0, can
lead to unexpected results.) It is the
responsibility of applications to appropriately scale pixel data before
rendering such that color components fall within the normalized range
of the ColorSpace
(obtained using the getMinValue
and getMaxValue
methods of the ColorSpace
class)
and the alpha component is between 0.0 and 1.0. If color or alpha
component values fall outside these ranges, rendering results are
indeterminate.
Methods that use a single int pixel representation throw
an IllegalArgumentException
, unless the number of components
for the ComponentColorModel
is one and the component
value is unsigned -- in other words, a single color component using
a transfer type of DataBuffer.TYPE_BYTE
,
DataBuffer.TYPE_USHORT
, or DataBuffer.TYPE_INT
and no alpha.
A ComponentColorModel
can be used in conjunction with a
ComponentSampleModel
, a BandedSampleModel
,
or a PixelInterleavedSampleModel
to construct a
BufferedImage
.