Top Description Fields Constructors Methods
java.awt.image

public abstract Class ColorModel

extends Object
implements Transparency
Class Inheritance
All Implemented Interfaces
java.awt.Transparency
Known Direct Subclasses
java.awt.image.ComponentColorModel, java.awt.image.IndexColorModel, java.awt.image.PackedColorModel
Imports
java.awt.Transparency, java.awt.color.ColorSpace, .ICC_ColorSpace, .ICC_Profile, java.util.Arrays, .Collections, .Map, .WeakHashMap, sun.java2d.cmm.CMSManager, .ColorTransform, .PCMM

The 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.

See Also
IndexColorModel, ComponentColorModel, PackedColorModel, DirectColorModel, java.awt.Image, BufferedImage, RenderedImage, java.awt.color.ColorSpace, SampleModel, Raster, DataBuffer

Field Summary

Modifier and TypeField and Description
pack-priv ColorSpace
pack-priv int
pack-priv static Map<ICC_ColorSpace, byte[]>
pack-priv static Map<ICC_ColorSpace, byte[]>
pack-priv boolean
pack-priv boolean
pack-priv static byte[]
pack-priv static byte[]
pack-priv static Map<ICC_ColorSpace, short[]>
pack-priv static Map<ICC_ColorSpace, byte[]>
private static boolean
loaded

This is copied from java.awt.Toolkit since we need the library loaded in java.awt.image also:

Warning

This is a temporary workaround for a problem in the way the AWT loads native libraries.

pack-priv int
pack-priv int[]
pack-priv int
pack-priv int
protected int
pixel_bits

The total number of bits in the pixel.

pack-priv static short[]
pack-priv static byte[]
pack-priv boolean
protected int
transferType

Data type of the array used to represent pixel values.

pack-priv int

Constructor Summary

AccessConstructor and Description
public
ColorModel(int
the number of bits of a pixel
bits
)

Constructs a ColorModel that translates pixels of the specified number of bits to color/alpha components.

protected
ColorModel(int
the number of bits in the pixel values
pixel_bits
,
int[]
array that specifies the number of significant bits per color and alpha component
bits
,
ColorSpace
the specified ColorSpace
cspace
,
boolean
true if alpha information is present; false otherwise
hasAlpha
,
boolean
true if color samples are assumed to be premultiplied by the alpha samples; false otherwise
isAlphaPremultiplied
,
int
what alpha values can be represented by this color model
transparency
,
int
the type of the array used to represent pixel values
transferType
)

Constructs a ColorModel that translates pixel values to color/alpha components.

Method Summary

Modifier and TypeMethod and Description
public ColorModel

Returns:

a ColorModel object that represents the coerced data.
coerceData
(WritableRaster
the WritableRaster data
raster
,
boolean
true if the alpha is premultiplied; false otherwise
isAlphaPremultiplied
)

Forces the raster data to match the state specified in the isAlphaPremultiplied variable, assuming the data is currently correctly described by this ColorModel.

public SampleModel

Returns:

a SampleModel object with the specified width and height.
createCompatibleSampleModel
(int
the width to apply to the new SampleModel
w
,
int
the height to apply to the new SampleModel
h
)

Creates a SampleModel with the specified width and height that has a data layout compatible with this ColorModel.

public WritableRaster

Returns:

a WritableRaster object with the specified width and height.
createCompatibleWritableRaster
(int
the width to apply to the new WritableRaster
w
,
int
the height to apply to the new WritableRaster
h
)

Creates a WritableRaster with the specified width and height that has a data layout (SampleModel) compatible with this ColorModel.

public boolean

Returns:

true if this object is the same as the obj argument; false otherwise.
equals
(Object
the reference object with which to compare.
obj
)

Overrides java.lang.Object.equals.

This method simply delegates to the default implementation in Object which is identical to an == test since this class cannot enforce the issues of a proper equality test among multiple independent subclass branches.

public abstract int

Returns:

the value of alpha component of the specified pixel.
getAlpha
(int
the specified pixel
pixel
)

Returns the alpha component for the specified pixel, scaled from 0 to 255.

public int

Returns:

the alpha component of the specified pixel, scaled from 0 to 255.
getAlpha
(Object
the specified pixel
inData
)

Returns the alpha component for the specified pixel, scaled from 0 to 255.

public WritableRaster

Returns:

