diff options
22 files changed, 359 insertions, 50 deletions
diff --git a/docs/html/reference/images/graphics/composite_ADD.png b/docs/html/reference/images/graphics/composite_ADD.png Binary files differnew file mode 100644 index 000000000000..90932c55ac53 --- /dev/null +++ b/docs/html/reference/images/graphics/composite_ADD.png diff --git a/docs/html/reference/images/graphics/composite_CLEAR.png b/docs/html/reference/images/graphics/composite_CLEAR.png Binary files differnew file mode 100644 index 000000000000..7c0731d43a5f --- /dev/null +++ b/docs/html/reference/images/graphics/composite_CLEAR.png diff --git a/docs/html/reference/images/graphics/composite_DARKEN.png b/docs/html/reference/images/graphics/composite_DARKEN.png Binary files differnew file mode 100644 index 000000000000..a798b97da588 --- /dev/null +++ b/docs/html/reference/images/graphics/composite_DARKEN.png diff --git a/docs/html/reference/images/graphics/composite_DST.png b/docs/html/reference/images/graphics/composite_DST.png Binary files differnew file mode 100644 index 000000000000..6dde48f87189 --- /dev/null +++ b/docs/html/reference/images/graphics/composite_DST.png diff --git a/docs/html/reference/images/graphics/composite_DST_ATOP.png b/docs/html/reference/images/graphics/composite_DST_ATOP.png Binary files differnew file mode 100644 index 000000000000..c6767bd5c631 --- /dev/null +++ b/docs/html/reference/images/graphics/composite_DST_ATOP.png diff --git a/docs/html/reference/images/graphics/composite_DST_IN.png b/docs/html/reference/images/graphics/composite_DST_IN.png Binary files differnew file mode 100644 index 000000000000..cf50a7b068b5 --- /dev/null +++ b/docs/html/reference/images/graphics/composite_DST_IN.png diff --git a/docs/html/reference/images/graphics/composite_DST_OUT.png b/docs/html/reference/images/graphics/composite_DST_OUT.png Binary files differnew file mode 100644 index 000000000000..ee8a46e0c2c2 --- /dev/null +++ b/docs/html/reference/images/graphics/composite_DST_OUT.png diff --git a/docs/html/reference/images/graphics/composite_DST_OVER.png b/docs/html/reference/images/graphics/composite_DST_OVER.png Binary files differnew file mode 100644 index 000000000000..18389723903b --- /dev/null +++ b/docs/html/reference/images/graphics/composite_DST_OVER.png diff --git a/docs/html/reference/images/graphics/composite_LIGHTEN.png b/docs/html/reference/images/graphics/composite_LIGHTEN.png Binary files differnew file mode 100644 index 000000000000..8fc0a1054fa3 --- /dev/null +++ b/docs/html/reference/images/graphics/composite_LIGHTEN.png diff --git a/docs/html/reference/images/graphics/composite_MULTIPLY.png b/docs/html/reference/images/graphics/composite_MULTIPLY.png Binary files differnew file mode 100644 index 000000000000..8816ab09ab5f --- /dev/null +++ b/docs/html/reference/images/graphics/composite_MULTIPLY.png diff --git a/docs/html/reference/images/graphics/composite_OVERLAY.png b/docs/html/reference/images/graphics/composite_OVERLAY.png Binary files differnew file mode 100644 index 000000000000..700a6b29fa54 --- /dev/null +++ b/docs/html/reference/images/graphics/composite_OVERLAY.png diff --git a/docs/html/reference/images/graphics/composite_SCREEN.png b/docs/html/reference/images/graphics/composite_SCREEN.png Binary files differnew file mode 100644 index 000000000000..b698819615e7 --- /dev/null +++ b/docs/html/reference/images/graphics/composite_SCREEN.png diff --git a/docs/html/reference/images/graphics/composite_SRC.png b/docs/html/reference/images/graphics/composite_SRC.png Binary files differnew file mode 100644 index 000000000000..2d70a54ad807 --- /dev/null +++ b/docs/html/reference/images/graphics/composite_SRC.png diff --git a/docs/html/reference/images/graphics/composite_SRC_ATOP.png b/docs/html/reference/images/graphics/composite_SRC_ATOP.png Binary files differnew file mode 100644 index 000000000000..111869e2d2f1 --- /dev/null +++ b/docs/html/reference/images/graphics/composite_SRC_ATOP.png diff --git a/docs/html/reference/images/graphics/composite_SRC_IN.png b/docs/html/reference/images/graphics/composite_SRC_IN.png Binary files differnew file mode 100644 index 000000000000..1d6145b88f09 --- /dev/null +++ b/docs/html/reference/images/graphics/composite_SRC_IN.png diff --git a/docs/html/reference/images/graphics/composite_SRC_OUT.png b/docs/html/reference/images/graphics/composite_SRC_OUT.png Binary files differnew file mode 100644 index 000000000000..39c0c1707d15 --- /dev/null +++ b/docs/html/reference/images/graphics/composite_SRC_OUT.png diff --git a/docs/html/reference/images/graphics/composite_SRC_OVER.png b/docs/html/reference/images/graphics/composite_SRC_OVER.png Binary files differnew file mode 100644 index 000000000000..1489487d2df9 --- /dev/null +++ b/docs/html/reference/images/graphics/composite_SRC_OVER.png diff --git a/docs/html/reference/images/graphics/composite_XOR.png b/docs/html/reference/images/graphics/composite_XOR.png Binary files differnew file mode 100644 index 000000000000..6d0c5ba14762 --- /dev/null +++ b/docs/html/reference/images/graphics/composite_XOR.png diff --git a/graphics/java/android/graphics/ColorSpace.java b/graphics/java/android/graphics/ColorSpace.java index 929ac22f2960..e03dcf34a40c 100644 --- a/graphics/java/android/graphics/ColorSpace.java +++ b/graphics/java/android/graphics/ColorSpace.java @@ -143,7 +143,7 @@ import java.util.function.DoubleUnaryOperator; * .render(); * </pre> * <p> - * <img src="{@docRoot}reference/android/images/graphics/colorspace_renderer.png" /> + * <img style="display: block; margin: 0 auto;" src="{@docRoot}reference/android/images/graphics/colorspace_renderer.png" /> * <figcaption style="text-align: center;">DCI-P3 vs ProPhoto RGB</figcaption> * </p> * @@ -281,7 +281,7 @@ public abstract class ColorSpace { * <tr><td>Range</td><td colspan="4">\([0..1]\)</td></tr> * </table> * <p> - * <img src="{@docRoot}reference/android/images/graphics/colorspace_srgb.png" /> + * <img style="display: block; margin: 0 auto;" src="{@docRoot}reference/android/images/graphics/colorspace_srgb.png" /> * <figcaption style="text-align: center;">sRGB</figcaption> * </p> */ @@ -308,7 +308,7 @@ public abstract class ColorSpace { * <tr><td>Range</td><td colspan="4">\([0..1]\)</td></tr> * </table> * <p> - * <img src="{@docRoot}reference/android/images/graphics/colorspace_srgb.png" /> + * <img style="display: block; margin: 0 auto;" src="{@docRoot}reference/android/images/graphics/colorspace_srgb.png" /> * <figcaption style="text-align: center;">sRGB</figcaption> * </p> */ @@ -347,7 +347,7 @@ public abstract class ColorSpace { * <tr><td>Range</td><td colspan="4">\([-0.799..2.399[\)</td></tr> * </table> * <p> - * <img src="{@docRoot}reference/android/images/graphics/colorspace_scrgb.png" /> + * <img style="display: block; margin: 0 auto;" src="{@docRoot}reference/android/images/graphics/colorspace_scrgb.png" /> * <figcaption style="text-align: center;">Extended sRGB (orange) vs sRGB (white)</figcaption> * </p> */ @@ -374,7 +374,7 @@ public abstract class ColorSpace { * <tr><td>Range</td><td colspan="4">\([-0.5..7.499[\)</td></tr> * </table> * <p> - * <img src="{@docRoot}reference/android/images/graphics/colorspace_scrgb.png" /> + * <img style="display: block; margin: 0 auto;" src="{@docRoot}reference/android/images/graphics/colorspace_scrgb.png" /> * <figcaption style="text-align: center;">Extended sRGB (orange) vs sRGB (white)</figcaption> * </p> */ @@ -409,7 +409,7 @@ public abstract class ColorSpace { * <tr><td>Range</td><td colspan="4">\([0..1]\)</td></tr> * </table> * <p> - * <img src="{@docRoot}reference/android/images/graphics/colorspace_bt709.png" /> + * <img style="display: block; margin: 0 auto;" src="{@docRoot}reference/android/images/graphics/colorspace_bt709.png" /> * <figcaption style="text-align: center;">BT.709</figcaption> * </p> */ @@ -444,7 +444,7 @@ public abstract class ColorSpace { * <tr><td>Range</td><td colspan="4">\([0..1]\)</td></tr> * </table> * <p> - * <img src="{@docRoot}reference/android/images/graphics/colorspace_bt2020.png" /> + * <img style="display: block; margin: 0 auto;" src="{@docRoot}reference/android/images/graphics/colorspace_bt2020.png" /> * <figcaption style="text-align: center;">BT.2020 (orange) vs sRGB (white)</figcaption> * </p> */ @@ -471,7 +471,7 @@ public abstract class ColorSpace { * <tr><td>Range</td><td colspan="4">\([0..1]\)</td></tr> * </table> * <p> - * <img src="{@docRoot}reference/android/images/graphics/colorspace_dci_p3.png" /> + * <img style="display: block; margin: 0 auto;" src="{@docRoot}reference/android/images/graphics/colorspace_dci_p3.png" /> * <figcaption style="text-align: center;">DCI-P3 (orange) vs sRGB (white)</figcaption> * </p> */ @@ -506,7 +506,7 @@ public abstract class ColorSpace { * <tr><td>Range</td><td colspan="4">\([0..1]\)</td></tr> * </table> * <p> - * <img src="{@docRoot}reference/android/images/graphics/colorspace_display_p3.png" /> + * <img style="display: block; margin: 0 auto;" src="{@docRoot}reference/android/images/graphics/colorspace_display_p3.png" /> * <figcaption style="text-align: center;">Display P3 (orange) vs sRGB (white)</figcaption> * </p> */ @@ -541,7 +541,7 @@ public abstract class ColorSpace { * <tr><td>Range</td><td colspan="4">\([0..1]\)</td></tr> * </table> * <p> - * <img src="{@docRoot}reference/android/images/graphics/colorspace_ntsc_1953.png" /> + * <img style="display: block; margin: 0 auto;" src="{@docRoot}reference/android/images/graphics/colorspace_ntsc_1953.png" /> * <figcaption style="text-align: center;">NTSC 1953 (orange) vs sRGB (white)</figcaption> * </p> */ @@ -576,7 +576,7 @@ public abstract class ColorSpace { * <tr><td>Range</td><td colspan="4">\([0..1]\)</td></tr> * </table> * <p> - * <img src="{@docRoot}reference/android/images/graphics/colorspace_smpte_c.png" /> + * <img style="display: block; margin: 0 auto;" src="{@docRoot}reference/android/images/graphics/colorspace_smpte_c.png" /> * <figcaption style="text-align: center;">SMPTE-C (orange) vs sRGB (white)</figcaption> * </p> */ @@ -603,7 +603,7 @@ public abstract class ColorSpace { * <tr><td>Range</td><td colspan="4">\([0..1]\)</td></tr> * </table> * <p> - * <img src="{@docRoot}reference/android/images/graphics/colorspace_adobe_rgb.png" /> + * <img style="display: block; margin: 0 auto;" src="{@docRoot}reference/android/images/graphics/colorspace_adobe_rgb.png" /> * <figcaption style="text-align: center;">Adobe RGB (orange) vs sRGB (white)</figcaption> * </p> */ @@ -638,7 +638,7 @@ public abstract class ColorSpace { * <tr><td>Range</td><td colspan="4">\([0..1]\)</td></tr> * </table> * <p> - * <img src="{@docRoot}reference/android/images/graphics/colorspace_pro_photo_rgb.png" /> + * <img style="display: block; margin: 0 auto;" src="{@docRoot}reference/android/images/graphics/colorspace_pro_photo_rgb.png" /> * <figcaption style="text-align: center;">ProPhoto RGB (orange) vs sRGB (white)</figcaption> * </p> */ @@ -665,7 +665,7 @@ public abstract class ColorSpace { * <tr><td>Range</td><td colspan="4">\([-65504.0, 65504.0]\)</td></tr> * </table> * <p> - * <img src="{@docRoot}reference/android/images/graphics/colorspace_aces.png" /> + * <img style="display: block; margin: 0 auto;" src="{@docRoot}reference/android/images/graphics/colorspace_aces.png" /> * <figcaption style="text-align: center;">ACES (orange) vs sRGB (white)</figcaption> * </p> */ @@ -692,7 +692,7 @@ public abstract class ColorSpace { * <tr><td>Range</td><td colspan="4">\([-65504.0, 65504.0]\)</td></tr> * </table> * <p> - * <img src="{@docRoot}reference/android/images/graphics/colorspace_acescg.png" /> + * <img style="display: block; margin: 0 auto;" src="{@docRoot}reference/android/images/graphics/colorspace_acescg.png" /> * <figcaption style="text-align: center;">ACEScg (orange) vs sRGB (white)</figcaption> * </p> */ @@ -1931,7 +1931,7 @@ public abstract class ColorSpace { * are internally converted to xyY.</p> * * <p> - * <img src="{@docRoot}reference/android/images/graphics/colorspace_srgb.png" /> + * <img style="display: block; margin: 0 auto;" src="{@docRoot}reference/android/images/graphics/colorspace_srgb.png" /> * <figcaption style="text-align: center;">sRGB primaries and white point</figcaption> * </p> * @@ -1989,7 +1989,7 @@ public abstract class ColorSpace { * the range \([-65504, 65504]\).</p> * * <p> - * <img src="{@docRoot}reference/android/images/graphics/colorspace_scrgb.png" /> + * <img style="display: block; margin: 0 auto;" src="{@docRoot}reference/android/images/graphics/colorspace_scrgb.png" /> * <figcaption style="text-align: center;">Extended sRGB and its large range</figcaption> * </p> * @@ -3703,7 +3703,7 @@ public abstract class ColorSpace { * .render(); * </pre> * <p> - * <img src="{@docRoot}reference/android/images/graphics/colorspace_clipped.png" /> + * <img style="display: block; margin: 0 auto;" src="{@docRoot}reference/android/images/graphics/colorspace_clipped.png" /> * <figcaption style="text-align: center;">sRGB vs DCI-P3</figcaption> * </p> * @@ -3746,7 +3746,7 @@ public abstract class ColorSpace { * .render(); * </pre> * <p> - * <img src="{@docRoot}reference/android/images/graphics/colorspace_comparison.png" /> + * <img style="display: block; margin: 0 auto;" src="{@docRoot}reference/android/images/graphics/colorspace_comparison.png" /> * <figcaption style="text-align: center;">Clipping disabled</figcaption> * </p> * @@ -3759,7 +3759,7 @@ public abstract class ColorSpace { * .render(); * </pre> * <p> - * <img src="{@docRoot}reference/android/images/graphics/colorspace_clipped.png" /> + * <img style="display: block; margin: 0 auto;" src="{@docRoot}reference/android/images/graphics/colorspace_clipped.png" /> * <figcaption style="text-align: center;">Clipping enabled</figcaption> * </p> * @@ -3789,7 +3789,7 @@ public abstract class ColorSpace { * .render(); * </pre> * <p> - * <img src="{@docRoot}reference/android/images/graphics/colorspace_ucs.png" /> + * <img style="display: block; margin: 0 auto;" src="{@docRoot}reference/android/images/graphics/colorspace_ucs.png" /> * <figcaption style="text-align: center;">CIE 1976 UCS diagram</figcaption> * </p> * @@ -3847,7 +3847,7 @@ public abstract class ColorSpace { * .render(); * </pre> * <p> - * <img src="{@docRoot}reference/android/images/graphics/colorspace_comparison.png" /> + * <img style="display: block; margin: 0 auto;" src="{@docRoot}reference/android/images/graphics/colorspace_comparison.png" /> * <figcaption style="text-align: center;">sRGB vs DCI-P3</figcaption> * </p> * @@ -3863,7 +3863,7 @@ public abstract class ColorSpace { * .render(); * </pre> * <p> - * <img src="{@docRoot}reference/android/images/graphics/colorspace_comparison2.png" /> + * <img style="display: block; margin: 0 auto;" src="{@docRoot}reference/android/images/graphics/colorspace_comparison2.png" /> * <figcaption style="text-align: center;">sRGB, DCI-P3, ACES and scRGB</figcaption> * </p> * @@ -3901,7 +3901,7 @@ public abstract class ColorSpace { * .render(); * </pre> * <p> - * <img src="{@docRoot}reference/android/images/graphics/colorspace_points.png" /> + * <img style="display: block; margin: 0 auto;" src="{@docRoot}reference/android/images/graphics/colorspace_points.png" /> * <figcaption style="text-align: center;"> * Locating colors on the chromaticity diagram * </figcaption> diff --git a/graphics/java/android/graphics/Paint.java b/graphics/java/android/graphics/Paint.java index f4bf0798ad18..c4f7dc39b4bd 100644 --- a/graphics/java/android/graphics/Paint.java +++ b/graphics/java/android/graphics/Paint.java @@ -1067,19 +1067,23 @@ public class Paint { } /** - * Get the paint's xfermode object. + * Get the paint's transfer mode object. * - * @return the paint's xfermode (or null) + * @return the paint's transfer mode (or null) */ public Xfermode getXfermode() { return mXfermode; } /** - * Set or clear the xfermode object. + * Set or clear the transfer mode object. A transfer mode defines how + * source pixels (generate by a drawing command) are composited with + * the destination pixels (content of the render target). * <p /> - * Pass null to clear any previous xfermode. + * Pass null to clear any previous transfer mode. * As a convenience, the parameter passed is also returned. + * <p /> + * {@link PorterDuffXfermode} is the most common transfer mode. * * @param xfermode May be null. The xfermode to be installed in the paint * @return xfermode diff --git a/graphics/java/android/graphics/PorterDuff.java b/graphics/java/android/graphics/PorterDuff.java index 2bbbff309414..d7d3049b0efa 100644 --- a/graphics/java/android/graphics/PorterDuff.java +++ b/graphics/java/android/graphics/PorterDuff.java @@ -16,46 +16,345 @@ package android.graphics; +/** + * <p>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.</p> + */ public class PorterDuff { + /** + * {@usesMathJax} + * + * <h3>Porter-Duff</h3> + * + * <p>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).</p> + * + * <p>"Compositing Digital Images" was published in <em>Computer Graphics</em> + * Volume 18, Number 3 dated July 1984.</p> + * + * <p>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.</p> + * + * <p>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.</p> + * + * <h3>Diagrams</h3> + * + * <p>All the example diagrams presented below use the same source and destination + * images:</p> + * + * <table summary="Source and Destination" style="background-color: transparent;"> + * <tr> + * <td style="border: none; text-align: center;"> + * <img src="{@docRoot}reference/android/images/graphics/composite_SRC.png" /> + * <figcaption>Source image</figcaption> + * </td> + * <td style="border: none; text-align: center;"> + * <img src="{@docRoot}reference/android/images/graphics/composite_DST.png" /> + * <figcaption>Destination image</figcaption> + * </td> + * </tr> + * </table> + * + * <p>The order of drawing operations used to generate each diagram is shown in the + * following code snippet:</p> + * + * <pre class="prettyprint"> + * 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); + * </pre> - // these value must match their native equivalents. See SkXfermode.h + * + * <h3>Alpha compositing modes</h3> + * + * <table summary="Alpha compositing modes" style="background-color: transparent;"> + * <tr> + * <td style="border: none; text-align: center;"> + * <img src="{@docRoot}reference/android/images/graphics/composite_SRC.png" /> + * <figcaption>{@link #SRC Source}</figcaption> + * </td> + * <td style="border: none; text-align: center;"> + * <img src="{@docRoot}reference/android/images/graphics/composite_SRC_OVER.png" /> + * <figcaption>{@link #SRC_OVER Source Over}</figcaption> + * </td> + * <td style="border: none; text-align: center;"> + * <img src="{@docRoot}reference/android/images/graphics/composite_SRC_IN.png" /> + * <figcaption>{@link #SRC_IN Source In}</figcaption> + * </td> + * <td style="border: none; text-align: center;"> + * <img src="{@docRoot}reference/android/images/graphics/composite_SRC_ATOP.png" /> + * <figcaption>{@link #SRC_ATOP Source Atop}</figcaption> + * </td> + * </tr> + * <tr> + * <td style="border: none; text-align: center;"> + * <img src="{@docRoot}reference/android/images/graphics/composite_DST.png" /> + * <figcaption>{@link #DST Destination}</figcaption> + * </td> + * <td style="border: none; text-align: center;"> + * <img src="{@docRoot}reference/android/images/graphics/composite_DST_OVER.png" /> + * <figcaption>{@link #DST_OVER Destination Over}</figcaption> + * </td> + * <td style="border: none; text-align: center;"> + * <img src="{@docRoot}reference/android/images/graphics/composite_DST_IN.png" /> + * <figcaption>{@link #DST_IN Destination In}</figcaption> + * </td> + * <td style="border: none; text-align: center;"> + * <img src="{@docRoot}reference/android/images/graphics/composite_DST_ATOP.png" /> + * <figcaption>{@link #DST_ATOP Destination Atop}</figcaption> + * </td> + * </tr> + * <tr> + * <td style="border: none; text-align: center;"> + * <img src="{@docRoot}reference/android/images/graphics/composite_CLEAR.png" /> + * <figcaption>{@link #CLEAR Clear}</figcaption> + * </td> + * <td style="border: none; text-align: center;"> + * <img src="{@docRoot}reference/android/images/graphics/composite_SRC_OUT.png" /> + * <figcaption>{@link #SRC_OUT Source Out}</figcaption> + * </td> + * <td style="border: none; text-align: center;"> + * <img src="{@docRoot}reference/android/images/graphics/composite_DST_OUT.png" /> + * <figcaption>{@link #DST_OUT Destination Out}</figcaption> + * </td> + * <td style="border: none; text-align: center;"> + * <img src="{@docRoot}reference/android/images/graphics/composite_XOR.png" /> + * <figcaption>{@link #XOR Exclusive Or}</figcaption> + * </td> + * </tr> + * </table> + * + * <h3>Blending modes</h3> + * + * <table summary="Blending modes" style="background-color: transparent;"> + * <tr> + * <td style="border: none; text-align: center;"> + * <img src="{@docRoot}reference/android/images/graphics/composite_DARKEN.png" /> + * <figcaption>{@link #DARKEN Darken}</figcaption> + * </td> + * <td style="border: none; text-align: center;"> + * <img src="{@docRoot}reference/android/images/graphics/composite_LIGHTEN.png" /> + * <figcaption>{@link #LIGHTEN Lighten}</figcaption> + * </td> + * <td style="border: none; text-align: center;"> + * <img src="{@docRoot}reference/android/images/graphics/composite_MULTIPLY.png" /> + * <figcaption>{@link #MULTIPLY Multiply}</figcaption> + * </td> + * </tr> + * <tr> + * <td style="border: none; text-align: center;"> + * <img src="{@docRoot}reference/android/images/graphics/composite_SCREEN.png" /> + * <figcaption>{@link #SCREEN Screen}</figcaption> + * </td> + * <td style="border: none; text-align: center;"> + * <img src="{@docRoot}reference/android/images/graphics/composite_OVERLAY.png" /> + * <figcaption>{@link #OVERLAY Overlay}</figcaption> + * </td> + * </tr> + * </table> + * + * <h3>Compositing equations</h3> + * + * <p>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.</p> + * + * <p>The result (or output) alpha value is noted \(\alpha_{out}\). The result (or output) + * color value is noted \(C_{out}\).</p> + */ public enum Mode { - /** [0, 0] */ + // these value must match their native equivalents. See SkXfermode.h + /** + * <p> + * <img src="{@docRoot}reference/android/images/graphics/composite_CLEAR.png" /> + * <figcaption>Destination pixels covered by the source are cleared to 0.</figcaption> + * </p> + * <p>\(\alpha_{out} = 0\)</p> + * <p>\(C_{out} = 0\)</p> + */ CLEAR (0), - /** [Sa, Sc] */ + /** + * <p> + * <img src="{@docRoot}reference/android/images/graphics/composite_SRC.png" /> + * <figcaption>The source pixels replace the destination pixels.</figcaption> + * </p> + * <p>\(\alpha_{out} = \alpha_{src}\)</p> + * <p>\(C_{out} = C_{src}\)</p> + */ SRC (1), - /** [Da, Dc] */ + /** + * <p> + * <img src="{@docRoot}reference/android/images/graphics/composite_DST.png" /> + * <figcaption>The source pixels are discarded, leaving the destination intact.</figcaption> + * </p> + * <p>\(\alpha_{out} = \alpha_{dst}\)</p> + * <p>\(C_{out} = C_{dst}\)</p> + */ DST (2), - /** [Sa + (1 - Sa)*Da, Rc = Sc + (1 - Sa)*Dc] */ + /** + * <p> + * <img src="{@docRoot}reference/android/images/graphics/composite_SRC_OVER.png" /> + * <figcaption>The source pixels are drawn over the destination pixels.</figcaption> + * </p> + * <p>\(\alpha_{out} = \alpha_{src} + (1 - \alpha_{src}) * \alpha_{dst}\)</p> + * <p>\(C_{out} = C_{src} + (1 - \alpha_{src}) * C_{dst}\)</p> + */ SRC_OVER (3), - /** [Sa + (1 - Sa)*Da, Rc = Dc + (1 - Da)*Sc] */ + /** + * <p> + * <img src="{@docRoot}reference/android/images/graphics/composite_DST_OVER.png" /> + * <figcaption>The source pixels are drawn behind the destination pixels.</figcaption> + * </p> + * <p>\(\alpha_{out} = \alpha_{dst} + (1 - \alpha_{dst}) * \alpha_{src}\)</p> + * <p>\(C_{out} = C_{dst} + (1 - \alpha_{dst}) * C_{src}\)</p> + */ DST_OVER (4), - /** [Sa * Da, Sc * Da] */ + /** + * <p> + * <img src="{@docRoot}reference/android/images/graphics/composite_SRC_IN.png" /> + * <figcaption>Keeps the source pixels that cover the destination pixels, + * discards the remaining source and destination pixels.</figcaption> + * </p> + * <p>\(\alpha_{out} = \alpha_{src} * \alpha_{dst}\)</p> + * <p>\(C_{out} = C_{src} * \alpha_{dst}\)</p> + */ SRC_IN (5), - /** [Sa * Da, Sa * Dc] */ + /** + * <p> + * <img src="{@docRoot}reference/android/images/graphics/composite_DST_IN.png" /> + * <figcaption>Keeps the destination pixels that cover source pixels, + * discards the remaining source and destination pixels.</figcaption> + * </p> + * <p>\(\alpha_{out} = \alpha_{src} * \alpha_{dst}\)</p> + * <p>\(C_{out} = C_{dst} * \alpha_{src}\)</p> + */ DST_IN (6), - /** [Sa * (1 - Da), Sc * (1 - Da)] */ + /** + * <p> + * <img src="{@docRoot}reference/android/images/graphics/composite_SRC_OUT.png" /> + * <figcaption>Keeps the source pixels that do not cover destination pixels. + * Discards source pixels that cover destination pixels. Discards all + * destination pixels.</figcaption> + * </p> + * <p>\(\alpha_{out} = (1 - \alpha_{dst}) * \alpha_{src}\)</p> + * <p>\(C_{out} = (1 - \alpha_{dst}) * C_{src}\)</p> + */ SRC_OUT (7), - /** [Da * (1 - Sa), Dc * (1 - Sa)] */ + /** + * <p> + * <img src="{@docRoot}reference/android/images/graphics/composite_DST_OUT.png" /> + * <figcaption>Keeps the destination pixels that are not covered by source pixels. + * Discards destination pixels that are covered by source pixels. Discards all + * source pixels.</figcaption> + * </p> + * <p>\(\alpha_{out} = (1 - \alpha_{src}) * \alpha_{dst}\)</p> + * <p>\(C_{out} = (1 - \alpha_{src}) * C_{dst}\)</p> + */ DST_OUT (8), - /** [Da, Sc * Da + (1 - Sa) * Dc] */ + /** + * <p> + * <img src="{@docRoot}reference/android/images/graphics/composite_SRC_ATOP.png" /> + * <figcaption>Discards the source pixels that do not cover destination pixels. + * Draws remaining source pixels over destination pixels.</figcaption> + * </p> + * <p>\(\alpha_{out} = \alpha_{dst}\)</p> + * <p>\(C_{out} = \alpha_{dst} * C_{src} + (1 - \alpha_{src}) * C_{dst}\)</p> + */ SRC_ATOP (9), - /** [Sa, Sa * Dc + Sc * (1 - Da)] */ + /** + * <p> + * <img src="{@docRoot}reference/android/images/graphics/composite_DST_ATOP.png" /> + * <figcaption>Discards the destination pixels that are not covered by source pixels. + * Draws remaining destination pixels over source pixels.</figcaption> + * </p> + * <p>\(\alpha_{out} = \alpha_{src}\)</p> + * <p>\(C_{out} = \alpha_{src} * C_{dst} + (1 - \alpha_{dst}) * C_{src}\)</p> + */ DST_ATOP (10), - /** [Sa + Da - 2 * Sa * Da, Sc * (1 - Da) + (1 - Sa) * Dc] */ + /** + * <p> + * <img src="{@docRoot}reference/android/images/graphics/composite_XOR.png" /> + * <figcaption>Discards the source and destination pixels where source pixels + * cover destination pixels. Draws remaining source pixels.</figcaption> + * </p> + * <p>\(\alpha_{out} = (1 - \alpha_{dst}) * \alpha_{src} + (1 - \alpha_{src}) * \alpha_{dst}\)</p> + * <p>\(C_{out} = (1 - \alpha_{dst}) * C_{src} + (1 - \alpha_{src}) * C_{dst}\)</p> + */ XOR (11), - /** [Sa + Da - Sa*Da, - Sc*(1 - Da) + Dc*(1 - Sa) + min(Sc, Dc)] */ + /** + * <p> + * <img src="{@docRoot}reference/android/images/graphics/composite_DARKEN.png" /> + * <figcaption>Retains the smallest component of the source and + * destination pixels.</figcaption> + * </p> + * <p>\(\alpha_{out} = \alpha_{src} + \alpha_{dst} - \alpha_{src} * \alpha_{dst}\)</p> + * <p>\(C_{out} = (1 - \alpha_{dst}) * C_{src} + (1 - \alpha_{src}) * C_{dst} + min(C_{src}, C_{dst})\)</p> + */ DARKEN (16), - /** [Sa + Da - Sa*Da, - Sc*(1 - Da) + Dc*(1 - Sa) + max(Sc, Dc)] */ + /** + * <p> + * <img src="{@docRoot}reference/android/images/graphics/composite_LIGHTEN.png" /> + * <figcaption>Retains the largest component of the source and + * destination pixel.</figcaption> + * </p> + * <p>\(\alpha_{out} = \alpha_{src} + \alpha_{dst} - \alpha_{src} * \alpha_{dst}\)</p> + * <p>\(C_{out} = (1 - \alpha_{dst}) * C_{src} + (1 - \alpha_{src}) * C_{dst} + max(C_{src}, C_{dst})\)</p> + */ LIGHTEN (17), - /** [Sa * Da, Sc * Dc] */ + /** + * <p> + * <img src="{@docRoot}reference/android/images/graphics/composite_MULTIPLY.png" /> + * <figcaption>Multiplies the source and destination pixels.</figcaption> + * </p> + * <p>\(\alpha_{out} = \alpha_{src} * \alpha_{dst}\)</p> + * <p>\(C_{out} = C_{src} * C_{dst}\)</p> + */ MULTIPLY (13), - /** [Sa + Da - Sa * Da, Sc + Dc - Sc * Dc] */ + /** + * <p> + * <img src="{@docRoot}reference/android/images/graphics/composite_SCREEN.png" /> + * <figcaption>Adds the source and destination pixels, then subtracts the + * source pixels multiplied by the destination.</figcaption> + * </p> + * <p>\(\alpha_{out} = \alpha_{src} + \alpha_{dst} - \alpha_{src} * \alpha_{dst}\)</p> + * <p>\(C_{out} = C_{src} + C_{dst} - C_{src} * C_{dst}\)</p> + */ SCREEN (14), - /** Saturate(S + D) */ + /** + * <p> + * <img src="{@docRoot}reference/android/images/graphics/composite_ADD.png" /> + * <figcaption>Adds the source pixels to the destination pixels and saturates + * the result.</figcaption> + * </p> + * <p>\(\alpha_{out} = max(0, min(\alpha_{src} + \alpha_{dst}, 1))\)</p> + * <p>\(C_{out} = max(0, min(C_{src} + C_{dst}, 1))\)</p> + */ ADD (12), + /** + * <p> + * <img src="{@docRoot}reference/android/images/graphics/composite_OVERLAY.png" /> + * <figcaption>Multiplies or screens the source and destination depending on the + * destination color.</figcaption> + * </p> + * <p>\(\alpha_{out} = \alpha_{src} + \alpha_{dst} - \alpha_{src} * \alpha_{dst}\)</p> + * <p>\(\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}\)</p> + */ 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 51044103003b..84d953de91db 100644 --- a/graphics/java/android/graphics/PorterDuffXfermode.java +++ b/graphics/java/android/graphics/PorterDuffXfermode.java @@ -16,6 +16,12 @@ package android.graphics; +/** + * <p>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.</p> + */ public class PorterDuffXfermode extends Xfermode { /** * Create an xfermode that uses the specified porter-duff mode. |
