AlphaComposite


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