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 * <blockquote>
76 * <table class="borderless">
77 * <caption style="display:none">Factors</caption>
78 * <tr><th style="text-align:left">Factor <th style="text-align:left">Definition
79 * <tr><td><em>A<sub>s</sub></em><td>the alpha component of the source pixel
80 * <tr><td><em>C<sub>s</sub></em><td>a color component of the source pixel in premultiplied form
81 * <tr><td><em>A<sub>d</sub></em><td>the alpha component of the destination pixel
82 * <tr><td><em>C<sub>d</sub></em><td>a color component of the destination pixel in premultiplied form
83 * <tr><td><em>F<sub>s</sub></em><td>the fraction of the source pixel that contributes to the output
84 * <tr><td><em>F<sub>d</sub></em><td>the fraction of the destination pixel that contributes
85 * to the output
86 * <tr><td><em>A<sub>r</sub></em><td>the alpha component of the result
87 * <tr><td><em>C<sub>r</sub></em><td>a color component of the result in premultiplied form
88 * </table>
89 * </blockquote>
90 *
91 * <p>
92 * Using these factors, Porter and Duff define 12 ways of choosing
93 * the blending factors <em>F<sub>s</sub></em> and <em>F<sub>d</sub></em> to
94 * produce each of 12 desirable visual effects.
95 * The equations for determining <em>F<sub>s</sub></em> and <em>F<sub>d</sub></em>
96 * are given in the descriptions of the 12 static fields
97 * that specify visual effects.
98 * For example,
99 * the description for
100 * <a href="#SRC_OVER">{@code SRC_OVER}</a>
101 * specifies that <em>F<sub>s</sub></em> = 1 and <em>F<sub>d</sub></em> = (1-<em>A<sub>s</sub></em>).
102 * Once a set of equations for determining the blending factors is
103 * known they can then be applied to each pixel to produce a result
104 * using the following set of equations:
105 *
106 * <pre>
107 * <em>F<sub>s</sub></em> = <em>f</em>(<em>A<sub>d</sub></em>)
108 * <em>F<sub>d</sub></em> = <em>f</em>(<em>A<sub>s</sub></em>)
109 * <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>
110 * <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>
111 *
112 * <p>
113 * The following factors will be used to discuss our extensions to
114 * the blending equation in the Porter and Duff paper:
115 *
116 * <blockquote>
117 * <table class="borderless">
118 * <caption style="display:none">Factors</caption>
119 * <tr><th style="text-align:left">Factor <th style="text-align:left">Definition
120 * <tr><td><em>C<sub>sr</sub></em> <td>one of the raw color components of the source pixel
121 * <tr><td><em>C<sub>dr</sub></em> <td>one of the raw color components of the destination pixel
122 * <tr><td><em>A<sub>ac</sub></em> <td>the "extra" alpha component from the AlphaComposite instance
123 * <tr><td><em>A<sub>sr</sub></em> <td>the raw alpha component of the source pixel
124 * <tr><td><em>A<sub>dr</sub></em><td>the raw alpha component of the destination pixel
125 * <tr><td><em>A<sub>df</sub></em> <td>the final alpha component stored in the destination
126 * <tr><td><em>C<sub>df</sub></em> <td>the final raw color component stored in the destination
127 * </table>
128 *</blockquote>
129 *
130 * <h3>Preparing Inputs</h3>
131 *
132 * <p>
133 * The {@code AlphaComposite} class defines an additional alpha
134 * value that is applied to the source alpha.
135 * This value is applied as if an implicit SRC_IN rule were first
136 * applied to the source pixel against a pixel with the indicated
137 * alpha by multiplying both the raw source alpha and the raw
138 * source colors by the alpha in the {@code AlphaComposite}.
139 * This leads to the following equation for producing the alpha
140 * used in the Porter and Duff blending equation:
141 *
142 * <pre>
143 * <em>A<sub>s</sub></em> = <em>A<sub>sr</sub></em> * <em>A<sub>ac</sub></em> </pre>
144 *
145 * All of the raw source color components need to be multiplied
146 * by the alpha in the {@code AlphaComposite} instance.
147 * Additionally, if the source was not in premultiplied form
148 * then the color components also need to be multiplied by the
149 * source alpha.
150 * Thus, the equation for producing the source color components
151 * for the Porter and Duff equation depends on whether the source
152 * pixels are premultiplied or not:
153 *
154 * <pre>
155 * <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)
156 * <em>C<sub>s</sub></em> = <em>C<sub>sr</sub></em> * <em>A<sub>ac</sub></em> (if source is premultiplied) </pre>
157 *
158 * No adjustment needs to be made to the destination alpha:
159 *
160 * <pre>
161 * <em>A<sub>d</sub></em> = <em>A<sub>dr</sub></em> </pre>
162 *
163 * <p>
164 * The destination color components need to be adjusted only if
165 * they are not in premultiplied form:
166 *
167 * <pre>
168 * <em>C<sub>d</sub></em> = <em>C<sub>dr</sub></em> * <em>A<sub>d</sub></em> (if destination is not premultiplied)
169 * <em>C<sub>d</sub></em> = <em>C<sub>dr</sub></em> (if destination is premultiplied) </pre>
170 *
171 * <h3>Applying the Blending Equation</h3>
172 *
173 * <p>
174 * The adjusted <em>A<sub>s</sub></em>, <em>A<sub>d</sub></em>,
175 * <em>C<sub>s</sub></em>, and <em>C<sub>d</sub></em> are used in the standard
176 * Porter and Duff equations to calculate the blending factors
177 * <em>F<sub>s</sub></em> and <em>F<sub>d</sub></em> and then the resulting
178 * premultiplied components <em>A<sub>r</sub></em> and <em>C<sub>r</sub></em>.
179 *
180 * <h3>Preparing Results</h3>
181 *
182 * <p>
183 * The results only need to be adjusted if they are to be stored
184 * back into a destination buffer that holds data that is not
185 * premultiplied, using the following equations:
186 *
187 * <pre>
188 * <em>A<sub>df</sub></em> = <em>A<sub>r</sub></em>
189 * <em>C<sub>df</sub></em> = <em>C<sub>r</sub></em> (if dest is premultiplied)
190 * <em>C<sub>df</sub></em> = <em>C<sub>r</sub></em> / <em>A<sub>r</sub></em> (if dest is not premultiplied) </pre>
191 *
192 * Note that since the division is undefined if the resulting alpha
193 * is zero, the division in that case is omitted to avoid the "divide
194 * by zero" and the color components are left as
195 * all zeros.
196 *
197 * <h3>Performance Considerations</h3>
198 *
199 * <p>
200 * For performance reasons, it is preferable that
201 * {@code Raster} objects passed to the {@code compose}
202 * method of a {@link CompositeContext} object created by the
203 * {@code AlphaComposite} class have premultiplied data.
204 * If either the source {@code Raster}
205 * or the destination {@code Raster}
206 * is not premultiplied, however,
207 * appropriate conversions are performed before and after the compositing
208 * operation.
209 *
210 * <h3><a id="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} 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 * <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 * <li>
230 * The accuracy of the results depends on the manner in which pixels
231 * are stored in the destination.
232 * An image format that provides at least 8 bits of storage per color
233 * and alpha component is at least adequate for use as a destination
234 * for a sequence of a few to a dozen compositing operations.
235 * An image format with fewer than 8 bits of storage per component
236 * is of limited use for just one or two compositing operations
237 * before the rounding errors dominate the results.
238 * An image format
239 * that does not separately store
240 * color components is not a
241 * good candidate for any type of translucent blending.
242 * For example, {@code BufferedImage.TYPE_BYTE_INDEXED}
243 * should not be used as a destination for a blending operation
244 * because every operation
245 * can introduce large errors, due to
246 * the need to choose a pixel from a limited palette to match the
247 * results of the blending equations.
248 *
249 * <li>
250 * Nearly all formats store pixels as discrete integers rather than
251 * the floating point values used in the reference equations above.
252 * The implementation can either scale the integer pixel
253 * values into floating point values in the range 0.0 to 1.0 or
254 * use slightly modified versions of the equations
255 * that operate entirely in the integer domain and yet produce
256 * analogous results to the reference equations.
257 *
258 * <p>
259 * Typically the integer values are related to the floating point
260 * values in such a way that the integer 0 is equated
261 * to the floating point value 0.0 and the integer
262 * 2^<em>n</em>-1 (where <em>n</em> is the number of bits
263 * in the representation) is equated to 1.0.
264 * For 8-bit representations, this means that 0x00
265 * represents 0.0 and 0xff represents
266 * 1.0.
267 *
268 * <li>
269 * The internal implementation can approximate some of the equations
270 * and it can also eliminate some steps to avoid unnecessary operations.
271 * For example, consider a discrete integer image with non-premultiplied
272 * alpha values that uses 8 bits per component for storage.
273 * The stored values for a
274 * nearly transparent darkened red might be:
275 *
276 * <pre>
277 * (A, R, G, B) = (0x01, 0xb0, 0x00, 0x00)</pre>
278 *
279 * <p>
280 * If integer math were being used and this value were being
281 * composited in
282 * <a href="#SRC">{@code SRC}</a>
283 * mode with no extra alpha, then the math would
284 * indicate that the results were (in integer format):
285 *
286 * <pre>
287 * (A, R, G, B) = (0x01, 0x01, 0x00, 0x00)</pre>
288 *
289 * <p>
290 * Note that the intermediate values, which are always in premultiplied
291 * form, would only allow the integer red component to be either 0x00
292 * or 0x01. When we try to store this result back into a destination
293 * that is not premultiplied, dividing out the alpha will give us
294 * very few choices for the non-premultiplied red value.
295 * In this case an implementation that performs the math in integer
296 * space without shortcuts is likely to end up with the final pixel
297 * values of:
298 *
299 * <pre>
300 * (A, R, G, B) = (0x01, 0xff, 0x00, 0x00)</pre>
301 *
302 * <p>
303 * (Note that 0x01 divided by 0x01 gives you 1.0, which is equivalent
304 * to the value 0xff in an 8-bit storage format.)
305 *
306 * <p>
307 * Alternately, an implementation that uses floating point math
308 * might produce more accurate results and end up returning to the
309 * original pixel value with little, if any, round-off error.
310 * Or, an implementation using integer math might decide that since
311 * the equations boil down to a virtual NOP on the color values
312 * if performed in a floating point space, it can transfer the
313 * pixel untouched to the destination and avoid all the math entirely.
314 *
315 * <p>
316 * These implementations all attempt to honor the
317 * same equations, but use different tradeoffs of integer and
318 * floating point math and reduced or full equations.
319 * To account for such differences, it is probably best to
320 * expect only that the premultiplied form of the results to
321 * match between implementations and image formats. In this
322 * case both answers, expressed in premultiplied form would
323 * equate to:
324 *
325 * <pre>
326 * (A, R, G, B) = (0x01, 0x01, 0x00, 0x00)</pre>
327 *
328 * <p>
329 * and thus they would all match.
330 *
331 * <li>
332 * Because of the technique of simplifying the equations for
333 * calculation efficiency, some implementations might perform
334 * differently when encountering result alpha values of 0.0
335 * on a non-premultiplied destination.
336 * Note that the simplification of removing the divide by alpha
337 * in the case of the SRC rule is technically not valid if the
338 * denominator (alpha) is 0.
339 * But, since the results should only be expected to be accurate
340 * when viewed in premultiplied form, a resulting alpha of 0
341 * essentially renders the resulting color components irrelevant
342 * and so exact behavior in this case should not be expected.
343 * </ul>
344 * @see Composite
345 * @see CompositeContext
346 */
347
348 public final class AlphaComposite implements Composite {
349 /**
350 * Both the color and the alpha of the destination are cleared
351 * (Porter-Duff Clear rule).
352 * Neither the source nor the destination is used as input.
353 *<p>
354 * <em>F<sub>s</sub></em> = 0 and <em>F<sub>d</sub></em> = 0, thus:
355 *<pre>
356 * <em>A<sub>r</sub></em> = 0
357 * <em>C<sub>r</sub></em> = 0
358 *</pre>
359 */
360 @Native public static final int CLEAR = 1;
361
362 /**
363 * The source is copied to the destination
364 * (Porter-Duff Source rule).
365 * The destination is not used as input.
366 *<p>
367 * <em>F<sub>s</sub></em> = 1 and <em>F<sub>d</sub></em> = 0, thus:
368 *<pre>
369 * <em>A<sub>r</sub></em> = <em>A<sub>s</sub></em>
370 * <em>C<sub>r</sub></em> = <em>C<sub>s</sub></em>
371 *</pre>
372 */
373 @Native public static final int SRC = 2;
374
375 /**
376 * The destination is left untouched
377 * (Porter-Duff Destination rule).
378 *<p>
379 * <em>F<sub>s</sub></em> = 0 and <em>F<sub>d</sub></em> = 1, thus:
380 *<pre>
381 * <em>A<sub>r</sub></em> = <em>A<sub>d</sub></em>
382 * <em>C<sub>r</sub></em> = <em>C<sub>d</sub></em>
383 *</pre>
384 * @since 1.4
385 */
386 @Native public static final int DST = 9;
387 // Note that DST was added in 1.4 so it is numbered out of order...
388
389 /**
390 * The source is composited over the destination
391 * (Porter-Duff Source Over Destination rule).
392 *<p>
393 * <em>F<sub>s</sub></em> = 1 and <em>F<sub>d</sub></em> = (1-<em>A<sub>s</sub></em>), thus:
394 *<pre>
395 * <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>)
396 * <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>)
397 *</pre>
398 */
399 @Native public static final int SRC_OVER = 3;
400
401 /**
402 * The destination is composited over the source and
403 * the result replaces the destination
404 * (Porter-Duff Destination Over Source rule).
405 *<p>
406 * <em>F<sub>s</sub></em> = (1-<em>A<sub>d</sub></em>) and <em>F<sub>d</sub></em> = 1, thus:
407 *<pre>
408 * <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>
409 * <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>
410 *</pre>
411 */
412 @Native public static final int DST_OVER = 4;
413
414 /**
415 * The part of the source lying inside of the destination replaces
416 * the destination
417 * (Porter-Duff Source In Destination rule).
418 *<p>
419 * <em>F<sub>s</sub></em> = <em>A<sub>d</sub></em> and <em>F<sub>d</sub></em> = 0, thus:
420 *<pre>
421 * <em>A<sub>r</sub></em> = <em>A<sub>s</sub></em>*<em>A<sub>d</sub></em>
422 * <em>C<sub>r</sub></em> = <em>C<sub>s</sub></em>*<em>A<sub>d</sub></em>
423 *</pre>
424 */
425 @Native public static final int SRC_IN = 5;
426
427 /**
428 * The part of the destination lying inside of the source
429 * replaces the destination
430 * (Porter-Duff Destination In Source rule).
431 *<p>
432 * <em>F<sub>s</sub></em> = 0 and <em>F<sub>d</sub></em> = <em>A<sub>s</sub></em>, thus:
433 *<pre>
434 * <em>A<sub>r</sub></em> = <em>A<sub>d</sub></em>*<em>A<sub>s</sub></em>
435 * <em>C<sub>r</sub></em> = <em>C<sub>d</sub></em>*<em>A<sub>s</sub></em>
436 *</pre>
437 */
438 @Native public static final int DST_IN = 6;
439
440 /**
441 * The part of the source lying outside of the destination
442 * replaces the destination
443 * (Porter-Duff Source Held Out By Destination rule).
444 *<p>
445 * <em>F<sub>s</sub></em> = (1-<em>A<sub>d</sub></em>) and <em>F<sub>d</sub></em> = 0, thus:
446 *<pre>
447 * <em>A<sub>r</sub></em> = <em>A<sub>s</sub></em>*(1-<em>A<sub>d</sub></em>)
448 * <em>C<sub>r</sub></em> = <em>C<sub>s</sub></em>*(1-<em>A<sub>d</sub></em>)
449 *</pre>
450 */
451 @Native public static final int SRC_OUT = 7;
452
453 /**
454 * The part of the destination lying outside of the source
455 * replaces the destination
456 * (Porter-Duff Destination Held Out By Source rule).
457 *<p>
458 * <em>F<sub>s</sub></em> = 0 and <em>F<sub>d</sub></em> = (1-<em>A<sub>s</sub></em>), thus:
459 *<pre>
460 * <em>A<sub>r</sub></em> = <em>A<sub>d</sub></em>*(1-<em>A<sub>s</sub></em>)
461 * <em>C<sub>r</sub></em> = <em>C<sub>d</sub></em>*(1-<em>A<sub>s</sub></em>)
462 *</pre>
463 */
464 @Native public static final int DST_OUT = 8;
465
466 // Rule 9 is DST which is defined above where it fits into the
467 // list logically, rather than numerically
468 //
469 // public static final int DST = 9;
470
471 /**
472 * The part of the source lying inside of the destination
473 * is composited onto the destination
474 * (Porter-Duff Source Atop Destination rule).
475 *<p>
476 * <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:
477 *<pre>
478 * <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>
479 * <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>)
480 *</pre>
481 * @since 1.4
482 */
483 @Native public static final int SRC_ATOP = 10;
484
485 /**
486 * The part of the destination lying inside of the source
487 * is composited over the source and replaces the destination
488 * (Porter-Duff Destination Atop Source rule).
489 *<p>
490 * <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:
491 *<pre>
492 * <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>
493 * <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>
494 *</pre>
495 * @since 1.4
496 */
497 @Native public static final int DST_ATOP = 11;
498
499 /**
500 * The part of the source that lies outside of the destination
501 * is combined with the part of the destination that lies outside
502 * of the source
503 * (Porter-Duff Source Xor Destination rule).
504 *<p>
505 * <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:
506 *<pre>
507 * <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>)
508 * <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>)
509 *</pre>
510 * @since 1.4
511 */
512 @Native public static final int XOR = 12;
513
514 /**
515 * {@code AlphaComposite} object that implements the opaque CLEAR rule
516 * with an alpha of 1.0f.
517 * @see #CLEAR
518 */
519 public static final AlphaComposite Clear = new AlphaComposite(CLEAR);
520
521 /**
522 * {@code AlphaComposite} object that implements the opaque SRC rule
523 * with an alpha of 1.0f.
524 * @see #SRC
525 */
526 public static final AlphaComposite Src = new AlphaComposite(SRC);
527
528 /**
529 * {@code AlphaComposite} object that implements the opaque DST rule
530 * with an alpha of 1.0f.
531 * @see #DST
532 * @since 1.4
533 */
534 public static final AlphaComposite Dst = new AlphaComposite(DST);
535
536 /**
537 * {@code AlphaComposite} object that implements the opaque SRC_OVER rule
538 * with an alpha of 1.0f.
539 * @see #SRC_OVER
540 */
541 public static final AlphaComposite SrcOver = new AlphaComposite(SRC_OVER);
542
543 /**
544 * {@code AlphaComposite} object that implements the opaque DST_OVER rule
545 * with an alpha of 1.0f.
546 * @see #DST_OVER
547 */
548 public static final AlphaComposite DstOver = new AlphaComposite(DST_OVER);
549
550 /**
551 * {@code AlphaComposite} object that implements the opaque SRC_IN rule
552 * with an alpha of 1.0f.
553 * @see #SRC_IN
554 */
555 public static final AlphaComposite SrcIn = new AlphaComposite(SRC_IN);
556
557 /**
558 * {@code AlphaComposite} object that implements the opaque DST_IN rule
559 * with an alpha of 1.0f.
560 * @see #DST_IN
561 */
562 public static final AlphaComposite DstIn = new AlphaComposite(DST_IN);
563
564 /**
565 * {@code AlphaComposite} object that implements the opaque SRC_OUT rule
566 * with an alpha of 1.0f.
567 * @see #SRC_OUT
568 */
569 public static final AlphaComposite SrcOut = new AlphaComposite(SRC_OUT);
570
571 /**
572 * {@code AlphaComposite} object that implements the opaque DST_OUT rule
573 * with an alpha of 1.0f.
574 * @see #DST_OUT
575 */
576 public static final AlphaComposite DstOut = new AlphaComposite(DST_OUT);
577
578 /**
579 * {@code AlphaComposite} object that implements the opaque SRC_ATOP rule
580 * with an alpha of 1.0f.
581 * @see #SRC_ATOP
582 * @since 1.4
583 */
584 public static final AlphaComposite SrcAtop = new AlphaComposite(SRC_ATOP);
585
586 /**
587 * {@code AlphaComposite} object that implements the opaque DST_ATOP rule
588 * with an alpha of 1.0f.
589 * @see #DST_ATOP
590 * @since 1.4
591 */
592 public static final AlphaComposite DstAtop = new AlphaComposite(DST_ATOP);
593
594 /**
595 * {@code AlphaComposite} object that implements the opaque XOR rule
596 * with an alpha of 1.0f.
597 * @see #XOR
598 * @since 1.4
599 */
600 public static final AlphaComposite Xor = new AlphaComposite(XOR);
601
602 @Native private static final int MIN_RULE = CLEAR;
603 @Native private static final int MAX_RULE = XOR;
604
605 float extraAlpha;
606 int rule;
607
608 private AlphaComposite(int rule) {
609 this(rule, 1.0f);
610 }
611
612 private AlphaComposite(int rule, float alpha) {
613 if (rule < MIN_RULE || rule > MAX_RULE) {
614 throw new IllegalArgumentException("unknown composite rule");
615 }
616 if (alpha >= 0.0f && alpha <= 1.0f) {
617 this.rule = rule;
618 this.extraAlpha = alpha;
619 } else {
620 throw new IllegalArgumentException("alpha value out of range");
621 }
622 }
623
624 /**
625 * Creates an {@code AlphaComposite} object with the specified rule.
626 *
627 * @param rule the compositing rule
628 * @return the {@code AlphaComposite} object created
629 * @throws IllegalArgumentException if {@code rule} is not one of
630 * the following: {@link #CLEAR}, {@link #SRC}, {@link #DST},
631 * {@link #SRC_OVER}, {@link #DST_OVER}, {@link #SRC_IN},
632 * {@link #DST_IN}, {@link #SRC_OUT}, {@link #DST_OUT},
633 * {@link #SRC_ATOP}, {@link #DST_ATOP}, or {@link #XOR}
634 */
635 public static AlphaComposite getInstance(int rule) {
636 switch (rule) {
637 case CLEAR:
638 return Clear;
639 case SRC:
640 return Src;
641 case DST:
642 return Dst;
643 case SRC_OVER:
644 return SrcOver;
645 case DST_OVER:
646 return DstOver;
647 case SRC_IN:
648 return SrcIn;
649 case DST_IN:
650 return DstIn;
651 case SRC_OUT:
652 return SrcOut;
653 case DST_OUT:
654 return DstOut;
655 case SRC_ATOP:
656 return SrcAtop;
657 case DST_ATOP:
658 return DstAtop;
659 case XOR:
660 return Xor;
661 default:
662 throw new IllegalArgumentException("unknown composite rule");
663 }
664 }
665
666 /**
667 * Creates an {@code AlphaComposite} object with the specified rule and
668 * the constant alpha to multiply with the alpha of the source.
669 * The source is multiplied with the specified alpha before being composited
670 * with the destination.
671 *
672 * @param rule the compositing rule
673 * @param alpha the constant alpha to be multiplied with the alpha of
674 * the source. {@code alpha} must be a floating point number in the
675 * inclusive range [0.0, 1.0].
676 * @return the {@code AlphaComposite} object created
677 * @throws IllegalArgumentException if
678 * {@code alpha} is less than 0.0 or greater than 1.0, or if
679 * {@code rule} 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} of the destination
698 * @return the {@code CompositeContext} 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}. If this
709 * {@code AlphaComposite} does not have an alpha value, 1.0 is returned.
710 * @return the alpha value of this {@code AlphaComposite}.
711 */
712 public float getAlpha() {
713 return extraAlpha;
714 }
715
716 /**
717 * Returns the compositing rule of this {@code AlphaComposite}.
718 * @return the compositing rule of this {@code AlphaComposite}.
719 */
720 public int getRule() {
721 return rule;
722 }
723
724 /**
725 * Returns a similar {@code AlphaComposite} 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} 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} 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} 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} 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} must be a floating point number in the
755 * inclusive range [0.0, 1.0].
756 * @throws IllegalArgumentException if
757 * {@code alpha} 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}.
777 * <p>
778 * The result is {@code true} if and only if
779 * the argument is not {@code null} and is an
780 * {@code AlphaComposite} object that has the same
781 * compositing rule and alpha value as this object.
782 *
783 * @param obj the {@code Object} to test for equality
784 * @return {@code true} if {@code obj} equals this
785 * {@code AlphaComposite}; {@code false} 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 }