/* * Copyright (c) 1997, 2017, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it * under the terms of the GNU General Public License version 2 only, as * published by the Free Software Foundation. Oracle designates this * particular file as subject to the "Classpath" exception as provided * by Oracle in the LICENSE file that accompanied this code. * * This code is distributed in the hope that it will be useful, but WITHOUT * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License * version 2 for more details (a copy is included in the LICENSE file that * accompanied this code). * * You should have received a copy of the GNU General Public License version * 2 along with this work; if not, write to the Free Software Foundation, * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. * * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA * or visit www.oracle.com if you need additional information or have any * questions. */ package java.awt; 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 * T. Porter and T. Duff, "Compositing Digital Images", SIGGRAPH 84, * 253-259. * The rest of this documentation assumes some familiarity with the * definitions and concepts outlined in that paper. * *

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

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

* Also note that this class defines only the equations * for combining color and alpha values in a purely mathematical * sense. The accurate application of its equations depends * on the way the data is retrieved from its sources and stored * in its destinations. * See Implementation Caveats * for further information. * *

* The following factors are used in the description of the blending * equation in the Porter and Duff paper: * * * * * * * * * * * * * * * * *
Factors
Factor * Definition *
As * the alpha component of the source pixel *
Cs * a color component of the source pixel in premultiplied form *
Ad * the alpha component of the destination pixel *
Cd * a color component of the destination pixel in premultiplied form *
Fs * the fraction of the source pixel that contributes to the output *
Fd * the fraction of the destination pixel that contributes to the output *
Ar * the alpha component of the result *
Cr * a color component of the result in premultiplied form *
*

* Using these factors, Porter and Duff define 12 ways of choosing * the blending factors Fs and Fd to * produce each of 12 desirable visual effects. * The equations for determining Fs and Fd * are given in the descriptions of the 12 static fields * that specify visual effects. * For example, * the description for * {@code SRC_OVER} * specifies that Fs = 1 and Fd = (1-As). * 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: * * 

 *      Fs = f(Ad)
 *      Fd = f(As)
 *      Ar = As*Fs + Ad*Fd
 *      Cr = Cs*Fs + Cd*Fd
* *

* The following factors will be used to discuss our extensions to * the blending equation in the Porter and Duff paper: * * * * * * * * * * * * * * * *
Factors
Factor * Definition *
Csr * one of the raw color components of the source pixel *
Cdr * one of the raw color components of the destination pixel *
Aac * the "extra" alpha component from the AlphaComposite instance *
Asr * the raw alpha component of the source pixel *
Adr * the raw alpha component of the destination pixel *
Adf * the final alpha component stored in the destination *
Cdf * the final raw color component stored in the destination *
* *

Preparing Inputs

* *

* 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: * * 

 *      As = Asr * Aac
* * 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 * pixels are premultiplied or not: * * 
 *      Cs = Csr * Asr * Aac     (if source is not premultiplied)
 *      Cs = Csr * Aac           (if source is premultiplied)
* * No adjustment needs to be made to the destination alpha: * * 
 *      Ad = Adr
* *

* The destination color components need to be adjusted only if * they are not in premultiplied form: * * 

 *      Cd = Cdr * Ad    (if destination is not premultiplied)
 *      Cd = Cdr         (if destination is premultiplied)
* *

Applying the Blending Equation

* *

* The adjusted As, Ad, * Cs, and Cd are used in the standard * Porter and Duff equations to calculate the blending factors * Fs and Fd and then the resulting * premultiplied components Ar and Cr. * *

Preparing Results

* *

* The results only need to be adjusted if they are to be stored * back into a destination buffer that holds data that is not * premultiplied, using the following equations: * * 

 *      Adf = Ar
 *      Cdf = Cr                 (if dest is premultiplied)
 *      Cdf = Cr / Ar            (if dest is not premultiplied)
* * Note that since the division is undefined if the resulting alpha * is zero, the division in that case is omitted to avoid the "divide * by zero" and the color components are left as * all zeros. * *

Performance Considerations

* *

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

Implementation Caveats