a Raster representing the alpha channel of an image, obtained from the specified Raster.
getAlphaRaster
(WritableRaster
the specified Raster
raster
)

Returns a Raster representing the alpha channel of an image, extracted from the input Raster, provided that pixel values of this ColorModel represent color and alpha information as separate spatial bands (e.g. ComponentColorModel and DirectColorModel).

public abstract int

Returns:

the value of the blue component of the specified pixel.
getBlue
(int
the specified pixel
pixel
)

Returns the blue color component for the specified pixel, scaled from 0 to 255 in the default RGB ColorSpace, sRGB.

public int

Returns:

the value of the blue component of the specified pixel.
getBlue
(Object
an array of pixel values
inData
)

Returns the blue color component for the specified pixel, scaled from 0 to 255 in the default RGB ColorSpace, sRGB.

public final ColorSpace

Returns:

the ColorSpace of this ColorModel.
getColorSpace
()

Returns the ColorSpace associated with this ColorModel.

public int[]

Returns:

an array containing the color and alpha components of the specified pixel starting at the specified offset.
getComponents
(int
the specified pixel
pixel
,
int[]
the array to receive the color and alpha components of the specified pixel
components
,
int
the offset into the components array at which to start storing the color and alpha components
offset
)

Returns an array of unnormalized color/alpha components given a pixel in this ColorModel.

public int[]

Returns:

an array containing the color and alpha components of the specified pixel starting at the specified offset.
getComponents
(Object
the specified pixel
pixel
,
int[]
an array that receives the color and alpha components of the specified pixel
components
,
int
the index into the components array at which to begin storing the color and alpha components of the specified pixel
offset
)

Returns an array of unnormalized color/alpha components given a pixel in this ColorModel.

public int

Returns:

the number of bits for the color/alpha component at the specified index.
getComponentSize
(int
the index of the color/alpha component
componentIdx
)

Returns the number of bits for the specified color/alpha component.

public int[]

Returns:

an array of the number of bits per color/alpha component
getComponentSize
()

Returns an array of the number of bits per color/alpha component.

public int

Returns:

an int pixel value in this ColorModel corresponding to the specified components.
getDataElement
(int[]
an array of unnormalized color and alpha components
components
,
int
the index into components at which to begin retrieving the color and alpha components
offset
)

Returns a pixel value represented as an int in this ColorModel, given an array of unnormalized color/alpha components.

public int

Returns:

an int pixel value in this ColorModel corresponding to the specified components.
getDataElement
(float[]
an array of normalized color and alpha components
normComponents
,
int
the index into normComponents at which to begin retrieving the color and alpha components
normOffset
)

Returns a pixel value represented as an int in this ColorModel, given an array of normalized color/alpha components.

public Object

Returns:

an array representation of the specified pixel in this ColorModel.
getDataElements
(int
the integer pixel representation in the default RGB color model
rgb
,
Object
the specified pixel
pixel
)

Returns a data element array representation of a pixel in this ColorModel, given an integer pixel representation in the default RGB color model.

public Object

Returns:

an Object representing an array of color and alpha components.
getDataElements
(int[]
an array of unnormalized color and alpha components
components
,
int
the index into components at which to begin retrieving color and alpha components
offset
,
Object
the Object representing an array of color and alpha components
obj
)

Returns a data element array representation of a pixel in this ColorModel, given an array of unnormalized color/alpha components.

public Object

Returns:

an Object which is a primitive data array representation of a pixel
getDataElements
(float[]
an array of normalized color and alpha components
normComponents
,
int
the index into normComponents at which to begin retrieving color and alpha components
normOffset
,
Object
a primitive data array to hold the returned pixel
obj
)

Returns a data element array representation of a pixel in this ColorModel, given an array of normalized color/alpha components.

pack-priv static int
getDefaultTransferType(int pixel_bits)

pack-priv static byte[]
pack-priv static byte[]
public abstract int

Returns:

the value of the green component of the specified pixel.
getGreen
(int
the specified pixel
pixel
)

Returns the green color component for the specified pixel, scaled from 0 to 255 in the default RGB ColorSpace, sRGB.

public int

Returns:

the value of the green component of the specified pixel.
getGreen
(Object
an array of pixel values
inData
)

Returns the green color component for the specified pixel, scaled from 0 to 255 in the default RGB ColorSpace, sRGB.

