java.awt.image.ColorModel Maven / Gradle / Ivy

Neither this file nor any files generated from it describe a complete specification, and they may only be used as described below. For example, no permission is given for you to incorporate this file, in whole or in part, in an implementation of a Java specification.

Sun Microsystems Inc. owns the copyright in this file and it is provided to you for informative, as opposed to normative, use. The file and any files generated from it may be used to generate other informative documentation, such as a unified set of documents of API signatures for a platform that includes technologies expressed as Java APIs. The file may also be used to produce "compilation stubs," which allow applications to be compiled and validated for such platforms.

Any work generated from this file, such as unified javadocs or compiled stub files, must be accompanied by this notice in its entirety.

This work corresponds to the API signatures of JSR 217: Personal Basis Profile 1.1. In the event of a discrepency between this work and the JSR 217 specification, which is available at http://www.jcp.org/en/jsr/detail?id=217, the latter takes precedence. */ package java.awt.image; import java.awt.Transparency; import java.awt.color.ColorSpace; // import java.awt.color.ICC_ColorSpace; // import sun.awt.color.ICC_Transform; // import sun.awt.color.CMM; import java.awt.Toolkit; import java.util.Collections; import java.util.Map; import java.util.WeakHashMap; // PBP/PP /** * 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. *

*

* 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 * 0.0 and 1.0. * 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 * 2ⁿ - 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 2ⁿ - 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 {@link IllegalArgumentException} when methods involving * an unnormalized argument are called. Subclasses of ColorModel * must specify the conditions under which this occurs. * * @see IndexColorModel * @see DirectColorModel * @see java.awt.Image * @see BufferedImage * @see java.awt.color.ColorSpace * @see DataBuffer * @version 10 Feb 1997 */ public abstract class ColorModel implements Transparency { /** * The total number of bits in the pixel. */ protected int pixel_bits; // /** // * Data type of the array used to represent pixel values. // */ // protected int transferType; /** * Constructs a 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. * @param bits the number of bits of a pixel * @throws IllegalArgumentException if the number * of bits in bits is less than 1 */ public ColorModel(int bits) { } /** * Constructs a 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. * @param pixel_bits the number of bits in the pixel values * @param bits array that specifies the number of significant bits * per color and alpha component * @param cspace the specified ColorSpace * @param hasAlpha true if alpha information is present; * false otherwise * @param isAlphaPremultiplied true if color samples are * assumed to be premultiplied by the alpha samples; * false otherwise * @param transparency what alpha values can be represented by this * color model * @param transferType the type of the array used to represent pixel * values * @throws IllegalArgumentException 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. * @throws 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. * @see java.awt.Transparency */ protected ColorModel(int pixel_bits, int[] bits, ColorSpace cspace, boolean hasAlpha, boolean isAlphaPremultiplied, int transparency, int transferType) { } /** * 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. * The color space is the default {@link 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. * @return a DirectColorModelobject describing default * RGB values. */ public static ColorModel getRGBdefault() { return null;} /** * Returns whether or not alpha is supported in this * ColorModel. * @return true if alpha is supported in this * ColorModel; false otherwise. */ public final boolean hasAlpha() { return false;} /** * Returns whether or not the alpha has been premultiplied in the * pixel values to be translated by this 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. * @return true if the alpha values are premultiplied * in the pixel values to be translated by this * ColorModel; false otherwise. */ public final boolean isAlphaPremultiplied() {return false; } /** * Returns the transfer type of this ColorModel. * The transfer type is the type of primitive array used to represent * pixel values as arrays. * @return the transfer type. */ public final int getTransferType() { return 0;} /** * Returns the number of bits per pixel described by this * ColorModel. * @return the number of bits per pixel. */ public int getPixelSize() { return 0; } /** * Returns the number of bits for the specified color/alpha component. * Color components are indexed in the order 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. If this ColorModel supports alpha, the alpha * component corresponds to the index following the last color * component. * @param componentIdx the index of the color/alpha component * @return the number of bits for the color/alpha component at the * specified index. * @throws ArrayIndexOutOfBoundsException if componentIdx * is greater than the number of components or * less than zero * @throws NullPointerException if the number of bits array is * null */ public int getComponentSize(int componentIdx) {return 0; } /** * Returns an array of the number of bits per color/alpha component. * The array contains the color components in the order specified by the * ColorSpace, followed by the alpha component, if * present. * @return an array of the number of bits per color/alpha component */ public int[] getComponentSize() {return null; } /** * Returns the transparency. Returns either OPAQUE, BITMASK, * or TRANSLUCENT. * @return the transparency of this ColorModel. * @see Transparency#OPAQUE * @see Transparency#BITMASK * @see Transparency#TRANSLUCENT */ public int getTransparency() { return 0;} /** * Returns the number of components, including alpha, in this * ColorModel. This is equal to the number of color * components, optionally plus one, if there is an alpha component. * @return the number of components in this ColorModel */ public int getNumComponents() { return 0;} /** * Returns the number of color components in this * ColorModel. * This is the number of components returned by * {@link ColorSpace#getNumComponents}. * @return the number of color components in this * ColorModel. * @see ColorSpace#getNumComponents */ public int getNumColorComponents() { return 0; } /** * Returns the red color component for the specified pixel, scaled * from 0 to 255 in the default RGB ColorSpace, sRGB. A color conversion * is done if necessary. The pixel value is specified as an int. * An 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. * @param pixel a specified pixel * @return the value of the red component of the specified pixel. */ public abstract int getRed(int pixel); /** * Returns the green color component for the specified pixel, scaled * from 0 to 255 in the default RGB ColorSpace, sRGB. A color conversion * is done if necessary. The pixel value is specified as an int. * An 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. * @param pixel the specified pixel * @return the value of the green component of the specified pixel. */ public abstract int getGreen(int pixel); /** * Returns the blue color component for the specified pixel, scaled * from 0 to 255 in the default RGB ColorSpace, sRGB. A color conversion * is done if necessary. The pixel value is specified as an int. * An 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. * @param pixel the specified pixel * @return the value of the blue component of the specified pixel. */ public abstract int getBlue(int pixel); /** * Returns the alpha component for the specified pixel, scaled * from 0 to 255. The pixel value is specified as an int. * An IllegalArgumentException is thrown if pixel * values for this ColorModel are not conveniently * representable as a single int. * @param pixel the specified pixel * @return the value of alpha component of the specified pixel. */ public abstract int getAlpha(int pixel); /** * Returns the color/alpha components of the pixel in the default * RGB color model format. A color conversion is done if necessary. * The pixel value is specified as an int. * An 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. * @param pixel the specified pixel * @return the RGB value of the color/alpha components of the * specified pixel. * @see ColorModel#getRGBdefault */ public int getRGB(int pixel) { return 0;} /** * Returns the red color component for the specified pixel, scaled * from 0 to 255 in the default RGB ColorSpace, sRGB. A * color conversion is done if necessary. The pixel value is * specified by an array of data elements of type transferType passed * in as an object reference. The returned value is a non * pre-multiplied value. For example, if alpha is premultiplied, * this method divides it out before returning * the value. If the alpha value is 0, the red value is 0. * If inData is not a primitive array of type * transferType, a ClassCastException is thrown. An * ArrayIndexOutOfBoundsException is thrown if * inData is not large enough to hold a pixel value for * this ColorModel. * If this transferType is not supported, a * UnsupportedOperationException will be * thrown. Since * ColorModel is an abstract class, any instance * must be an instance of a subclass. Subclasses inherit the * implementation of this method and if they don't override it, this * method throws an exception if the subclass uses a * transferType other than * DataBuffer.TYPE_BYTE, * DataBuffer.TYPE_USHORT, or * DataBuffer.TYPE_INT. * @param inData an array of pixel values * @return the value of the red component of the specified pixel. * @throws ClassCastException if inData * is not a primitive array of type transferType * @throws ArrayIndexOutOfBoundsException if * inData is not large enough to hold a pixel value * for this ColorModel * @throws UnsupportedOperationException if this * tranferType is not supported by this * ColorModel */ // public int getRed(Object inData) { return 0;} /** * Returns the green color component for the specified pixel, scaled * from 0 to 255 in the default RGB ColorSpace, sRGB. A * color conversion is done if necessary. The pixel value is * specified by an array of data elements of type transferType passed * in as an object reference. The returned value will be 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. If inData is * not a primitive array of type transferType, a * ClassCastException is thrown. An * ArrayIndexOutOfBoundsException is thrown if * inData is not large enough to hold a pixel value for * this ColorModel. * If this transferType is not supported, a * UnsupportedOperationException will be * thrown. Since * ColorModel is an abstract class, any instance * must be an instance of a subclass. Subclasses inherit the * implementation of this method and if they don't override it, this * method throws an exception if the subclass uses a * transferType other than * DataBuffer.TYPE_BYTE, * DataBuffer.TYPE_USHORT, or * DataBuffer.TYPE_INT. * @param inData an array of pixel values * @return the value of the green component of the specified pixel. * @throws ClassCastException if inData * is not a primitive array of type transferType * @throws ArrayIndexOutOfBoundsException if * inData is not large enough to hold a pixel value * for this ColorModel * @throws UnsupportedOperationException if this * tranferType is not supported by this * ColorModel */ // public int getGreen(Object inData) { return 0; } /** * Returns the blue color component for the specified pixel, scaled * from 0 to 255 in the default RGB ColorSpace, sRGB. A * color conversion is done if necessary. The pixel value is * specified by an array of data elements of type transferType passed * in as an object reference. 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 will be 0. If * inData is not a primitive array of type transferType, * a ClassCastException is thrown. An * ArrayIndexOutOfBoundsException is * thrown if inData is not large enough to hold a pixel * value for this ColorModel. * If this transferType is not supported, a * UnsupportedOperationException will be * thrown. Since * ColorModel is an abstract class, any instance * must be an instance of a subclass. Subclasses inherit the * implementation of this method and if they don't override it, this * method throws an exception if the subclass uses a * transferType other than * DataBuffer.TYPE_BYTE, * DataBuffer.TYPE_USHORT, or * DataBuffer.TYPE_INT. * @param inData an array of pixel values * @return the value of the blue component of the specified pixel. * @throws ClassCastException if inData * is not a primitive array of type transferType * @throws ArrayIndexOutOfBoundsException if * inData is not large enough to hold a pixel value * for this ColorModel * @throws UnsupportedOperationException if this * tranferType is not supported by this * ColorModel */ // public int getBlue(Object inData) { return 0; } /** * Returns the alpha component for the specified pixel, scaled * from 0 to 255. The pixel value is specified by an array of data * elements of type transferType passed in as an object reference. * If inData is not a primitive array of type transferType, a * ClassCastException is thrown. An * ArrayIndexOutOfBoundsException is thrown if * inData is not large enough to hold a pixel value for * this ColorModel. * If this transferType is not supported, a * UnsupportedOperationException will be * thrown. Since * ColorModel is an abstract class, any instance * must be an instance of a subclass. Subclasses inherit the * implementation of this method and if they don't override it, this * method throws an exception if the subclass uses a * transferType other than * DataBuffer.TYPE_BYTE, * DataBuffer.TYPE_USHORT, or * DataBuffer.TYPE_INT. * @param inData the specified pixel * @return the alpha component of the specified pixel, scaled from * 0 to 255. * @throws ClassCastException if inData * is not a primitive array of type transferType * @throws ArrayIndexOutOfBoundsException if * inData is not large enough to hold a pixel value * for this ColorModel * @throws UnsupportedOperationException if this * tranferType is not supported by this * ColorModel */ // public int getAlpha(Object inData) { return 0; } /** * Returns the color/alpha components for the specified pixel in the * default RGB color model format. A color conversion is done if * necessary. The pixel value is specified by an array of data * elements of type transferType passed in as an object reference. * If inData is not a primitive array of type transferType, a * ClassCastException is thrown. An * ArrayIndexOutOfBoundsException is * thrown if inData is not large enough to hold a pixel * value for this ColorModel. * The returned value will be in a non pre-multiplied format, i.e. if * the alpha is premultiplied, this method will divide it out of the * color components (if the alpha value is 0, the color values will be 0). * @param inData the specified pixel * @return the color and alpha components of the specified pixel. * @see ColorModel#getRGBdefault */ // public int getRGB(Object inData) { return 0; } // /** // * Returns a data element array representation of a pixel in this // * ColorModel, given an integer pixel representation in // * the default RGB color model. // * This array can then be passed to the // * {@link WritableRaster#setDataElements} method of // * a {@link WritableRaster} object. If the pixel variable is // * null, a new array will be allocated. If // * pixel is not // * null, it must be a primitive array of type // * transferType; otherwise, a // * ClassCastException is thrown. An // * ArrayIndexOutOfBoundsException is thrown if // * pixel is // * not large enough to hold a pixel value for this // * ColorModel. The pixel array is returned. // * If this transferType is not supported, a // * UnsupportedOperationException will be // * thrown. Since ColorModel is an abstract class, // * any instance is an instance of a subclass. Subclasses must // * override this method since the implementation in this abstract // * class throws an UnsupportedOperationException. // * @param rgb the integer pixel representation in the default RGB // * color model // * @param pixel the specified pixel // * @return an array representation of the specified pixel in this // * ColorModel. // * @throws ClassCastException if pixel // * is not a primitive array of type transferType // * @throws ArrayIndexOutOfBoundsException if // * pixel is not large enough to hold a pixel value // * for this ColorModel // * @throws UnsupportedOperationException if this // * method is not supported by this ColorModel // * @see WritableRaster#setDataElements // * @see SampleModel#setDataElements // */ // public Object getDataElements(int rgb, Object pixel) { } // /** // * Returns an array of unnormalized color/alpha components given a pixel // * in this ColorModel. The pixel value is specified as // * an int. An IllegalArgumentException // * will be thrown if pixel values for this ColorModel are // * not conveniently representable as a single int or if // * color component values for this ColorModel are not // * conveniently representable in the unnormalized form. // * For example, this method can be used to retrieve the // * components for a specific pixel value in a // * DirectColorModel. If the components array is // * null, a new array will be allocated. The // * components array will be returned. Color/alpha components are // * stored in the components array starting at offset // * (even if the array is allocated by this method). An // * ArrayIndexOutOfBoundsException is thrown if the // * components array is not null and is not large // * enough to hold all the color and alpha components (starting at offset). // * Since ColorModel is an abstract class, // * any instance is an instance of a subclass. Subclasses must // * override this method since the implementation in this abstract // * class throws an UnsupportedOperationException. // * @param pixel the specified pixel // * @param components the array to receive the color and alpha // * components of the specified pixel // * @param offset the offset into the components array at // * which to start storing the color and alpha components // * @return an array containing the color and alpha components of the // * specified pixel starting at the specified offset. // * @throws UnsupportedOperationException if this // * method is not supported by this ColorModel // */ // public int[] getComponents(int pixel, int[] components, int offset) { } // /** // * Returns an array of unnormalized color/alpha components given a pixel // * in this ColorModel. The pixel value is specified by // * an array of data elements of type transferType passed in as an // * object reference. If pixel is not a primitive array // * of type transferType, a ClassCastException is thrown. // * An IllegalArgumentException will be thrown if color // * component values for this ColorModel are not // * conveniently representable in the unnormalized form. // * An ArrayIndexOutOfBoundsException is // * thrown if pixel is not large enough to hold a pixel // * value for this ColorModel. // * This method can be used to retrieve the components for a specific // * pixel value in any ColorModel. If the components // * array is null, a new array will be allocated. The // * components array will be returned. Color/alpha components are // * stored in the components array starting at // * offset (even if the array is allocated by this // * method). An ArrayIndexOutOfBoundsException // * is thrown if the components array is not null and is // * not large enough to hold all the color and alpha components // * (starting at offset). // * Since ColorModel is an abstract class, // * any instance is an instance of a subclass. Subclasses must // * override this method since the implementation in this abstract // * class throws an UnsupportedOperationException. // * @param pixel the specified pixel // * @param components an array that receives the color and alpha // * components of the specified pixel // * @param offset the index into the components array at // * which to begin storing the color and alpha components of the // * specified pixel // * @return an array containing the color and alpha components of the // * specified pixel starting at the specified offset. // * @throws UnsupportedOperationException if this // * method is not supported by this ColorModel // */ // public int[] getComponents(Object pixel, int[] components, int offset) { } // /** // * Returns an array of all of the color/alpha components in unnormalized // * form, given a normalized component array. Unnormalized components // * are unsigned integral values between 0 and 2ⁿ - 1, where // * n is the number of bits for a particular component. Normalized // * components are float values between a per component minimum and // * maximum specified by the ColorSpace object for this // * ColorModel. An IllegalArgumentException // * will be thrown if color component values for this // * ColorModel are not conveniently representable in the // * unnormalized form. If the // * components array is null, a new array // * will be allocated. The components array will // * be returned. Color/alpha components are stored in the // * components array starting at offset (even // * if the array is allocated by this method). An // * ArrayIndexOutOfBoundsException is thrown if the // * components array is not null and is not // * large enough to hold all the color and alpha // * components (starting at offset). An // * IllegalArgumentException is thrown if the // * normComponents array is not large enough to hold // * all the color and alpha components starting at // * normOffset. // * @param normComponents an array containing normalized components // * @param normOffset the offset into the normComponents // * array at which to start retrieving normalized components // * @param components an array that receives the components from // * normComponents // * @param offset the index into components at which to // * begin storing normalized components from // * normComponents // * @return an array containing unnormalized color and alpha // * components. // * @throws IllegalArgumentException If the component values for this // * ColorModel are not conveniently representable in the // * unnormalized form. // * @throws IllegalArgumentException if the length of // * normComponents minus normOffset // * is less than numComponents // * @throws UnsupportedOperationException if the // * constructor of this ColorModel called the // * super(bits) constructor, but did not // * override this method. See the constructor, // * {@link #ColorModel(int)}. // */ // public int[] getUnnormalizedComponents(float[] normComponents, int // normOffset, int[] components, int offset) // { } // /** // * Returns an array of all of the color/alpha components in normalized // * form, given an unnormalized component array. Unnormalized components // * are unsigned integral values between 0 and 2ⁿ - 1, where // * n is the number of bits for a particular component. Normalized // * components are float values between a per component minimum and // * maximum specified by the ColorSpace object for this // * ColorModel. An IllegalArgumentException // * will be thrown if color component values for this // * ColorModel are not conveniently representable in the // * unnormalized form. If the // * normComponents array is null, a new array // * will be allocated. The normComponents array // * will be returned. Color/alpha components are stored in the // * normComponents array starting at // * normOffset (even if the array is allocated by this // * method). An ArrayIndexOutOfBoundsException is thrown // * if the normComponents array is not null // * and is not large enough to hold all the color and alpha components // * (starting at normOffset). An // * IllegalArgumentException is thrown if the // * components array is not large enough to hold all the // * color and alpha components starting at offset. // *