src.android.graphics.PorterDuff Maven / Gradle / Ivy
Show all versions of android-all Show documentation
/*
* Copyright (C) 2006 The Android Open Source Project
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package android.graphics;
import android.compat.annotation.UnsupportedAppUsage;
/**
* 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.
*
* Consider using {@link BlendMode} instead as it provides a wider variety of tinting options
*/
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.
*
* Diagrams
*
* All the example diagrams presented below use the same source and destination
* images:
*
*
*
*
* 
* Source image
*
*
* 
* Destination image
*
*
*
*
* 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);
*
*
* Alpha compositing modes
*
*
*
*
*
* {@link #SRC Source}
*
*
* 
* {@link #SRC_OVER Source Over}
*
*
* 
* {@link #SRC_IN Source In}
*
*
* 
* {@link #SRC_ATOP Source Atop}
*
*
*
*
*
* {@link #DST Destination}
*
*
* 
* {@link #DST_OVER Destination Over}
*
*
* 
* {@link #DST_IN Destination In}
*
*
* 
* {@link #DST_ATOP Destination Atop}
*
*
*
*
* 
* {@link #CLEAR Clear}
*
*
* 
* {@link #SRC_OUT Source Out}
*
*
* 
* {@link #DST_OUT Destination Out}
*
*
* 
* {@link #XOR Exclusive Or}
*
*
*
*
* Blending modes
*
*
*
*
* 
* {@link #DARKEN Darken}
*
*
* 
* {@link #LIGHTEN Lighten}
*
*
* 
* {@link #MULTIPLY Multiply}
*
*
*
*
* 
* {@link #SCREEN Screen}
*
*
* 
* {@link #OVERLAY Overlay}
*
*
*
*
* Compositing equations
*
* 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 {
// these value must match their native equivalents. See SkXfermode.h
/**
*
*
* Destination pixels covered by the source are cleared to 0.
*
* \(\alpha_{out} = 0\)
* \(C_{out} = 0\)
*/
CLEAR (0),
/**
*
*
* The source pixels replace the destination pixels.
*
* \(\alpha_{out} = \alpha_{src}\)
* \(C_{out} = C_{src}\)
*/
SRC (1),
/**
*
*
* The source pixels are discarded, leaving the destination intact.
*
* \(\alpha_{out} = \alpha_{dst}\)
* \(C_{out} = C_{dst}\)
*/
DST (2),
/**
*
*
* The source pixels are drawn over the destination pixels.
*
* \(\alpha_{out} = \alpha_{src} + (1 - \alpha_{src}) * \alpha_{dst}\)
* \(C_{out} = C_{src} + (1 - \alpha_{src}) * C_{dst}\)
*/
SRC_OVER (3),
/**
*
*
* The source pixels are drawn behind the destination pixels.
*
* \(\alpha_{out} = \alpha_{dst} + (1 - \alpha_{dst}) * \alpha_{src}\)
* \(C_{out} = C_{dst} + (1 - \alpha_{dst}) * C_{src}\)
*/
DST_OVER (4),
/**
*
*
* Keeps the source pixels that cover the destination pixels,
* discards the remaining source and destination pixels.
*
* \(\alpha_{out} = \alpha_{src} * \alpha_{dst}\)
* \(C_{out} = C_{src} * \alpha_{dst}\)
*/
SRC_IN (5),
/**
*
*
* Keeps the destination pixels that cover source pixels,
* discards the remaining source and destination pixels.
*
* \(\alpha_{out} = \alpha_{src} * \alpha_{dst}\)
* \(C_{out} = C_{dst} * \alpha_{src}\)
*/
DST_IN (6),
/**
*
*
* Keeps the source pixels that do not cover destination pixels.
* Discards source pixels that cover destination pixels. Discards all
* destination pixels.
*
* \(\alpha_{out} = (1 - \alpha_{dst}) * \alpha_{src}\)
* \(C_{out} = (1 - \alpha_{dst}) * C_{src}\)
*/
SRC_OUT (7),
/**
*
*
* Keeps the destination pixels that are not covered by source pixels.
* Discards destination pixels that are covered by source pixels. Discards all
* source pixels.
*
* \(\alpha_{out} = (1 - \alpha_{src}) * \alpha_{dst}\)
* \(C_{out} = (1 - \alpha_{src}) * C_{dst}\)
*/
DST_OUT (8),
/**
*
*
* Discards the source pixels that do not cover destination pixels.
* Draws remaining source pixels over destination pixels.
*
* \(\alpha_{out} = \alpha_{dst}\)
* \(C_{out} = \alpha_{dst} * C_{src} + (1 - \alpha_{src}) * C_{dst}\)
*/
SRC_ATOP (9),
/**
*
*
* Discards the destination pixels that are not covered by source pixels.
* Draws remaining destination pixels over source pixels.
*
* \(\alpha_{out} = \alpha_{src}\)
* \(C_{out} = \alpha_{src} * C_{dst} + (1 - \alpha_{dst}) * C_{src}\)
*/
DST_ATOP (10),
/**
*
*
* Discards the source and destination pixels where source pixels
* cover destination pixels. Draws remaining source pixels.
*
* \(\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),
/**
*
*
* Retains the smallest component of the source and
* destination pixels.
*
* \(\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),
/**
*
*
* Retains the largest component of the source and
* destination pixel.
*
* \(\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),
/**
*
*
* Multiplies the source and destination pixels.
*
* \(\alpha_{out} = \alpha_{src} * \alpha_{dst}\)
* \(C_{out} = C_{src} * C_{dst}\)
*/
MULTIPLY (13),
/**
*
*
* Adds the source and destination pixels, then subtracts the
* source pixels multiplied by the destination.
*
* \(\alpha_{out} = \alpha_{src} + \alpha_{dst} - \alpha_{src} * \alpha_{dst}\)
* \(C_{out} = C_{src} + C_{dst} - C_{src} * C_{dst}\)
*/
SCREEN (14),
/**
*
* 
* Adds the source pixels to the destination pixels and saturates
* the result.
*
* \(\alpha_{out} = max(0, min(\alpha_{src} + \alpha_{dst}, 1))\)
* \(C_{out} = max(0, min(C_{src} + C_{dst}, 1))\)
*/
ADD (12),
/**
*
*
* Multiplies or screens the source and destination depending on the
* destination color.
*
* \(\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) {
this.nativeInt = nativeInt;
}
/**
* @hide
*/
@UnsupportedAppUsage
public final int nativeInt;
}
/**
* @hide
*/
public static int modeToInt(Mode mode) {
return mode.nativeInt;
}
/**
* @hide
*/
public static Mode intToMode(int val) {
switch (val) {
default:
case 0: return Mode.CLEAR;
case 1: return Mode.SRC;
case 2: return Mode.DST;
case 3: return Mode.SRC_OVER;
case 4: return Mode.DST_OVER;
case 5: return Mode.SRC_IN;
case 6: return Mode.DST_IN;
case 7: return Mode.SRC_OUT;
case 8: return Mode.DST_OUT;
case 9: return Mode.SRC_ATOP;
case 10: return Mode.DST_ATOP;
case 11: return Mode.XOR;
case 16: return Mode.DARKEN;
case 17: return Mode.LIGHTEN;
case 13: return Mode.MULTIPLY;
case 14: return Mode.SCREEN;
case 12: return Mode.ADD;
case 15: return Mode.OVERLAY;
}
}
}