SkXfermode.h revision fb6deed66c20f86c86c105f41dbbf3f3c4a47e4c
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 GrContext; 17class GrEffectRef; 18class GrTexture; 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 SkXfermode() {} 37 38 virtual void xfer32(SkPMColor dst[], const SkPMColor src[], int count, 39 const SkAlpha aa[]) const; 40 virtual void xfer16(uint16_t dst[], const SkPMColor src[], int count, 41 const SkAlpha aa[]) const; 42 virtual void xferA8(SkAlpha dst[], const SkPMColor src[], int count, 43 const SkAlpha aa[]) const; 44 45 /** Enum of possible coefficients to describe some xfermodes 46 */ 47 enum Coeff { 48 kZero_Coeff, /** 0 */ 49 kOne_Coeff, /** 1 */ 50 kSC_Coeff, /** src color */ 51 kISC_Coeff, /** inverse src color (i.e. 1 - sc) */ 52 kDC_Coeff, /** dst color */ 53 kIDC_Coeff, /** inverse dst color (i.e. 1 - dc) */ 54 kSA_Coeff, /** src alpha */ 55 kISA_Coeff, /** inverse src alpha (i.e. 1 - sa) */ 56 kDA_Coeff, /** dst alpha */ 57 kIDA_Coeff, /** inverse dst alpha (i.e. 1 - da) */ 58 59 kCoeffCount 60 }; 61 62 /** If the xfermode can be expressed as an equation using the coefficients 63 in Coeff, then asCoeff() returns true, and sets (if not null) src and 64 dst accordingly. 65 66 result = src_coeff * src_color + dst_coeff * dst_color; 67 68 As examples, here are some of the porterduff coefficients 69 70 MODE SRC_COEFF DST_COEFF 71 clear zero zero 72 src one zero 73 dst zero one 74 srcover one isa 75 dstover ida one 76 */ 77 virtual bool asCoeff(Coeff* src, Coeff* dst) const; 78 79 /** 80 * The same as calling xfermode->asCoeff(..), except that this also checks 81 * if the xfermode is NULL, and if so, treats it as kSrcOver_Mode. 82 */ 83 static bool AsCoeff(const SkXfermode*, Coeff* src, Coeff* dst); 84 85 /** List of predefined xfermodes. 86 The algebra for the modes uses the following symbols: 87 Sa, Sc - source alpha and color 88 Da, Dc - destination alpha and color (before compositing) 89 [a, c] - Resulting (alpha, color) values 90 For these equations, the colors are in premultiplied state. 91 If no xfermode is specified, kSrcOver is assumed. 92 The modes are ordered by those that can be expressed as a pair of Coeffs, followed by those 93 that aren't Coeffs but have separable r,g,b computations, and finally 94 those that are not separable. 95 */ 96 enum Mode { 97 kClear_Mode, //!< [0, 0] 98 kSrc_Mode, //!< [Sa, Sc] 99 kDst_Mode, //!< [Da, Dc] 100 kSrcOver_Mode, //!< [Sa + Da - Sa*Da, Rc = Sc + (1 - Sa)*Dc] 101 kDstOver_Mode, //!< [Sa + Da - Sa*Da, Rc = Dc + (1 - Da)*Sc] 102 kSrcIn_Mode, //!< [Sa * Da, Sc * Da] 103 kDstIn_Mode, //!< [Sa * Da, Sa * Dc] 104 kSrcOut_Mode, //!< [Sa * (1 - Da), Sc * (1 - Da)] 105 kDstOut_Mode, //!< [Da * (1 - Sa), Dc * (1 - Sa)] 106 kSrcATop_Mode, //!< [Da, Sc * Da + (1 - Sa) * Dc] 107 kDstATop_Mode, //!< [Sa, Sa * Dc + Sc * (1 - Da)] 108 kXor_Mode, //!< [Sa + Da - 2 * Sa * Da, Sc * (1 - Da) + (1 - Sa) * Dc] 109 kPlus_Mode, //!< [Sa + Da, Sc + Dc] 110 kModulate_Mode, // multiplies all components (= alpha and color) 111 112 // Following blend modes are defined in the CSS Compositing standard: 113 // https://dvcs.w3.org/hg/FXTF/rawfile/tip/compositing/index.html#blending 114 kScreen_Mode, 115 kLastCoeffMode = kScreen_Mode, 116 117 kOverlay_Mode, 118 kDarken_Mode, 119 kLighten_Mode, 120 kColorDodge_Mode, 121 kColorBurn_Mode, 122 kHardLight_Mode, 123 kSoftLight_Mode, 124 kDifference_Mode, 125 kExclusion_Mode, 126 kMultiply_Mode, 127 kLastSeparableMode = kMultiply_Mode, 128 129 kHue_Mode, 130 kSaturation_Mode, 131 kColor_Mode, 132 kLuminosity_Mode, 133 kLastMode = kLuminosity_Mode 134 }; 135 136 /** 137 * Gets the name of the Mode as a string. 138 */ 139 static const char* ModeName(Mode); 140 141 /** 142 * If the xfermode is one of the modes in the Mode enum, then asMode() 143 * returns true and sets (if not null) mode accordingly. Otherwise it 144 * returns false and ignores the mode parameter. 145 */ 146 virtual bool asMode(Mode* mode) const; 147 148 /** 149 * The same as calling xfermode->asMode(mode), except that this also checks 150 * if the xfermode is NULL, and if so, treats it as kSrcOver_Mode. 151 */ 152 static bool AsMode(const SkXfermode*, Mode* mode); 153 154 /** 155 * Returns true if the xfermode claims to be the specified Mode. This works 156 * correctly even if the xfermode is NULL (which equates to kSrcOver.) Thus 157 * you can say this without checking for a null... 158 * 159 * If (SkXfermode::IsMode(paint.getXfermode(), 160 * SkXfermode::kDstOver_Mode)) { 161 * ... 162 * } 163 */ 164 static bool IsMode(const SkXfermode* xfer, Mode mode); 165 166 /** Return an SkXfermode object for the specified mode. 167 */ 168 static SkXfermode* Create(Mode mode); 169 170 /** Return a function pointer to a routine that applies the specified 171 porter-duff transfer mode. 172 */ 173 static SkXfermodeProc GetProc(Mode mode); 174 175 /** Return a function pointer to a routine that applies the specified 176 porter-duff transfer mode and srcColor to a 16bit device color. Note, 177 if the mode+srcColor might return a non-opaque color, then there is not 178 16bit proc, and this will return NULL. 179 */ 180 static SkXfermodeProc16 GetProc16(Mode mode, SkColor srcColor); 181 182 /** 183 * If the specified mode can be represented by a pair of Coeff, then return 184 * true and set (if not NULL) the corresponding coeffs. If the mode is 185 * not representable as a pair of Coeffs, return false and ignore the 186 * src and dst parameters. 187 */ 188 static bool ModeAsCoeff(Mode mode, Coeff* src, Coeff* dst); 189 190 // DEPRECATED: call AsMode(...) 191 static bool IsMode(const SkXfermode* xfer, Mode* mode) { 192 return AsMode(xfer, mode); 193 } 194 195 /** A subclass may implement this factory function to work with the GPU backend. It is legal 196 to call this with all but the context param NULL to simply test the return value. effect, 197 src, and dst must all be NULL or all non-NULL. If effect is non-NULL then the xfermode may 198 optionally allocate an effect to return and the caller as *effect. The caller will install 199 it and own a ref to it. Since the xfermode may or may not assign *effect, the caller should 200 set *effect to NULL beforehand. If the function returns true and *effect is NULL then the 201 src and dst coeffs will be applied to the draw. When *effect is non-NULL the coeffs are 202 ignored. background specifies the texture to use as the background for compositing, and 203 should be accessed in the effect's fragment shader. If NULL, the effect should request 204 access to destination color (setWillReadDstColor()), and use that in the fragment shader 205 (builder->dstColor()). 206 */ 207 virtual bool asNewEffectOrCoeff(GrContext*, 208 GrEffectRef** effect, 209 Coeff* src, 210 Coeff* dst, 211 GrTexture* background = NULL) const; 212 213 /** 214 * The same as calling xfermode->asNewEffect(...), except that this also checks if the xfermode 215 * is NULL, and if so, treats it as kSrcOver_Mode. 216 */ 217 static bool AsNewEffectOrCoeff(SkXfermode*, 218 GrContext*, 219 GrEffectRef** effect, 220 Coeff* src, 221 Coeff* dst, 222 GrTexture* background = NULL); 223 224 SkDEVCODE(virtual void toString(SkString* str) const = 0;) 225 SK_DECLARE_FLATTENABLE_REGISTRAR_GROUP() 226protected: 227 SkXfermode(SkFlattenableReadBuffer& rb) : SkFlattenable(rb) {} 228 229 /** The default implementation of xfer32/xfer16/xferA8 in turn call this 230 method, 1 color at a time (upscaled to a SkPMColor). The default 231 implmentation of this method just returns dst. If performance is 232 important, your subclass should override xfer32/xfer16/xferA8 directly. 233 234 This method will not be called directly by the client, so it need not 235 be implemented if your subclass has overridden xfer32/xfer16/xferA8 236 */ 237 virtual SkPMColor xferColor(SkPMColor src, SkPMColor dst) const; 238 239private: 240 enum { 241 kModeCount = kLastMode + 1 242 }; 243 244 friend class SkGraphics; 245 static void Term(); 246 247 typedef SkFlattenable INHERITED; 248}; 249 250/////////////////////////////////////////////////////////////////////////////// 251 252/** \class SkProcXfermode 253 254 SkProcXfermode is a xfermode that applies the specified proc to its colors. 255 This class is not exported to java. 256*/ 257class SkProcXfermode : public SkXfermode { 258public: 259 SkProcXfermode(SkXfermodeProc proc) : fProc(proc) {} 260 261 // overrides from SkXfermode 262 virtual void xfer32(SkPMColor dst[], const SkPMColor src[], int count, 263 const SkAlpha aa[]) const SK_OVERRIDE; 264 virtual void xfer16(uint16_t dst[], const SkPMColor src[], int count, 265 const SkAlpha aa[]) const SK_OVERRIDE; 266 virtual void xferA8(SkAlpha dst[], const SkPMColor src[], int count, 267 const SkAlpha aa[]) const SK_OVERRIDE; 268 269 SK_DEVELOPER_TO_STRING() 270 SK_DECLARE_PUBLIC_FLATTENABLE_DESERIALIZATION_PROCS(SkProcXfermode) 271 272protected: 273 SkProcXfermode(SkFlattenableReadBuffer&); 274 virtual void flatten(SkFlattenableWriteBuffer&) const SK_OVERRIDE; 275 276 // allow subclasses to update this after we unflatten 277 void setProc(SkXfermodeProc proc) { 278 fProc = proc; 279 } 280 281 SkXfermodeProc getProc() const { 282 return fProc; 283 } 284 285private: 286 SkXfermodeProc fProc; 287 288 typedef SkXfermode INHERITED; 289}; 290 291#endif 292