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