stan/jdk-24
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

8212790: Javadoc cleanup of java.awt.color package

Browse Source 
Reviewed-by: prr, kaddepalli
This commit is contained in:
Sergey Bylokhov 2018-10-29 17:34:05 -07:00
parent 7f642e200b
commit b6be5030eb
7 changed files with 844 additions and 935 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

25
src/java.desktop/share/classes/java/awt/color/CMMException.java
View File

@ -1,4 +1,5 @@
/* /*
* Copyright (c) 1997, 2018, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
* *
* This code is free software; you can redistribute it and/or modify it * This code is free software; you can redistribute it and/or modify it
@ -22,13 +23,7 @@
* questions. * questions.
*/ */
/* /* ********************************************************************
Created by gbp, October 25, 1997
*
*/
/*
**********************************************************************
********************************************************************** **********************************************************************
********************************************************************** **********************************************************************
*** COPYRIGHT (c) Eastman Kodak Company, 1997 *** *** COPYRIGHT (c) Eastman Kodak Company, 1997 ***
@ -38,22 +33,24 @@
********************************************************************** **********************************************************************
**********************************************************************/ **********************************************************************/
package java.awt.color; package java.awt.color;
/** /**
* This exception is thrown if the native CMM returns an error. * This exception is thrown if the native CMM returns an error.
*/ */
public class CMMException extends java.lang.RuntimeException { public class CMMException extends java.lang.RuntimeException {
/**
* Use serialVersionUID from JDK 1.2 for interoperability.
*/
private static final long serialVersionUID = 5775558044142994965L; private static final long serialVersionUID = 5775558044142994965L;
/** /**
* Constructs a CMMException with the specified detail message. * Constructs a {@code CMMException} with the specified detail message.
* @param s the specified detail message *
* @param s the specified detail message
*/ */
public CMMException (String s) { public CMMException(String s) {
super (s); super(s);
} }
} }

322
src/java.desktop/share/classes/java/awt/color/ColorSpace.java
View File

