1 /* 2 * Copyright (c) 1997, 2014, 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</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 * <h3>Preparing Results</h3> 179 * 180 * <p> 181 * The results only need to be adjusted if they are to be stored 182 * back into a destination buffer that holds data that is not 183 * premultiplied, using the following equations: 184 * 185 * <pre> 186 * <em>A<sub>df</sub></em> = <em>A<sub>r</sub></em> 187 * <em>C<sub>df</sub></em> = <em>C<sub>r</sub></em> (if dest is premultiplied) 188 * <em>C<sub>df</sub></em> = <em>C<sub>r</sub></em> / <em>A<sub>r</sub></em> (if dest is not premultiplied) </pre> 189 * 190 * Note that since the division is undefined if the resulting alpha 191 * is zero, the division in that case is omitted to avoid the "divide 192 * by zero" and the color components are left as 193 * all zeros. 194 * 195 * <h3>Performance Considerations</h3> 196 * 197 * <p> 198 * For performance reasons, it is preferable that 199 * <code>Raster</code> objects passed to the <code>compose</code> 200 * method of a {@link CompositeContext} object created by the 201 * <code>AlphaComposite</code> class have premultiplied data. 202 * If either the source <code>Raster</code> 203 * or the destination <code>Raster</code> 204 * is not premultiplied, however, 205 * appropriate conversions are performed before and after the compositing 206 * operation. 207 * 208 * <h3><a name="caveats">Implementation Caveats</a></h3> 209 * 210 * <ul> 211 * <li> 212 * Many sources, such as some of the opaque image types listed 213 * in the <code>BufferedImage</code> class, do not store alpha values 214 * for their pixels. Such sources supply an alpha of 1.0 for 215 * all of their pixels. 216 * 217 * <li> 218 * Many destinations also have no place to store the alpha values 219 * that result from the blending calculations performed by this class. 220 * Such destinations thus implicitly discard the resulting 221 * alpha values that this class produces. 222 * It is recommended that such destinations should treat their stored 223 * color values as non-premultiplied and divide the resulting color 224 * values by the resulting alpha value before storing the color 225 * values and discarding the alpha value. 226 * 227 * <li> 228 * The accuracy of the results depends on the manner in which pixels 229 * are stored in the destination. 230 * An image format that provides at least 8 bits of storage per color 231 * and alpha component is at least adequate for use as a destination 232 * for a sequence of a few to a dozen compositing operations. 233 * An image format with fewer than 8 bits of storage per component 234 * is of limited use for just one or two compositing operations 235 * before the rounding errors dominate the results. 236 * An image format 237 * that does not separately store 238 * color components is not a 239 * good candidate for any type of translucent blending. 240 * For example, <code>BufferedImage.TYPE_BYTE_INDEXED</code> 241 * should not be used as a destination for a blending operation 242 * because every operation 243 * can introduce large errors, due to 244 * the need to choose a pixel from a limited palette to match the 245 * results of the blending equations. 246 * 247 * <li> 248 * Nearly all formats store pixels as discrete integers rather than 249 * the floating point values used in the reference equations above. 250 * The implementation can either scale the integer pixel 251 * values into floating point values in the range 0.0 to 1.0 or 252 * use slightly modified versions of the equations 253 * that operate entirely in the integer domain and yet produce 254 * analogous results to the reference equations. 255 * 256 * <p> 257 * Typically the integer values are related to the floating point 258 * values in such a way that the integer 0 is equated 259 * to the floating point value 0.0 and the integer 260 * 2^<em>n</em>-1 (where <em>n</em> is the number of bits 261 * in the representation) is equated to 1.0. 262 * For 8-bit representations, this means that 0x00 263 * represents 0.0 and 0xff represents 264 * 1.0. 265 * 266 * <li> 267 * The internal implementation can approximate some of the equations 268 * and it can also eliminate some steps to avoid unnecessary operations. 269 * For example, consider a discrete integer image with non-premultiplied 270 * alpha values that uses 8 bits per component for storage. 271 * The stored values for a 272 * nearly transparent darkened red might be: 273 * 274 * <pre> 275 * (A, R, G, B) = (0x01, 0xb0, 0x00, 0x00)</pre> 276 * 277 * <p> 278 * If integer math were being used and this value were being 279 * composited in 280 * <a href="#SRC"><code>SRC</code></a> 281 * mode with no extra alpha, then the math would 282 * indicate that the results were (in integer format): 283 * 284 * <pre> 285 * (A, R, G, B) = (0x01, 0x01, 0x00, 0x00)</pre> 286 * 287 * <p> 288 * Note that the intermediate values, which are always in premultiplied 289 * form, would only allow the integer red component to be either 0x00 290 * or 0x01. When we try to store this result back into a destination 291 * that is not premultiplied, dividing out the alpha will give us 292 * very few choices for the non-premultiplied red value. 293 * In this case an implementation that performs the math in integer 294 * space without shortcuts is likely to end up with the final pixel 295 * values of: 296 * 297 * <pre> 298 * (A, R, G, B) = (0x01, 0xff, 0x00, 0x00)</pre> 299 * 300 * <p> 301 * (Note that 0x01 divided by 0x01 gives you 1.0, which is equivalent 302 * to the value 0xff in an 8-bit storage format.) 303 * 304 * <p> 305 * Alternately, an implementation that uses floating point math 306 * might produce more accurate results and end up returning to the 307 * original pixel value with little, if any, roundoff error. 308 * Or, an implementation using integer math might decide that since 309 * the equations boil down to a virtual NOP on the color values 310 * if performed in a floating point space, it can transfer the 311 * pixel untouched to the destination and avoid all the math entirely. 312 * 313 * <p> 314 * These implementations all attempt to honor the 315 * same equations, but use different tradeoffs of integer and 316 * floating point math and reduced or full equations. 317 * To account for such differences, it is probably best to 318 * expect only that the premultiplied form of the results to 319 * match between implementations and image formats. In this 320 * case both answers, expressed in premultiplied form would 321 * equate to: 322 * 323 * <pre> 324 * (A, R, G, B) = (0x01, 0x01, 0x00, 0x00)</pre> 325 * 326 * <p> 327 * and thus they would all match. 328 * 329 * <li> 330 * Because of the technique of simplifying the equations for 331 * calculation efficiency, some implementations might perform 332 * differently when encountering result alpha values of 0.0 333 * on a non-premultiplied destination. 334 * Note that the simplification of removing the divide by alpha 335 * in the case of the SRC rule is technically not valid if the 336 * denominator (alpha) is 0. 337 * But, since the results should only be expected to be accurate 338 * when viewed in premultiplied form, a resulting alpha of 0 339 * essentially renders the resulting color components irrelevant 340 * and so exact behavior in this case should not be expected. 341 * </ul> 342 * @see Composite 343 * @see CompositeContext 344 */ 345 346 public final class AlphaComposite implements Composite { 347 /** 348 * Both the color and the alpha of the destination are cleared 349 * (Porter-Duff Clear rule). 350 * Neither the source nor the destination is used as input. 351 *<p> 352 * <em>F<sub>s</sub></em> = 0 and <em>F<sub>d</sub></em> = 0, thus: 353 *<pre> 354 * <em>A<sub>r</sub></em> = 0 355 * <em>C<sub>r</sub></em> = 0 356 *</pre> 357 */ 358 @Native public static final int CLEAR = 1; 359 360 /** 361 * The source is copied to the destination 362 * (Porter-Duff Source rule). 363 * The destination is not used as input. 364 *<p> 365 * <em>F<sub>s</sub></em> = 1 and <em>F<sub>d</sub></em> = 0, thus: 366 *<pre> 367 * <em>A<sub>r</sub></em> = <em>A<sub>s</sub></em> 368 * <em>C<sub>r</sub></em> = <em>C<sub>s</sub></em> 369 *</pre> 370 */ 371 @Native public static final int SRC = 2; 372 373 /** 374 * The destination is left untouched 375 * (Porter-Duff Destination rule). 376 *<p> 377 * <em>F<sub>s</sub></em> = 0 and <em>F<sub>d</sub></em> = 1, thus: 378 *<pre> 379 * <em>A<sub>r</sub></em> = <em>A<sub>d</sub></em> 380 * <em>C<sub>r</sub></em> = <em>C<sub>d</sub></em> 381 *</pre> 382 * @since 1.4 383 */ 384 @Native public static final int DST = 9; 385 // Note that DST was added in 1.4 so it is numbered out of order... 386 387 /** 388 * The source is composited over the destination 389 * (Porter-Duff Source Over Destination rule). 390 *<p> 391 * <em>F<sub>s</sub></em> = 1 and <em>F<sub>d</sub></em> = (1-<em>A<sub>s</sub></em>), thus: 392 *<pre> 393 * <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>) 394 * <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>) 395 *</pre> 396 */ 397 @Native public static final int SRC_OVER = 3; 398 399 /** 400 * The destination is composited over the source and 401 * the result replaces the destination 402 * (Porter-Duff Destination Over Source rule). 403 *<p> 404 * <em>F<sub>s</sub></em> = (1-<em>A<sub>d</sub></em>) and <em>F<sub>d</sub></em> = 1, thus: 405 *<pre> 406 * <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> 407 * <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> 408 *</pre> 409 */ 410 @Native public static final int DST_OVER = 4; 411 412 /** 413 * The part of the source lying inside of the destination replaces 414 * the destination 415 * (Porter-Duff Source In Destination rule). 416 *<p> 417 * <em>F<sub>s</sub></em> = <em>A<sub>d</sub></em> and <em>F<sub>d</sub></em> = 0, thus: 418 *<pre> 419 * <em>A<sub>r</sub></em> = <em>A<sub>s</sub></em>*<em>A<sub>d</sub></em> 420 * <em>C<sub>r</sub></em> = <em>C<sub>s</sub></em>*<em>A<sub>d</sub></em> 421 *</pre> 422 */ 423 @Native public static final int SRC_IN = 5; 424 425 /** 426 * The part of the destination lying inside of the source 427 * replaces the destination 428 * (Porter-Duff Destination In Source rule). 429 *<p> 430 * <em>F<sub>s</sub></em> = 0 and <em>F<sub>d</sub></em> = <em>A<sub>s</sub></em>, thus: 431 *<pre> 432 * <em>A<sub>r</sub></em> = <em>A<sub>d</sub></em>*<em>A<sub>s</sub></em> 433 * <em>C<sub>r</sub></em> = <em>C<sub>d</sub></em>*<em>A<sub>s</sub></em> 434 *</pre> 435 */ 436 @Native public static final int DST_IN = 6; 437 438 /** 439 * The part of the source lying outside of the destination 440 * replaces the destination 441 * (Porter-Duff Source Held Out By Destination rule). 442 *<p> 443 * <em>F<sub>s</sub></em> = (1-<em>A<sub>d</sub></em>) and <em>F<sub>d</sub></em> = 0, thus: 444 *<pre> 445 * <em>A<sub>r</sub></em> = <em>A<sub>s</sub></em>*(1-<em>A<sub>d</sub></em>) 446 * <em>C<sub>r</sub></em> = <em>C<sub>s</sub></em>*(1-<em>A<sub>d</sub></em>) 447 *</pre> 448 */ 449 @Native public static final int SRC_OUT = 7; 450 451 /** 452 * The part of the destination lying outside of the source 453 * replaces the destination 454 * (Porter-Duff Destination Held Out By Source rule). 455 *<p> 456 * <em>F<sub>s</sub></em> = 0 and <em>F<sub>d</sub></em> = (1-<em>A<sub>s</sub></em>), thus: 457 *<pre> 458 * <em>A<sub>r</sub></em> = <em>A<sub>d</sub></em>*(1-<em>A<sub>s</sub></em>) 459 * <em>C<sub>r</sub></em> = <em>C<sub>d</sub></em>*(1-<em>A<sub>s</sub></em>) 460 *</pre> 461 */ 462 @Native public static final int DST_OUT = 8; 463 464 // Rule 9 is DST which is defined above where it fits into the 465 // list logically, rather than numerically 466 // 467 // public static final int DST = 9; 468 469 /** 470 * The part of the source lying inside of the destination 471 * is composited onto the destination 472 * (Porter-Duff Source Atop Destination rule). 473 *<p> 474 * <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: 475 *<pre> 476 * <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> 477 * <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>) 478 *</pre> 479 * @since 1.4 480 */ 481 @Native public static final int SRC_ATOP = 10; 482 483 /** 484 * The part of the destination lying inside of the source 485 * is composited over the source and replaces the destination 486 * (Porter-Duff Destination Atop Source rule). 487 *<p> 488 * <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: 489 *<pre> 490 * <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> 491 * <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> 492 *</pre> 493 * @since 1.4 494 */ 495 @Native public static final int DST_ATOP = 11; 496 497 /** 498 * The part of the source that lies outside of the destination 499 * is combined with the part of the destination that lies outside 500 * of the source 501 * (Porter-Duff Source Xor Destination rule). 502 *<p> 503 * <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: 504 *<pre> 505 * <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>) 506 * <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>) 507 *</pre> 508 * @since 1.4 509 */ 510 @Native public static final int XOR = 12; 511 512 /** 513 * <code>AlphaComposite</code> object that implements the opaque CLEAR rule 514 * with an alpha of 1.0f. 515 * @see #CLEAR 516 */ 517 public static final AlphaComposite Clear = new AlphaComposite(CLEAR); 518 519 /** 520 * <code>AlphaComposite</code> object that implements the opaque SRC rule 521 * with an alpha of 1.0f. 522 * @see #SRC 523 */ 524 public static final AlphaComposite Src = new AlphaComposite(SRC); 525 526 /** 527 * <code>AlphaComposite</code> object that implements the opaque DST rule 528 * with an alpha of 1.0f. 529 * @see #DST 530 * @since 1.4 531 */ 532 public static final AlphaComposite Dst = new AlphaComposite(DST); 533 534 /** 535 * <code>AlphaComposite</code> object that implements the opaque SRC_OVER rule 536 * with an alpha of 1.0f. 537 * @see #SRC_OVER 538 */ 539 public static final AlphaComposite SrcOver = new AlphaComposite(SRC_OVER); 540 541 /** 542 * <code>AlphaComposite</code> object that implements the opaque DST_OVER rule 543 * with an alpha of 1.0f. 544 * @see #DST_OVER 545 */ 546 public static final AlphaComposite DstOver = new AlphaComposite(DST_OVER); 547 548 /** 549 * <code>AlphaComposite</code> object that implements the opaque SRC_IN rule 550 * with an alpha of 1.0f. 551 * @see #SRC_IN 552 */ 553 public static final AlphaComposite SrcIn = new AlphaComposite(SRC_IN); 554 555 /** 556 * <code>AlphaComposite</code> object that implements the opaque DST_IN rule 557 * with an alpha of 1.0f. 558 * @see #DST_IN 559 */ 560 public static final AlphaComposite DstIn = new AlphaComposite(DST_IN); 561 562 /** 563 * <code>AlphaComposite</code> object that implements the opaque SRC_OUT rule 564 * with an alpha of 1.0f. 565 * @see #SRC_OUT 566 */ 567 public static final AlphaComposite SrcOut = new AlphaComposite(SRC_OUT); 568 569 /** 570 * <code>AlphaComposite</code> object that implements the opaque DST_OUT rule 571 * with an alpha of 1.0f. 572 * @see #DST_OUT 573 */ 574 public static final AlphaComposite DstOut = new AlphaComposite(DST_OUT); 575 576 /** 577 * <code>AlphaComposite</code> object that implements the opaque SRC_ATOP rule 578 * with an alpha of 1.0f. 579 * @see #SRC_ATOP 580 * @since 1.4 581 */ 582 public static final AlphaComposite SrcAtop = new AlphaComposite(SRC_ATOP); 583 584 /** 585 * <code>AlphaComposite</code> object that implements the opaque DST_ATOP rule 586 * with an alpha of 1.0f. 587 * @see #DST_ATOP 588 * @since 1.4 589 */ 590 public static final AlphaComposite DstAtop = new AlphaComposite(DST_ATOP); 591 592 /** 593 * <code>AlphaComposite</code> object that implements the opaque XOR rule 594 * with an alpha of 1.0f. 595 * @see #XOR 596 * @since 1.4 597 */ 598 public static final AlphaComposite Xor = new AlphaComposite(XOR); 599 600 @Native private static final int MIN_RULE = CLEAR; 601 @Native private static final int MAX_RULE = XOR; 602 603 float extraAlpha; 604 int rule; 605 606 private AlphaComposite(int rule) { 607 this(rule, 1.0f); 608 } 609 610 private AlphaComposite(int rule, float alpha) { 611 if (rule < MIN_RULE || rule > MAX_RULE) { 612 throw new IllegalArgumentException("unknown composite rule"); 613 } 614 if (alpha >= 0.0f && alpha <= 1.0f) { 615 this.rule = rule; 616 this.extraAlpha = alpha; 617 } else { 618 throw new IllegalArgumentException("alpha value out of range"); 619 } 620 } 621 622 /** 623 * Creates an <code>AlphaComposite</code> object with the specified rule. 624 * 625 * @param rule the compositing rule 626 * @return the {@code AlphaComposite} object created 627 * @throws IllegalArgumentException if <code>rule</code> is not one of 628 * the following: {@link #CLEAR}, {@link #SRC}, {@link #DST}, 629 * {@link #SRC_OVER}, {@link #DST_OVER}, {@link #SRC_IN}, 630 * {@link #DST_IN}, {@link #SRC_OUT}, {@link #DST_OUT}, 631 * {@link #SRC_ATOP}, {@link #DST_ATOP}, or {@link #XOR} 632 */ 633 public static AlphaComposite getInstance(int rule) { 634 switch (rule) { 635 case CLEAR: 636 return Clear; 637 case SRC: 638 return Src; 639 case DST: 640 return Dst; 641 case SRC_OVER: 642 return SrcOver; 643 case DST_OVER: 644 return DstOver; 645 case SRC_IN: 646 return SrcIn; 647 case DST_IN: 648 return DstIn; 649 case SRC_OUT: 650 return SrcOut; 651 case DST_OUT: 652 return DstOut; 653 case SRC_ATOP: 654 return SrcAtop; 655 case DST_ATOP: 656 return DstAtop; 657 case XOR: 658 return Xor; 659 default: 660 throw new IllegalArgumentException("unknown composite rule"); 661 } 662 } 663 664 /** 665 * Creates an <code>AlphaComposite</code> object with the specified rule and 666 * the constant alpha to multiply with the alpha of the source. 667 * The source is multiplied with the specified alpha before being composited 668 * with the destination. 669 * 670 * @param rule the compositing rule 671 * @param alpha the constant alpha to be multiplied with the alpha of 672 * the source. <code>alpha</code> must be a floating point number in the 673 * inclusive range [0.0, 1.0]. 674 * @return the {@code AlphaComposite} object created 675 * @throws IllegalArgumentException if 676 * <code>alpha</code> is less than 0.0 or greater than 1.0, or if 677 * <code>rule</code> is not one of 678 * the following: {@link #CLEAR}, {@link #SRC}, {@link #DST}, 679 * {@link #SRC_OVER}, {@link #DST_OVER}, {@link #SRC_IN}, 680 * {@link #DST_IN}, {@link #SRC_OUT}, {@link #DST_OUT}, 681 * {@link #SRC_ATOP}, {@link #DST_ATOP}, or {@link #XOR} 682 */ 683 public static AlphaComposite getInstance(int rule, float alpha) { 684 if (alpha == 1.0f) { 685 return getInstance(rule); 686 } 687 return new AlphaComposite(rule, alpha); 688 } 689 690 /** 691 * Creates a context for the compositing operation. 692 * The context contains state that is used in performing 693 * the compositing operation. 694 * @param srcColorModel the {@link ColorModel} of the source 695 * @param dstColorModel the <code>ColorModel</code> of the destination 696 * @return the <code>CompositeContext</code> object to be used to perform 697 * compositing operations. 698 */ 699 public CompositeContext createContext(ColorModel srcColorModel, 700 ColorModel dstColorModel, 701 RenderingHints hints) { 702 return new SunCompositeContext(this, srcColorModel, dstColorModel); 703 } 704 705 /** 706 * Returns the alpha value of this <code>AlphaComposite</code>. If this 707 * <code>AlphaComposite</code> does not have an alpha value, 1.0 is returned. 708 * @return the alpha value of this <code>AlphaComposite</code>. 709 */ 710 public float getAlpha() { 711 return extraAlpha; 712 } 713 714 /** 715 * Returns the compositing rule of this <code>AlphaComposite</code>. 716 * @return the compositing rule of this <code>AlphaComposite</code>. 717 */ 718 public int getRule() { 719 return rule; 720 } 721 722 /** 723 * Returns a similar <code>AlphaComposite</code> object that uses 724 * the specified compositing rule. 725 * If this object already uses the specified compositing rule, 726 * this object is returned. 727 * @return an <code>AlphaComposite</code> object derived from 728 * this object that uses the specified compositing rule. 729 * @param rule the compositing rule 730 * @throws IllegalArgumentException if 731 * <code>rule</code> is not one of 732 * the following: {@link #CLEAR}, {@link #SRC}, {@link #DST}, 733 * {@link #SRC_OVER}, {@link #DST_OVER}, {@link #SRC_IN}, 734 * {@link #DST_IN}, {@link #SRC_OUT}, {@link #DST_OUT}, 735 * {@link #SRC_ATOP}, {@link #DST_ATOP}, or {@link #XOR} 736 * @since 1.6 737 */ 738 public AlphaComposite derive(int rule) { 739 return (this.rule == rule) 740 ? this 741 : getInstance(rule, this.extraAlpha); 742 } 743 744 /** 745 * Returns a similar <code>AlphaComposite</code> object that uses 746 * the specified alpha value. 747 * If this object already has the specified alpha value, 748 * this object is returned. 749 * @return an <code>AlphaComposite</code> object derived from 750 * this object that uses the specified alpha value. 751 * @param alpha the constant alpha to be multiplied with the alpha of 752 * the source. <code>alpha</code> must be a floating point number in the 753 * inclusive range [0.0, 1.0]. 754 * @throws IllegalArgumentException if 755 * <code>alpha</code> is less than 0.0 or greater than 1.0 756 * @since 1.6 757 */ 758 public AlphaComposite derive(float alpha) { 759 return (this.extraAlpha == alpha) 760 ? this 761 : getInstance(this.rule, alpha); 762 } 763 764 /** 765 * Returns the hashcode for this composite. 766 * @return a hash code for this composite. 767 */ 768 public int hashCode() { 769 return (Float.floatToIntBits(extraAlpha) * 31 + rule); 770 } 771 772 /** 773 * Determines whether the specified object is equal to this 774 * <code>AlphaComposite</code>. 775 * <p> 776 * The result is <code>true</code> if and only if 777 * the argument is not <code>null</code> and is an 778 * <code>AlphaComposite</code> object that has the same 779 * compositing rule and alpha value as this object. 780 * 781 * @param obj the <code>Object</code> to test for equality 782 * @return <code>true</code> if <code>obj</code> equals this 783 * <code>AlphaComposite</code>; <code>false</code> otherwise. 784 */ 785 public boolean equals(Object obj) { 786 if (!(obj instanceof AlphaComposite)) { 787 return false; 788 } 789 790 AlphaComposite ac = (AlphaComposite) obj; 791 792 if (rule != ac.rule) { 793 return false; 794 } 795 796 if (extraAlpha != ac.extraAlpha) { 797 return false; 798 } 799 800 return true; 801 } 802 803 }