KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > java > awt > 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 JavaDoc;
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 JavaDoc {
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 JavaDoc Clear = new AlphaComposite JavaDoc(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 JavaDoc Src = new AlphaComposite JavaDoc(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 JavaDoc Dst = new AlphaComposite JavaDoc(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 JavaDoc SrcOver = new AlphaComposite JavaDoc(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 JavaDoc DstOver = new AlphaComposite JavaDoc(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 JavaDoc SrcIn = new AlphaComposite JavaDoc(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 JavaDoc DstIn = new AlphaComposite JavaDoc(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 JavaDoc SrcOut = new AlphaComposite JavaDoc(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 JavaDoc DstOut = new AlphaComposite JavaDoc(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 JavaDoc SrcAtop = new AlphaComposite JavaDoc(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 JavaDoc DstAtop = new AlphaComposite JavaDoc(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 JavaDoc Xor = new AlphaComposite JavaDoc(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 JavaDoc("alpha value out of range");
602     }
603     if (rule < MIN_RULE || rule > MAX_RULE) {
604         throw new IllegalArgumentException JavaDoc("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 JavaDoc 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 JavaDoc("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 JavaDoc getInstance(int rule, float alpha) {
668     if (alpha == 1.0f) {
669         return getInstance(rule);
670     }
671     return new AlphaComposite JavaDoc(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 JavaDoc createContext(ColorModel JavaDoc srcColorModel,
684                       ColorModel JavaDoc dstColorModel,
685                                           RenderingHints JavaDoc 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 JavaDoc obj) {
728         if (!(obj instanceof AlphaComposite JavaDoc)) {
729             return false;
730         }
731
732         AlphaComposite JavaDoc ac = (AlphaComposite JavaDoc) 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
Popular Tags