< prev index next >
src/java.desktop/share/classes/java/awt/AlphaComposite.java
Print this page
*** 28,38 ****
import java.awt.image.ColorModel;
import java.lang.annotation.Native;
import sun.java2d.SunCompositeContext;
/**
! * The <code>AlphaComposite</code> class implements basic alpha
* compositing rules for combining source and destination colors
* to achieve blending and transparency effects with graphics and
* images.
* The specific rules implemented by this class are the basic set
* of 12 rules described in
--- 28,38 ----
import java.awt.image.ColorModel;
import java.lang.annotation.Native;
import sun.java2d.SunCompositeContext;
/**
! * The {@code AlphaComposite} class implements basic alpha
* compositing rules for combining source and destination colors
* to achieve blending and transparency effects with graphics and
* images.
* The specific rules implemented by this class are the basic set
* of 12 rules described in
*** 42,60 ****
* definitions and concepts outlined in that paper.
*
* <p>
* This class extends the standard equations defined by Porter and
* Duff to include one additional factor.
! * An instance of the <code>AlphaComposite</code> class can contain
* an alpha value that is used to modify the opacity or coverage of
* every source pixel before it is used in the blending equations.
*
* <p>
* It is important to note that the equations defined by the Porter
* and Duff paper are all defined to operate on color components
* that are premultiplied by their corresponding alpha components.
! * Since the <code>ColorModel</code> and <code>Raster</code> classes
* allow the storage of pixel data in either premultiplied or
* non-premultiplied form, all input data must be normalized into
* premultiplied form before applying the equations and all results
* might need to be adjusted back to the form required by the destination
* before the pixel values are stored.
--- 42,60 ----
* definitions and concepts outlined in that paper.
*
* <p>
* This class extends the standard equations defined by Porter and
* Duff to include one additional factor.
! * An instance of the {@code AlphaComposite} class can contain
* an alpha value that is used to modify the opacity or coverage of
* every source pixel before it is used in the blending equations.
*
* <p>
* It is important to note that the equations defined by the Porter
* and Duff paper are all defined to operate on color components
* that are premultiplied by their corresponding alpha components.
! * Since the {@code ColorModel} and {@code Raster} classes
* allow the storage of pixel data in either premultiplied or
* non-premultiplied form, all input data must be normalized into
* premultiplied form before applying the equations and all results
* might need to be adjusted back to the form required by the destination
* before the pixel values are stored.
*** 94,104 ****
* The equations for determining <em>F<sub>s</sub></em> and <em>F<sub>d</sub></em>
* are given in the descriptions of the 12 static fields
* that specify visual effects.
* For example,
* the description for
! * <a href="#SRC_OVER"><code>SRC_OVER</code></a>
* specifies that <em>F<sub>s</sub></em> = 1 and <em>F<sub>d</sub></em> = (1-<em>A<sub>s</sub></em>).
* Once a set of equations for determining the blending factors is
* known they can then be applied to each pixel to produce a result
* using the following set of equations:
*
--- 94,104 ----
* The equations for determining <em>F<sub>s</sub></em> and <em>F<sub>d</sub></em>
* are given in the descriptions of the 12 static fields
* that specify visual effects.
* For example,
* the description for
! * <a href="#SRC_OVER">{@code SRC_OVER}</a>
* specifies that <em>F<sub>s</sub></em> = 1 and <em>F<sub>d</sub></em> = (1-<em>A<sub>s</sub></em>).
* Once a set of equations for determining the blending factors is
* known they can then be applied to each pixel to produce a result
* using the following set of equations:
*
*** 126,149 ****
*</blockquote>
*
* <h3>Preparing Inputs</h3>
*
* <p>
! * The <code>AlphaComposite</code> class defines an additional alpha
* value that is applied to the source alpha.
* This value is applied as if an implicit SRC_IN rule were first
* applied to the source pixel against a pixel with the indicated
* alpha by multiplying both the raw source alpha and the raw
! * source colors by the alpha in the <code>AlphaComposite</code>.
* This leads to the following equation for producing the alpha
* used in the Porter and Duff blending equation:
*
* <pre>
* <em>A<sub>s</sub></em> = <em>A<sub>sr</sub></em> * <em>A<sub>ac</sub></em> </pre>
*
* All of the raw source color components need to be multiplied
! * by the alpha in the <code>AlphaComposite</code> instance.
* Additionally, if the source was not in premultiplied form
* then the color components also need to be multiplied by the
* source alpha.
* Thus, the equation for producing the source color components
* for the Porter and Duff equation depends on whether the source
--- 126,149 ----
*</blockquote>
*
* <h3>Preparing Inputs</h3>
*
* <p>
! * The {@code AlphaComposite} class defines an additional alpha
* value that is applied to the source alpha.
* This value is applied as if an implicit SRC_IN rule were first
* applied to the source pixel against a pixel with the indicated
* alpha by multiplying both the raw source alpha and the raw
! * source colors by the alpha in the {@code AlphaComposite}.
* This leads to the following equation for producing the alpha
* used in the Porter and Duff blending equation:
*
* <pre>
* <em>A<sub>s</sub></em> = <em>A<sub>sr</sub></em> * <em>A<sub>ac</sub></em> </pre>
*
* All of the raw source color components need to be multiplied
! * by the alpha in the {@code AlphaComposite} instance.
* Additionally, if the source was not in premultiplied form
* then the color components also need to be multiplied by the
* source alpha.
* Thus, the equation for producing the source color components
* for the Porter and Duff equation depends on whether the source
*** 194,218 ****
*
* <h3>Performance Considerations</h3>
*
* <p>
* For performance reasons, it is preferable that
! * <code>Raster</code> objects passed to the <code>compose</code>
* method of a {@link CompositeContext} object created by the
! * <code>AlphaComposite</code> class have premultiplied data.
! * If either the source <code>Raster</code>
! * or the destination <code>Raster</code>
* is not premultiplied, however,
* appropriate conversions are performed before and after the compositing
* operation.
*
* <h3><a name="caveats">Implementation Caveats</a></h3>
*
* <ul>
* <li>
* Many sources, such as some of the opaque image types listed
! * in the <code>BufferedImage</code> class, do not store alpha values
* for their pixels. Such sources supply an alpha of 1.0 for
* all of their pixels.
*
* <li>
* Many destinations also have no place to store the alpha values
--- 194,218 ----
*
* <h3>Performance Considerations</h3>
*
* <p>
* For performance reasons, it is preferable that
! * {@code Raster} objects passed to the {@code compose}
* method of a {@link CompositeContext} object created by the
! * {@code AlphaComposite} class have premultiplied data.
! * If either the source {@code Raster}
! * or the destination {@code Raster}
* is not premultiplied, however,
* appropriate conversions are performed before and after the compositing
* operation.
*
* <h3><a name="caveats">Implementation Caveats</a></h3>
*
* <ul>
* <li>
* Many sources, such as some of the opaque image types listed
! * in the {@code BufferedImage} class, do not store alpha values
* for their pixels. Such sources supply an alpha of 1.0 for
* all of their pixels.
*
* <li>
* Many destinations also have no place to store the alpha values
*** 235,245 ****
* before the rounding errors dominate the results.
* An image format
* that does not separately store
* color components is not a
* good candidate for any type of translucent blending.
! * For example, <code>BufferedImage.TYPE_BYTE_INDEXED</code>
* should not be used as a destination for a blending operation
* because every operation
* can introduce large errors, due to
* the need to choose a pixel from a limited palette to match the
* results of the blending equations.
--- 235,245 ----
* before the rounding errors dominate the results.
* An image format
* that does not separately store
* color components is not a
* good candidate for any type of translucent blending.
! * For example, {@code BufferedImage.TYPE_BYTE_INDEXED}
* should not be used as a destination for a blending operation
* because every operation
* can introduce large errors, due to
* the need to choose a pixel from a limited palette to match the
* results of the blending equations.
*** 275,285 ****
* (A, R, G, B) = (0x01, 0xb0, 0x00, 0x00)</pre>
*
* <p>
* If integer math were being used and this value were being
* composited in
! * <a href="#SRC"><code>SRC</code></a>
* mode with no extra alpha, then the math would
* indicate that the results were (in integer format):
*
* <pre>
* (A, R, G, B) = (0x01, 0x01, 0x00, 0x00)</pre>
--- 275,285 ----
* (A, R, G, B) = (0x01, 0xb0, 0x00, 0x00)</pre>
*
* <p>
* If integer math were being used and this value were being
* composited in
! * <a href="#SRC">{@code SRC}</a>
* mode with no extra alpha, then the math would
* indicate that the results were (in integer format):
*
* <pre>
* (A, R, G, B) = (0x01, 0x01, 0x00, 0x00)</pre>
*** 508,598 ****
* @since 1.4
*/
@Native public static final int XOR = 12;
/**
! * <code>AlphaComposite</code> object that implements the opaque CLEAR rule
* with an alpha of 1.0f.
* @see #CLEAR
*/
public static final AlphaComposite Clear = new AlphaComposite(CLEAR);
/**
! * <code>AlphaComposite</code> object that implements the opaque SRC rule
* with an alpha of 1.0f.
* @see #SRC
*/
public static final AlphaComposite Src = new AlphaComposite(SRC);
/**
! * <code>AlphaComposite</code> object that implements the opaque DST rule
* with an alpha of 1.0f.
* @see #DST
* @since 1.4
*/
public static final AlphaComposite Dst = new AlphaComposite(DST);
/**
! * <code>AlphaComposite</code> object that implements the opaque SRC_OVER rule
* with an alpha of 1.0f.
* @see #SRC_OVER
*/
public static final AlphaComposite SrcOver = new AlphaComposite(SRC_OVER);
/**
! * <code>AlphaComposite</code> object that implements the opaque DST_OVER rule
* with an alpha of 1.0f.
* @see #DST_OVER
*/
public static final AlphaComposite DstOver = new AlphaComposite(DST_OVER);
/**
! * <code>AlphaComposite</code> object that implements the opaque SRC_IN rule
* with an alpha of 1.0f.
* @see #SRC_IN
*/
public static final AlphaComposite SrcIn = new AlphaComposite(SRC_IN);
/**
! * <code>AlphaComposite</code> object that implements the opaque DST_IN rule
* with an alpha of 1.0f.
* @see #DST_IN
*/
public static final AlphaComposite DstIn = new AlphaComposite(DST_IN);
/**
! * <code>AlphaComposite</code> object that implements the opaque SRC_OUT rule
* with an alpha of 1.0f.
* @see #SRC_OUT
*/
public static final AlphaComposite SrcOut = new AlphaComposite(SRC_OUT);
/**
! * <code>AlphaComposite</code> object that implements the opaque DST_OUT rule
* with an alpha of 1.0f.
* @see #DST_OUT
*/
public static final AlphaComposite DstOut = new AlphaComposite(DST_OUT);
/**
! * <code>AlphaComposite</code> object that implements the opaque SRC_ATOP rule
* with an alpha of 1.0f.
* @see #SRC_ATOP
* @since 1.4
*/
public static final AlphaComposite SrcAtop = new AlphaComposite(SRC_ATOP);
/**
! * <code>AlphaComposite</code> object that implements the opaque DST_ATOP rule
* with an alpha of 1.0f.
* @see #DST_ATOP
* @since 1.4
*/
public static final AlphaComposite DstAtop = new AlphaComposite(DST_ATOP);
/**
! * <code>AlphaComposite</code> object that implements the opaque XOR rule
* with an alpha of 1.0f.
* @see #XOR
* @since 1.4
*/
public static final AlphaComposite Xor = new AlphaComposite(XOR);
--- 508,598 ----
* @since 1.4
*/
@Native public static final int XOR = 12;
/**
! * {@code AlphaComposite} object that implements the opaque CLEAR rule
* with an alpha of 1.0f.
* @see #CLEAR
*/
public static final AlphaComposite Clear = new AlphaComposite(CLEAR);
/**
! * {@code AlphaComposite} object that implements the opaque SRC rule
* with an alpha of 1.0f.
* @see #SRC
*/
public static final AlphaComposite Src = new AlphaComposite(SRC);
/**
! * {@code AlphaComposite} object that implements the opaque DST rule
* with an alpha of 1.0f.
* @see #DST
* @since 1.4
*/
public static final AlphaComposite Dst = new AlphaComposite(DST);
/**
! * {@code AlphaComposite} object that implements the opaque SRC_OVER rule
* with an alpha of 1.0f.
* @see #SRC_OVER
*/
public static final AlphaComposite SrcOver = new AlphaComposite(SRC_OVER);
/**
! * {@code AlphaComposite} object that implements the opaque DST_OVER rule
* with an alpha of 1.0f.
* @see #DST_OVER
*/
public static final AlphaComposite DstOver = new AlphaComposite(DST_OVER);
/**
! * {@code AlphaComposite} object that implements the opaque SRC_IN rule
* with an alpha of 1.0f.
* @see #SRC_IN
*/
public static final AlphaComposite SrcIn = new AlphaComposite(SRC_IN);
/**
! * {@code AlphaComposite} object that implements the opaque DST_IN rule
* with an alpha of 1.0f.
* @see #DST_IN
*/
public static final AlphaComposite DstIn = new AlphaComposite(DST_IN);
/**
! * {@code AlphaComposite} object that implements the opaque SRC_OUT rule
* with an alpha of 1.0f.
* @see #SRC_OUT
*/
public static final AlphaComposite SrcOut = new AlphaComposite(SRC_OUT);
/**
! * {@code AlphaComposite} object that implements the opaque DST_OUT rule
* with an alpha of 1.0f.
* @see #DST_OUT
*/
public static final AlphaComposite DstOut = new AlphaComposite(DST_OUT);
/**
! * {@code AlphaComposite} object that implements the opaque SRC_ATOP rule
* with an alpha of 1.0f.
* @see #SRC_ATOP
* @since 1.4
*/
public static final AlphaComposite SrcAtop = new AlphaComposite(SRC_ATOP);
/**
! * {@code AlphaComposite} object that implements the opaque DST_ATOP rule
* with an alpha of 1.0f.
* @see #DST_ATOP
* @since 1.4
*/
public static final AlphaComposite DstAtop = new AlphaComposite(DST_ATOP);
/**
! * {@code AlphaComposite} object that implements the opaque XOR rule
* with an alpha of 1.0f.
* @see #XOR
* @since 1.4
*/
public static final AlphaComposite Xor = new AlphaComposite(XOR);
*** 618,632 ****
throw new IllegalArgumentException("alpha value out of range");
}
}
/**
! * Creates an <code>AlphaComposite</code> object with the specified rule.
*
* @param rule the compositing rule
* @return the {@code AlphaComposite} object created
! * @throws IllegalArgumentException if <code>rule</code> is not one of
* the following: {@link #CLEAR}, {@link #SRC}, {@link #DST},
* {@link #SRC_OVER}, {@link #DST_OVER}, {@link #SRC_IN},
* {@link #DST_IN}, {@link #SRC_OUT}, {@link #DST_OUT},
* {@link #SRC_ATOP}, {@link #DST_ATOP}, or {@link #XOR}
*/
--- 618,632 ----
throw new IllegalArgumentException("alpha value out of range");
}
}
/**
! * Creates an {@code AlphaComposite} object with the specified rule.
*
* @param rule the compositing rule
* @return the {@code AlphaComposite} object created
! * @throws IllegalArgumentException if {@code rule} is not one of
* the following: {@link #CLEAR}, {@link #SRC}, {@link #DST},
* {@link #SRC_OVER}, {@link #DST_OVER}, {@link #SRC_IN},
* {@link #DST_IN}, {@link #SRC_OUT}, {@link #DST_OUT},
* {@link #SRC_ATOP}, {@link #DST_ATOP}, or {@link #XOR}
*/
*** 660,682 ****
throw new IllegalArgumentException("unknown composite rule");
}
}
/**
! * Creates an <code>AlphaComposite</code> object with the specified rule and
* the constant alpha to multiply with the alpha of the source.
* The source is multiplied with the specified alpha before being composited
* with the destination.
*
* @param rule the compositing rule
* @param alpha the constant alpha to be multiplied with the alpha of
! * the source. <code>alpha</code> must be a floating point number in the
* inclusive range [0.0, 1.0].
* @return the {@code AlphaComposite} object created
* @throws IllegalArgumentException if
! * <code>alpha</code> is less than 0.0 or greater than 1.0, or if
! * <code>rule</code> is not one of
* the following: {@link #CLEAR}, {@link #SRC}, {@link #DST},
* {@link #SRC_OVER}, {@link #DST_OVER}, {@link #SRC_IN},
* {@link #DST_IN}, {@link #SRC_OUT}, {@link #DST_OUT},
* {@link #SRC_ATOP}, {@link #DST_ATOP}, or {@link #XOR}
*/
--- 660,682 ----
throw new IllegalArgumentException("unknown composite rule");
}
}
/**
! * Creates an {@code AlphaComposite} object with the specified rule and
* the constant alpha to multiply with the alpha of the source.
* The source is multiplied with the specified alpha before being composited
* with the destination.
*
* @param rule the compositing rule
* @param alpha the constant alpha to be multiplied with the alpha of
! * the source. {@code alpha} must be a floating point number in the
* inclusive range [0.0, 1.0].
* @return the {@code AlphaComposite} object created
* @throws IllegalArgumentException if
! * {@code alpha} is less than 0.0 or greater than 1.0, or if
! * {@code rule} is not one of
* the following: {@link #CLEAR}, {@link #SRC}, {@link #DST},
* {@link #SRC_OVER}, {@link #DST_OVER}, {@link #SRC_IN},
* {@link #DST_IN}, {@link #SRC_OUT}, {@link #DST_OUT},
* {@link #SRC_ATOP}, {@link #DST_ATOP}, or {@link #XOR}
*/
*** 690,736 ****
/**
* Creates a context for the compositing operation.
* The context contains state that is used in performing
* the compositing operation.
* @param srcColorModel the {@link ColorModel} of the source
! * @param dstColorModel the <code>ColorModel</code> of the destination
! * @return the <code>CompositeContext</code> object to be used to perform
* compositing operations.
*/
public CompositeContext createContext(ColorModel srcColorModel,
ColorModel dstColorModel,
RenderingHints hints) {
return new SunCompositeContext(this, srcColorModel, dstColorModel);
}
/**
! * Returns the alpha value of this <code>AlphaComposite</code>. If this
! * <code>AlphaComposite</code> does not have an alpha value, 1.0 is returned.
! * @return the alpha value of this <code>AlphaComposite</code>.
*/
public float getAlpha() {
return extraAlpha;
}
/**
! * Returns the compositing rule of this <code>AlphaComposite</code>.
! * @return the compositing rule of this <code>AlphaComposite</code>.
*/
public int getRule() {
return rule;
}
/**
! * Returns a similar <code>AlphaComposite</code> object that uses
* the specified compositing rule.
* If this object already uses the specified compositing rule,
* this object is returned.
! * @return an <code>AlphaComposite</code> object derived from
* this object that uses the specified compositing rule.
* @param rule the compositing rule
* @throws IllegalArgumentException if
! * <code>rule</code> is not one of
* the following: {@link #CLEAR}, {@link #SRC}, {@link #DST},
* {@link #SRC_OVER}, {@link #DST_OVER}, {@link #SRC_IN},
* {@link #DST_IN}, {@link #SRC_OUT}, {@link #DST_OUT},
* {@link #SRC_ATOP}, {@link #DST_ATOP}, or {@link #XOR}
* @since 1.6
--- 690,736 ----
/**
* Creates a context for the compositing operation.
* The context contains state that is used in performing
* the compositing operation.
* @param srcColorModel the {@link ColorModel} of the source
! * @param dstColorModel the {@code ColorModel} of the destination
! * @return the {@code CompositeContext} object to be used to perform
* compositing operations.
*/
public CompositeContext createContext(ColorModel srcColorModel,
ColorModel dstColorModel,
RenderingHints hints) {
return new SunCompositeContext(this, srcColorModel, dstColorModel);
}
/**
! * Returns the alpha value of this {@code AlphaComposite}. If this
! * {@code AlphaComposite} does not have an alpha value, 1.0 is returned.
! * @return the alpha value of this {@code AlphaComposite}.
*/
public float getAlpha() {
return extraAlpha;
}
/**
! * Returns the compositing rule of this {@code AlphaComposite}.
! * @return the compositing rule of this {@code AlphaComposite}.
*/
public int getRule() {
return rule;
}
/**
! * Returns a similar {@code AlphaComposite} object that uses
* the specified compositing rule.
* If this object already uses the specified compositing rule,
* this object is returned.
! * @return an {@code AlphaComposite} object derived from
* this object that uses the specified compositing rule.
* @param rule the compositing rule
* @throws IllegalArgumentException if
! * {@code rule} is not one of
* the following: {@link #CLEAR}, {@link #SRC}, {@link #DST},
* {@link #SRC_OVER}, {@link #DST_OVER}, {@link #SRC_IN},
* {@link #DST_IN}, {@link #SRC_OUT}, {@link #DST_OUT},
* {@link #SRC_ATOP}, {@link #DST_ATOP}, or {@link #XOR}
* @since 1.6
*** 740,760 ****
? this
: getInstance(rule, this.extraAlpha);
}
/**
! * Returns a similar <code>AlphaComposite</code> object that uses
* the specified alpha value.
* If this object already has the specified alpha value,
* this object is returned.
! * @return an <code>AlphaComposite</code> object derived from
* this object that uses the specified alpha value.
* @param alpha the constant alpha to be multiplied with the alpha of
! * the source. <code>alpha</code> must be a floating point number in the
* inclusive range [0.0, 1.0].
* @throws IllegalArgumentException if
! * <code>alpha</code> is less than 0.0 or greater than 1.0
* @since 1.6
*/
public AlphaComposite derive(float alpha) {
return (this.extraAlpha == alpha)
? this
--- 740,760 ----
? this
: getInstance(rule, this.extraAlpha);
}
/**
! * Returns a similar {@code AlphaComposite} object that uses
* the specified alpha value.
* If this object already has the specified alpha value,
* this object is returned.
! * @return an {@code AlphaComposite} object derived from
* this object that uses the specified alpha value.
* @param alpha the constant alpha to be multiplied with the alpha of
! * the source. {@code alpha} must be a floating point number in the
* inclusive range [0.0, 1.0].
* @throws IllegalArgumentException if
! * {@code alpha} is less than 0.0 or greater than 1.0
* @since 1.6
*/
public AlphaComposite derive(float alpha) {
return (this.extraAlpha == alpha)
? this
*** 769,788 ****
return (Float.floatToIntBits(extraAlpha) * 31 + rule);
}
/**
* Determines whether the specified object is equal to this
! * <code>AlphaComposite</code>.
* <p>
! * The result is <code>true</code> if and only if
! * the argument is not <code>null</code> and is an
! * <code>AlphaComposite</code> object that has the same
* compositing rule and alpha value as this object.
*
! * @param obj the <code>Object</code> to test for equality
! * @return <code>true</code> if <code>obj</code> equals this
! * <code>AlphaComposite</code>; <code>false</code> otherwise.
*/
public boolean equals(Object obj) {
if (!(obj instanceof AlphaComposite)) {
return false;
}
--- 769,788 ----
return (Float.floatToIntBits(extraAlpha) * 31 + rule);
}
/**
* Determines whether the specified object is equal to this
! * {@code AlphaComposite}.
* <p>
! * The result is {@code true} if and only if
! * the argument is not {@code null} and is an
! * {@code AlphaComposite} object that has the same
* compositing rule and alpha value as this object.
*
! * @param obj the {@code Object} to test for equality
! * @return {@code true} if {@code obj} equals this
! * {@code AlphaComposite}; {@code false} otherwise.
*/
public boolean equals(Object obj) {
if (!(obj instanceof AlphaComposite)) {
return false;
}
< prev index next >