* * * @see Composite * @see CompositeContext */ public final class AlphaComposite implements Composite { /** * Both the color and the alpha of the destination are cleared * (Porter-Duff Clear rule). * Neither the source nor the destination is used as input. *

* Fs = 0 and Fd = 0, thus: *

     *  Ar = 0
     *  Cr = 0
     *
*/ @Native public static final int CLEAR = 1; /** * The source is copied to the destination * (Porter-Duff Source rule). * The destination is not used as input. *

* Fs = 1 and Fd = 0, thus: *

     *  Ar = As
     *  Cr = Cs
     *
*/ @Native public static final int SRC = 2; /** * The destination is left untouched * (Porter-Duff Destination rule). *

* Fs = 0 and Fd = 1, thus: *

     *  Ar = Ad
     *  Cr = Cd
     *
* @since 1.4 */ @Native public static final int DST = 9; // Note that DST was added in 1.4 so it is numbered out of order... /** * The source is composited over the destination * (Porter-Duff Source Over Destination rule). *

* Fs = 1 and Fd = (1-As), thus: *

     *  Ar = As + Ad*(1-As)
     *  Cr = Cs + Cd*(1-As)
     *
*/ @Native public static final int SRC_OVER = 3; /** * The destination is composited over the source and * the result replaces the destination * (Porter-Duff Destination Over Source rule). *

* Fs = (1-Ad) and Fd = 1, thus: *

     *  Ar = As*(1-Ad) + Ad
     *  Cr = Cs*(1-Ad) + Cd
     *
*/ @Native public static final int DST_OVER = 4; /** * The part of the source lying inside of the destination replaces * the destination * (Porter-Duff Source In Destination rule). *

* Fs = Ad and Fd = 0, thus: *

     *  Ar = As*Ad
     *  Cr = Cs*Ad
     *
*/ @Native public static final int SRC_IN = 5; /** * The part of the destination lying inside of the source * replaces the destination * (Porter-Duff Destination In Source rule). *

* Fs = 0 and Fd = As, thus: *

     *  Ar = Ad*As
     *  Cr = Cd*As
     *
*/ @Native public static final int DST_IN = 6; /** * The part of the source lying outside of the destination * replaces the destination * (Porter-Duff Source Held Out By Destination rule). *

* Fs = (1-Ad) and Fd = 0, thus: *

     *  Ar = As*(1-Ad)
     *  Cr = Cs*(1-Ad)
     *
*/ @Native public static final int SRC_OUT = 7; /** * The part of the destination lying outside of the source * replaces the destination * (Porter-Duff Destination Held Out By Source rule). *

* Fs = 0 and Fd = (1-As), thus: *

     *  Ar = Ad*(1-As)
     *  Cr = Cd*(1-As)
     *
*/ @Native public static final int DST_OUT = 8; // Rule 9 is DST which is defined above where it fits into the // list logically, rather than numerically // // public static final int DST = 9; /** * The part of the source lying inside of the destination * is composited onto the destination * (Porter-Duff Source Atop Destination rule). *

* Fs = Ad and Fd = (1-As), thus: *

     *  Ar = As*Ad + Ad*(1-As) = Ad
     *  Cr = Cs*Ad + Cd*(1-As)
     *
* @since 1.4 */ @Native public static final int SRC_ATOP = 10; /** * The part of the destination lying inside of the source * is composited over the source and replaces the destination * (Porter-Duff Destination Atop Source rule). *

* Fs = (1-Ad) and Fd = As, thus: *

     *  Ar = As*(1-Ad) + Ad*As = As
     *  Cr = Cs*(1-Ad) + Cd*As
     *
* @since 1.4 */ @Native public static final int DST_ATOP = 11; /** * The part of the source that lies outside of the destination * is combined with the part of the destination that lies outside * of the source * (Porter-Duff Source Xor Destination rule). *

* Fs = (1-Ad) and Fd = (1-As), thus: *

     *  Ar = As*(1-Ad) + Ad*(1-As)
     *  Cr = Cs*(1-Ad) + Cd*(1-As)
     *
* @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); @Native private static final int MIN_RULE = CLEAR; @Native private static final int MAX_RULE = XOR; float extraAlpha; int rule; private AlphaComposite(int rule) { this(rule, 1.0f); } private AlphaComposite(int rule, float alpha) { if (rule < MIN_RULE || rule > MAX_RULE) { throw new IllegalArgumentException("unknown composite rule"); } if (alpha >= 0.0f && alpha <= 1.0f) { this.rule = rule; this.extraAlpha = alpha; } else { 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} */ public static AlphaComposite getInstance(int rule) { switch (rule) { case CLEAR: return Clear; case SRC: return Src; case DST: return Dst; case SRC_OVER: return SrcOver; case DST_OVER: return DstOver; case SRC_IN: return SrcIn; case DST_IN: return DstIn; case SRC_OUT: return SrcOut; case DST_OUT: return DstOut; case SRC_ATOP: return SrcAtop; case DST_ATOP: return DstAtop; case XOR: return Xor; default: 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} */ public static AlphaComposite getInstance(int rule, float alpha) { if (alpha == 1.0f) { return getInstance(rule); } return new AlphaComposite(rule, alpha); } /** * 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 */ public AlphaComposite derive(int rule) { return (this.rule == rule) ? 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 : getInstance(this.rule, alpha); } /** * Returns the hashcode for this composite. * @return a hash code for this composite. */ public int hashCode() { return (Float.floatToIntBits(extraAlpha) * 31 + rule); } /** * Determines whether the specified object is equal to this * {@code AlphaComposite}. *

* 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; } AlphaComposite ac = (AlphaComposite) obj; if (rule != ac.rule) { return false; } if (extraAlpha != ac.extraAlpha) { return false; } return true; } }