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