Home » openjdk-7 » java » awt » [javadoc | source]

    1   /*
    2    * Copyright (c) 1997, 2010, Oracle and/or its affiliates. All rights reserved.
    3    * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
    4    *
    5    * This code is free software; you can redistribute it and/or modify it
    6    * under the terms of the GNU General Public License version 2 only, as
    7    * published by the Free Software Foundation.  Oracle designates this
    8    * particular file as subject to the "Classpath" exception as provided
    9    * by Oracle in the LICENSE file that accompanied this code.
   10    *
   11    * This code is distributed in the hope that it will be useful, but WITHOUT
   12    * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
   13    * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
   14    * version 2 for more details (a copy is included in the LICENSE file that
   15    * accompanied this code).
   16    *
   17    * You should have received a copy of the GNU General Public License version
   18    * 2 along with this work; if not, write to the Free Software Foundation,
   19    * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
   20    *
   21    * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
   22    * or visit www.oracle.com if you need additional information or have any
   23    * questions.
   24    */
   25   
   26   package java.awt;
   27   
   28   import java.awt.image.ColorModel;
   29   import sun.java2d.SunCompositeContext;
   30   
   31   /**
   32    * The <code>AlphaComposite</code> class implements basic alpha
   33    * compositing rules for combining source and destination colors
   34    * to achieve blending and transparency effects with graphics and
   35    * images.
   36    * The specific rules implemented by this class are the basic set
   37    * of 12 rules described in
   38    * T. Porter and T. Duff, "Compositing Digital Images", SIGGRAPH 84,
   39    * 253-259.
   40    * The rest of this documentation assumes some familiarity with the
   41    * definitions and concepts outlined in that paper.
   42    *
   43    * <p>
   44    * This class extends the standard equations defined by Porter and
   45    * Duff to include one additional factor.
   46    * An instance of the <code>AlphaComposite</code> class can contain
   47    * an alpha value that is used to modify the opacity or coverage of
   48    * every source pixel before it is used in the blending equations.
   49    *
   50    * <p>
   51    * It is important to note that the equations defined by the Porter
   52    * and Duff paper are all defined to operate on color components
   53    * that are premultiplied by their corresponding alpha components.
   54    * Since the <code>ColorModel</code> and <code>Raster</code> classes
   55    * allow the storage of pixel data in either premultiplied or
   56    * non-premultiplied form, all input data must be normalized into
   57    * premultiplied form before applying the equations and all results
   58    * might need to be adjusted back to the form required by the destination
   59    * before the pixel values are stored.
   60    *
   61    * <p>
   62    * Also note that this class defines only the equations
   63    * for combining color and alpha values in a purely mathematical
   64    * sense. The accurate application of its equations depends
   65    * on the way the data is retrieved from its sources and stored
   66    * in its destinations.
   67    * See <a href="#caveats">Implementation Caveats</a>
   68    * for further information.
   69    *
   70    * <p>
   71    * The following factors are used in the description of the blending
   72    * equation in the Porter and Duff paper:
   73    *
   74    * <blockquote>
   75    * <table summary="layout">
   76    * <tr><th align=left>Factor&nbsp;&nbsp;<th align=left>Definition
   77    * <tr><td><em>A<sub>s</sub></em><td>the alpha component of the source pixel
   78    * <tr><td><em>C<sub>s</sub></em><td>a color component of the source pixel in premultiplied form
   79    * <tr><td><em>A<sub>d</sub></em><td>the alpha component of the destination pixel
   80    * <tr><td><em>C<sub>d</sub></em><td>a color component of the destination pixel in premultiplied form
   81    * <tr><td><em>F<sub>s</sub></em><td>the fraction of the source pixel that contributes to the output
   82    * <tr><td><em>F<sub>d</sub></em><td>the fraction of the destination pixel that contributes
   83    * to the output
   84    * <tr><td><em>A<sub>r</sub></em><td>the alpha component of the result
   85    * <tr><td><em>C<sub>r</sub></em><td>a color component of the result in premultiplied form
   86    * </table>
   87    * </blockquote>
   88    *
   89    * <p>
   90    * Using these factors, Porter and Duff define 12 ways of choosing
   91    * the blending factors <em>F<sub>s</sub></em> and <em>F<sub>d</sub></em> to
   92    * produce each of 12 desirable visual effects.
   93    * The equations for determining <em>F<sub>s</sub></em> and <em>F<sub>d</sub></em>
   94    * are given in the descriptions of the 12 static fields
   95    * that specify visual effects.
   96    * For example,
   97    * the description for
   98    * <a href="#SRC_OVER"><code>SRC_OVER</code></a>
   99    * specifies that <em>F<sub>s</sub></em> = 1 and <em>F<sub>d</sub></em> = (1-<em>A<sub>s</sub></em>).
  100    * Once a set of equations for determining the blending factors is
  101    * known they can then be applied to each pixel to produce a result
  102    * using the following set of equations:
  103    *
  104    * <pre>
  105    *      <em>F<sub>s</sub></em> = <em>f</em>(<em>A<sub>d</sub></em>)
  106    *      <em>F<sub>d</sub></em> = <em>f</em>(<em>A<sub>s</sub></em>)
  107    *      <em>A<sub>r</sub></em> = <em>A<sub>s</sub></em>*<em>F<sub>s</sub></em> + <em>A<sub>d</sub></em>*<em>F<sub>d</sub></em>
  108    *      <em>C<sub>r</sub></em> = <em>C<sub>s</sub></em>*<em>F<sub>s</sub></em> + <em>C<sub>d</sub></em>*<em>F<sub>d</sub></em></pre>
  109    *
  110    * <p>
  111    * The following factors will be used to discuss our extensions to
  112    * the blending equation in the Porter and Duff paper:
  113    *
  114    * <blockquote>
  115    * <table summary="layout">
  116    * <tr><th align=left>Factor&nbsp;&nbsp;<th align=left>Definition
  117    * <tr><td><em>C<sub>sr</sub></em> <td>one of the raw color components of the source pixel
  118    * <tr><td><em>C<sub>dr</sub></em> <td>one of the raw color components of the destination pixel
  119    * <tr><td><em>A<sub>ac</sub></em>  <td>the "extra" alpha component from the AlphaComposite instance
  120    * <tr><td><em>A<sub>sr</sub></em> <td>the raw alpha component of the source pixel
  121    * <tr><td><em>A<sub>dr</sub></em><td>the raw alpha component of the destination pixel
  122    * <tr><td><em>A<sub>df</sub></em> <td>the final alpha component stored in the destination
  123    * <tr><td><em>C<sub>df</sub></em> <td>the final raw color component stored in the destination
  124    * </table>
  125    *</blockquote>
  126    *
  127    * <h3>Preparing Inputs</h3>
  128    *
  129    * <p>
  130    * The <code>AlphaComposite</code> class defines an additional alpha
  131    * value that is applied to the source alpha.
  132    * This value is applied as if an implicit SRC_IN rule were first
  133    * applied to the source pixel against a pixel with the indicated
  134    * alpha by multiplying both the raw source alpha and the raw
  135    * source colors by the alpha in the <code>AlphaComposite</code>.
  136    * This leads to the following equation for producing the alpha
  137    * used in the Porter and Duff blending equation:
  138    *
  139    * <pre>
  140    *      <em>A<sub>s</sub></em> = <em>A<sub>sr</sub></em> * <em>A<sub>ac</sub></em> </pre>
  141    *
  142    * All of the raw source color components need to be multiplied
  143    * by the alpha in the <code>AlphaComposite</code> instance.
  144    * Additionally, if the source was not in premultiplied form
  145    * then the color components also need to be multiplied by the
  146    * source alpha.
  147    * Thus, the equation for producing the source color components
  148    * for the Porter and Duff equation depends on whether the source
  149    * pixels are premultiplied or not:
  150    *
  151    * <pre>
  152    *      <em>C<sub>s</sub></em> = <em>C<sub>sr</sub></em> * <em>A<sub>sr</sub></em> * <em>A<sub>ac</sub></em>     (if source is not premultiplied)
  153    *      <em>C<sub>s</sub></em> = <em>C<sub>sr</sub></em> * <em>A<sub>ac</sub></em>           (if source is premultiplied) </pre>
  154    *
  155    * No adjustment needs to be made to the destination alpha:
  156    *
  157    * <pre>
  158    *      <em>A<sub>d</sub></em> = <em>A<sub>dr</sub></em> </pre>
  159    *
  160    * <p>
  161    * The destination color components need to be adjusted only if
  162    * they are not in premultiplied form:
  163    *
  164    * <pre>
  165    *      <em>C<sub>d</sub></em> = <em>C<sub>dr</sub></em> * <em>A<sub>d</sub></em>    (if destination is not premultiplied)
  166    *      <em>C<sub>d</sub></em> = <em>C<sub>dr</sub></em>         (if destination is premultiplied) </pre>
  167    *
  168    * <h3>Applying the Blending Equation</h3>
  169    *
  170    * <p>
  171    * The adjusted <em>A<sub>s</sub></em>, <em>A<sub>d</sub></em>,
  172    * <em>C<sub>s</sub></em>, and <em>C<sub>d</sub></em> are used in the standard
  173    * Porter and Duff equations to calculate the blending factors
  174    * <em>F<sub>s</sub></em> and <em>F<sub>d</sub></em> and then the resulting
  175    * premultiplied components <em>A<sub>r</sub></em> and <em>C<sub>r</sub></em>.
  176    *
  177    * <p>
  178    * <h3>Preparing Results</h3>
  179    *
  180    * <p>
  181    * The results only need to be adjusted if they are to be stored
  182    * back into a destination buffer that holds data that is not
  183    * premultiplied, using the following equations:
  184    *
  185    * <pre>
  186    *      <em>A<sub>df</sub></em> = <em>A<sub>r</sub></em>
  187    *      <em>C<sub>df</sub></em> = <em>C<sub>r</sub></em>                 (if dest is premultiplied)
  188    *      <em>C<sub>df</sub></em> = <em>C<sub>r</sub></em> / <em>A<sub>r</sub></em>            (if dest is not premultiplied) </pre>
  189    *
  190    * Note that since the division is undefined if the resulting alpha
  191    * is zero, the division in that case is omitted to avoid the "divide
  192    * by zero" and the color components are left as
  193    * all zeros.
  194    *
  195    * <p>
  196    * <h3>Performance Considerations</h3>
  197    *
  198    * <p>
  199    * For performance reasons, it is preferrable that
  200    * <code>Raster</code> objects passed to the <code>compose</code>
  201    * method of a {@link CompositeContext} object created by the
  202    * <code>AlphaComposite</code> class have premultiplied data.
  203    * If either the source <code>Raster</code>
  204    * or the destination <code>Raster</code>
  205    * is not premultiplied, however,
  206    * appropriate conversions are performed before and after the compositing
  207    * operation.
  208    *
  209    * <h3><a name="caveats">Implementation Caveats</a></h3>
  210    *
  211    * <ul>
  212    * <li>
  213    * Many sources, such as some of the opaque image types listed
  214    * in the <code>BufferedImage</code> class, do not store alpha values
  215    * for their pixels.  Such sources supply an alpha of 1.0 for
  216    * all of their pixels.
  217    *
  218    * <p>
  219    * <li>
  220    * Many destinations also have no place to store the alpha values
  221    * that result from the blending calculations performed by this class.
  222    * Such destinations thus implicitly discard the resulting
  223    * alpha values that this class produces.
  224    * It is recommended that such destinations should treat their stored
  225    * color values as non-premultiplied and divide the resulting color
  226    * values by the resulting alpha value before storing the color
  227    * values and discarding the alpha value.
  228    *
  229    * <p>
  230    * <li>
  231    * The accuracy of the results depends on the manner in which pixels
  232    * are stored in the destination.
  233    * An image format that provides at least 8 bits of storage per color
  234    * and alpha component is at least adequate for use as a destination
  235    * for a sequence of a few to a dozen compositing operations.
  236    * An image format with fewer than 8 bits of storage per component
  237    * is of limited use for just one or two compositing operations
  238    * before the rounding errors dominate the results.
  239    * An image format
  240    * that does not separately store
  241    * color components is not a
  242    * good candidate for any type of translucent blending.
  243    * For example, <code>BufferedImage.TYPE_BYTE_INDEXED</code>
  244    * should not be used as a destination for a blending operation
  245    * because every operation
  246    * can introduce large errors, due to
  247    * the need to choose a pixel from a limited palette to match the
  248    * results of the blending equations.
  249    *
  250    * <p>
  251    * <li>
  252    * Nearly all formats store pixels as discrete integers rather than
  253    * the floating point values used in the reference equations above.
  254    * The implementation can either scale the integer pixel
  255    * values into floating point values in the range 0.0 to 1.0 or
  256    * use slightly modified versions of the equations
  257    * that operate entirely in the integer domain and yet produce
  258    * analogous results to the reference equations.
  259    *
  260    * <p>
  261    * Typically the integer values are related to the floating point
  262    * values in such a way that the integer 0 is equated
  263    * to the floating point value 0.0 and the integer
  264    * 2^<em>n</em>-1 (where <em>n</em> is the number of bits
  265    * in the representation) is equated to 1.0.
  266    * For 8-bit representations, this means that 0x00
  267    * represents 0.0 and 0xff represents
  268    * 1.0.
  269    *
  270    * <p>
  271    * <li>
  272    * The internal implementation can approximate some of the equations
  273    * and it can also eliminate some steps to avoid unnecessary operations.
  274    * For example, consider a discrete integer image with non-premultiplied
  275    * alpha values that uses 8 bits per component for storage.
  276    * The stored values for a
  277    * nearly transparent darkened red might be:
  278    *
  279    * <pre>
  280    *    (A, R, G, B) = (0x01, 0xb0, 0x00, 0x00)</pre>
  281    *
  282    * <p>
  283    * If integer math were being used and this value were being
  284    * composited in
  285    * <a href="#SRC"><code>SRC</code></a>
  286    * mode with no extra alpha, then the math would
  287    * indicate that the results were (in integer format):
  288    *
  289    * <pre>
  290    *    (A, R, G, B) = (0x01, 0x01, 0x00, 0x00)</pre>
  291    *
  292    * <p>
  293    * Note that the intermediate values, which are always in premultiplied
  294    * form, would only allow the integer red component to be either 0x00
  295    * or 0x01.  When we try to store this result back into a destination
  296    * that is not premultiplied, dividing out the alpha will give us
  297    * very few choices for the non-premultiplied red value.
  298    * In this case an implementation that performs the math in integer
  299    * space without shortcuts is likely to end up with the final pixel
  300    * values of:
  301    *
  302    * <pre>
  303    *    (A, R, G, B) = (0x01, 0xff, 0x00, 0x00)</pre>
  304    *
  305    * <p>
  306    * (Note that 0x01 divided by 0x01 gives you 1.0, which is equivalent
  307    * to the value 0xff in an 8-bit storage format.)
  308    *
  309    * <p>
  310    * Alternately, an implementation that uses floating point math
  311    * might produce more accurate results and end up returning to the
  312    * original pixel value with little, if any, roundoff error.
  313    * Or, an implementation using integer math might decide that since
  314    * the equations boil down to a virtual NOP on the color values
  315    * if performed in a floating point space, it can transfer the
  316    * pixel untouched to the destination and avoid all the math entirely.
  317    *
  318    * <p>
  319    * These implementations all attempt to honor the
  320    * same equations, but use different tradeoffs of integer and
  321    * floating point math and reduced or full equations.
  322    * To account for such differences, it is probably best to
  323    * expect only that the premultiplied form of the results to
  324    * match between implementations and image formats.  In this
  325    * case both answers, expressed in premultiplied form would
  326    * equate to:
  327    *
  328    * <pre>
  329    *    (A, R, G, B) = (0x01, 0x01, 0x00, 0x00)</pre>
  330    *
  331    * <p>
  332    * and thus they would all match.
  333    *
  334    * <p>
  335    * <li>
  336    * Because of the technique of simplifying the equations for
  337    * calculation efficiency, some implementations might perform
  338    * differently when encountering result alpha values of 0.0
  339    * on a non-premultiplied destination.
  340    * Note that the simplification of removing the divide by alpha
  341    * in the case of the SRC rule is technically not valid if the
  342    * denominator (alpha) is 0.
  343    * But, since the results should only be expected to be accurate
  344    * when viewed in premultiplied form, a resulting alpha of 0
  345    * essentially renders the resulting color components irrelevant
  346    * and so exact behavior in this case should not be expected.
  347    * </ul>
  348    * @see Composite
  349    * @see CompositeContext
  350    */
  351   
  352   public final class AlphaComposite implements Composite {
  353       /**
  354        * Both the color and the alpha of the destination are cleared
  355        * (Porter-Duff Clear rule).
  356        * Neither the source nor the destination is used as input.
  357        *<p>
  358        * <em>F<sub>s</sub></em> = 0 and <em>F<sub>d</sub></em> = 0, thus:
  359        *<pre>
  360        *  <em>A<sub>r</sub></em> = 0
  361        *  <em>C<sub>r</sub></em> = 0
  362        *</pre>
  363        */
  364       public static final int     CLEAR           = 1;
  365   
  366       /**
  367        * The source is copied to the destination
  368        * (Porter-Duff Source rule).
  369        * The destination is not used as input.
  370        *<p>
  371        * <em>F<sub>s</sub></em> = 1 and <em>F<sub>d</sub></em> = 0, thus:
  372        *<pre>
  373        *  <em>A<sub>r</sub></em> = <em>A<sub>s</sub></em>
  374        *  <em>C<sub>r</sub></em> = <em>C<sub>s</sub></em>
  375        *</pre>
  376        */
  377       public static final int     SRC             = 2;
  378   
  379       /**
  380        * The destination is left untouched
  381        * (Porter-Duff Destination rule).
  382        *<p>
  383        * <em>F<sub>s</sub></em> = 0 and <em>F<sub>d</sub></em> = 1, thus:
  384        *<pre>
  385        *  <em>A<sub>r</sub></em> = <em>A<sub>d</sub></em>
  386        *  <em>C<sub>r</sub></em> = <em>C<sub>d</sub></em>
  387        *</pre>
  388        * @since 1.4
  389        */
  390       public static final int     DST             = 9;
  391       // Note that DST was added in 1.4 so it is numbered out of order...
  392   
  393       /**
  394        * The source is composited over the destination
  395        * (Porter-Duff Source Over Destination rule).
  396        *<p>
  397        * <em>F<sub>s</sub></em> = 1 and <em>F<sub>d</sub></em> = (1-<em>A<sub>s</sub></em>), thus:
  398        *<pre>
  399        *  <em>A<sub>r</sub></em> = <em>A<sub>s</sub></em> + <em>A<sub>d</sub></em>*(1-<em>A<sub>s</sub></em>)
  400        *  <em>C<sub>r</sub></em> = <em>C<sub>s</sub></em> + <em>C<sub>d</sub></em>*(1-<em>A<sub>s</sub></em>)
  401        *</pre>
  402        */
  403       public static final int     SRC_OVER        = 3;
  404   
  405       /**
  406        * The destination is composited over the source and
  407        * the result replaces the destination
  408        * (Porter-Duff Destination Over Source rule).
  409        *<p>
  410        * <em>F<sub>s</sub></em> = (1-<em>A<sub>d</sub></em>) and <em>F<sub>d</sub></em> = 1, thus:
  411        *<pre>
  412        *  <em>A<sub>r</sub></em> = <em>A<sub>s</sub></em>*(1-<em>A<sub>d</sub></em>) + <em>A<sub>d</sub></em>
  413        *  <em>C<sub>r</sub></em> = <em>C<sub>s</sub></em>*(1-<em>A<sub>d</sub></em>) + <em>C<sub>d</sub></em>
  414        *</pre>
  415        */
  416       public static final int     DST_OVER        = 4;
  417   
  418       /**
  419        * The part of the source lying inside of the destination replaces
  420        * the destination
  421        * (Porter-Duff Source In Destination rule).
  422        *<p>
  423        * <em>F<sub>s</sub></em> = <em>A<sub>d</sub></em> and <em>F<sub>d</sub></em> = 0, thus:
  424        *<pre>
  425        *  <em>A<sub>r</sub></em> = <em>A<sub>s</sub></em>*<em>A<sub>d</sub></em>
  426        *  <em>C<sub>r</sub></em> = <em>C<sub>s</sub></em>*<em>A<sub>d</sub></em>
  427        *</pre>
  428        */
  429       public static final int     SRC_IN          = 5;
  430   
  431       /**
  432        * The part of the destination lying inside of the source
  433        * replaces the destination
  434        * (Porter-Duff Destination In Source rule).
  435        *<p>
  436        * <em>F<sub>s</sub></em> = 0 and <em>F<sub>d</sub></em> = <em>A<sub>s</sub></em>, thus:
  437        *<pre>
  438        *  <em>A<sub>r</sub></em> = <em>A<sub>d</sub></em>*<em>A<sub>s</sub></em>
  439        *  <em>C<sub>r</sub></em> = <em>C<sub>d</sub></em>*<em>A<sub>s</sub></em>
  440        *</pre>
  441        */
  442       public static final int     DST_IN          = 6;
  443   
  444       /**
  445        * The part of the source lying outside of the destination
  446        * replaces the destination
  447        * (Porter-Duff Source Held Out By Destination rule).
  448        *<p>
  449        * <em>F<sub>s</sub></em> = (1-<em>A<sub>d</sub></em>) and <em>F<sub>d</sub></em> = 0, thus:
  450        *<pre>
  451        *  <em>A<sub>r</sub></em> = <em>A<sub>s</sub></em>*(1-<em>A<sub>d</sub></em>)
  452        *  <em>C<sub>r</sub></em> = <em>C<sub>s</sub></em>*(1-<em>A<sub>d</sub></em>)
  453        *</pre>
  454        */
  455       public static final int     SRC_OUT         = 7;
  456   
  457       /**
  458        * The part of the destination lying outside of the source
  459        * replaces the destination
  460        * (Porter-Duff Destination Held Out By Source rule).
  461        *<p>
  462        * <em>F<sub>s</sub></em> = 0 and <em>F<sub>d</sub></em> = (1-<em>A<sub>s</sub></em>), thus:
  463        *<pre>
  464        *  <em>A<sub>r</sub></em> = <em>A<sub>d</sub></em>*(1-<em>A<sub>s</sub></em>)
  465        *  <em>C<sub>r</sub></em> = <em>C<sub>d</sub></em>*(1-<em>A<sub>s</sub></em>)
  466        *</pre>
  467        */
  468       public static final int     DST_OUT         = 8;
  469   
  470       // Rule 9 is DST which is defined above where it fits into the
  471       // list logically, rather than numerically
  472       //
  473       // public static final int  DST             = 9;
  474   
  475       /**
  476        * The part of the source lying inside of the destination
  477        * is composited onto the destination
  478        * (Porter-Duff Source Atop Destination rule).
  479        *<p>
  480        * <em>F<sub>s</sub></em> = <em>A<sub>d</sub></em> and <em>F<sub>d</sub></em> = (1-<em>A<sub>s</sub></em>), thus:
  481        *<pre>
  482        *  <em>A<sub>r</sub></em> = <em>A<sub>s</sub></em>*<em>A<sub>d</sub></em> + <em>A<sub>d</sub></em>*(1-<em>A<sub>s</sub></em>) = <em>A<sub>d</sub></em>
  483        *  <em>C<sub>r</sub></em> = <em>C<sub>s</sub></em>*<em>A<sub>d</sub></em> + <em>C<sub>d</sub></em>*(1-<em>A<sub>s</sub></em>)
  484        *</pre>
  485        * @since 1.4
  486        */
  487       public static final int     SRC_ATOP        = 10;
  488   
  489       /**
  490        * The part of the destination lying inside of the source
  491        * is composited over the source and replaces the destination
  492        * (Porter-Duff Destination Atop Source rule).
  493        *<p>
  494        * <em>F<sub>s</sub></em> = (1-<em>A<sub>d</sub></em>) and <em>F<sub>d</sub></em> = <em>A<sub>s</sub></em>, thus:
  495        *<pre>
  496        *  <em>A<sub>r</sub></em> = <em>A<sub>s</sub></em>*(1-<em>A<sub>d</sub></em>) + <em>A<sub>d</sub></em>*<em>A<sub>s</sub></em> = <em>A<sub>s</sub></em>
  497        *  <em>C<sub>r</sub></em> = <em>C<sub>s</sub></em>*(1-<em>A<sub>d</sub></em>) + <em>C<sub>d</sub></em>*<em>A<sub>s</sub></em>
  498        *</pre>
  499        * @since 1.4
  500        */
  501       public static final int     DST_ATOP        = 11;
  502   
  503       /**
  504        * The part of the source that lies outside of the destination
  505        * is combined with the part of the destination that lies outside
  506        * of the source
  507        * (Porter-Duff Source Xor Destination rule).
  508        *<p>
  509        * <em>F<sub>s</sub></em> = (1-<em>A<sub>d</sub></em>) and <em>F<sub>d</sub></em> = (1-<em>A<sub>s</sub></em>), thus:
  510        *<pre>
  511        *  <em>A<sub>r</sub></em> = <em>A<sub>s</sub></em>*(1-<em>A<sub>d</sub></em>) + <em>A<sub>d</sub></em>*(1-<em>A<sub>s</sub></em>)
  512        *  <em>C<sub>r</sub></em> = <em>C<sub>s</sub></em>*(1-<em>A<sub>d</sub></em>) + <em>C<sub>d</sub></em>*(1-<em>A<sub>s</sub></em>)
  513        *</pre>
  514        * @since 1.4
  515        */
  516       public static final int     XOR             = 12;
  517   
  518       /**
  519        * <code>AlphaComposite</code> object that implements the opaque CLEAR rule
  520        * with an alpha of 1.0f.
  521        * @see #CLEAR
  522        */
  523       public static final AlphaComposite Clear    = new AlphaComposite(CLEAR);
  524   
  525       /**
  526        * <code>AlphaComposite</code> object that implements the opaque SRC rule
  527        * with an alpha of 1.0f.
  528        * @see #SRC
  529        */
  530       public static final AlphaComposite Src      = new AlphaComposite(SRC);
  531   
  532       /**
  533        * <code>AlphaComposite</code> object that implements the opaque DST rule
  534        * with an alpha of 1.0f.
  535        * @see #DST
  536        * @since 1.4
  537        */
  538       public static final AlphaComposite Dst      = new AlphaComposite(DST);
  539   
  540       /**
  541        * <code>AlphaComposite</code> object that implements the opaque SRC_OVER rule
  542        * with an alpha of 1.0f.
  543        * @see #SRC_OVER
  544        */
  545       public static final AlphaComposite SrcOver  = new AlphaComposite(SRC_OVER);
  546   
  547       /**
  548        * <code>AlphaComposite</code> object that implements the opaque DST_OVER rule
  549        * with an alpha of 1.0f.
  550        * @see #DST_OVER
  551        */
  552       public static final AlphaComposite DstOver  = new AlphaComposite(DST_OVER);
  553   
  554       /**
  555        * <code>AlphaComposite</code> object that implements the opaque SRC_IN rule
  556        * with an alpha of 1.0f.
  557        * @see #SRC_IN
  558        */
  559       public static final AlphaComposite SrcIn    = new AlphaComposite(SRC_IN);
  560   
  561       /**
  562        * <code>AlphaComposite</code> object that implements the opaque DST_IN rule
  563        * with an alpha of 1.0f.
  564        * @see #DST_IN
  565        */
  566       public static final AlphaComposite DstIn    = new AlphaComposite(DST_IN);
  567   
  568       /**
  569        * <code>AlphaComposite</code> object that implements the opaque SRC_OUT rule
  570        * with an alpha of 1.0f.
  571        * @see #SRC_OUT
  572        */
  573       public static final AlphaComposite SrcOut   = new AlphaComposite(SRC_OUT);
  574   
  575       /**
  576        * <code>AlphaComposite</code> object that implements the opaque DST_OUT rule
  577        * with an alpha of 1.0f.
  578        * @see #DST_OUT
  579        */
  580       public static final AlphaComposite DstOut   = new AlphaComposite(DST_OUT);
  581   
  582       /**
  583        * <code>AlphaComposite</code> object that implements the opaque SRC_ATOP rule
  584        * with an alpha of 1.0f.
  585        * @see #SRC_ATOP
  586        * @since 1.4
  587        */
  588       public static final AlphaComposite SrcAtop  = new AlphaComposite(SRC_ATOP);
  589   
  590       /**
  591        * <code>AlphaComposite</code> object that implements the opaque DST_ATOP rule
  592        * with an alpha of 1.0f.
  593        * @see #DST_ATOP
  594        * @since 1.4
  595        */
  596       public static final AlphaComposite DstAtop  = new AlphaComposite(DST_ATOP);
  597   
  598       /**
  599        * <code>AlphaComposite</code> object that implements the opaque XOR rule
  600        * with an alpha of 1.0f.
  601        * @see #XOR
  602        * @since 1.4
  603        */
  604       public static final AlphaComposite Xor      = new AlphaComposite(XOR);
  605   
  606       private static final int MIN_RULE = CLEAR;
  607       private static final int MAX_RULE = XOR;
  608   
  609       float extraAlpha;
  610       int rule;
  611   
  612       private AlphaComposite(int rule) {
  613           this(rule, 1.0f);
  614       }
  615   
  616       private AlphaComposite(int rule, float alpha) {
  617           if (rule < MIN_RULE || rule > MAX_RULE) {
  618               throw new IllegalArgumentException("unknown composite rule");
  619           }
  620           if (alpha >= 0.0f && alpha <= 1.0f) {
  621               this.rule = rule;
  622               this.extraAlpha = alpha;
  623           } else {
  624               throw new IllegalArgumentException("alpha value out of range");
  625           }
  626       }
  627   
  628       /**
  629        * Creates an <code>AlphaComposite</code> object with the specified rule.
  630        * @param rule the compositing rule
  631        * @throws IllegalArgumentException if <code>rule</code> is not one of
  632        *         the following:  {@link #CLEAR}, {@link #SRC}, {@link #DST},
  633        *         {@link #SRC_OVER}, {@link #DST_OVER}, {@link #SRC_IN},
  634        *         {@link #DST_IN}, {@link #SRC_OUT}, {@link #DST_OUT},
  635        *         {@link #SRC_ATOP}, {@link #DST_ATOP}, or {@link #XOR}
  636        */
  637       public static AlphaComposite getInstance(int rule) {
  638           switch (rule) {
  639           case CLEAR:
  640               return Clear;
  641           case SRC:
  642               return Src;
  643           case DST:
  644               return Dst;
  645           case SRC_OVER:
  646               return SrcOver;
  647           case DST_OVER:
  648               return DstOver;
  649           case SRC_IN:
  650               return SrcIn;
  651           case DST_IN:
  652               return DstIn;
  653           case SRC_OUT:
  654               return SrcOut;
  655           case DST_OUT:
  656               return DstOut;
  657           case SRC_ATOP:
  658               return SrcAtop;
  659           case DST_ATOP:
  660               return DstAtop;
  661           case XOR:
  662               return Xor;
  663           default:
  664               throw new IllegalArgumentException("unknown composite rule");
  665           }
  666       }
  667   
  668       /**
  669        * Creates an <code>AlphaComposite</code> object with the specified rule and
  670        * the constant alpha to multiply with the alpha of the source.
  671        * The source is multiplied with the specified alpha before being composited
  672        * with the destination.
  673        * @param rule the compositing rule
  674        * @param alpha the constant alpha to be multiplied with the alpha of
  675        * the source. <code>alpha</code> must be a floating point number in the
  676        * inclusive range [0.0,&nbsp;1.0].
  677        * @throws IllegalArgumentException if
  678        *         <code>alpha</code> is less than 0.0 or greater than 1.0, or if
  679        *         <code>rule</code> is not one of
  680        *         the following:  {@link #CLEAR}, {@link #SRC}, {@link #DST},
  681        *         {@link #SRC_OVER}, {@link #DST_OVER}, {@link #SRC_IN},
  682        *         {@link #DST_IN}, {@link #SRC_OUT}, {@link #DST_OUT},
  683        *         {@link #SRC_ATOP}, {@link #DST_ATOP}, or {@link #XOR}
  684        */
  685       public static AlphaComposite getInstance(int rule, float alpha) {
  686           if (alpha == 1.0f) {
  687               return getInstance(rule);
  688           }
  689           return new AlphaComposite(rule, alpha);
  690       }
  691   
  692       /**
  693        * Creates a context for the compositing operation.
  694        * The context contains state that is used in performing
  695        * the compositing operation.
  696        * @param srcColorModel  the {@link ColorModel} of the source
  697        * @param dstColorModel  the <code>ColorModel</code> of the destination
  698        * @return the <code>CompositeContext</code> object to be used to perform
  699        * compositing operations.
  700        */
  701       public CompositeContext createContext(ColorModel srcColorModel,
  702                                             ColorModel dstColorModel,
  703                                             RenderingHints hints) {
  704           return new SunCompositeContext(this, srcColorModel, dstColorModel);
  705       }
  706   
  707       /**
  708        * Returns the alpha value of this <code>AlphaComposite</code>.  If this
  709        * <code>AlphaComposite</code> does not have an alpha value, 1.0 is returned.
  710        * @return the alpha value of this <code>AlphaComposite</code>.
  711        */
  712       public float getAlpha() {
  713           return extraAlpha;
  714       }
  715   
  716       /**
  717        * Returns the compositing rule of this <code>AlphaComposite</code>.
  718        * @return the compositing rule of this <code>AlphaComposite</code>.
  719        */
  720       public int getRule() {
  721           return rule;
  722       }
  723   
  724       /**
  725        * Returns a similar <code>AlphaComposite</code> object that uses
  726        * the specified compositing rule.
  727        * If this object already uses the specified compositing rule,
  728        * this object is returned.
  729        * @return an <code>AlphaComposite</code> object derived from
  730        * this object that uses the specified compositing rule.
  731        * @param rule the compositing rule
  732        * @throws IllegalArgumentException if
  733        *         <code>rule</code> is not one of
  734        *         the following:  {@link #CLEAR}, {@link #SRC}, {@link #DST},
  735        *         {@link #SRC_OVER}, {@link #DST_OVER}, {@link #SRC_IN},
  736        *         {@link #DST_IN}, {@link #SRC_OUT}, {@link #DST_OUT},
  737        *         {@link #SRC_ATOP}, {@link #DST_ATOP}, or {@link #XOR}
  738        * @since 1.6
  739        */
  740       public AlphaComposite derive(int rule) {
  741           return (this.rule == rule)
  742               ? this
  743               : getInstance(rule, this.extraAlpha);
  744       }
  745   
  746       /**
  747        * Returns a similar <code>AlphaComposite</code> object that uses
  748        * the specified alpha value.
  749        * If this object already has the specified alpha value,
  750        * this object is returned.
  751        * @return an <code>AlphaComposite</code> object derived from
  752        * this object that uses the specified alpha value.
  753        * @param alpha the constant alpha to be multiplied with the alpha of
  754        * the source. <code>alpha</code> must be a floating point number in the
  755        * inclusive range [0.0,&nbsp;1.0].
  756        * @throws IllegalArgumentException if
  757        *         <code>alpha</code> is less than 0.0 or greater than 1.0
  758        * @since 1.6
  759        */
  760       public AlphaComposite derive(float alpha) {
  761           return (this.extraAlpha == alpha)
  762               ? this
  763               : getInstance(this.rule, alpha);
  764       }
  765   
  766       /**
  767        * Returns the hashcode for this composite.
  768        * @return      a hash code for this composite.
  769        */
  770       public int hashCode() {
  771           return (Float.floatToIntBits(extraAlpha) * 31 + rule);
  772       }
  773   
  774       /**
  775        * Determines whether the specified object is equal to this
  776        * <code>AlphaComposite</code>.
  777        * <p>
  778        * The result is <code>true</code> if and only if
  779        * the argument is not <code>null</code> and is an
  780        * <code>AlphaComposite</code> object that has the same
  781        * compositing rule and alpha value as this object.
  782        *
  783        * @param obj the <code>Object</code> to test for equality
  784        * @return <code>true</code> if <code>obj</code> equals this
  785        * <code>AlphaComposite</code>; <code>false</code> otherwise.
  786        */
  787       public boolean equals(Object obj) {
  788           if (!(obj instanceof AlphaComposite)) {
  789               return false;
  790           }
  791   
  792           AlphaComposite ac = (AlphaComposite) obj;
  793   
  794           if (rule != ac.rule) {
  795               return false;
  796           }
  797   
  798           if (extraAlpha != ac.extraAlpha) {
  799               return false;
  800           }
  801   
  802           return true;
  803       }
  804   
  805   }

Home » openjdk-7 » java » awt » [javadoc | source]