+ *
*
- *
+ *
*
- * 
+ *
*
- *
+ *
*
- * 
+ *
*
- *
+ *
*
- * 
+ *
*
- * 
+ *
*
- * 
+ *
*
- * 
+ *
*
- * 
+ *
*
- * 
+ *
*
- * 
+ *
*
- * 
+ *
*
- * 
+ *
*
- * 
+ *
*
- *
+ *
*
- *
+ *
*
- * 
+ *
*
- * 
+ *
*
- *
+ *
*
- * 
+ *
*
- *
+ *
*
- * 
+ *
*
- * 
+ *
*
This class contains the list of alpha compositing and blending modes + * that can be passed to {@link PorterDuffXfermode}, a specialized implementation + * of {@link Paint}'s {@link Paint#setXfermode(Xfermode) transfer mode}. + * All the available modes can be found in the {@link Mode} enum.
+ */ public class PorterDuff { + /** + * {@usesMathJax} + * + *The name of the parent class is an homage to the work of Thomas Porter and + * Tom Duff, presented in their seminal 1984 paper titled "Compositing Digital Images". + * In this paper, the authors describe 12 compositing operators that govern how to + * compute the color resulting of the composition of a source (the graphics object + * to render) with a destination (the content of the render target).
+ * + *"Compositing Digital Images" was published in Computer Graphics + * Volume 18, Number 3 dated July 1984.
+ * + *Because the work of Porter and Duff focuses solely on the effects of the alpha + * channel of the source and destination, the 12 operators described in the original + * paper are called alpha compositing modes here.
+ * + *For convenience, this class also provides several blending modes, which similarly + * define the result of compositing a source and a destination but without being + * constrained to the alpha channel. These blending modes are not defined by Porter + * and Duff but have been included in this class for convenience purposes.
+ * + *All the example diagrams presented below use the same source and destination + * images:
+ * + *
+ * 
+ * |
+ *
+ * 
+ * |
+ *
The order of drawing operations used to generate each diagram is shown in the + * following code snippet:
+ * + *+ * Paint paint = new Paint(); + * canvas.drawBitmap(destinationImage, 0, 0, paint); + * + * PorterDuff.Mode mode = // choose a mode + * paint.setXfermode(new PorterDuffXfermode(mode)); + * + * canvas.drawBitmap(sourceImage, 0, 0, paint); + *- // these value must match their native equivalents. See SkXfermode.h + * + *
|
+ *
+ * |
+ *
+ * 
+ * |
+ *
+ * 
+ * |
+ *
+ * 
+ * |
+ *
|
+ *
+ * |
+ *
+ * 
+ * |
+ *
+ * 
+ * |
+ *
+ * 
+ * |
+ *
+ * 
+ * |
+ *
+ * 
+ * |
+ *
+ * 
+ * |
+ *
+ * 
+ * |
+ *
+ * 
+ * |
+ *
+ * 
+ * |
+ *
+ * 
+ * |
+ *
+ * 
+ * |
+ *
+ * 
+ * |
+ *
The documentation of each individual alpha compositing or blending mode below + * provides the exact equation used to compute alpha and color value of the result + * of the composition of a source and destination.
+ * + *The result (or output) alpha value is noted \(\alpha_{out}\). The result (or output) + * color value is noted \(C_{out}\).
+ */ public enum Mode { - /** [0, 0] */ + // these value must match their native equivalents. See SkXfermode.h + /** + *
+ *
+ *
\(\alpha_{out} = 0\)
+ *\(C_{out} = 0\)
+ */ CLEAR (0), - /** [Sa, Sc] */ + /** + *
+ *
+ *
\(\alpha_{out} = \alpha_{src}\)
+ *\(C_{out} = C_{src}\)
+ */ SRC (1), - /** [Da, Dc] */ + /** + *
+ *
+ *
\(\alpha_{out} = \alpha_{dst}\)
+ *\(C_{out} = C_{dst}\)
+ */ DST (2), - /** [Sa + (1 - Sa)*Da, Rc = Sc + (1 - Sa)*Dc] */ + /** + *
+ *
+ *
\(\alpha_{out} = \alpha_{src} + (1 - \alpha_{src}) * \alpha_{dst}\)
+ *\(C_{out} = C_{src} + (1 - \alpha_{src}) * C_{dst}\)
+ */ SRC_OVER (3), - /** [Sa + (1 - Sa)*Da, Rc = Dc + (1 - Da)*Sc] */ + /** + *
+ *
+ *
\(\alpha_{out} = \alpha_{dst} + (1 - \alpha_{dst}) * \alpha_{src}\)
+ *\(C_{out} = C_{dst} + (1 - \alpha_{dst}) * C_{src}\)
+ */ DST_OVER (4), - /** [Sa * Da, Sc * Da] */ + /** + *
+ *
+ *
\(\alpha_{out} = \alpha_{src} * \alpha_{dst}\)
+ *\(C_{out} = C_{src} * \alpha_{dst}\)
+ */ SRC_IN (5), - /** [Sa * Da, Sa * Dc] */ + /** + *
+ *
+ *
\(\alpha_{out} = \alpha_{src} * \alpha_{dst}\)
+ *\(C_{out} = C_{dst} * \alpha_{src}\)
+ */ DST_IN (6), - /** [Sa * (1 - Da), Sc * (1 - Da)] */ + /** + *
+ *
+ *
\(\alpha_{out} = (1 - \alpha_{dst}) * \alpha_{src}\)
+ *\(C_{out} = (1 - \alpha_{dst}) * C_{src}\)
+ */ SRC_OUT (7), - /** [Da * (1 - Sa), Dc * (1 - Sa)] */ + /** + *
+ *
+ *
\(\alpha_{out} = (1 - \alpha_{src}) * \alpha_{dst}\)
+ *\(C_{out} = (1 - \alpha_{src}) * C_{dst}\)
+ */ DST_OUT (8), - /** [Da, Sc * Da + (1 - Sa) * Dc] */ + /** + *
+ *
+ *
\(\alpha_{out} = \alpha_{dst}\)
+ *\(C_{out} = \alpha_{dst} * C_{src} + (1 - \alpha_{src}) * C_{dst}\)
+ */ SRC_ATOP (9), - /** [Sa, Sa * Dc + Sc * (1 - Da)] */ + /** + *
+ *
+ *
\(\alpha_{out} = \alpha_{src}\)
+ *\(C_{out} = \alpha_{src} * C_{dst} + (1 - \alpha_{dst}) * C_{src}\)
+ */ DST_ATOP (10), - /** [Sa + Da - 2 * Sa * Da, Sc * (1 - Da) + (1 - Sa) * Dc] */ + /** + *
+ *
+ *
\(\alpha_{out} = (1 - \alpha_{dst}) * \alpha_{src} + (1 - \alpha_{src}) * \alpha_{dst}\)
+ *\(C_{out} = (1 - \alpha_{dst}) * C_{src} + (1 - \alpha_{src}) * C_{dst}\)
+ */ XOR (11), - /** [Sa + Da - Sa*Da, - Sc*(1 - Da) + Dc*(1 - Sa) + min(Sc, Dc)] */ + /** + *
+ *
+ *
\(\alpha_{out} = \alpha_{src} + \alpha_{dst} - \alpha_{src} * \alpha_{dst}\)
+ *\(C_{out} = (1 - \alpha_{dst}) * C_{src} + (1 - \alpha_{src}) * C_{dst} + min(C_{src}, C_{dst})\)
+ */ DARKEN (16), - /** [Sa + Da - Sa*Da, - Sc*(1 - Da) + Dc*(1 - Sa) + max(Sc, Dc)] */ + /** + *
+ *
+ *
\(\alpha_{out} = \alpha_{src} + \alpha_{dst} - \alpha_{src} * \alpha_{dst}\)
+ *\(C_{out} = (1 - \alpha_{dst}) * C_{src} + (1 - \alpha_{src}) * C_{dst} + max(C_{src}, C_{dst})\)
+ */ LIGHTEN (17), - /** [Sa * Da, Sc * Dc] */ + /** + *
+ *
+ *
\(\alpha_{out} = \alpha_{src} * \alpha_{dst}\)
+ *\(C_{out} = C_{src} * C_{dst}\)
+ */ MULTIPLY (13), - /** [Sa + Da - Sa * Da, Sc + Dc - Sc * Dc] */ + /** + *
+ *
+ *
\(\alpha_{out} = \alpha_{src} + \alpha_{dst} - \alpha_{src} * \alpha_{dst}\)
+ *\(C_{out} = C_{src} + C_{dst} - C_{src} * C_{dst}\)
+ */ SCREEN (14), - /** Saturate(S + D) */ + /** + *
+ * 
+ *
\(\alpha_{out} = max(0, min(\alpha_{src} + \alpha_{dst}, 1))\)
+ *\(C_{out} = max(0, min(C_{src} + C_{dst}, 1))\)
+ */ ADD (12), + /** + *
+ *
+ *
\(\alpha_{out} = \alpha_{src} + \alpha_{dst} - \alpha_{src} * \alpha_{dst}\)
+ *\(\begin{equation} + * C_{out} = \begin{cases} 2 * C_{src} * C_{dst} & 2 * C_{dst} \lt \alpha_{dst} \\ + * \alpha_{src} * \alpha_{dst} - 2 (\alpha_{dst} - C_{src}) (\alpha_{src} - C_{dst}) & otherwise \end{cases} + * \end{equation}\)
+ */ OVERLAY (15); Mode(int nativeInt) { @@ -71,14 +370,14 @@ public class PorterDuff { /** * @hide */ - public static final int modeToInt(Mode mode) { + public static int modeToInt(Mode mode) { return mode.nativeInt; } /** * @hide */ - public static final Mode intToMode(int val) { + public static Mode intToMode(int val) { switch (val) { default: case 0: return Mode.CLEAR; diff --git a/graphics/java/android/graphics/PorterDuffXfermode.java b/graphics/java/android/graphics/PorterDuffXfermode.java index 51044103003b2..84d953de91db9 100644 --- a/graphics/java/android/graphics/PorterDuffXfermode.java +++ b/graphics/java/android/graphics/PorterDuffXfermode.java @@ -16,6 +16,12 @@ package android.graphics; +/** + *Specialized implementation of {@link Paint}'s + * {@link Paint#setXfermode(Xfermode) transfer mode}. Refer to the + * documentation of the {@link PorterDuff.Mode} enum for more + * information on the available alpha compositing and blending modes.
+ */ public class PorterDuffXfermode extends Xfermode { /** * Create an xfermode that uses the specified porter-duff mode.