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