1
2/*
3 * Copyright 2006 The Android Open Source Project
4 *
5 * Use of this source code is governed by a BSD-style license that can be
6 * found in the LICENSE file.
7 */
8
9
10#ifndef SkXfermode_DEFINED
11#define SkXfermode_DEFINED
12
13#include "SkFlattenable.h"
14#include "SkColor.h"
15
16class GrFragmentProcessor;
17class GrTexture;
18class GrXPFactory;
19class SkString;
20
21/** \class SkXfermode
22 *
23 *  SkXfermode is the base class for objects that are called to implement custom
24 *  "transfer-modes" in the drawing pipeline. The static function Create(Modes)
25 *  can be called to return an instance of any of the predefined subclasses as
26 *  specified in the Modes enum. When an SkXfermode is assigned to an SkPaint,
27 *  then objects drawn with that paint have the xfermode applied.
28 *
29 *  All subclasses are required to be reentrant-safe : it must be legal to share
30 *  the same instance between several threads.
31 */
32class SK_API SkXfermode : public SkFlattenable {
33public:
34    SK_DECLARE_INST_COUNT(SkXfermode)
35
36    virtual void xfer32(SkPMColor dst[], const SkPMColor src[], int count,
37                        const SkAlpha aa[]) const;
38    virtual void xfer16(uint16_t dst[], const SkPMColor src[], int count,
39                        const SkAlpha aa[]) const;
40    virtual void xferA8(SkAlpha dst[], const SkPMColor src[], int count,
41                        const SkAlpha aa[]) const;
42
43    /** Enum of possible coefficients to describe some xfermodes
44     */
45    enum Coeff {
46        kZero_Coeff,    /** 0 */
47        kOne_Coeff,     /** 1 */
48        kSC_Coeff,      /** src color */
49        kISC_Coeff,     /** inverse src color (i.e. 1 - sc) */
50        kDC_Coeff,      /** dst color */
51        kIDC_Coeff,     /** inverse dst color (i.e. 1 - dc) */
52        kSA_Coeff,      /** src alpha */
53        kISA_Coeff,     /** inverse src alpha (i.e. 1 - sa) */
54        kDA_Coeff,      /** dst alpha */
55        kIDA_Coeff,     /** inverse dst alpha (i.e. 1 - da) */
56
57        kCoeffCount
58    };
59
60    /** List of predefined xfermodes.
61        The algebra for the modes uses the following symbols:
62        Sa, Sc  - source alpha and color
63        Da, Dc - destination alpha and color (before compositing)
64        [a, c] - Resulting (alpha, color) values
65        For these equations, the colors are in premultiplied state.
66        If no xfermode is specified, kSrcOver is assumed.
67        The modes are ordered by those that can be expressed as a pair of Coeffs, followed by those
68        that aren't Coeffs but have separable r,g,b computations, and finally
69        those that are not separable.
70     */
71    enum Mode {
72        kClear_Mode,    //!< [0, 0]
73        kSrc_Mode,      //!< [Sa, Sc]
74        kDst_Mode,      //!< [Da, Dc]
75        kSrcOver_Mode,  //!< [Sa + Da - Sa*Da, Rc = Sc + (1 - Sa)*Dc]
76        kDstOver_Mode,  //!< [Sa + Da - Sa*Da, Rc = Dc + (1 - Da)*Sc]
77        kSrcIn_Mode,    //!< [Sa * Da, Sc * Da]
78        kDstIn_Mode,    //!< [Sa * Da, Sa * Dc]
79        kSrcOut_Mode,   //!< [Sa * (1 - Da), Sc * (1 - Da)]
80        kDstOut_Mode,   //!< [Da * (1 - Sa), Dc * (1 - Sa)]
81        kSrcATop_Mode,  //!< [Da, Sc * Da + (1 - Sa) * Dc]
82        kDstATop_Mode,  //!< [Sa, Sa * Dc + Sc * (1 - Da)]
83        kXor_Mode,      //!< [Sa + Da - 2 * Sa * Da, Sc * (1 - Da) + (1 - Sa) * Dc]
84        kPlus_Mode,     //!< [Sa + Da, Sc + Dc]
85        kModulate_Mode, // multiplies all components (= alpha and color)
86
87        // Following blend modes are defined in the CSS Compositing standard:
88        // https://dvcs.w3.org/hg/FXTF/rawfile/tip/compositing/index.html#blending
89        kScreen_Mode,
90        kLastCoeffMode = kScreen_Mode,
91
92        kOverlay_Mode,
93        kDarken_Mode,
94        kLighten_Mode,
95        kColorDodge_Mode,
96        kColorBurn_Mode,
97        kHardLight_Mode,
98        kSoftLight_Mode,
99        kDifference_Mode,
100        kExclusion_Mode,
101        kMultiply_Mode,
102        kLastSeparableMode = kMultiply_Mode,
103
104        kHue_Mode,
105        kSaturation_Mode,
106        kColor_Mode,
107        kLuminosity_Mode,
108        kLastMode = kLuminosity_Mode
109    };
110
111    /**
112     * Gets the name of the Mode as a string.
113     */
114    static const char* ModeName(Mode);
115
116    /**
117     *  If the xfermode is one of the modes in the Mode enum, then asMode()
118     *  returns true and sets (if not null) mode accordingly. Otherwise it
119     *  returns false and ignores the mode parameter.
120     */
121    virtual bool asMode(Mode* mode) const;
122
123    /**
124     *  The same as calling xfermode->asMode(mode), except that this also checks
125     *  if the xfermode is NULL, and if so, treats it as kSrcOver_Mode.
126     */
127    static bool AsMode(const SkXfermode*, Mode* mode);
128
129    /**
130     *  Returns true if the xfermode claims to be the specified Mode. This works
131     *  correctly even if the xfermode is NULL (which equates to kSrcOver.) Thus
132     *  you can say this without checking for a null...
133     *
134     *  If (SkXfermode::IsMode(paint.getXfermode(),
135     *                         SkXfermode::kDstOver_Mode)) {
136     *      ...
137     *  }
138     */
139    static bool IsMode(const SkXfermode* xfer, Mode mode);
140
141    /** Return an SkXfermode object for the specified mode.
142     */
143    static SkXfermode* Create(Mode mode);
144
145    /** Return a function pointer to a routine that applies the specified
146        porter-duff transfer mode.
147     */
148    static SkXfermodeProc GetProc(Mode mode);
149
150    /** Return a function pointer to a routine that applies the specified
151        porter-duff transfer mode and srcColor to a 16bit device color. Note,
152        if the mode+srcColor might return a non-opaque color, then there is not
153        16bit proc, and this will return NULL.
154      */
155    static SkXfermodeProc16 GetProc16(Mode mode, SkColor srcColor);
156
157    /**
158     *  If the specified mode can be represented by a pair of Coeff, then return
159     *  true and set (if not NULL) the corresponding coeffs. If the mode is
160     *  not representable as a pair of Coeffs, return false and ignore the
161     *  src and dst parameters.
162     */
163    static bool ModeAsCoeff(Mode mode, Coeff* src, Coeff* dst);
164
165    SK_ATTR_DEPRECATED("use AsMode(...)")
166    static bool IsMode(const SkXfermode* xfer, Mode* mode) {
167        return AsMode(xfer, mode);
168    }
169
170    /**
171     * Returns whether or not the xfer mode can support treating coverage as alpha
172     */
173    virtual bool supportsCoverageAsAlpha() const;
174
175    /**
176     *  The same as calling xfermode->supportsCoverageAsAlpha(), except that this also checks if
177     *  the xfermode is NULL, and if so, treats it as kSrcOver_Mode.
178     */
179    static bool SupportsCoverageAsAlpha(const SkXfermode* xfer);
180
181    enum SrcColorOpacity {
182        // The src color is known to be opaque (alpha == 255)
183        kOpaque_SrcColorOpacity = 0,
184        // The src color is known to be fully transparent (color == 0)
185        kTransparentBlack_SrcColorOpacity = 1,
186        // The src alpha is known to be fully transparent (alpha == 0)
187        kTransparentAlpha_SrcColorOpacity = 2,
188        // The src color opacity is unknown
189        kUnknown_SrcColorOpacity = 3
190    };
191
192    /**
193     * Returns whether or not the result of the draw with the xfer mode will be opaque or not. The
194     * input to this call is an enum describing known information about the opacity of the src color
195     * that will be given to the xfer mode.
196     */
197    virtual bool isOpaque(SrcColorOpacity opacityType) const;
198
199    /**
200     *  The same as calling xfermode->isOpaque(...), except that this also checks if
201     *  the xfermode is NULL, and if so, treats it as kSrcOver_Mode.
202     */
203    static bool IsOpaque(const SkXfermode* xfer, SrcColorOpacity opacityType);
204
205    /** Implemented by a subclass to support use as an image filter in the GPU backend. When used as
206        an image filter the xfer mode blends the source color against a background texture rather
207        than the destination. It is implemented as a fragment processor. This can be called with
208        both params set to NULL to query whether it would succeed. Otherwise, both params are
209        required. Upon success the function returns true and the caller owns a ref to the fragment
210        parameter. Upon failure false is returned and the processor param is not written to.
211     */
212    virtual bool asFragmentProcessor(GrFragmentProcessor**, GrTexture* background) const;
213
214    /** A subclass may implement this factory function to work with the GPU backend. It is legal
215        to call this with xpf NULL to simply test the return value. If xpf is non-NULL then the
216        xfermode may optionally allocate a factory to return to the caller as *xpf. The caller
217        will install it and own a ref to it. Since the xfermode may or may not assign *xpf, the
218        caller should set *xpf to NULL beforehand. XferProcessors cannot use a background texture.
219     */
220    virtual bool asXPFactory(GrXPFactory** xpf) const;
221
222    /** Returns true if the xfermode can be expressed as an xfer processor factory (xpFactory).
223        This helper calls the asXPFactory() virtual. If the xfermode is NULL, it is treated as
224        kSrcOver_Mode. It is legal to call this with xpf param NULL to simply test the return value.
225     */
226    static bool AsXPFactory(SkXfermode*, GrXPFactory**);
227
228    SK_TO_STRING_PUREVIRT()
229    SK_DECLARE_FLATTENABLE_REGISTRAR_GROUP()
230    SK_DEFINE_FLATTENABLE_TYPE(SkXfermode)
231
232protected:
233    SkXfermode() {}
234    /** The default implementation of xfer32/xfer16/xferA8 in turn call this
235        method, 1 color at a time (upscaled to a SkPMColor). The default
236        implmentation of this method just returns dst. If performance is
237        important, your subclass should override xfer32/xfer16/xferA8 directly.
238
239        This method will not be called directly by the client, so it need not
240        be implemented if your subclass has overridden xfer32/xfer16/xferA8
241    */
242    virtual SkPMColor xferColor(SkPMColor src, SkPMColor dst) const;
243
244private:
245    enum {
246        kModeCount = kLastMode + 1
247    };
248
249    typedef SkFlattenable INHERITED;
250};
251
252#endif
253