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