@ -1,5 +1,5 @@
/* /*
* Copyright (c) 1997, 2014, Oracle and/or its affiliates. All rights reserved. * Copyright (c) 1997, 2018, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
* *
* This code is free software; you can redistribute it and/or modify it * This code is free software; you can redistribute it and/or modify it
@ -23,8 +23,7 @@
* questions. * questions.
*/ */
/* /* ********************************************************************
**********************************************************************
********************************************************************** **********************************************************************
********************************************************************** **********************************************************************
*** COPYRIGHT (c) Eastman Kodak Company, 1997 *** *** COPYRIGHT (c) Eastman Kodak Company, 1997 ***
@ -38,63 +37,60 @@ package java.awt.color;
import java.lang.annotation.Native; import java.lang.annotation.Native;
import sun.java2d.cmm.PCMM;
import sun.java2d.cmm.CMSManager; import sun.java2d.cmm.CMSManager;
/** /**
* This abstract class is used to serve as a color space tag to identify the * This abstract class is used to serve as a color space tag to identify the
* specific color space of a Color object or, via a ColorModel object, * specific color space of a {@code Color} object or, via a {@code ColorModel}
* of an Image, a BufferedImage, or a GraphicsDevice. It contains * object, of an {@code Image}, a {@code BufferedImage}, or a
* methods that transform colors in a specific color space to/from sRGB * {@code GraphicsDevice}. It contains methods that transform colors in a
* and to/from a well-defined CIEXYZ color space. * specific color space to/from sRGB and to/from a well-defined CIEXYZ color
* space.
* <p> * <p>
* For purposes of the methods in this class, colors are represented as * For purposes of the methods in this class, colors are represented as arrays
* arrays of color components represented as floats in a normalized range * of color components represented as floats in a normalized range defined by
* defined by each ColorSpace. For many ColorSpaces (e.g. sRGB), this * each {@code ColorSpace}. For many {@code ColorSpaces} (e.g. sRGB), this range
* range is 0.0 to 1.0. However, some ColorSpaces have components whose * is 0.0 to 1.0. However, some {@code ColorSpaces} have components whose values
* values have a different range. Methods are provided to inquire per * have a different range. Methods are provided to inquire per component minimum
* component minimum and maximum normalized values. * and maximum normalized values.
* <p> * <p>
* Several variables are defined for purposes of referring to color * Several variables are defined for purposes of referring to color space types
* space types (e.g. TYPE_RGB, TYPE_XYZ, etc.) and to refer to specific * (e.g. {@code TYPE_RGB}, {@code TYPE_XYZ}, etc.) and to refer to specific
* color spaces (e.g. CS_sRGB and CS_CIEXYZ). * color spaces (e.g. {@code CS_sRGB} and {@code CS_CIEXYZ}). sRGB is a proposed
* sRGB is a proposed standard RGB color space. For more information, * standard RGB color space. For more information, see
* see <A href="http://www.w3.org/pub/WWW/Graphics/Color/sRGB.html"> * <a href="http://www.w3.org/pub/WWW/Graphics/Color/sRGB.html">
* http://www.w3.org/pub/WWW/Graphics/Color/sRGB.html * http://www.w3.org/pub/WWW/Graphics/Color/sRGB.html</a>.
* </A>.
* <p> * <p>
* The purpose of the methods to transform to/from the well-defined * The purpose of the methods to transform to/from the well-defined CIEXYZ color
* CIEXYZ color space is to support conversions between any two color * space is to support conversions between any two color spaces at a reasonably
* spaces at a reasonably high degree of accuracy. It is expected that * high degree of accuracy. It is expected that particular implementations of
* particular implementations of subclasses of ColorSpace (e.g. * subclasses of {@code ColorSpace} (e.g. {@code ICC_ColorSpace}) will support
* ICC_ColorSpace) will support high performance conversion based on * high performance conversion based on underlying platform color management
* underlying platform color management systems. * systems.
* <p> * <p>
* The CS_CIEXYZ space used by the toCIEXYZ/fromCIEXYZ methods can be * The {@code CS_CIEXYZ} space used by the {@code toCIEXYZ/fromCIEXYZ} methods
* described as follows: * can be described as follows:
<pre> * <pre>
*
&nbsp; CIEXYZ * &nbsp; CIEXYZ
&nbsp; viewing illuminance: 200 lux * &nbsp; viewing illuminance: 200 lux
&nbsp; viewing white point: CIE D50 * &nbsp; viewing white point: CIE D50
&nbsp; media white point: "that of a perfectly reflecting diffuser" -- D50 * &nbsp; media white point: "that of a perfectly reflecting diffuser" -- D50
&nbsp; media black point: 0 lux or 0 Reflectance * &nbsp; media black point: 0 lux or 0 Reflectance
&nbsp; flare: 1 percent * &nbsp; flare: 1 percent
&nbsp; surround: 20percent of the media white point * &nbsp; surround: 20percent of the media white point
&nbsp; media description: reflection print (i.e., RLAB, Hunt viewing media) * &nbsp; media description: reflection print (i.e., RLAB, Hunt viewing media)
&nbsp; note: For developers creating an ICC profile for this conversion * &nbsp; note: For developers creating an ICC profile for this conversion
&nbsp; space, the following is applicable. Use a simple Von Kries * &nbsp; space, the following is applicable. Use a simple Von Kries
&nbsp; white point adaptation folded into the 3X3 matrix parameters * &nbsp; white point adaptation folded into the 3X3 matrix parameters
&nbsp; and fold the flare and surround effects into the three * &nbsp; and fold the flare and surround effects into the three
&nbsp; one-dimensional lookup tables (assuming one uses the minimal * &nbsp; one-dimensional lookup tables (assuming one uses the minimal
&nbsp; model for monitors). * &nbsp; model for monitors).
*
</pre> * </pre>
* *
* @see ICC_ColorSpace * @see ICC_ColorSpace
*/ */
public abstract class ColorSpace implements java.io.Serializable { public abstract class ColorSpace implements java.io.Serializable {
static final long serialVersionUID = -409452704308689724L; static final long serialVersionUID = -409452704308689724L;
@ -237,15 +233,14 @@ public abstract class ColorSpace implements java.io.Serializable {
/** /**
* The sRGB color space defined at * The sRGB color space defined at
* <A href="http://www.w3.org/pub/WWW/Graphics/Color/sRGB.html"> * <a href="http://www.w3.org/pub/WWW/Graphics/Color/sRGB.html">
* http://www.w3.org/pub/WWW/Graphics/Color/sRGB.html * http://www.w3.org/pub/WWW/Graphics/Color/sRGB.html</a>.
* </A>.
*/ */
@Native public static final int CS_sRGB = 1000; @Native public static final int CS_sRGB = 1000;
/** /**
* A built-in linear RGB color space. This space is based on the * A built-in linear RGB color space. This space is based on the same RGB
* same RGB primaries as CS_sRGB, but has a linear tone reproduction curve. * primaries as {@code CS_sRGB}, but has a linear tone reproduction curve.
*/ */
@Native public static final int CS_LINEAR_RGB = 1004; @Native public static final int CS_LINEAR_RGB = 1004;
@ -264,25 +259,26 @@ public abstract class ColorSpace implements java.io.Serializable {
*/ */
@Native public static final int CS_GRAY = 1003; @Native public static final int CS_GRAY = 1003;
/** /**
* Constructs a ColorSpace object given a color space type * Constructs a {@code ColorSpace} object given a color space type and the
* and the number of components. * number of components.
* @param type one of the {@code ColorSpace} type constants *
* @param numcomponents the number of components in the color space * @param type one of the {@code ColorSpace} type constants
* @param numcomponents the number of components in the color space
*/ */
protected ColorSpace (int type, int numcomponents) { protected ColorSpace(int type, int numcomponents) {
this.type = type; this.type = type;
this.numComponents = numcomponents; this.numComponents = numcomponents;
} }
/** /**
* Returns a ColorSpace representing one of the specific * Returns a {@code ColorSpace} representing one of the specific predefined
* predefined color spaces. * color spaces.
* @param colorspace a specific color space identified by one of *
* the predefined class constants (e.g. CS_sRGB, CS_LINEAR_RGB, * @param colorspace a specific color space identified by one of the
* CS_CIEXYZ, CS_GRAY, or CS_PYCC) * predefined class constants (e.g. {@code CS_sRGB},
* {@code CS_LINEAR_RGB}, {@code CS_CIEXYZ}, {@code CS_GRAY}, or
* {@code CS_PYCC})
* @return the requested {@code ColorSpace} object * @return the requested {@code ColorSpace} object
*/ */
// NOTE: This method may be called by privileged threads. // NOTE: This method may be called by privileged threads.
@ -363,11 +359,11 @@ public abstract class ColorSpace implements java.io.Serializable {
return theColorSpace; return theColorSpace;
} }
/** /**
* Returns true if the ColorSpace is CS_sRGB. * Returns true if the {@code ColorSpace} is {@code CS_sRGB}.
* @return {@code true} if this is a {@code CS_sRGB} color *
* space, {@code false} if it is not * @return {@code true} if this is a {@code CS_sRGB} color space,
* {@code false} if it is not
*/ */
public boolean isCS_sRGB () { public boolean isCS_sRGB () {
/* REMIND - make sure we know sRGBspace exists already */ /* REMIND - make sure we know sRGBspace exists already */
@ -375,115 +371,105 @@ public abstract class ColorSpace implements java.io.Serializable {
} }
/** /**
* Transforms a color value assumed to be in this ColorSpace * Transforms a color value assumed to be in this {@code ColorSpace} into a
* into a value in the default CS_sRGB color space. * value in the default {@code CS_sRGB} color space.
* <p> * <p>
* This method transforms color values using algorithms designed * This method transforms color values using algorithms designed to produce
* to produce the best perceptual match between input and output * the best perceptual match between input and output colors. In order to do
* colors. In order to do colorimetric conversion of color values, * colorimetric conversion of color values, you should use the
* you should use the {@code toCIEXYZ} * {@code toCIEXYZ} method of this color space to first convert from the
* method of this color space to first convert from the input * input color space to the CS_CIEXYZ color space, and then use the
* color space to the CS_CIEXYZ color space, and then use the * {@code fromCIEXYZ} method of the {@code CS_sRGB} color space to convert
* {@code fromCIEXYZ} method of the CS_sRGB color space to * from {@code CS_CIEXYZ} to the output color space. See
* convert from CS_CIEXYZ to the output color space. * {@link #toCIEXYZ(float[]) toCIEXYZ} and
* See {@link #toCIEXYZ(float[]) toCIEXYZ} and
* {@link #fromCIEXYZ(float[]) fromCIEXYZ} for further information. * {@link #fromCIEXYZ(float[]) fromCIEXYZ} for further information.
* *
* @param colorvalue a float array with length of at least the number * @param colorvalue a float array with length of at least the number of
* of components in this ColorSpace * components in this {@code ColorSpace}
* @return a float array of length 3 * @return a float array of length 3
* @throws ArrayIndexOutOfBoundsException if array length is not * @throws ArrayIndexOutOfBoundsException if array length is not at least
* at least the number of components in this ColorSpace * the number of components in this {@code ColorSpace}
*/ */
public abstract float[] toRGB(float[] colorvalue); public abstract float[] toRGB(float[] colorvalue);
/** /**
* Transforms a color value assumed to be in the default CS_sRGB * Transforms a color value assumed to be in the default {@code CS_sRGB}
* color space into this ColorSpace. * color space into this {@code ColorSpace}.
* <p> * <p>
* This method transforms color values using algorithms designed * This method transforms color values using algorithms designed to produce
* to produce the best perceptual match between input and output * the best perceptual match between input and output colors. In order to do
* colors. In order to do colorimetric conversion of color values, * colorimetric conversion of color values, you should use the
* you should use the {@code toCIEXYZ} * {@code toCIEXYZ} method of the {@code CS_sRGB} color space to first
* method of the CS_sRGB color space to first convert from the input * convert from the input color space to the {@code CS_CIEXYZ} color space,
* color space to the CS_CIEXYZ color space, and then use the * and then use the {@code fromCIEXYZ} method of this color space to convert
* {@code fromCIEXYZ} method of this color space to * from {@code CS_CIEXYZ} to the output color space. See
* convert from CS_CIEXYZ to the output color space. * {@link #toCIEXYZ(float[]) toCIEXYZ} and
* See {@link #toCIEXYZ(float[]) toCIEXYZ} and
* {@link #fromCIEXYZ(float[]) fromCIEXYZ} for further information. * {@link #fromCIEXYZ(float[]) fromCIEXYZ} for further information.
* *
* @param rgbvalue a float array with length of at least 3 * @param rgbvalue a float array with length of at least 3
* @return a float array with length equal to the number of * @return a float array with length equal to the number of components in
* components in this ColorSpace * this {@code ColorSpace}
* @throws ArrayIndexOutOfBoundsException if array length is not * @throws ArrayIndexOutOfBoundsException if array length is not at least 3
* at least 3
*/ */
public abstract float[] fromRGB(float[] rgbvalue); public abstract float[] fromRGB(float[] rgbvalue);
/** /**
* Transforms a color value assumed to be in this ColorSpace * Transforms a color value assumed to be in this {@code ColorSpace} into
* into the CS_CIEXYZ conversion color space. * the {@code CS_CIEXYZ} conversion color space.
* <p> * <p>
* This method transforms color values using relative colorimetry, * This method transforms color values using relative colorimetry, as
* as defined by the International Color Consortium standard. This * defined by the International Color Consortium standard. This means that
* means that the XYZ values returned by this method are represented * the XYZ values returned by this method are represented relative to the
* relative to the D50 white point of the CS_CIEXYZ color space. * D50 white point of the {@code CS_CIEXYZ} color space. This representation
* This representation is useful in a two-step color conversion * is useful in a two-step color conversion process in which colors are
* process in which colors are transformed from an input color * transformed from an input color space to {@code CS_CIEXYZ} and then to an
* space to CS_CIEXYZ and then to an output color space. This * output color space. This representation is not the same as the XYZ values
* representation is not the same as the XYZ values that would * that would be measured from the given color value by a colorimeter. A
* be measured from the given color value by a colorimeter. * further transformation is necessary to compute the XYZ values that would
* A further transformation is necessary to compute the XYZ values * be measured using current CIE recommended practices. See the
* that would be measured using current CIE recommended practices. * {@link ICC_ColorSpace#toCIEXYZ(float[]) toCIEXYZ} method of
* See the {@link ICC_ColorSpace#toCIEXYZ(float[]) toCIEXYZ} method of
* {@code ICC_ColorSpace} for further information. * {@code ICC_ColorSpace} for further information.
* *
* @param colorvalue a float array with length of at least the number * @param colorvalue a float array with length of at least the number of
* of components in this ColorSpace * components in this {@code ColorSpace}
* @return a float array of length 3 * @return a float array of length 3
* @throws ArrayIndexOutOfBoundsException if array length is not * @throws ArrayIndexOutOfBoundsException if array length is not at least
* at least the number of components in this ColorSpace. * the number of components in this {@code ColorSpace}.
*/ */
public abstract float[] toCIEXYZ(float[] colorvalue); public abstract float[] toCIEXYZ(float[] colorvalue);
/** /**
* Transforms a color value assumed to be in the CS_CIEXYZ conversion * Transforms a color value assumed to be in the {@code CS_CIEXYZ}
* color space into this ColorSpace. * conversion color space into this {@code ColorSpace}.
* <p> * <p>
* This method transforms color values using relative colorimetry, * This method transforms color values using relative colorimetry, as
* as defined by the International Color Consortium standard. This * defined by the International Color Consortium standard. This means that
* means that the XYZ argument values taken by this method are represented * the XYZ argument values taken by this method are represented relative to
* relative to the D50 white point of the CS_CIEXYZ color space. * the D50 white point of the {@code CS_CIEXYZ} color space. This
* This representation is useful in a two-step color conversion * representation is useful in a two-step color conversion process in which
* process in which colors are transformed from an input color * colors are transformed from an input color space to {@code CS_CIEXYZ} and
* space to CS_CIEXYZ and then to an output color space. The color * then to an output color space. The color values returned by this method
* values returned by this method are not those that would produce * are not those that would produce the XYZ value passed to the method when
* the XYZ value passed to the method when measured by a colorimeter. * measured by a colorimeter. If you have XYZ values corresponding to
* If you have XYZ values corresponding to measurements made using * measurements made using current CIE recommended practices, they must be
* current CIE recommended practices, they must be converted to D50 * converted to D50 relative values before being passed to this method. See
* relative values before being passed to this method. * the {@link ICC_ColorSpace#fromCIEXYZ(float[]) fromCIEXYZ} method of
* See the {@link ICC_ColorSpace#fromCIEXYZ(float[]) fromCIEXYZ} method of
* {@code ICC_ColorSpace} for further information. * {@code ICC_ColorSpace} for further information.
* *
* @param colorvalue a float array with length of at least 3 * @param colorvalue a float array with length of at least 3
* @return a float array with length equal to the number of * @return a float array with length equal to the number of components in
* components in this ColorSpace * this {@code ColorSpace}
* @throws ArrayIndexOutOfBoundsException if array length is not * @throws ArrayIndexOutOfBoundsException if array length is not at least 3
* at least 3
*/ */
public abstract float[] fromCIEXYZ(float[] colorvalue); public abstract float[] fromCIEXYZ(float[] colorvalue);
/** /**
* Returns the color space type of this ColorSpace (for example * Returns the color space type of this {@code ColorSpace} (for example
* TYPE_RGB, TYPE_XYZ, ...). The type defines the * {@code TYPE_RGB}, {@code TYPE_XYZ}, ...). The type defines the number of
* number of components of the color space and the interpretation, * components of the color space and the interpretation, e.g.
* e.g. TYPE_RGB identifies a color space with three components - red, * {@code TYPE_RGB} identifies a color space with three components - red,
* green, and blue. It does not define the particular color * green, and blue. It does not define the particular color characteristics
* characteristics of the space, e.g. the chromaticities of the * of the space, e.g. the chromaticities of the primaries.
* primaries.
* *
* @return the type constant that represents the type of this * @return the type constant that represents the type of this
* {@code ColorSpace} * {@code ColorSpace}
@ -494,7 +480,8 @@ public abstract class ColorSpace implements java.io.Serializable {
/** /**
* Returns the number of components of this ColorSpace. * Returns the number of components of this ColorSpace.
* @return The number of components in this {@code ColorSpace}. *
* @return the number of components in this {@code ColorSpace}
*/ */
public int getNumComponents() { public int getNumComponents() {
return numComponents; return numComponents;
@ -503,10 +490,10 @@ public abstract class ColorSpace implements java.io.Serializable {
/** /**
* Returns the name of the component given the component index. * Returns the name of the component given the component index.
* *
* @param idx the component index * @param idx the component index
* @return the name of the component at the specified index * @return the name of the component at the specified index
* @throws IllegalArgumentException if {@code idx} is * @throws IllegalArgumentException if {@code idx} is less than 0 or greater
* less than 0 or greater than numComponents - 1 * than {@code numComponents - 1}
*/ */
public String getName (int idx) { public String getName (int idx) {
/* REMIND - handle common cases here */ /* REMIND - handle common cases here */
@ -564,15 +551,14 @@ public abstract class ColorSpace implements java.io.Serializable {
} }
/** /**
* Returns the minimum normalized color component value for the * Returns the minimum normalized color component value for the specified
* specified component. The default implementation in this abstract * component. The default implementation in this abstract class returns 0.0
* class returns 0.0 for all components. Subclasses should override * for all components. Subclasses should override this method if necessary.
* this method if necessary.
* *
* @param component the component index * @param component the component index
* @return the minimum normalized component value * @return the minimum normalized component value
* @throws IllegalArgumentException if component is less than 0 or * @throws IllegalArgumentException if component is less than 0 or greater
* greater than numComponents - 1 * than {@code numComponents - 1}
* @since 1.4 * @since 1.4
*/ */
public float getMinValue(int component) { public float getMinValue(int component) {
@ -584,15 +570,14 @@ public abstract class ColorSpace implements java.io.Serializable {
} }
/** /**
* Returns the maximum normalized color component value for the * Returns the maximum normalized color component value for the specified
* specified component. The default implementation in this abstract * component. The default implementation in this abstract class returns 1.0
* class returns 1.0 for all components. Subclasses should override * for all components. Subclasses should override this method if necessary.
* this method if necessary.
* *
* @param component the component index * @param component the component index
* @return the maximum normalized component value * @return the maximum normalized component value
* @throws IllegalArgumentException if component is less than 0 or * @throws IllegalArgumentException if component is less than 0 or greater
* greater than numComponents - 1 * than {@code numComponents - 1}
* @since 1.4 * @since 1.4
*/ */
public float getMaxValue(int component) { public float getMaxValue(int component) {
@ -603,7 +588,8 @@ public abstract class ColorSpace implements java.io.Serializable {
return 1.0f; return 1.0f;
} }
/* Returns true if cspace is the XYZspace. /*
* Returns {@code true} if {@code cspace} is the XYZspace.
*/ */
static boolean isCS_CIEXYZ(ColorSpace cspace) { static boolean isCS_CIEXYZ(ColorSpace cspace) {
return (cspace == XYZspace); return (cspace == XYZspace);

477
src/java.desktop/share/classes/java/awt/color/ICC_ColorSpace.java
View File

@ -23,8 +23,7 @@
* questions. * questions.
*/ */
/* /* ********************************************************************
**********************************************************************
********************************************************************** **********************************************************************
********************************************************************** **********************************************************************
*** COPYRIGHT (c) Eastman Kodak Company, 1997 *** *** COPYRIGHT (c) Eastman Kodak Company, 1997 ***
@ -36,54 +35,46 @@
package java.awt.color; package java.awt.color;
import sun.java2d.cmm.ColorTransform;
import sun.java2d.cmm.CMSManager; import sun.java2d.cmm.CMSManager;
import sun.java2d.cmm.ColorTransform;
import sun.java2d.cmm.PCMM; import sun.java2d.cmm.PCMM;
/** /**
* The {@code ICC_ColorSpace} class is an implementation of the abstract
* {@code ColorSpace} class. This representation of device independent and
* device dependent color spaces is based on the International Color Consortium
* Specification ICC.1:2001-12, File Format for Color Profiles (see
* <a href="http://www.color.org">http://www.color.org</a>).
* <p>
* Typically, a {@code Color} or {@code ColorModel} would be associated with an
* ICC Profile which is either an input, display, or output profile (see the ICC
* specification). There are other types of ICC Profiles, e.g. abstract
* profiles, device link profiles, and named color profiles, which do not
* contain information appropriate for representing the color space of a color,
* image, or device (see {@code ICC_Profile}). Attempting to create an
* {@code ICC_ColorSpace} object from an inappropriate ICC Profile is an error.
* <p>
* ICC Profiles represent transformations from the color space of the profile
* (e.g. a monitor) to a Profile Connection Space (PCS). Profiles of interest
* for tagging images or colors have a PCS which is one of the device
* independent spaces (one CIEXYZ space and two CIELab spaces) defined in the
* ICC Profile Format Specification. Most profiles of interest either have
* invertible transformations or explicitly specify transformations going both
* directions. Should an {@code ICC_ColorSpace} object be used in a way
* requiring a conversion from PCS to the profile's native space and there is
* inadequate data to correctly perform the conversion, the
* {@code ICC_ColorSpace} object will produce output in the specified type of
* color space (e.g. {@code TYPE_RGB}, {@code TYPE_CMYK}, etc.), but the
* specific color values of the output data will be undefined.
* <p>
* The details of this class are not important for simple applets, which draw in
* a default color space or manipulate and display imported images with a known
* color space. At most, such applets would need to get one of the default color
* spaces via {@link ColorSpace#getInstance}.
* *
* The ICC_ColorSpace class is an implementation of the abstract
* ColorSpace class. This representation of
* device independent and device dependent color spaces is based on the
* International Color Consortium Specification ICC.1:2001-12, File Format for
* Color Profiles (see <A href="http://www.color.org">http://www.color.org</A>).
* <p>
* Typically, a Color or ColorModel would be associated with an ICC
* Profile which is either an input, display, or output profile (see
* the ICC specification). There are other types of ICC Profiles, e.g.
* abstract profiles, device link profiles, and named color profiles,
* which do not contain information appropriate for representing the color
* space of a color, image, or device (see ICC_Profile).
* Attempting to create an ICC_ColorSpace object from an inappropriate ICC
* Profile is an error.
* <p>
* ICC Profiles represent transformations from the color space of
* the profile (e.g. a monitor) to a Profile Connection Space (PCS).
* Profiles of interest for tagging images or colors have a
* PCS which is one of the device independent
* spaces (one CIEXYZ space and two CIELab spaces) defined in the
* ICC Profile Format Specification. Most profiles of interest
* either have invertible transformations or explicitly specify
* transformations going both directions. Should an ICC_ColorSpace
* object be used in a way requiring a conversion from PCS to
* the profile's native space and there is inadequate data to
* correctly perform the conversion, the ICC_ColorSpace object will
* produce output in the specified type of color space (e.g. TYPE_RGB,
* TYPE_CMYK, etc.), but the specific color values of the output data
* will be undefined.
* <p>
* The details of this class are not important for simple applets,
* which draw in a default color space or manipulate and display
* imported images with a known color space. At most, such applets
* would need to get one of the default color spaces via
* ColorSpace.getInstance().
* @see ColorSpace * @see ColorSpace
* @see ICC_Profile * @see ICC_Profile
*/ */
public class ICC_ColorSpace extends ColorSpace { public class ICC_ColorSpace extends ColorSpace {
static final long serialVersionUID = 3455889114070431483L; static final long serialVersionUID = 3455889114070431483L;
@ -101,13 +92,14 @@ public class ICC_ColorSpace extends ColorSpace {
private transient ColorTransform this2xyz; private transient ColorTransform this2xyz;
private transient ColorTransform xyz2this; private transient ColorTransform xyz2this;
/** /**
* Constructs a new ICC_ColorSpace from an ICC_Profile object. * Constructs a new {@code ICC_ColorSpace} from an {@code ICC_Profile}
* @param profile the specified ICC_Profile object * object.
* @exception IllegalArgumentException if profile is inappropriate for *
* representing a ColorSpace. * @param profile the specified {@code ICC_Profile} object
*/ * @throws IllegalArgumentException if profile is inappropriate for
* representing a {@code ColorSpace}
*/
public ICC_ColorSpace (ICC_Profile profile) { public ICC_ColorSpace (ICC_Profile profile) {
super (profile.getColorSpaceType(), profile.getNumComponents()); super (profile.getColorSpaceType(), profile.getNumComponents());
@ -140,33 +132,33 @@ public class ICC_ColorSpace extends ColorSpace {
} }
/** /**
* Returns the ICC_Profile for this ICC_ColorSpace. * Returns the {@code ICC_Profile} for this {@code ICC_ColorSpace}.
* @return the ICC_Profile for this ICC_ColorSpace. *
*/ * @return the {@code ICC_Profile} for this {@code ICC_ColorSpace}
*/
public ICC_Profile getProfile() { public ICC_Profile getProfile() {
return thisProfile; return thisProfile;
} }
/** /**
* Transforms a color value assumed to be in this ColorSpace * Transforms a color value assumed to be in this {@code ColorSpace} into a
* into a value in the default CS_sRGB color space. * value in the default {@code CS_sRGB} color space.
* <p> * <p>
* This method transforms color values using algorithms designed * This method transforms color values using algorithms designed to produce
* to produce the best perceptual match between input and output * the best perceptual match between input and output colors. In order to do
* colors. In order to do colorimetric conversion of color values, * colorimetric conversion of color values, you should use the
* you should use the {@code toCIEXYZ} * {@code toCIEXYZ} method of this color space to first convert from the
* method of this color space to first convert from the input * input color space to the {@code CS_CIEXYZ} color space, and then use the
* color space to the CS_CIEXYZ color space, and then use the * {@code fromCIEXYZ} method of the {@code CS_sRGB} color space to convert
* {@code fromCIEXYZ} method of the CS_sRGB color space to * from {@code CS_CIEXYZ} to the output color space. See
* convert from CS_CIEXYZ to the output color space. * {@link #toCIEXYZ(float[]) toCIEXYZ} and
* See {@link #toCIEXYZ(float[]) toCIEXYZ} and
* {@link #fromCIEXYZ(float[]) fromCIEXYZ} for further information. * {@link #fromCIEXYZ(float[]) fromCIEXYZ} for further information.
* *
* @param colorvalue a float array with length of at least the number * @param colorvalue a float array with length of at least the number of
* of components in this ColorSpace. * components in this {@code ColorSpace}
* @return a float array of length 3. * @return a float array of length 3
* @throws ArrayIndexOutOfBoundsException if array length is not * @throws ArrayIndexOutOfBoundsException if array length is not at least
* at least the number of components in this ColorSpace. * the number of components in this {@code ColorSpace}
*/ */
public float[] toRGB (float[] colorvalue) { public float[] toRGB (float[] colorvalue) {
@ -200,25 +192,23 @@ public class ICC_ColorSpace extends ColorSpace {
} }
/** /**
* Transforms a color value assumed to be in the default CS_sRGB * Transforms a color value assumed to be in the default {@code CS_sRGB}
* color space into this ColorSpace. * color space into this {@code ColorSpace}.
* <p> * <p>
* This method transforms color values using algorithms designed * This method transforms color values using algorithms designed to produce
* to produce the best perceptual match between input and output * the best perceptual match between input and output colors. In order to do
* colors. In order to do colorimetric conversion of color values, * colorimetric conversion of color values, you should use the
* you should use the {@code toCIEXYZ} * {@code toCIEXYZ} method of the {@code CS_sRGB} color space to first
* method of the CS_sRGB color space to first convert from the input * convert from the input color space to the {@code CS_CIEXYZ} color space,
* color space to the CS_CIEXYZ color space, and then use the * and then use the {@code fromCIEXYZ} method of this color space to convert
* {@code fromCIEXYZ} method of this color space to * from {@code CS_CIEXYZ} to the output color space. See
* convert from CS_CIEXYZ to the output color space. * {@link #toCIEXYZ(float[]) toCIEXYZ} and
* See {@link #toCIEXYZ(float[]) toCIEXYZ} and
* {@link #fromCIEXYZ(float[]) fromCIEXYZ} for further information. * {@link #fromCIEXYZ(float[]) fromCIEXYZ} for further information.
* *
* @param rgbvalue a float array with length of at least 3. * @param rgbvalue a float array with length of at least 3
* @return a float array with length equal to the number of * @return a float array with length equal to the number of components in
* components in this ColorSpace. * this {@code ColorSpace}
* @throws ArrayIndexOutOfBoundsException if array length is not * @throws ArrayIndexOutOfBoundsException if array length is not at least 3
* at least 3.
*/ */
public float[] fromRGB(float[] rgbvalue) { public float[] fromRGB(float[] rgbvalue) {
@ -251,70 +241,66 @@ public class ICC_ColorSpace extends ColorSpace {
return result; return result;
} }
/** /**
* Transforms a color value assumed to be in this ColorSpace * Transforms a color value assumed to be in this {@code ColorSpace} into
* into the CS_CIEXYZ conversion color space. * the {@code CS_CIEXYZ} conversion color space.
* <p> * <p>
* This method transforms color values using relative colorimetry, * This method transforms color values using relative colorimetry, as
* as defined by the ICC Specification. This * defined by the ICC Specification. This means that the XYZ values returned
* means that the XYZ values returned by this method are represented * by this method are represented relative to the D50 white point of the
* relative to the D50 white point of the CS_CIEXYZ color space. * {@code CS_CIEXYZ} color space. This representation is useful in a
* This representation is useful in a two-step color conversion * two-step color conversion process in which colors are transformed from an
* process in which colors are transformed from an input color * input color space to {@code CS_CIEXYZ} and then to an output color space.
* space to CS_CIEXYZ and then to an output color space. This * This representation is not the same as the XYZ values that would be
* representation is not the same as the XYZ values that would * measured from the given color value by a colorimeter. A further
* be measured from the given color value by a colorimeter. * transformation is necessary to compute the XYZ values that would be
* A further transformation is necessary to compute the XYZ values * measured using current CIE recommended practices. The paragraphs below
* that would be measured using current CIE recommended practices. * explain this in more detail.
* The paragraphs below explain this in more detail.
* <p> * <p>
* The ICC standard uses a device independent color space (DICS) as the * The ICC standard uses a device independent color space (DICS) as the
* mechanism for converting color from one device to another device. In * mechanism for converting color from one device to another device. In this
* this architecture, colors are converted from the source device's color * architecture, colors are converted from the source device's color space
* space to the ICC DICS and then from the ICC DICS to the destination * to the ICC DICS and then from the ICC DICS to the destination device's
* device's color space. The ICC standard defines device profiles which * color space. The ICC standard defines device profiles which contain
* contain transforms which will convert between a device's color space * transforms which will convert between a device's color space and the ICC
* and the ICC DICS. The overall conversion of colors from a source * DICS. The overall conversion of colors from a source device to colors of
* device to colors of a destination device is done by connecting the * a destination device is done by connecting the device-to-DICS transform
* device-to-DICS transform of the profile for the source device to the * of the profile for the source device to the DICS-to-device transform of
* DICS-to-device transform of the profile for the destination device. * the profile for the destination device. For this reason, the ICC DICS is
* For this reason, the ICC DICS is commonly referred to as the profile * commonly referred to as the profile connection space (PCS). The color
* connection space (PCS). The color space used in the methods * space used in the methods {@code toCIEXYZ} and {@code fromCIEXYZ} is the
* toCIEXYZ and fromCIEXYZ is the CIEXYZ PCS defined by the ICC * CIEXYZ PCS defined by the ICC Specification. This is also the color space
* Specification. This is also the color space represented by * represented by {@code ColorSpace.CS_CIEXYZ}.
* ColorSpace.CS_CIEXYZ.
* <p> * <p>
* The XYZ values of a color are often represented as relative to some * The XYZ values of a color are often represented as relative to some white
* white point, so the actual meaning of the XYZ values cannot be known * point, so the actual meaning of the XYZ values cannot be known without
* without knowing the white point of those values. This is known as * knowing the white point of those values. This is known as relative
* relative colorimetry. The PCS uses a white point of D50, so the XYZ * colorimetry. The PCS uses a white point of D50, so the XYZ values of the
* values of the PCS are relative to D50. For example, white in the PCS * PCS are relative to D50. For example, white in the PCS will have the XYZ
* will have the XYZ values of D50, which is defined to be X=.9642, * values of D50, which is defined to be X=.9642, Y=1.000, and Z=0.8249.
* Y=1.000, and Z=0.8249. This white point is commonly used for graphic * This white point is commonly used for graphic arts applications, but
* arts applications, but others are often used in other applications. * others are often used in other applications.
* <p> * <p>
* To quantify the color characteristics of a device such as a printer * To quantify the color characteristics of a device such as a printer or
* or monitor, measurements of XYZ values for particular device colors * monitor, measurements of XYZ values for particular device colors are
* are typically made. For purposes of this discussion, the term * typically made. For purposes of this discussion, the term device XYZ
* device XYZ values is used to mean the XYZ values that would be * values is used to mean the XYZ values that would be measured from device
* measured from device colors using current CIE recommended practices. * colors using current CIE recommended practices.
* <p> * <p>
* Converting between device XYZ values and the PCS XYZ values returned * Converting between device XYZ values and the PCS XYZ values returned by
* by this method corresponds to converting between the device's color * this method corresponds to converting between the device's color space,
* space, as represented by CIE colorimetric values, and the PCS. There * as represented by CIE colorimetric values, and the PCS. There are many
* are many factors involved in this process, some of which are quite * factors involved in this process, some of which are quite subtle. The
* subtle. The most important, however, is the adjustment made to account * most important, however, is the adjustment made to account for
* for differences between the device's white point and the white point of * differences between the device's white point and the white point of the
* the PCS. There are many techniques for doing this and it is the * PCS. There are many techniques for doing this and it is the subject of
* subject of much current research and controversy. Some commonly used * much current research and controversy. Some commonly used methods are XYZ
* methods are XYZ scaling, the von Kries transform, and the Bradford * scaling, the von Kries transform, and the Bradford transform. The proper
* transform. The proper method to use depends upon each particular * method to use depends upon each particular application.
* application.
* <p> * <p>
* The simplest method is XYZ scaling. In this method each device XYZ * The simplest method is XYZ scaling. In this method each device XYZ value
* value is converted to a PCS XYZ value by multiplying it by the ratio * is converted to a PCS XYZ value by multiplying it by the ratio of the PCS
* of the PCS white point (D50) to the device white point. * white point (D50) to the device white point.
* <pre> * <pre>
* *
* Xd, Yd, Zd are the device XYZ values * Xd, Yd, Zd are the device XYZ values
@ -338,22 +324,21 @@ public class ICC_ColorSpace extends ColorSpace {
* *
* </pre> * </pre>
* <p> * <p>
* Note that the media white point tag in an ICC profile is not the same * Note that the media white point tag in an ICC profile is not the same as
* as the device white point. The media white point tag is expressed in * the device white point. The media white point tag is expressed in PCS
* PCS values and is used to represent the difference between the XYZ of * values and is used to represent the difference between the XYZ of device
* device illuminant and the XYZ of the device media when measured under * illuminant and the XYZ of the device media when measured under that
* that illuminant. The device white point is expressed as the device * illuminant. The device white point is expressed as the device XYZ values
* XYZ values corresponding to white displayed on the device. For * corresponding to white displayed on the device. For example, displaying
* example, displaying the RGB color (1.0, 1.0, 1.0) on an sRGB device * the RGB color (1.0, 1.0, 1.0) on an sRGB device will result in a measured
* will result in a measured device XYZ value of D65. This will not * device XYZ value of D65. This will not be the same as the media white
* be the same as the media white point tag XYZ value in the ICC * point tag XYZ value in the ICC profile for an sRGB device.
* profile for an sRGB device.
* *
* @param colorvalue a float array with length of at least the number * @param colorvalue a float array with length of at least the number of
* of components in this ColorSpace. * components in this {@code ColorSpace}
* @return a float array of length 3. * @return a float array of length 3
* @throws ArrayIndexOutOfBoundsException if array length is not * @throws ArrayIndexOutOfBoundsException if array length is not at least
* at least the number of components in this ColorSpace. * the number of components in this {@code ColorSpace}
*/ */
public float[] toCIEXYZ(float[] colorvalue) { public float[] toCIEXYZ(float[] colorvalue) {
@ -394,71 +379,67 @@ public class ICC_ColorSpace extends ColorSpace {
return result; return result;
} }
/** /**
* Transforms a color value assumed to be in the CS_CIEXYZ conversion * Transforms a color value assumed to be in the {@code CS_CIEXYZ}
* color space into this ColorSpace. * conversion color space into this ColorSpace.
* <p> * <p>
* This method transforms color values using relative colorimetry, * This method transforms color values using relative colorimetry, as
* as defined by the ICC Specification. This * defined by the ICC Specification. This means that the XYZ argument values
* means that the XYZ argument values taken by this method are represented * taken by this method are represented relative to the D50 white point of
* relative to the D50 white point of the CS_CIEXYZ color space. * the {@code CS_CIEXYZ} color space. This representation is useful in a
* This representation is useful in a two-step color conversion * two-step color conversion process in which colors are transformed from an
* process in which colors are transformed from an input color * input color space to {@code CS_CIEXYZ} and then to an output color space.
* space to CS_CIEXYZ and then to an output color space. The color * The color values returned by this method are not those that would produce
* values returned by this method are not those that would produce * the XYZ value passed to the method when measured by a colorimeter. If you
* the XYZ value passed to the method when measured by a colorimeter. * have XYZ values corresponding to measurements made using current CIE
* If you have XYZ values corresponding to measurements made using * recommended practices, they must be converted to D50 relative values
* current CIE recommended practices, they must be converted to D50 * before being passed to this method. The paragraphs below explain this in
* relative values before being passed to this method. * more detail.
* The paragraphs below explain this in more detail.
* <p> * <p>
* The ICC standard uses a device independent color space (DICS) as the * The ICC standard uses a device independent color space (DICS) as the
* mechanism for converting color from one device to another device. In * mechanism for converting color from one device to another device. In this
* this architecture, colors are converted from the source device's color * architecture, colors are converted from the source device's color space
* space to the ICC DICS and then from the ICC DICS to the destination * to the ICC DICS and then from the ICC DICS to the destination device's
* device's color space. The ICC standard defines device profiles which * color space. The ICC standard defines device profiles which contain
* contain transforms which will convert between a device's color space * transforms which will convert between a device's color space and the ICC
* and the ICC DICS. The overall conversion of colors from a source * DICS. The overall conversion of colors from a source device to colors of
* device to colors of a destination device is done by connecting the * a destination device is done by connecting the device-to-DICS transform
* device-to-DICS transform of the profile for the source device to the * of the profile for the source device to the DICS-to-device transform of
* DICS-to-device transform of the profile for the destination device. * the profile for the destination device. For this reason, the ICC DICS is
* For this reason, the ICC DICS is commonly referred to as the profile * commonly referred to as the profile connection space (PCS). The color
* connection space (PCS). The color space used in the methods * space used in the methods {@code toCIEXYZ} and {@code fromCIEXYZ} is the
* toCIEXYZ and fromCIEXYZ is the CIEXYZ PCS defined by the ICC * CIEXYZ PCS defined by the ICC Specification. This is also the color space
* Specification. This is also the color space represented by * represented by {@code ColorSpace.CS_CIEXYZ}.
* ColorSpace.CS_CIEXYZ.
* <p> * <p>
* The XYZ values of a color are often represented as relative to some * The XYZ values of a color are often represented as relative to some white
* white point, so the actual meaning of the XYZ values cannot be known * point, so the actual meaning of the XYZ values cannot be known without
* without knowing the white point of those values. This is known as * knowing the white point of those values. This is known as relative
* relative colorimetry. The PCS uses a white point of D50, so the XYZ * colorimetry. The PCS uses a white point of D50, so the XYZ values of the
* values of the PCS are relative to D50. For example, white in the PCS * PCS are relative to D50. For example, white in the PCS will have the XYZ
* will have the XYZ values of D50, which is defined to be X=.9642, * values of D50, which is defined to be X=.9642, Y=1.000, and Z=0.8249.
* Y=1.000, and Z=0.8249. This white point is commonly used for graphic * This white point is commonly used for graphic arts applications, but
* arts applications, but others are often used in other applications. * others are often used in other applications.
* <p> * <p>
* To quantify the color characteristics of a device such as a printer * To quantify the color characteristics of a device such as a printer or
* or monitor, measurements of XYZ values for particular device colors * monitor, measurements of XYZ values for particular device colors are
* are typically made. For purposes of this discussion, the term * typically made. For purposes of this discussion, the term device XYZ
* device XYZ values is used to mean the XYZ values that would be * values is used to mean the XYZ values that would be measured from device
* measured from device colors using current CIE recommended practices. * colors using current CIE recommended practices.
* <p> * <p>
* Converting between device XYZ values and the PCS XYZ values taken as * Converting between device XYZ values and the PCS XYZ values taken as
* arguments by this method corresponds to converting between the device's * arguments by this method corresponds to converting between the device's
* color space, as represented by CIE colorimetric values, and the PCS. * color space, as represented by CIE colorimetric values, and the PCS.
* There are many factors involved in this process, some of which are quite * There are many factors involved in this process, some of which are quite
* subtle. The most important, however, is the adjustment made to account * subtle. The most important, however, is the adjustment made to account
* for differences between the device's white point and the white point of * for differences between the device's white point and the white point of
* the PCS. There are many techniques for doing this and it is the * the PCS. There are many techniques for doing this and it is the subject
* subject of much current research and controversy. Some commonly used * of much current research and controversy. Some commonly used methods are
* methods are XYZ scaling, the von Kries transform, and the Bradford * XYZ scaling, the von Kries transform, and the Bradford transform. The
* transform. The proper method to use depends upon each particular * proper method to use depends upon each particular application.
* application.
* <p> * <p>
* The simplest method is XYZ scaling. In this method each device XYZ * The simplest method is XYZ scaling. In this method each device XYZ value
* value is converted to a PCS XYZ value by multiplying it by the ratio * is converted to a PCS XYZ value by multiplying it by the ratio of the PCS
* of the PCS white point (D50) to the device white point. * white point (D50) to the device white point.
* <pre> * <pre>
* *
* Xd, Yd, Zd are the device XYZ values * Xd, Yd, Zd are the device XYZ values
@ -482,22 +463,20 @@ public class ICC_ColorSpace extends ColorSpace {
* *
* </pre> * </pre>
* <p> * <p>
* Note that the media white point tag in an ICC profile is not the same * Note that the media white point tag in an ICC profile is not the same as
* as the device white point. The media white point tag is expressed in * the device white point. The media white point tag is expressed in PCS
* PCS values and is used to represent the difference between the XYZ of * values and is used to represent the difference between the XYZ of device
* device illuminant and the XYZ of the device media when measured under * illuminant and the XYZ of the device media when measured under that
* that illuminant. The device white point is expressed as the device * illuminant. The device white point is expressed as the device XYZ values
* XYZ values corresponding to white displayed on the device. For * corresponding to white displayed on the device. For example, displaying
* example, displaying the RGB color (1.0, 1.0, 1.0) on an sRGB device * the RGB color (1.0, 1.0, 1.0) on an sRGB device will result in a measured
* will result in a measured device XYZ value of D65. This will not * device XYZ value of D65. This will not be the same as the media white
* be the same as the media white point tag XYZ value in the ICC * point tag XYZ value in the ICC profile for an sRGB device.
* profile for an sRGB device.
* *
* @param colorvalue a float array with length of at least 3. * @param colorvalue a float array with length of at least 3
* @return a float array with length equal to the number of * @return a float array with length equal to the number of components in
* components in this ColorSpace. * this {@code ColorSpace}
* @throws ArrayIndexOutOfBoundsException if array length is not * @throws ArrayIndexOutOfBoundsException if array length is not at least 3
* at least 3.
*/ */
public float[] fromCIEXYZ(float[] colorvalue) { public float[] fromCIEXYZ(float[] colorvalue) {
@ -540,19 +519,20 @@ public class ICC_ColorSpace extends ColorSpace {
} }
/** /**
* Returns the minimum normalized color component value for the * Returns the minimum normalized color component value for the specified
* specified component. For TYPE_XYZ spaces, this method returns * component. For {@code TYPE_XYZ} spaces, this method returns minimum
* minimum values of 0.0 for all components. For TYPE_Lab spaces, * values of 0.0 for all components. For {@code TYPE_Lab} spaces, this
* this method returns 0.0 for L and -128.0 for a and b components. * method returns 0.0 for L and -128.0 for a and b components. This is
* This is consistent with the encoding of the XYZ and Lab Profile * consistent with the encoding of the XYZ and Lab Profile Connection Spaces
* Connection Spaces in the ICC specification. For all other types, this * in the ICC specification. For all other types, this method returns 0.0
* method returns 0.0 for all components. When using an ICC_ColorSpace * for all components. When using an {@code ICC_ColorSpace} with a profile
* with a profile that requires different minimum component values, * that requires different minimum component values, it is necessary to
* it is necessary to subclass this class and override this method. * subclass this class and override this method.
* @param component The component index. *
* @return The minimum normalized component value. * @param component the component index
* @throws IllegalArgumentException if component is less than 0 or * @return the minimum normalized component value
* greater than numComponents - 1. * @throws IllegalArgumentException if component is less than 0 or greater
* than {@code numComponents - 1}
* @since 1.4 * @since 1.4
*/ */
public float getMinValue(int component) { public float getMinValue(int component) {
@ -564,20 +544,21 @@ public class ICC_ColorSpace extends ColorSpace {
} }
/** /**
* Returns the maximum normalized color component value for the * Returns the maximum normalized color component value for the specified
* specified component. For TYPE_XYZ spaces, this method returns * component. For {@code TYPE_XYZ} spaces, this method returns maximum
* maximum values of 1.0 + (32767.0 / 32768.0) for all components. * values of 1.0 + (32767.0 / 32768.0) for all components. For
* For TYPE_Lab spaces, * {@code TYPE_Lab} spaces, this method returns 100.0 for L and 127.0 for a
* this method returns 100.0 for L and 127.0 for a and b components. * and b components. This is consistent with the encoding of the XYZ and Lab
* This is consistent with the encoding of the XYZ and Lab Profile * Profile Connection Spaces in the ICC specification. For all other types,
* Connection Spaces in the ICC specification. For all other types, this * this method returns 1.0 for all components. When using an
* method returns 1.0 for all components. When using an ICC_ColorSpace * {@code ICC_ColorSpace} with a profile that requires different maximum
* with a profile that requires different maximum component values, * component values, it is necessary to subclass this class and override
* it is necessary to subclass this class and override this method. * this method.
* @param component The component index. *
* @return The maximum normalized component value. * @param component the component index
* @throws IllegalArgumentException if component is less than 0 or * @return the maximum normalized component value
* greater than numComponents - 1. * @throws IllegalArgumentException if component is less than 0 or greater
* than {@code numComponents - 1}
* @since 1.4 * @since 1.4
*/ */
public float getMaxValue(int component) { public float getMaxValue(int component) {

648
src/java.desktop/share/classes/java/awt/color/ICC_Profile.java
View File

@ -23,8 +23,7 @@
* questions. * questions.
*/ */
/* /* ********************************************************************
**********************************************************************
********************************************************************** **********************************************************************
********************************************************************** **********************************************************************
*** COPYRIGHT (c) Eastman Kodak Company, 1997 *** *** COPYRIGHT (c) Eastman Kodak Company, 1997 ***
@ -36,17 +35,8 @@
package java.awt.color; package java.awt.color;
import sun.java2d.cmm.PCMM;
import sun.java2d.cmm.CMSManager;
import sun.java2d.cmm.Profile;
import sun.java2d.cmm.ProfileDataVerifier;
import sun.java2d.cmm.ProfileDeferralMgr;
import sun.java2d.cmm.ProfileDeferralInfo;
import sun.java2d.cmm.ProfileActivator;
import java.io.File; import java.io.File;
import java.io.FileInputStream; import java.io.FileInputStream;
import java.io.FileNotFoundException;
import java.io.FileOutputStream; import java.io.FileOutputStream;
import java.io.FilePermission; import java.io.FilePermission;
import java.io.IOException; import java.io.IOException;
@ -56,42 +46,43 @@ import java.io.ObjectOutputStream;
import java.io.ObjectStreamException; import java.io.ObjectStreamException;
import java.io.OutputStream; import java.io.OutputStream;
import java.io.Serializable; import java.io.Serializable;
import java.util.StringTokenizer;
import java.security.AccessController; import java.security.AccessController;
import java.security.PrivilegedAction; import java.security.PrivilegedAction;
import java.util.StringTokenizer;
import sun.java2d.cmm.CMSManager;
import sun.java2d.cmm.PCMM;
import sun.java2d.cmm.Profile;
import sun.java2d.cmm.ProfileActivator;
import sun.java2d.cmm.ProfileDataVerifier;
import sun.java2d.cmm.ProfileDeferralInfo;
import sun.java2d.cmm.ProfileDeferralMgr;
/** /**
* A representation of color profile data for device independent and * A representation of color profile data for device independent and device
* device dependent color spaces based on the International Color * dependent color spaces based on the International Color Consortium
* Consortium Specification ICC.1:2001-12, File Format for Color Profiles, * Specification ICC.1:2001-12, File Format for Color Profiles, (see
* (see <A href="http://www.color.org"> http://www.color.org</A>). * <a href="http://www.color.org"> http://www.color.org</a>).
* <p> * <p>
* An ICC_ColorSpace object can be constructed from an appropriate * An {@code ICC_ColorSpace} object can be constructed from an appropriate
* ICC_Profile. * {@code ICC_Profile}. Typically, an {@code ICC_ColorSpace} would be associated
* Typically, an ICC_ColorSpace would be associated with an ICC * with an ICC Profile which is either an input, display, or output profile (see
* Profile which is either an input, display, or output profile (see * the ICC specification). There are also device link, abstract, color space
* the ICC specification). There are also device link, abstract, * conversion, and named color profiles. These are less useful for tagging a
* color space conversion, and named color profiles. These are less * color or image, but are useful for other purposes (in particular device link
* useful for tagging a color or image, but are useful for other * profiles can provide improved performance for converting from one device's
* purposes (in particular device link profiles can provide improved * color space to another's).
* performance for converting from one device's color space to
* another's).
* <p> * <p>
* ICC Profiles represent transformations from the color space of * ICC Profiles represent transformations from the color space of the profile
* the profile (e.g. a monitor) to a Profile Connection Space (PCS). * (e.g. a monitor) to a Profile Connection Space (PCS). Profiles of interest
* Profiles of interest for tagging images or colors have a PCS * for tagging images or colors have a PCS which is one of the two specific
* which is one of the two specific device independent * device independent spaces (one CIEXYZ space and one CIELab space) defined in
* spaces (one CIEXYZ space and one CIELab space) defined in the * the ICC Profile Format Specification. Most profiles of interest either have
* ICC Profile Format Specification. Most profiles of interest * invertible transformations or explicitly specify transformations going both
* either have invertible transformations or explicitly specify * directions.
* transformations going both directions. *
* @see ICC_ColorSpace * @see ICC_ColorSpace
*/ */
public class ICC_Profile implements Serializable { public class ICC_Profile implements Serializable {
private static final long serialVersionUID = -3938515861990936766L; private static final long serialVersionUID = -3938515861990936766L;
@ -110,7 +101,6 @@ public class ICC_Profile implements Serializable {
private static ICC_Profile GRAYprofile; private static ICC_Profile GRAYprofile;
private static ICC_Profile LINEAR_RGBprofile; private static ICC_Profile LINEAR_RGBprofile;
/** /**
* Profile class is input. * Profile class is input.
*/ */
@ -146,7 +136,6 @@ public class ICC_Profile implements Serializable {
*/ */
public static final int CLASS_NAMEDCOLOR = 6; public static final int CLASS_NAMEDCOLOR = 6;
/** /**
* ICC Profile Color Space Type Signature: 'XYZ '. * ICC Profile Color Space Type Signature: 'XYZ '.
*/ */
@ -321,6 +310,7 @@ public class ICC_Profile implements Serializable {
/** /**
* ICC Profile Rendering Intent: Media-RelativeColorimetric. * ICC Profile Rendering Intent: Media-RelativeColorimetric.
*
* @since 1.5 * @since 1.5
*/ */
public static final int icMediaRelativeColorimetric = 1; public static final int icMediaRelativeColorimetric = 1;
@ -337,6 +327,7 @@ public class ICC_Profile implements Serializable {
/** /**
* ICC Profile Rendering Intent: ICC-AbsoluteColorimetric. * ICC Profile Rendering Intent: ICC-AbsoluteColorimetric.
*
* @since 1.5 * @since 1.5
*/ */
public static final int icICCAbsoluteColorimetric = 3; public static final int icICCAbsoluteColorimetric = 3;
@ -369,6 +360,7 @@ public class ICC_Profile implements Serializable {
/** /**
* ICC Profile Tag Signature: 'bXYZ'. * ICC Profile Tag Signature: 'bXYZ'.
*
* @since 1.5 * @since 1.5
*/ */
public static final int icSigBlueMatrixColumnTag = 0x6258595A; /* 'bXYZ' */ public static final int icSigBlueMatrixColumnTag = 0x6258595A; /* 'bXYZ' */
@ -446,6 +438,7 @@ public class ICC_Profile implements Serializable {
/** /**
* ICC Profile Tag Signature: 'gXYZ'. * ICC Profile Tag Signature: 'gXYZ'.
*
* @since 1.5 * @since 1.5
*/ */
public static final int icSigGreenMatrixColumnTag = 0x6758595A;/* 'gXYZ' */ public static final int icSigGreenMatrixColumnTag = 0x6758595A;/* 'gXYZ' */
@ -550,6 +543,7 @@ public class ICC_Profile implements Serializable {
/** /**
* ICC Profile Tag Signature: 'rXYZ'. * ICC Profile Tag Signature: 'rXYZ'.
*
* @since 1.5 * @since 1.5
*/ */
public static final int icSigRedMatrixColumnTag = 0x7258595A; /* 'rXYZ' */ public static final int icSigRedMatrixColumnTag = 0x7258595A; /* 'rXYZ' */
@ -596,18 +590,21 @@ public class ICC_Profile implements Serializable {
/** /**
* ICC Profile Tag Signature: 'chad'. * ICC Profile Tag Signature: 'chad'.
*
* @since 1.5 * @since 1.5
*/ */
public static final int icSigChromaticAdaptationTag = 0x63686164;/* 'chad' */ public static final int icSigChromaticAdaptationTag = 0x63686164;/* 'chad' */
/** /**
* ICC Profile Tag Signature: 'clro'. * ICC Profile Tag Signature: 'clro'.
*
* @since 1.5 * @since 1.5
*/ */
public static final int icSigColorantOrderTag = 0x636C726F; /* 'clro' */ public static final int icSigColorantOrderTag = 0x636C726F; /* 'clro' */
/** /**
* ICC Profile Tag Signature: 'clrt'. * ICC Profile Tag Signature: 'clrt'.
*
* @since 1.5 * @since 1.5
*/ */
public static final int icSigColorantTableTag = 0x636C7274; /* 'clrt' */ public static final int icSigColorantTableTag = 0x636C7274; /* 'clrt' */
@ -695,6 +692,7 @@ public class ICC_Profile implements Serializable {
/** /**
* ICC Profile Header Location: profile's ID. * ICC Profile Header Location: profile's ID.
*
* @since 1.5 * @since 1.5
*/ */
public static final int icHdrProfileID = 84; /* Profile's ID */ public static final int icHdrProfileID = 84; /* Profile's ID */
@ -727,15 +725,14 @@ public class ICC_Profile implements Serializable {
/** /**
* Constructs an ICC_Profile object with a given ID. * Constructs an {@code ICC_Profile} object with a given ID.
*/ */
ICC_Profile(Profile p) { ICC_Profile(Profile p) {
this.cmmProfile = p; this.cmmProfile = p;
} }
/** /**
* Constructs an ICC_Profile object whose loading will be deferred. * Constructs an {@code ICC_Profile} object whose loading will be deferred.
* The ID will be 0 until the profile is loaded. * The ID will be 0 until the profile is loaded.
*/ */
ICC_Profile(ProfileDeferralInfo pdi) { ICC_Profile(ProfileDeferralInfo pdi) {
@ -748,18 +745,18 @@ public class ICC_Profile implements Serializable {
ProfileDeferralMgr.registerDeferral(this.profileActivator); ProfileDeferralMgr.registerDeferral(this.profileActivator);
} }
/** /**
* Frees the resources associated with an ICC_Profile object. * Frees the resources associated with an {@code ICC_Profile} object.
* *
* @deprecated The {@code finalize} method has been deprecated. * @deprecated The {@code finalize} method has been deprecated. Subclasses
* Subclasses that override {@code finalize} in order to perform cleanup * that override {@code finalize} in order to perform cleanup should
* should be modified to use alternative cleanup mechanisms and * be modified to use alternative cleanup mechanisms and to remove
* to remove the overriding {@code finalize} method. * the overriding {@code finalize} method. When overriding the
* When overriding the {@code finalize} method, its implementation must explicitly * {@code finalize} method, its implementation must explicitly
* ensure that {@code super.finalize()} is invoked as described in {@link Object#finalize}. * ensure that {@code super.finalize()} is invoked as described in
* See the specification for {@link Object#finalize()} for further * {@link Object#finalize}. See the specification for {@link
* information about migration options. * Object#finalize()} for further information about migration
* options.
*/ */
@Deprecated(since="9") @Deprecated(since="9")
protected void finalize () { protected void finalize () {
@ -770,14 +767,14 @@ public class ICC_Profile implements Serializable {
} }
} }
/** /**
* Constructs an ICC_Profile object corresponding to the data in * Constructs an {@code ICC_Profile} object corresponding to the data in a
* a byte array. Throws an IllegalArgumentException if the data * byte array. Throws an {@code IllegalArgumentException} if the data does
* does not correspond to a valid ICC Profile. * not correspond to a valid ICC Profile.
* @param data the specified ICC Profile data *
* @return an {@code ICC_Profile} object corresponding to * @param data the specified ICC Profile data
* the data in the specified {@code data} array. * @return an {@code ICC_Profile} object corresponding to the data in the
* specified {@code data} array
*/ */
public static ICC_Profile getInstance(byte[] data) { public static ICC_Profile getInstance(byte[] data) {
ICC_Profile thisProfile; ICC_Profile thisProfile;
@ -821,22 +818,19 @@ public class ICC_Profile implements Serializable {
return thisProfile; return thisProfile;
} }
/** /**
* Constructs an ICC_Profile corresponding to one of the specific color * Constructs an {@code ICC_Profile} corresponding to one of the specific
* spaces defined by the ColorSpace class (for example CS_sRGB). * color spaces defined by the {@code ColorSpace} class (for example
* Throws an IllegalArgumentException if cspace is not one of the * {@code CS_sRGB}). Throws an {@code IllegalArgumentException} if cspace is
* defined color spaces. * not one of the defined color spaces.
* *
* @param cspace the type of color space to create a profile for. * @param cspace the type of color space to create a profile for. The
* The specified type is one of the color * specified type is one of the color space constants defined in the
* space constants defined in the {@code ColorSpace} class. * {@code ColorSpace} class.
* * @return an {@code ICC_Profile} object corresponding to the specified
* @return an {@code ICC_Profile} object corresponding to * {@code ColorSpace} type
* the specified {@code ColorSpace} type. * @throws IllegalArgumentException If {@code cspace} is not one of the
* @exception IllegalArgumentException If {@code cspace} is not * predefined color space types
* one of the predefined color space types.
*/ */
public static ICC_Profile getInstance (int cspace) { public static ICC_Profile getInstance (int cspace) {
ICC_Profile thisProfile = null; ICC_Profile thisProfile = null;
@ -931,51 +925,49 @@ public class ICC_Profile implements Serializable {
return thisProfile; return thisProfile;
} }
/* This asserts system privileges, so is used only for the /**
* standard profiles. * This method asserts system privileges, so is used only for the standard
* profiles.
*/ */
private static ICC_Profile getStandardProfile(final String name) { private static ICC_Profile getStandardProfile(final String name) {
return AccessController.doPrivileged( return AccessController.doPrivileged(
new PrivilegedAction<ICC_Profile>() { new PrivilegedAction<ICC_Profile>() {
public ICC_Profile run() { public ICC_Profile run() {
ICC_Profile p = null; ICC_Profile p = null;
try { try {
p = getInstance (name); p = getInstance(name);
} catch (IOException ex) { } catch (IOException ex) {
throw new IllegalArgumentException( throw new IllegalArgumentException(
"Can't load standard profile: " + name); "Can't load standard profile: " + name);
} }
return p; return p;
} }
}); });
} }
/** /**
* Constructs an ICC_Profile corresponding to the data in a file. * Constructs an {@code ICC_Profile} corresponding to the data in a file.
* fileName may be an absolute or a relative file specification. * {@code fileName} may be an absolute or a relative file specification.
* Relative file names are looked for in several places: first, relative * Relative file names are looked for in several places: first, relative to
* to any directories specified by the java.iccprofile.path property; * any directories specified by the {@code java.iccprofile.path} property;
* second, relative to any directories specified by the java.class.path * second, relative to any directories specified by the
* property; finally, in a directory used to store profiles always * {@code java.class.path} property; finally, in a directory used to store
* available, such as the profile for sRGB. Built-in profiles use .pf as * profiles always available, such as the profile for sRGB. Built-in
* the file name extension for profiles, e.g. sRGB.pf. * profiles use {@code .pf} as the file name extension for profiles, e.g.
* This method throws an IOException if the specified file cannot be * {@code sRGB.pf}. This method throws an {@code IOException} if the
* opened or if an I/O error occurs while reading the file. It throws * specified file cannot be opened or if an I/O error occurs while reading
* an IllegalArgumentException if the file does not contain valid ICC * the file. It throws an {@code IllegalArgumentException} if the file does
* Profile data. * not contain valid ICC Profile data.
* @param fileName The file that contains the data for the profile.
* *
* @return an {@code ICC_Profile} object corresponding to * @param fileName the file that contains the data for the profile
* the data in the specified file. * @return an {@code ICC_Profile} object corresponding to the data in the
* @exception IOException If the specified file cannot be opened or * specified file
* an I/O error occurs while reading the file. * @throws IOException If the specified file cannot be opened or an I/O
* * error occurs while reading the file
* @exception IllegalArgumentException If the file does not * @throws IllegalArgumentException If the file does not contain valid ICC
* contain valid ICC Profile data. * Profile data
* * @throws SecurityException If a security manager is installed and it does
* @exception SecurityException If a security manager is installed * not permit read access to the given file
* and it does not permit read access to the given file.
*/ */
public static ICC_Profile getInstance(String fileName) throws IOException { public static ICC_Profile getInstance(String fileName) throws IOException {
ICC_Profile thisProfile; ICC_Profile thisProfile;
@ -999,21 +991,19 @@ public class ICC_Profile implements Serializable {
return thisProfile; return thisProfile;
} }
/** /**
* Constructs an ICC_Profile corresponding to the data in an InputStream. * Constructs an {@code ICC_Profile} corresponding to the data in an
* This method throws an IllegalArgumentException if the stream does not * {@code InputStream}. This method throws an
* contain valid ICC Profile data. It throws an IOException if an I/O * {@code IllegalArgumentException} if the stream does not contain valid ICC
* error occurs while reading the stream. * Profile data. It throws an {@code IOException} if an I/O error occurs
* @param s The input stream from which to read the profile data. * while reading the stream.
* *
* @return an {@code ICC_Profile} object corresponding to the * @param s the input stream from which to read the profile data
* data in the specified {@code InputStream}. * @return an {@code ICC_Profile} object corresponding to the data in the
* * specified {@code InputStream}
* @exception IOException If an I/O error occurs while reading the stream. * @throws IOException If an I/O error occurs while reading the stream
* * @throws IllegalArgumentException If the stream does not contain valid ICC
* @exception IllegalArgumentException If the stream does not * Profile data
* contain valid ICC Profile data.
*/ */
public static ICC_Profile getInstance(InputStream s) throws IOException { public static ICC_Profile getInstance(InputStream s) throws IOException {
byte[] profileData; byte[] profileData;
@ -1070,17 +1060,15 @@ public class ICC_Profile implements Serializable {
return profileData; return profileData;
} }
/** /**
* Constructs an ICC_Profile for which the actual loading of the * Constructs an {@code ICC_Profile} for which the actual loading of the
* profile data from a file and the initialization of the CMM should * profile data from a file and the initialization of the CMM should be
* be deferred as long as possible. * deferred as long as possible. Deferral is only used for standard
* Deferral is only used for standard profiles. * profiles. If deferring is disabled, then getStandardProfile() ensures
* If deferring is disabled, then getStandardProfile() ensures * that all of the appropriate access privileges are granted when loading
* that all of the appropriate access privileges are granted * this profile. If deferring is enabled, then the deferred activation code
* when loading this profile. * will take care of access privileges.
* If deferring is enabled, then the deferred activation *
* code will take care of access privileges.
* @see #activateDeferredProfile() * @see #activateDeferredProfile()
*/ */
static ICC_Profile getDeferredInstance(ProfileDeferralInfo pdi) { static ICC_Profile getDeferredInstance(ProfileDeferralInfo pdi) {
@ -1131,10 +1119,10 @@ public class ICC_Profile implements Serializable {
} }
} }
/** /**
* Returns profile major version. * Returns profile major version.
* @return The major version of the profile. *
* @return the major version of the profile
*/ */
public int getMajorVersion() { public int getMajorVersion() {
byte[] theHeader; byte[] theHeader;
@ -1147,7 +1135,8 @@ public class ICC_Profile implements Serializable {
/** /**
* Returns profile minor version. * Returns profile minor version.
* @return The minor version of the profile. *
* @return the minor version of the profile
*/ */
public int getMinorVersion() { public int getMinorVersion() {
byte[] theHeader; byte[] theHeader;
@ -1160,7 +1149,8 @@ public class ICC_Profile implements Serializable {
/** /**
* Returns the profile class. * Returns the profile class.
* @return One of the predefined profile class constants. *
* @return one of the predefined profile class constants
*/ */
public int getProfileClass() { public int getProfileClass() {
byte[] theHeader; byte[] theHeader;
@ -1214,16 +1204,16 @@ public class ICC_Profile implements Serializable {
} }
/** /**
* Returns the color space type. Returns one of the color space type * Returns the color space type. Returns one of the color space type
* constants defined by the ColorSpace class. This is the * constants defined by the {@code ColorSpace} class. This is the "input"
* "input" color space of the profile. The type defines the * color space of the profile. The type defines the number of components of
* number of components of the color space and the interpretation, * the color space and the interpretation, e.g. {@code TYPE_RGB} identifies
* e.g. TYPE_RGB identifies a color space with three components - red, * a color space with three components - red, green, and blue. It does not
* green, and blue. It does not define the particular color * define the particular color characteristics of the space, e.g. the
* characteristics of the space, e.g. the chromaticities of the * chromaticities of the primaries.
* primaries. *
* @return One of the color space type constants defined in the * @return one of the color space type constants defined in the
* {@code ColorSpace} class. * {@code ColorSpace} class
*/ */
public int getColorSpaceType() { public int getColorSpaceType() {
if (deferralInfo != null) { if (deferralInfo != null) {
@ -1247,15 +1237,16 @@ public class ICC_Profile implements Serializable {
/** /**
* Returns the color space type of the Profile Connection Space (PCS). * Returns the color space type of the Profile Connection Space (PCS).
* Returns one of the color space type constants defined by the * Returns one of the color space type constants defined by the ColorSpace
* ColorSpace class. This is the "output" color space of the * class. This is the "output" color space of the profile. For an input,
* profile. For an input, display, or output profile useful * display, or output profile useful for tagging colors or images, this will
* for tagging colors or images, this will be either TYPE_XYZ or * be either {@code TYPE_XYZ} or {@code TYPE_Lab} and should be interpreted
* TYPE_Lab and should be interpreted as the corresponding specific * as the corresponding specific color space defined in the ICC
* color space defined in the ICC specification. For a device * specification. For a device link profile, this could be any of the color
* link profile, this could be any of the color space type constants. * space type constants.
* @return One of the color space type constants defined in the *
* {@code ColorSpace} class. * @return one of the color space type constants defined in the
* {@code ColorSpace} class
*/ */
public int getPCSType() { public int getPCSType() {
if (ProfileDeferralMgr.deferring) { if (ProfileDeferralMgr.deferring) {
@ -1275,14 +1266,12 @@ public class ICC_Profile implements Serializable {
return thePCS; return thePCS;
} }
/** /**
* Write this ICC_Profile to a file. * Write this {@code ICC_Profile} to a file.
* *
* @param fileName The file to write the profile data to. * @param fileName the file to write the profile data to
* * @throws IOException If the file cannot be opened for writing or an I/O
* @exception IOException If the file cannot be opened for writing * error occurs while writing to the file
* or an I/O error occurs while writing to the file.
*/ */
public void write(String fileName) throws IOException { public void write(String fileName) throws IOException {
FileOutputStream outputFile; FileOutputStream outputFile;
@ -1295,14 +1284,11 @@ public class ICC_Profile implements Serializable {
outputFile.close (); outputFile.close ();
} }
/** /**
* Write this ICC_Profile to an OutputStream. * Write this {@code ICC_Profile} to an {@code OutputStream}.
* *
* @param s The stream to write the profile data to. * @param s the stream to write the profile data to
* * @throws IOException If an I/O error occurs while writing to the stream
* @exception IOException If an I/O error occurs while writing to the
* stream.
*/ */
public void write(OutputStream s) throws IOException { public void write(OutputStream s) throws IOException {
byte[] profileData; byte[] profileData;
@ -1312,10 +1298,11 @@ public class ICC_Profile implements Serializable {
s.write(profileData); s.write(profileData);
} }
/** /**
* Returns a byte array corresponding to the data of this ICC_Profile. * Returns a byte array corresponding to the data of this
* @return A byte array that contains the profile data. * {@code ICC_Profile}.
*
* @return a byte array that contains the profile data
* @see #setData(int, byte[]) * @see #setData(int, byte[])
*/ */
public byte[] getData() { public byte[] getData() {
@ -1339,20 +1326,17 @@ public class ICC_Profile implements Serializable {
return profileData; return profileData;
} }
/** /**
* Returns a particular tagged data element from the profile as * Returns a particular tagged data element from the profile as a byte
* a byte array. Elements are identified by signatures * array. Elements are identified by signatures as defined in the ICC
* as defined in the ICC specification. The signature * specification. The signature icSigHead can be used to get the header.
* icSigHead can be used to get the header. This method is useful * This method is useful for advanced applets or applications which need to
* for advanced applets or applications which need to access * access profile data directly.
* profile data directly.
* *
* @param tagSignature The ICC tag signature for the data element you * @param tagSignature the ICC tag signature for the data element you want
* want to get. * to get
* * @return a byte array that contains the tagged data element. Returns
* @return A byte array that contains the tagged data element. Returns * {@code null} if the specified tag doesn't exist.
* {@code null} if the specified tag doesn't exist.
* @see #setData(int, byte[]) * @see #setData(int, byte[])
*/ */
public byte[] getData(int tagSignature) { public byte[] getData(int tagSignature) {
@ -1387,20 +1371,20 @@ public class ICC_Profile implements Serializable {
} }
/** /**
* Sets a particular tagged data element in the profile from * Sets a particular tagged data element in the profile from a byte array.
* a byte array. The array should contain data in a format, corresponded * The array should contain data in a format, corresponded to the
* to the {@code tagSignature} as defined in the ICC specification, section 10. * {@code tagSignature} as defined in the ICC specification, section 10.
* This method is useful for advanced applets or applications which need to * This method is useful for advanced applets or applications which need to
* access profile data directly. * access profile data directly.
* *
* @param tagSignature The ICC tag signature for the data element * @param tagSignature the ICC tag signature for the data element you want
* you want to set. * to set
* @param tagData the data to set for the specified tag signature * @param tagData the data to set for the specified tag signature
* @throws IllegalArgumentException if {@code tagSignature} is not a signature * @throws IllegalArgumentException if {@code tagSignature} is not a
* as defined in the ICC specification. * signature as defined in the ICC specification.
* @throws IllegalArgumentException if a content of the {@code tagData} * @throws IllegalArgumentException if a content of the {@code tagData}
* array can not be interpreted as valid tag data, corresponding * array can not be interpreted as valid tag data, corresponding to
* to the {@code tagSignature}. * the {@code tagSignature}
* @see #getData * @see #getData
*/ */
public void setData(int tagSignature, byte[] tagData) { public void setData(int tagSignature, byte[] tagData) {
@ -1413,9 +1397,8 @@ public class ICC_Profile implements Serializable {
} }
/** /**
* Sets the rendering intent of the profile. * Sets the rendering intent of the profile. This is used to select the
* This is used to select the proper transform from a profile that * proper transform from a profile that has multiple transforms.
* has multiple transforms.
*/ */
void setRenderingIntent(int renderingIntent) { void setRenderingIntent(int renderingIntent) {
byte[] theHeader = getData(icSigHead);/* getData will activate deferred byte[] theHeader = getData(icSigHead);/* getData will activate deferred
@ -1425,12 +1408,11 @@ public class ICC_Profile implements Serializable {
setData (icSigHead, theHeader); setData (icSigHead, theHeader);
} }
/** /**
* Returns the rendering intent of the profile. * Returns the rendering intent of the profile. This is used to select the
* This is used to select the proper transform from a profile that * proper transform from a profile that has multiple transforms. It is
* has multiple transforms. It is typically set in a source profile * typically set in a source profile to select a transform from an output
* to select a transform from an output profile. * profile.
*/ */
int getRenderingIntent() { int getRenderingIntent() {
byte[] theHeader = getData(icSigHead);/* getData will activate deferred byte[] theHeader = getData(icSigHead);/* getData will activate deferred
@ -1449,17 +1431,13 @@ public class ICC_Profile implements Serializable {
return (0xffff & renderingIntent); return (0xffff & renderingIntent);
} }
/** /**
* Returns the number of color components in the "input" color * Returns the number of color components in the "input" color space of this
* space of this profile. For example if the color space type * profile. For example if the color space type of this profile is
* of this profile is TYPE_RGB, then this method will return 3. * {@code TYPE_RGB}, then this method will return 3.
* *
* @return The number of color components in the profile's input * @return the number of color components in the profile's input color space
* color space. * @throws ProfileDataException if color space is in the profile is invalid
*
* @throws ProfileDataException if color space is in the profile
* is invalid
*/ */
public int getNumComponents() { public int getNumComponents() {
byte[] theHeader; byte[] theHeader;
@ -1553,20 +1531,18 @@ public class ICC_Profile implements Serializable {
return theNumComponents; return theNumComponents;
} }
/** /**
* Returns a float array of length 3 containing the X, Y, and Z * Returns a float array of length 3 containing the X, Y, and Z components
* components of the mediaWhitePointTag in the ICC profile. * of the mediaWhitePointTag in the ICC profile.
*/ */
float[] getMediaWhitePoint() { float[] getMediaWhitePoint() {
return getXYZTag(icSigMediaWhitePointTag); return getXYZTag(icSigMediaWhitePointTag);
/* get the media white point tag */ /* get the media white point tag */
} }
/** /**
* Returns a float array of length 3 containing the X, Y, and Z * Returns a float array of length 3 containing the X, Y, and Z components
* components encoded in an XYZType tag. * encoded in an XYZType tag.
*/ */
float[] getXYZTag(int theTagSignature) { float[] getXYZTag(int theTagSignature) {
byte[] theData; byte[] theData;
@ -1587,17 +1563,17 @@ public class ICC_Profile implements Serializable {
return theXYZNumber; return theXYZNumber;
} }
/** /**
* Returns a gamma value representing a tone reproduction * Returns a gamma value representing a tone reproduction curve (TRC). If
* curve (TRC). If the profile represents the TRC as a table rather * the profile represents the TRC as a table rather than a single gamma
* than a single gamma value, then an exception is thrown. In this * value, then an exception is thrown. In this case the actual table can be
* case the actual table can be obtained via getTRC(). * obtained via {@link #getTRC}. {@code theTagSignature} should be one of
* theTagSignature should be one of icSigGrayTRCTag, icSigRedTRCTag, * {@code icSigGrayTRCTag}, {@code icSigRedTRCTag},
* icSigGreenTRCTag, or icSigBlueTRCTag. * {@code icSigGreenTRCTag}, or {@code icSigBlueTRCTag}.
* @return the gamma value as a float. *
* @exception ProfileDataException if the profile does not specify * @return the gamma value as a float
* the TRC as a single gamma value. * @throws ProfileDataException if the profile does not specify the TRC as a
* single gamma value
*/ */
float getGamma(int theTagSignature) { float getGamma(int theTagSignature) {
byte[] theTRCData; byte[] theTRCData;
@ -1620,26 +1596,25 @@ public class ICC_Profile implements Serializable {
return theGamma; return theGamma;
} }
/** /**
* Returns the TRC as an array of shorts. If the profile has * Returns the TRC as an array of shorts. If the profile has specified the
* specified the TRC as linear (gamma = 1.0) or as a simple gamma * TRC as linear (gamma = 1.0) or as a simple gamma value, this method
* value, this method throws an exception, and the getGamma() method * throws an exception, and the {@link #getGamma} method should be used to
* should be used to get the gamma value. Otherwise the short array * get the gamma value. Otherwise the short array returned here represents a
* returned here represents a lookup table where the input Gray value * lookup table where the input Gray value is conceptually in the range
* is conceptually in the range [0.0, 1.0]. Value 0.0 maps * [0.0, 1.0]. Value 0.0 maps to array index 0 and value 1.0 maps to array
* to array index 0 and value 1.0 maps to array index length-1. * index length-1. Interpolation may be used to generate output values for
* Interpolation may be used to generate output values for * input values which do not map exactly to an index in the array. Output
* input values which do not map exactly to an index in the * values also map linearly to the range [0.0, 1.0]. Value 0.0 is
* array. Output values also map linearly to the range [0.0, 1.0]. * represented by an array value of 0x0000 and value 1.0 by 0xFFFF, i.e. the
* Value 0.0 is represented by an array value of 0x0000 and * values are really unsigned short values, although they are returned in a
* value 1.0 by 0xFFFF, i.e. the values are really unsigned * short array. {@code theTagSignature} should be one of
* short values, although they are returned in a short array. * {@code icSigGrayTRCTag}, {@code icSigRedTRCTag},
* theTagSignature should be one of icSigGrayTRCTag, icSigRedTRCTag, * {@code icSigGreenTRCTag}, or {@code icSigBlueTRCTag}.
* icSigGreenTRCTag, or icSigBlueTRCTag. *
* @return a short array representing the TRC. * @return a short array representing the TRC
* @exception ProfileDataException if the profile does not specify * @throws ProfileDataException if the profile does not specify the TRC as a
* the TRC as a table. * table
*/ */
short[] getTRC(int theTagSignature) { short[] getTRC(int theTagSignature) {
byte[] theTRCData; byte[] theTRCData;
@ -1666,8 +1641,9 @@ public class ICC_Profile implements Serializable {
return theTRC; return theTRC;
} }
/**
/* convert an ICC color space signature into a Java color space type */ * Convert an ICC color space signature into a Java color space type.
*/
static int iccCStoJCS(int theColorSpaceSig) { static int iccCStoJCS(int theColorSpaceSig) {
int theColorSpace; int theColorSpace;
@ -1775,7 +1751,6 @@ public class ICC_Profile implements Serializable {
default: default:
throw new IllegalArgumentException ("Unknown color space"); throw new IllegalArgumentException ("Unknown color space");
} }
return theColorSpace; return theColorSpace;
} }
@ -1807,17 +1782,16 @@ public class ICC_Profile implements Serializable {
array[index+1] = (byte) (value); array[index+1] = (byte) (value);
} }
/**
/* * {@code fileName} may be an absolute or a relative file specification.
* fileName may be an absolute or a relative file specification. * Relative file names are looked for in several places: first, relative to
* Relative file names are looked for in several places: first, relative * any directories specified by the {@code java.iccprofile.path} property;
* to any directories specified by the java.iccprofile.path property; * second, relative to any directories specified by the
* second, relative to any directories specified by the java.class.path. * {@code java.class.path}. The built-in profile files are now loaded as
* The built-in profile files are now loaded as resources, since they * resources, since they may not be individual disk files, and so this
* may not be individual disk files, and so this method will not find * method will not find these and on a {@code null} return, the caller needs
* these and on a null return, the caller needs to try as resources. * to try as resources. Built-in profiles use {@code .pf} as the file name
* Built-in profiles use .pf as the file name extension for profiles, * extension for profiles, e.g. {@code sRGB.pf}.
* e.g. sRGB.pf.
*/ */
private static File getProfileFile(String fileName) { private static File getProfileFile(String fileName) {
String path, dir, fullPath; String path, dir, fullPath;
@ -1862,10 +1836,9 @@ public class ICC_Profile implements Serializable {
} }
/** /**
* Returns a stream corresponding to a built-in profile * Returns a stream corresponding to a built-in profile specified by
* specified by fileName. * fileName. If there is no built-in profile with such name, then the method
* If there is no built-in profile with such name, then the method * returns {@code null}.
* returns null.
*/ */
private static InputStream getStandardProfileInputStream(String fileName) { private static InputStream getStandardProfileInputStream(String fileName) {
return AccessController.doPrivileged( return AccessController.doPrivileged(
@ -1909,68 +1882,58 @@ public class ICC_Profile implements Serializable {
}); });
} }
/* /*
* Serialization support. * Serialization support.
* *
* Directly deserialized profiles are useless since they are not * Directly deserialized profiles are useless since they are not registered
* registered with CMM. We don't allow constructor to be called * with CMM. We don't allow constructor to be called directly and instead
* directly and instead have clients to call one of getInstance * have clients to call one of getInstance factory methods that will
* factory methods that will register the profile with CMM. For * register the profile with CMM. For deserialization we implement
* deserialization we implement readResolve method that will * readResolve method that will resolve the bogus deserialized profile
* resolve the bogus deserialized profile object with one obtained * object with one obtained with getInstance as well.
* with getInstance as well.
* *
* There are two primary factory methods for construction of ICC * There are two primary factory methods for construction of ICC profiles:
* profiles: getInstance(int cspace) and getInstance(byte[] data). * getInstance(int cspace) and getInstance(byte[] data). This implementation
* This implementation of ICC_Profile uses the former to return a * of ICC_Profile uses the former to return a cached singleton profile
* cached singleton profile object, other implementations will * object, other implementations will likely use this technique too. To
* likely use this technique too. To preserve the singleton * preserve the singleton pattern across serialization we serialize cached
* pattern across serialization we serialize cached singleton * singleton profiles in such a way that deserializing VM could call
* profiles in such a way that deserializing VM could call * getInstance(int cspace) method that will resolve deserialized object into
* getInstance(int cspace) method that will resolve deserialized * the corresponding singleton as well.
* object into the corresponding singleton as well.
* *
* Since the singletons are private to ICC_Profile the readResolve * Since the singletons are private to ICC_Profile the readResolve method
* method have to be `protected' instead of `private' so that * have to be `protected' instead of `private' so that singletons that are
* singletons that are instances of subclasses of ICC_Profile * instances of subclasses of ICC_Profile could be correctly deserialized.
* could be correctly deserialized.
*/ */
/** /**
* Version of the format of additional serialized data in the * Version of the format of additional serialized data in the stream.
* stream. Version&nbsp;{@code 1} corresponds to Java&nbsp;2 * Version&nbsp;{@code 1} corresponds to Java&nbsp;2 Platform,&nbsp;v1.3.
* Platform,&nbsp;v1.3. *
* @since 1.3
* @serial * @serial
* @since 1.3
*/ */
private int iccProfileSerializedDataVersion = 1; private int iccProfileSerializedDataVersion = 1;
/** /**
* Writes default serializable fields to the stream. Writes a * Writes default serializable fields to the stream. Writes a string and an
* string and an array of bytes to the stream as additional data. * array of bytes to the stream as additional data.
* *
* @param s stream used for serialization. * @param s stream used for serialization
* @throws IOException * @throws IOException thrown by {@code ObjectInputStream}
* thrown by {@code ObjectInputStream}. * @serialData the {@code String} is the name of one of
* @serialData * <code>CS_<var>*</var></code> constants defined in the
* The {@code String} is the name of one of * {@link ColorSpace} class if the profile object is a profile for a
* <code>CS_<var>*</var></code> constants defined in the * predefined color space (for example {@code "CS_sRGB"}). The
* {@link ColorSpace} class if the profile object is a profile * string is {@code null} otherwise.
* for a predefined color space (for example * <p>
* {@code "CS_sRGB"}). The string is {@code null} * The {@code byte[]} array is the profile data for the profile. For
* otherwise. * predefined color spaces {@code null} is written instead of the
* <p> * profile data. If in the future versions of Java API new
* The {@code byte[]} array is the profile data for the * predefined color spaces will be added, future versions of this
* profile. For predefined color spaces {@code null} is * class may choose to write for new predefined color spaces not
* written instead of the profile data. If in the future * only the color space name, but the profile data as well so that
* versions of Java API new predefined color spaces will be * older versions could still deserialize the object.
* added, future versions of this class may choose to write
* for new predefined color spaces not only the color space
* name, but the profile data as well so that older versions
* could still deserialize the object.
*/ */
private void writeObject(ObjectOutputStream s) private void writeObject(ObjectOutputStream s)
throws IOException throws IOException
@ -2009,33 +1972,30 @@ public class ICC_Profile implements Serializable {
private transient ICC_Profile resolvedDeserializedProfile; private transient ICC_Profile resolvedDeserializedProfile;
/** /**
* Reads default serializable fields from the stream. Reads from * Reads default serializable fields from the stream. Reads from the stream
* the stream a string and an array of bytes as additional data. * a string and an array of bytes as additional data.
* *
* @param s stream used for deserialization. * @param s stream used for deserialization
* @throws IOException * @throws IOException thrown by {@code ObjectInputStream}
* thrown by {@code ObjectInputStream}. * @throws ClassNotFoundException thrown by {@code
* @throws ClassNotFoundException * ObjectInputStream}
* thrown by {@code ObjectInputStream}. * @serialData the {@code String} is the name of one of
* @serialData * <code>CS_<var>*</var></code> constants defined in the
* The {@code String} is the name of one of * {@link ColorSpace} class if the profile object is a profile for a
* <code>CS_<var>*</var></code> constants defined in the * predefined color space (for example {@code "CS_sRGB"}). The
* {@link ColorSpace} class if the profile object is a profile * string is {@code null} otherwise.
* for a predefined color space (for example * <p>
* {@code "CS_sRGB"}). The string is {@code null} * The {@code byte[]} array is the profile data for the profile. It
* otherwise. * will usually be {@code null} for the predefined profiles.
* <p> * <p>
* The {@code byte[]} array is the profile data for the * If the string is recognized as a constant name for predefined
* profile. It will usually be {@code null} for the * color space the object will be resolved into profile obtained
* predefined profiles. * with
* <p> * <code>getInstance(int&nbsp;cspace)</code> and the profile data
* If the string is recognized as a constant name for * are
* predefined color space the object will be resolved into * ignored. Otherwise the object will be resolved into profile
* profile obtained with * obtained with
* <code>getInstance(int&nbsp;cspace)</code> and the profile * <code>getInstance(byte[]&nbsp;data)</code>.
* data are ignored. Otherwise the object will be resolved
* into profile obtained with
* <code>getInstance(byte[]&nbsp;data)</code>.
* @see #readResolve() * @see #readResolve()
* @see #getInstance(int) * @see #getInstance(int)
* @see #getInstance(byte[]) * @see #getInstance(byte[])
@ -2075,11 +2035,11 @@ public class ICC_Profile implements Serializable {
} }
/** /**
* Resolves instances being deserialized into instances registered * Resolves instances being deserialized into instances registered with CMM.
* with CMM. *
* @return ICC_Profile object for profile registered with CMM. * @return ICC_Profile object for profile registered with CMM
* @throws ObjectStreamException * @throws ObjectStreamException never thrown, but mandated by the
* never thrown, but mandated by the serialization spec. * serialization spec
* @since 1.3 * @since 1.3
*/ */
protected Object readResolve() throws ObjectStreamException { protected Object readResolve() throws ObjectStreamException {

132
src/java.desktop/share/classes/java/awt/color/ICC_ProfileGray.java
View File

@ -1,5 +1,5 @@
/* /*
* Copyright (c) 1997, 2013, Oracle and/or its affiliates. All rights reserved. * Copyright (c) 1997, 2018, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
* *
* This code is free software; you can redistribute it and/or modify it * This code is free software; you can redistribute it and/or modify it
@ -23,8 +23,7 @@
* questions. * questions.
*/ */
/* /* ********************************************************************
**********************************************************************
********************************************************************** **********************************************************************
********************************************************************** **********************************************************************
*** COPYRIGHT (c) Eastman Kodak Company, 1997 *** *** COPYRIGHT (c) Eastman Kodak Company, 1997 ***
@ -40,80 +39,81 @@ import sun.java2d.cmm.Profile;
import sun.java2d.cmm.ProfileDeferralInfo; import sun.java2d.cmm.ProfileDeferralInfo;
/** /**
* * The {@code ICC_ProfileGray} class is a subclass of the {@code ICC_Profile}
* A subclass of the ICC_Profile class which represents profiles * class that represents profiles which meet the following criteria: the color
* which meet the following criteria: the color space type of the * space type of the profile is {@code TYPE_GRAY} and the profile includes the
* profile is TYPE_GRAY and the profile includes the grayTRCTag and * {@code grayTRCTag} and {@code mediaWhitePointTag} tags. The
* mediaWhitePointTag tags. Examples of this kind of profile are * {@code getInstance} methods in the {@code ICC_Profile} class will return an
* monochrome input profiles, monochrome display profiles, and * {@code ICC_ProfileGray} object when the above conditions are met. Examples of
* monochrome output profiles. The getInstance methods in the * this kind of profile are monochrome input profiles, monochrome display
* ICC_Profile class will * profiles, and monochrome output profiles.
* return an ICC_ProfileGray object when the above conditions are * <p>
* met. The advantage of this class is that it provides a lookup * The advantage of this class is that it provides a lookup table that Java
* table that Java or native methods may be able to use directly to * or native methods can use directly to optimize color conversion in some
* optimize color conversion in some cases. * cases.
* <p> * <p>
* To transform from a GRAY device profile color space to the CIEXYZ Profile * To transform from a GRAY device profile color space to the CIEXYZ Profile
* Connection Space, the device gray component is transformed by * Connection Space, the device gray component is transformed by a lookup
* a lookup through the tone reproduction curve (TRC). The result is * through the tone reproduction curve (TRC). The result is treated as the
* treated as the achromatic component of the PCS. * achromatic component of the PCS.
<pre> * <pre>
*
&nbsp; PCSY = grayTRC[deviceGray] * &nbsp; PCSY = grayTRC[deviceGray]
*
</pre> * </pre>
* The inverse transform is done by converting the PCS Y components to * The inverse transform is done by converting the PCS Y components to device
* device Gray via the inverse of the grayTRC. * Gray via the inverse of the grayTRC.
*/ */
public class ICC_ProfileGray public class ICC_ProfileGray
extends ICC_Profile { extends ICC_Profile {
/**
* Use serialVersionUID from JDK 1.2 for interoperability.
*/
static final long serialVersionUID = -1124721290732002649L; static final long serialVersionUID = -1124721290732002649L;
/** /**
* Constructs a new ICC_ProfileGray from a CMM ID. * Constructs a new {@code ICC_ProfileGray} from a CMM ID.
*/ */
ICC_ProfileGray(Profile p) { ICC_ProfileGray(Profile p) {
super(p); super(p);
} }
/** /**
* Constructs a new ICC_ProfileGray from a ProfileDeferralInfo object. * Constructs a new {@code ICC_ProfileGray} from a
* {@code ProfileDeferralInfo} object.
*/ */
ICC_ProfileGray(ProfileDeferralInfo pdi) { ICC_ProfileGray(ProfileDeferralInfo pdi) {
super(pdi); super(pdi);
} }
/** /**
* Returns a float array of length 3 containing the X, Y, and Z * Returns a float array of length 3 containing the X, Y, and Z components
* components of the mediaWhitePointTag in the ICC profile. * of the mediaWhitePointTag in the ICC profile.
* @return an array containing the components of the *
* mediaWhitePointTag in the ICC profile. * @return an array containing the components of the mediaWhitePointTag in
* the ICC profile
*/ */
public float[] getMediaWhitePoint() { public float[] getMediaWhitePoint() {
return super.getMediaWhitePoint(); return super.getMediaWhitePoint();
} }
/** /**
* Returns a gamma value representing the tone reproduction * Returns a gamma value representing the tone reproduction curve (TRC). If
* curve (TRC). If the profile represents the TRC as a table rather * the profile represents the TRC as a table rather than a single gamma
* than a single gamma value, then an exception is thrown. In this * value, then an exception is thrown. In this case the actual table can be
* case the actual table can be obtained via getTRC(). When * obtained via {@code getTRC()}. When using a gamma value, the PCS Y
* using a gamma value, the PCS Y component is computed as follows: * component is computed as follows:
<pre> * <pre>
*
&nbsp; gamma * &nbsp; gamma
&nbsp; PCSY = deviceGray * &nbsp; PCSY = deviceGray
*
</pre> * </pre>
* @return the gamma value as a float. *
* @exception ProfileDataException if the profile does not specify * @return the gamma value as a float
* the TRC as a single gamma value. * @throws ProfileDataException if the profile does not specify the TRC as a
* single gamma value
*/ */
public float getGamma() { public float getGamma() {
float theGamma; float theGamma;
@ -123,22 +123,22 @@ extends ICC_Profile {
} }
/** /**
* Returns the TRC as an array of shorts. If the profile has * Returns the TRC as an array of shorts. If the profile has specified the
* specified the TRC as linear (gamma = 1.0) or as a simple gamma * TRC as linear (gamma = 1.0) or as a simple gamma value, this method
* value, this method throws an exception, and the getGamma() method * throws an exception, and the {@code getGamma()} method should be used to
* should be used to get the gamma value. Otherwise the short array * get the gamma value. Otherwise the short array returned here represents a
* returned here represents a lookup table where the input Gray value * lookup table where the input Gray value is conceptually in the range
* is conceptually in the range [0.0, 1.0]. Value 0.0 maps * [0.0, 1.0]. Value 0.0 maps to array index 0 and value 1.0 maps to array
* to array index 0 and value 1.0 maps to array index length-1. * index {@code length-1}. Interpolation may be used to generate output
* Interpolation may be used to generate output values for * values for input values which do not map exactly to an index in the
* input values which do not map exactly to an index in the * array. Output values also map linearly to the range [0.0, 1.0]. Value 0.0
* array. Output values also map linearly to the range [0.0, 1.0]. * is represented by an array value of 0x0000 and value 1.0 by 0xFFFF, i.e.
* Value 0.0 is represented by an array value of 0x0000 and * the values are really unsigned short values, although they are returned
* value 1.0 by 0xFFFF, i.e. the values are really unsigned * in a short array.
* short values, although they are returned in a short array. *
* @return a short array representing the TRC. * @return a short array representing the TRC
* @exception ProfileDataException if the profile does not specify * @throws ProfileDataException if the profile does not specify the TRC as a
* the TRC as a table. * table
*/ */
public short[] getTRC() { public short[] getTRC() {
short[] theTRC; short[] theTRC;

156
src/java.desktop/share/classes/java/awt/color/ICC_ProfileRGB.java
View File

@ -1,5 +1,5 @@
/* /*
* Copyright (c) 1997, 2013, Oracle and/or its affiliates. All rights reserved. * Copyright (c) 1997, 2018, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
* *
* This code is free software; you can redistribute it and/or modify it * This code is free software; you can redistribute it and/or modify it
@ -23,8 +23,7 @@
* questions. * questions.
*/ */
/* /* ********************************************************************
**********************************************************************
********************************************************************** **********************************************************************
********************************************************************** **********************************************************************
*** COPYRIGHT (c) Eastman Kodak Company, 1997 *** *** COPYRIGHT (c) Eastman Kodak Company, 1997 ***
@ -40,30 +39,25 @@ import sun.java2d.cmm.Profile;
import sun.java2d.cmm.ProfileDeferralInfo; import sun.java2d.cmm.ProfileDeferralInfo;
/** /**
* * The {@code ICC_ProfileRGB} class is a subclass of the {@code ICC_Profile}
* The ICC_ProfileRGB class is a subclass of the ICC_Profile class * class that represents profiles which meet the following criteria: the
* that represents profiles which meet the following criteria: * profile's color space type is RGB, and the profile includes the
* <ul> * {@code redColorantTag}, {@code greenColorantTag}, {@code blueColorantTag},
* <li>The profile's color space type is RGB.</li> * {@code redTRCTag}, {@code greenTRCTag}, {@code blueTRCTag},
* <li>The profile includes the {@code redColorantTag}, * {@code mediaWhitePointTag} tags. The {@code getInstance} methods in the
* {@code greenColorantTag}, {@code blueColorantTag}, * {@code ICC_Profile} class will return an {@code ICC_ProfileRGB} object when
* {@code redTRCTag}, {@code greenTRCTag}, * the above conditions are met. Three-component, matrix-based input profiles
* {@code blueTRCTag}, and {@code mediaWhitePointTag} tags.</li> * and RGB display profiles are examples of this type of profile.
* </ul>
* The {@code ICC_Profile getInstance} method will
* return an {@code ICC_ProfileRGB} object when these conditions are met.
* Three-component, matrix-based input profiles and RGB display profiles are
* examples of this type of profile.
* <p> * <p>
* This profile class provides color transform matrices and lookup tables * The advantage of this class is that it provides color transform matrices and
* that Java or native methods can use directly to * lookup tables that Java or native methods can use directly to optimize color
* optimize color conversion in some cases. * conversion in some cases.
* <p> * <p>
* To transform from a device profile color space to the CIEXYZ Profile * To transform from a device profile color space to the CIEXYZ Profile
* Connection Space, each device color component is first linearized by * Connection Space, each device color component is first linearized by a lookup
* a lookup through the corresponding tone reproduction curve (TRC). * through the corresponding tone reproduction curve (TRC). The resulting linear
* The resulting linear RGB components are converted to the CIEXYZ PCS * RGB components are converted to the CIEXYZ PCS using a a 3x3 matrix
* using a a 3x3 matrix constructed from the RGB colorants. * constructed from the RGB colorants.
* <pre> * <pre>
* *
* &nbsp; linearR = redTRC[deviceR] * &nbsp; linearR = redTRC[deviceR]
@ -81,12 +75,9 @@ import sun.java2d.cmm.ProfileDeferralInfo;
* *
* </pre> * </pre>
* The inverse transform is performed by converting PCS XYZ components to linear * The inverse transform is performed by converting PCS XYZ components to linear
* RGB components through the inverse of the above 3x3 matrix, and then converting * RGB components through the inverse of the above 3x3 matrix, and then
* linear RGB to device RGB through inverses of the TRCs. * converting linear RGB to device RGB through inverses of the TRCs.
*/ */
public class ICC_ProfileRGB public class ICC_ProfileRGB
extends ICC_Profile { extends ICC_Profile {
@ -107,12 +98,10 @@ extends ICC_Profile {
*/ */
public static final int BLUECOMPONENT = 2; public static final int BLUECOMPONENT = 2;
/** /**
* Constructs an new {@code ICC_ProfileRGB} from a CMM ID. * Constructs an new {@code ICC_ProfileRGB} from a CMM ID.
* *
* @param p The CMM ID for the profile. * @param p the CMM ID for the profile.
*
*/ */
ICC_ProfileRGB(Profile p) { ICC_ProfileRGB(Profile p) {
super(p); super(p);
@ -120,7 +109,7 @@ extends ICC_Profile {
/** /**
* Constructs a new {@code ICC_ProfileRGB} from a * Constructs a new {@code ICC_ProfileRGB} from a
* ProfileDeferralInfo object. * {@code ProfileDeferralInfo} object.
* *
* @param pdi * @param pdi
*/ */
@ -128,31 +117,28 @@ extends ICC_Profile {
super(pdi); super(pdi);
} }
/** /**
* Returns an array that contains the components of the profile's * Returns an array that contains the components of the profile's
* {@code mediaWhitePointTag}. * {@code mediaWhitePointTag}.
* *
* @return A 3-element {@code float} array containing the x, y, * @return a 3-element {@code float} array containing the x, y, and z
* and z components of the profile's {@code mediaWhitePointTag}. * components of the profile's {@code mediaWhitePointTag}
*/ */
public float[] getMediaWhitePoint() { public float[] getMediaWhitePoint() {
return super.getMediaWhitePoint(); return super.getMediaWhitePoint();
} }
/** /**
* Returns a 3x3 {@code float} matrix constructed from the * Returns a 3x3 {@code float} matrix constructed from the X, Y, and Z
* X, Y, and Z components of the profile's {@code redColorantTag},
* {@code greenColorantTag}, and {@code blueColorantTag}.
* <p>
* This matrix can be used for color transforms in the forward
* direction of the profile--from the profile color space
* to the CIEXYZ PCS.
*
* @return A 3x3 {@code float} array that contains the x, y, and z
* components of the profile's {@code redColorantTag}, * components of the profile's {@code redColorantTag},
* {@code greenColorantTag}, and {@code blueColorantTag}. * {@code greenColorantTag}, and {@code blueColorantTag}.
* <p>
* This matrix can be used for color transforms in the forward direction of
* the profile--from the profile color space to the CIEXYZ PCS.
*
* @return a 3x3 {@code float} array that contains the x, y, and z
* components of the profile's {@code redColorantTag},
* {@code greenColorantTag}, and {@code blueColorantTag}
*/ */
public float[][] getMatrix() { public float[][] getMatrix() {
float[][] theMatrix = new float[3][3]; float[][] theMatrix = new float[3][3];
@ -174,28 +160,27 @@ extends ICC_Profile {
} }
/** /**
* Returns a gamma value representing the tone reproduction curve * Returns a gamma value representing the tone reproduction curve (TRC) for
* (TRC) for a particular component. The component parameter * a particular component. The component parameter must be one of
* must be one of REDCOMPONENT, GREENCOMPONENT, or BLUECOMPONENT. * {@code REDCOMPONENT}, {@code GREENCOMPONENT}, or {@code BLUECOMPONENT}.
* <p> * <p>
* If the profile * If the profile represents the TRC for the corresponding component as a
* represents the TRC for the corresponding component * table rather than a single gamma value, an exception is thrown. In this
* as a table rather than a single gamma value, an * case the actual table can be obtained through the {@link #getTRC(int)}
* exception is thrown. In this case the actual table * method. When using a gamma value, the linear component (R, G, or B) is
* can be obtained through the {@link #getTRC(int)} method. * computed as follows:
* When using a gamma value,
* the linear component (R, G, or B) is computed as follows:
* <pre> * <pre>
* *
* &nbsp; gamma * &nbsp; gamma
* &nbsp; linearComponent = deviceComponent * &nbsp; linearComponent = deviceComponent
* *
*</pre> * </pre>
* @param component The {@code ICC_ProfileRGB} constant that *
* represents the component whose TRC you want to retrieve * @param component the {@code ICC_ProfileRGB} constant that represents the
* @return the gamma value as a float. * component whose TRC you want to retrieve
* @exception ProfileDataException if the profile does not specify * @return the gamma value as a float
* the corresponding TRC as a single gamma value. * @throws ProfileDataException if the profile does not specify the
* corresponding TRC as a single gamma value
*/ */
public float getGamma(int component) { public float getGamma(int component) {
float theGamma; float theGamma;
@ -224,34 +209,29 @@ extends ICC_Profile {
} }
/** /**
* Returns the TRC for a particular component as an array. * Returns the TRC for a particular component as an array. Component must be
* Component must be {@code REDCOMPONENT}, * {@code REDCOMPONENT}, {@code GREENCOMPONENT}, or {@code BLUECOMPONENT}.
* {@code GREENCOMPONENT}, or {@code BLUECOMPONENT}. * Otherwise the returned array represents a lookup table where the input
* Otherwise the returned array * component value is conceptually in the range [0.0, 1.0]. Value 0.0 maps
* represents a lookup table where the input component value * to array index 0 and value 1.0 maps to array index {@code length-1}.
* is conceptually in the range [0.0, 1.0]. Value 0.0 maps * Interpolation might be used to generate output values for input values
* to array index 0 and value 1.0 maps to array index length-1. * that do not map exactly to an index in the array. Output values also map
* Interpolation might be used to generate output values for * linearly to the range [0.0, 1.0]. Value 0.0 is represented by an array
* input values that do not map exactly to an index in the * value of 0x0000 and value 1.0 by 0xFFFF. In other words, the values are
* array. Output values also map linearly to the range [0.0, 1.0]. * really unsigned {@code short} values even though they are returned in a
* Value 0.0 is represented by an array value of 0x0000 and
* value 1.0 by 0xFFFF. In other words, the values are really unsigned
* {@code short} values even though they are returned in a
* {@code short} array. * {@code short} array.
* <p>
* If the profile has specified the corresponding TRC as linear (gamma =
* 1.0) or as a simple gamma value, this method throws an exception. In this
* case, the {@link #getGamma(int)} method should be used to get the gamma
* value.
* *
* If the profile has specified the corresponding TRC * @param component the {@code ICC_ProfileRGB} constant that represents the
* as linear (gamma = 1.0) or as a simple gamma value, this method * component whose TRC you want to retrieve: {@code REDCOMPONENT},
* throws an exception. In this case, the {@link #getGamma(int)} * {@code GREENCOMPONENT}, or {@code BLUECOMPONENT}
* method should be used to get the gamma value. * @return a short array representing the TRC
* * @throws ProfileDataException if the profile does not specify the
* @param component The {@code ICC_ProfileRGB} constant that * corresponding TRC as a table
* represents the component whose TRC you want to retrieve:
* {@code REDCOMPONENT}, {@code GREENCOMPONENT}, or
* {@code BLUECOMPONENT}.
*
* @return a short array representing the TRC.
* @exception ProfileDataException if the profile does not specify
* the corresponding TRC as a table.
*/ */
public short[] getTRC(int component) { public short[] getTRC(int component) {
short[] theTRC; short[] theTRC;

19
src/java.desktop/share/classes/java/awt/color/ProfileDataException.java
View File

@ -1,5 +1,5 @@
/* /*
* Copyright (c) 1997, 2014, Oracle and/or its affiliates. All rights reserved. * Copyright (c) 1997, 2018, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
* *
* This code is free software; you can redistribute it and/or modify it * This code is free software; you can redistribute it and/or modify it
@ -26,18 +26,23 @@
package java.awt.color; package java.awt.color;
/** /**
* This exception is thrown when an error occurs in accessing or * This exception is thrown when an error occurs in accessing or processing an
* processing an ICC_Profile object. * {@code ICC_Profile} object.
*/ */
public class ProfileDataException extends java.lang.RuntimeException { public class ProfileDataException extends java.lang.RuntimeException {
/**
* Use serialVersionUID from JDK 1.2 for interoperability.
*/
private static final long serialVersionUID = 7286140888240322498L; private static final long serialVersionUID = 7286140888240322498L;
/** /**
* Constructs a ProfileDataException with the specified detail message. * Constructs a {@code ProfileDataException} with the specified detail
* @param s the specified detail message * message.
*
* @param s the specified detail message
*/ */
public ProfileDataException(String s) { public ProfileDataException(String s) {
super (s); super(s);
} }
} }