public abstract class ColorModel extends Object implements java.awt.Transparency
ColorModel
abstract class encapsulates the
methods for translating a pixel value to color components
(for example, red, green, and blue) and an alpha component.
In order to render an image to the screen, a printer, or another
image, pixel values must be converted to color and alpha components.
As arguments to or return values from methods of this class,
pixels are represented as 32-bit ints or as arrays of primitive types.
The number, order, and interpretation of color components for a
ColorModel
is specified by its ColorSpace
.
A ColorModel
used with pixel data that does not include
alpha information treats all pixels as opaque, which is an alpha
value of 1.0.
This ColorModel
class supports two representations of
pixel values. A pixel value can be a single 32-bit int or an
array of primitive types. The Java(tm) Platform 1.0 and 1.1 APIs
represented pixels as single byte
or single
int
values. For purposes of the ColorModel
class, pixel value arguments were passed as ints. The Java(tm) 2
Platform API introduced additional classes for representing images.
With BufferedImage
or RenderedImage
objects, based on Raster
and SampleModel
classes, pixel
values might not be conveniently representable as a single int.
Consequently, ColorModel
now has methods that accept
pixel values represented as arrays of primitive types. The primitive
type used by a particular ColorModel
object is called its
transfer type.
ColorModel
objects used with images for which pixel values
are not conveniently representable as a single int throw an
IllegalArgumentException
when methods taking a single int pixel
argument are called. Subclasses of ColorModel
must
specify the conditions under which this occurs. This does not
occur with DirectColorModel
or IndexColorModel
objects.
Currently, the transfer types supported by the Java 2D(tm) API are
DataBuffer.TYPE_BYTE, DataBuffer.TYPE_USHORT, DataBuffer.TYPE_INT,
DataBuffer.TYPE_SHORT, DataBuffer.TYPE_FLOAT, and DataBuffer.TYPE_DOUBLE.
Most rendering operations will perform much faster when using ColorModels
and images based on the first three of these types. In addition, some
image filtering operations are not supported for ColorModels and
images based on the latter three types.
The transfer type for a particular ColorModel
object is
specified when the object is created, either explicitly or by default.
All subclasses of ColorModel
must specify what the
possible transfer types are and how the number of elements in the
primitive arrays representing pixels is determined.
For BufferedImages
, the transfer type of its
Raster
and of the Raster
object's
SampleModel
(available from the
getTransferType
methods of these classes) must match that
of the ColorModel
. The number of elements in an array
representing a pixel for the Raster
and
SampleModel
(available from the
getNumDataElements
methods of these classes) must match
that of the ColorModel
.
The algorithm used to convert from pixel values to color and alpha
components varies by subclass. For example, there is not necessarily
a one-to-one correspondence between samples obtained from the
SampleModel
of a BufferedImage
object's
Raster
and color/alpha components. Even when
there is such a correspondence, the number of bits in a sample is not
necessarily the same as the number of bits in the corresponding color/alpha
component. Each subclass must specify how the translation from
pixel values to color/alpha components is done.
Methods in the ColorModel
class use two different
representations of color and alpha components - a normalized form
and an unnormalized form. In the normalized form, each component is a
float
value between some minimum and maximum values. For
the alpha component, the minimum is 0.0 and the maximum is 1.0. For
color components the minimum and maximum values for each component can
be obtained from the ColorSpace
object. These values
will often be 0.0 and 1.0 (e.g. normalized component values for the
default sRGB color space range from 0.0 to 1.0), but some color spaces
have component values with different upper and lower limits. These
limits can be obtained using the getMinValue
and
getMaxValue
methods of the ColorSpace
class. Normalized color component values are not premultiplied.
All ColorModels
must support the normalized form.
In the unnormalized
form, 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 pixel values for a particular
ColorModel
represent color samples premultiplied by
the alpha sample, unnormalized color component values are
also premultiplied. The unnormalized form is used only with instances
of ColorModel
whose ColorSpace
has minimum
component values of 0.0 for all components and maximum values of
1.0 for all components.
The unnormalized form for color and alpha components can be a convenient
representation for ColorModels
whose normalized component
values all lie
between 0.0 and 1.0. In such cases the integral value 0 maps to 0.0 and
the value 2n - 1 maps to 1.0. In other cases, such as
when the normalized component values can be either negative or positive,
the unnormalized form is not convenient. Such ColorModel
objects throw an IllegalArgumentException
when methods involving
an unnormalized argument are called. Subclasses of ColorModel
must specify the conditions under which this occurs.
IndexColorModel
,
ComponentColorModel
,
PackedColorModel
,
DirectColorModel
,
Image
,
BufferedImage
,
RenderedImage
,
ColorSpace
,
SampleModel
,
Raster
,
DataBuffer
Modifier and Type | Field and Description |
---|---|
protected int |
pixel_bits
The total number of bits in the pixel.
|
protected int |
transferType
Data type of the array used to represent pixel values.
|
Modifier | Constructor and Description |
---|---|
|
ColorModel(int bits)
Constructs a
ColorModel that translates pixels of the
specified number of bits to color/alpha components. |
protected |
ColorModel(int pixel_bits,
int[] bits,
java.awt.color.ColorSpace cspace,
boolean hasAlpha,
boolean isAlphaPremultiplied,
int transparency,
int transferType)
Constructs a
ColorModel that translates pixel values
to color/alpha components. |
Modifier and Type | Method and Description |
---|---|
boolean |
equals(Object obj)
Tests if the specified
Object is an instance of
ColorModel and if it equals this
ColorModel . |
void |
finalize()
Disposes of system resources associated with this
ColorModel once this ColorModel is no
longer referenced. |
abstract int |
getAlpha(int pixel)
Returns the alpha component for the specified pixel, scaled
from 0 to 255.
|
abstract int |
getBlue(int pixel)
Returns the blue color component for the specified pixel, scaled
from 0 to 255 in the default RGB ColorSpace, sRGB.
|
java.awt.color.ColorSpace |
getColorSpace()
Returns the
ColorSpace associated with this
ColorModel . |
int[] |
getComponentSize()
Returns an array of the number of bits per color/alpha component.
|
int |
getComponentSize(int componentIdx)
Returns the number of bits for the specified color/alpha component.
|
abstract int |
getGreen(int pixel)
Returns the green color component for the specified pixel, scaled
from 0 to 255 in the default RGB ColorSpace, sRGB.
|
int |
getNumColorComponents()
Returns the number of color components in this
ColorModel . |
int |
getNumComponents()
Returns the number of components, including alpha, in this
ColorModel . |
int |
getPixelSize()
Returns the number of bits per pixel described by this
ColorModel . |
abstract int |
getRed(int pixel)
Returns the red color component for the specified pixel, scaled
from 0 to 255 in the default RGB ColorSpace, sRGB.
|
int |
getRGB(int pixel)
Returns the color/alpha components of the pixel in the default
RGB color model format.
|
static ColorModel |
getRGBdefault()
Returns a
DirectColorModel that describes the default
format for integer RGB values used in many of the methods in the
AWT image interfaces for the convenience of the programmer. |
int |
getTransferType()
Returns the transfer type of this
ColorModel . |
int |
getTransparency()
Returns the transparency.
|
boolean |
hasAlpha()
Returns whether or not alpha is supported in this
ColorModel . |
int |
hashCode()
Returns the hash code for this ColorModel.
|
boolean |
isAlphaPremultiplied()
Returns whether or not the alpha has been premultiplied in the
pixel values to be translated by this
ColorModel . |
String |
toString()
Returns the
String representation of the contents of
this ColorModel object. |
protected int pixel_bits
protected int transferType
public ColorModel(int bits)
ColorModel
that translates pixels of the
specified number of bits to color/alpha components. The color
space is the default RGB ColorSpace
, which is sRGB.
Pixel values are assumed to include alpha information. If color
and alpha information are represented in the pixel value as
separate spatial bands, the color bands are assumed not to be
premultiplied with the alpha value. The transparency type is
java.awt.Transparency.TRANSLUCENT. The transfer type will be the
smallest of DataBuffer.TYPE_BYTE, DataBuffer.TYPE_USHORT,
or DataBuffer.TYPE_INT that can hold a single pixel
(or DataBuffer.TYPE_UNDEFINED if bits is greater
than 32). Since this constructor has no information about the
number of bits per color and alpha component, any subclass calling
this constructor should override any method that requires this
information.bits
- the number of bits of a pixelIllegalArgumentException
- if the number
of bits in bits
is less than 1protected ColorModel(int pixel_bits, int[] bits, java.awt.color.ColorSpace cspace, boolean hasAlpha, boolean isAlphaPremultiplied, int transparency, int transferType)
ColorModel
that translates pixel values
to color/alpha components. Color components will be in the
specified ColorSpace
. pixel_bits
is the
number of bits in the pixel values. The bits array
specifies the number of significant bits per color and alpha component.
Its length should be the number of components in the
ColorSpace
if there is no alpha information in the
pixel values, or one more than this number if there is alpha
information. hasAlpha
indicates whether or not alpha
information is present. The boolean
isAlphaPremultiplied
specifies how to interpret pixel
values in which color and alpha information are represented as
separate spatial bands. If the boolean
is true
, color samples are assumed to have been
multiplied by the alpha sample. The transparency
specifies what alpha values can be represented by this color model.
The transfer type is the type of primitive array used to represent
pixel values. Note that the bits array contains the number of
significant bits per color/alpha component after the translation
from pixel values. For example, for an
IndexColorModel
with pixel_bits
equal to
16, the bits array might have four elements with each element set
to 8.pixel_bits
- the number of bits in the pixel valuesbits
- array that specifies the number of significant bits
per color and alpha componentcspace
- the specified ColorSpace
hasAlpha
- true
if alpha information is present;
false
otherwiseisAlphaPremultiplied
- true
if color samples are
assumed to be premultiplied by the alpha samples;
false
otherwisetransparency
- what alpha values can be represented by this
color modeltransferType
- the type of the array used to represent pixel
valuesIllegalArgumentException
- if the length of
the bit array is less than the number of color or alpha
components in this ColorModel
, or if the
transparency is not a valid value.IllegalArgumentException
- if the sum of the number
of bits in bits
is less than 1 or if
any of the elements in bits
is less than 0.Transparency
public static ColorModel getRGBdefault()
DirectColorModel
that describes the default
format for integer RGB values used in many of the methods in the
AWT image interfaces for the convenience of the programmer.
The color space is the default ColorSpace
, sRGB.
The format for the RGB values is an integer with 8 bits
each of alpha, red, green, and blue color components ordered
correspondingly from the most significant byte to the least
significant byte, as in: 0xAARRGGBB. Color components are
not premultiplied by the alpha component. This format does not
necessarily represent the native or the most efficient
ColorModel
for a particular device or for all images.
It is merely used as a common color model format.DirectColorModel
object describing default
RGB values.public final boolean hasAlpha()
ColorModel
.true
if alpha is supported in this
ColorModel
; false
otherwise.public final boolean isAlphaPremultiplied()
ColorModel
.
If the boolean is true
, this ColorModel
is to be used to interpret pixel values in which color and alpha
information are represented as separate spatial bands, and color
samples are assumed to have been multiplied by the
alpha sample.true
if the alpha values are premultiplied
in the pixel values to be translated by this
ColorModel
; false
otherwise.public final int getTransferType()
ColorModel
.
The transfer type is the type of primitive array used to represent
pixel values as arrays.public int getPixelSize()
ColorModel
.public int getComponentSize(int componentIdx)
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. If this ColorModel
supports alpha, the alpha
component corresponds to the index following the last color
component.componentIdx
- the index of the color/alpha componentArrayIndexOutOfBoundsException
- if componentIdx
is greater than the number of components or
less than zeroNullPointerException
- if the number of bits array is
null
public int[] getComponentSize()
ColorSpace
, followed by the alpha component, if
present.public int getTransparency()
getTransparency
in interface java.awt.Transparency
ColorModel
.Transparency.OPAQUE
,
Transparency.BITMASK
,
Transparency.TRANSLUCENT
public int getNumComponents()
ColorModel
. This is equal to the number of color
components, optionally plus one, if there is an alpha component.ColorModel
public int getNumColorComponents()
ColorModel
.
This is the number of components returned by
ColorSpace.getNumComponents()
.ColorModel
.ColorSpace.getNumComponents()
public abstract int getRed(int pixel)
IllegalArgumentException
is thrown if pixel
values for this ColorModel
are not conveniently
representable as a single int. The returned value is not a
pre-multiplied value. For example, if the
alpha is premultiplied, this method divides it out before returning
the value. If the alpha value is 0, the red value is 0.pixel
- a specified pixelpublic abstract int getGreen(int pixel)
IllegalArgumentException
is thrown if pixel
values for this ColorModel
are not conveniently
representable as a single int. The returned value is a non
pre-multiplied value. For example, if the alpha is premultiplied,
this method divides it out before returning
the value. If the alpha value is 0, the green value is 0.pixel
- the specified pixelpublic abstract int getBlue(int pixel)
IllegalArgumentException
is thrown if pixel values
for this ColorModel
are not conveniently representable
as a single int. The returned value is a non pre-multiplied
value, for example, if the alpha is premultiplied, this method
divides it out before returning the value. If the alpha value is
0, the blue value is 0.pixel
- the specified pixelpublic abstract int getAlpha(int pixel)
IllegalArgumentException
is thrown if pixel
values for this ColorModel
are not conveniently
representable as a single int.pixel
- the specified pixelpublic int getRGB(int pixel)
IllegalArgumentException
thrown if pixel values
for this ColorModel
are not conveniently representable
as a single int. The returned value is in a non
pre-multiplied format. For example, if the alpha is premultiplied,
this method divides it out of the color components. If the alpha
value is 0, the color values are 0.pixel
- the specified pixelgetRGBdefault()
public boolean equals(Object obj)
Object
is an instance of
ColorModel
and if it equals this
ColorModel
.equals
in class Object
obj
- the Object
to test for equalitytrue
if the specified Object
is an instance of ColorModel
and equals this
ColorModel
; false
otherwise.Object.hashCode()
,
HashMap
public int hashCode()
hashCode
in class Object
Object.equals(java.lang.Object)
,
System.identityHashCode(java.lang.Object)
public final java.awt.color.ColorSpace getColorSpace()
ColorSpace
associated with this
ColorModel
.ColorSpace
of this
ColorModel
.public void finalize()
ColorModel
once this ColorModel
is no
longer referenced.finalize
in class Object
WeakReference
,
PhantomReference