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