pack-priv static short[]
pack-priv static byte[]
pack-priv static byte[]
pack-priv static byte[]
public float[]

Returns:

an array containing normalized color and alpha components.
getNormalizedComponents
(int[]
an array containing unnormalized components
components
,
int
the offset into the components array at which to start retrieving unnormalized components
offset
,
float[]
an array that receives the normalized components
normComponents
,
int
the index into normComponents at which to begin storing normalized components
normOffset
)

Returns an array of all of the color/alpha components in normalized form, given an unnormalized component array.

public float[]

Returns:

an array containing normalized color and alpha components.
getNormalizedComponents
(Object
the specified pixel
pixel
,
float[]
an array to receive the normalized components
normComponents
,
int
the offset into the normComponents array at which to start storing normalized components
normOffset
)

Returns an array of all of the color/alpha components in normalized form, given a pixel in this ColorModel.

public int

Returns:

the number of color components in this ColorModel.
getNumColorComponents
()

Returns the number of color components in this ColorModel.

public int

Returns:

the number of components in this ColorModel
getNumComponents
()

Returns the number of components, including alpha, in this ColorModel.

public int

Returns:

the number of bits per pixel.
getPixelSize
()

Returns the number of bits per pixel described by this ColorModel.

public abstract int

Returns:

the value of the red component of the specified pixel.
getRed
(int
a specified pixel
pixel
)

Returns the red color component for the specified pixel, scaled from 0 to 255 in the default RGB ColorSpace, sRGB.

public int

Returns:

the value of the red component of the specified pixel.
getRed
(Object
an array of pixel values
inData
)

Returns the red color component for the specified pixel, scaled from 0 to 255 in the default RGB ColorSpace, sRGB.

public int

Returns:

the RGB value of the color/alpha components of the specified pixel.
getRGB
(int
the specified pixel
pixel
)

Returns the color/alpha components of the pixel in the default RGB color model format.

public int

Returns:

the color and alpha components of the specified pixel.
getRGB
(Object
the specified pixel
inData
)

Returns the color/alpha components for the specified pixel in the default RGB color model format.

public static ColorModel

Returns:

a DirectColorModel object describing default RGB values.
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.

pack-priv static short[]
pack-priv static byte[]
public final int

Returns:

the transfer type.
getTransferType
()

Returns the transfer type of this ColorModel.

public int

Returns:

the transparency of this ColorModel.
getTransparency
()

Implements java.awt.Transparency.getTransparency.

Returns the transparency.

public int[]

Returns:

an array containing unnormalized color and alpha components.
getUnnormalizedComponents
(float[]
an array containing normalized components
normComponents
,
int
the offset into the normComponents array at which to start retrieving normalized components
normOffset
,
int[]
an array that receives the components from normComponents
components
,
int
the index into components at which to begin storing normalized components from normComponents
offset
)

Returns an array of all of the color/alpha components in unnormalized form, given a normalized component array.

public final boolean

Returns:

true if alpha is supported in this ColorModel; false otherwise.
hasAlpha
()

Returns whether or not alpha is supported in this ColorModel.

public int

Returns:

a hash code value for this object.
hashCode
()

Overrides java.lang.Object.hashCode.

This method simply delegates to the default implementation in Object which returns the system ID for the class.

private static native void
public final boolean

Returns:

true if the alpha values are premultiplied in the pixel values to be translated by this ColorModel; false otherwise.
isAlphaPremultiplied
()

Returns whether or not the alpha has been premultiplied in the pixel values to be translated by this ColorModel.

public boolean

Returns:

true if raster is compatible with this ColorModel.
isCompatibleRaster
(Raster
the Raster object to test for compatibility
raster
)

Returns true if raster is compatible with this ColorModel and false if it is not.

public boolean

Returns:

true if the specified SampleModel is compatible with this ColorModel; false otherwise.
isCompatibleSampleModel
(SampleModel
the specified SampleModel
sm
)

Checks if the SampleModel is compatible with this ColorModel.

pack-priv static boolean
pack-priv static boolean
pack-priv static void
public String

Returns:

a String representing the contents of this ColorModel object.
toString
()

Overrides java.lang.Object.toString.

Returns the String representation of the contents of this ColorModel object.

Inherited from java.lang.Object:
clonefinalizegetClassnotifynotifyAllwaitwaitwait