epoger@google.com | ec3ed6a | 2011-07-28 14:26:00 +0000 | [diff] [blame] | 1 | |
reed@android.com | 8a1c16f | 2008-12-17 15:59:43 +0000 | [diff] [blame] | 2 | /* |
epoger@google.com | ec3ed6a | 2011-07-28 14:26:00 +0000 | [diff] [blame] | 3 | * Copyright 2006 The Android Open Source Project |
reed@android.com | 8a1c16f | 2008-12-17 15:59:43 +0000 | [diff] [blame] | 4 | * |
epoger@google.com | ec3ed6a | 2011-07-28 14:26:00 +0000 | [diff] [blame] | 5 | * Use of this source code is governed by a BSD-style license that can be |
| 6 | * found in the LICENSE file. |
reed@android.com | 8a1c16f | 2008-12-17 15:59:43 +0000 | [diff] [blame] | 7 | */ |
| 8 | |
epoger@google.com | ec3ed6a | 2011-07-28 14:26:00 +0000 | [diff] [blame] | 9 | |
reed@android.com | 8a1c16f | 2008-12-17 15:59:43 +0000 | [diff] [blame] | 10 | #ifndef SkShader_DEFINED |
| 11 | #define SkShader_DEFINED |
| 12 | |
| 13 | #include "SkBitmap.h" |
| 14 | #include "SkFlattenable.h" |
| 15 | #include "SkMask.h" |
| 16 | #include "SkMatrix.h" |
| 17 | #include "SkPaint.h" |
| 18 | |
| 19 | class SkPath; |
| 20 | |
| 21 | /** \class SkShader |
reed@google.com | ad91799 | 2011-04-11 19:01:12 +0000 | [diff] [blame] | 22 | * |
| 23 | * SkShader is the based class for objects that return horizontal spans of |
| 24 | * colors during drawing. A subclass of SkShader is installed in a SkPaint |
| 25 | * calling paint.setShader(shader). After that any object (other than a bitmap) |
| 26 | * that is drawn with that paint will get its color(s) from the shader. |
| 27 | */ |
ctguil@chromium.org | 7ffb1b2 | 2011-03-15 21:27:08 +0000 | [diff] [blame] | 28 | class SK_API SkShader : public SkFlattenable { |
reed@android.com | 8a1c16f | 2008-12-17 15:59:43 +0000 | [diff] [blame] | 29 | public: |
| 30 | SkShader(); |
| 31 | virtual ~SkShader(); |
| 32 | |
reed@google.com | ad91799 | 2011-04-11 19:01:12 +0000 | [diff] [blame] | 33 | /** |
| 34 | * Return true if the shader has a non-identity local matrix. |
| 35 | * @param localM Optional: If not null, return the shader's local matrix |
| 36 | * @return true if the shader has a non-identity local matrix. |
| 37 | */ |
reed@android.com | 8a1c16f | 2008-12-17 15:59:43 +0000 | [diff] [blame] | 38 | bool getLocalMatrix(SkMatrix* localM) const; |
reed@google.com | ad91799 | 2011-04-11 19:01:12 +0000 | [diff] [blame] | 39 | |
| 40 | /** |
| 41 | * Set the shader's local matrix. |
| 42 | * @param localM The shader's new local matrix. |
| 43 | */ |
reed@android.com | 8a1c16f | 2008-12-17 15:59:43 +0000 | [diff] [blame] | 44 | void setLocalMatrix(const SkMatrix& localM); |
reed@google.com | ad91799 | 2011-04-11 19:01:12 +0000 | [diff] [blame] | 45 | |
| 46 | /** |
| 47 | * Reset the shader's local matrix to identity. |
| 48 | */ |
reed@android.com | 8a1c16f | 2008-12-17 15:59:43 +0000 | [diff] [blame] | 49 | void resetLocalMatrix(); |
| 50 | |
| 51 | enum TileMode { |
reed@google.com | 0beaba5 | 2012-03-16 14:38:06 +0000 | [diff] [blame] | 52 | /** replicate the edge color if the shader draws outside of its |
| 53 | * original bounds |
| 54 | */ |
| 55 | kClamp_TileMode, |
| 56 | |
| 57 | /** repeat the shader's image horizontally and vertically */ |
| 58 | kRepeat_TileMode, |
| 59 | |
| 60 | /** repeat the shader's image horizontally and vertically, alternating |
| 61 | * mirror images so that adjacent images always seam |
| 62 | */ |
| 63 | kMirror_TileMode, |
| 64 | |
| 65 | #if 0 |
| 66 | /** only draw within the original domain, return 0 everywhere else */ |
| 67 | kDecal_TileMode, |
| 68 | #endif |
reed@android.com | 8a1c16f | 2008-12-17 15:59:43 +0000 | [diff] [blame] | 69 | |
| 70 | kTileModeCount |
| 71 | }; |
| 72 | |
| 73 | // override these in your subclass |
| 74 | |
| 75 | enum Flags { |
| 76 | //!< set if all of the colors will be opaque |
reed@android.com | 3c9b2a4 | 2009-08-27 19:28:37 +0000 | [diff] [blame] | 77 | kOpaqueAlpha_Flag = 0x01, |
reed@android.com | 5119bdb | 2009-06-12 21:27:03 +0000 | [diff] [blame] | 78 | |
reed@android.com | 8a1c16f | 2008-12-17 15:59:43 +0000 | [diff] [blame] | 79 | //! set if this shader's shadeSpan16() method can be called |
reed@android.com | 3c9b2a4 | 2009-08-27 19:28:37 +0000 | [diff] [blame] | 80 | kHasSpan16_Flag = 0x02, |
reed@android.com | 5119bdb | 2009-06-12 21:27:03 +0000 | [diff] [blame] | 81 | |
reed@android.com | 8a1c16f | 2008-12-17 15:59:43 +0000 | [diff] [blame] | 82 | /** Set this bit if the shader's native data type is instrinsically 16 |
| 83 | bit, meaning that calling the 32bit shadeSpan() entry point will |
| 84 | mean the the impl has to up-sample 16bit data into 32bit. Used as a |
| 85 | a means of clearing a dither request if the it will have no effect |
| 86 | */ |
reed@android.com | 5119bdb | 2009-06-12 21:27:03 +0000 | [diff] [blame] | 87 | kIntrinsicly16_Flag = 0x04, |
| 88 | |
| 89 | /** set (after setContext) if the spans only vary in X (const in Y). |
| 90 | e.g. an Nx1 bitmap that is being tiled in Y, or a linear-gradient |
reed@android.com | 3c9b2a4 | 2009-08-27 19:28:37 +0000 | [diff] [blame] | 91 | that varies from left-to-right. This flag specifies this for |
| 92 | shadeSpan(). |
reed@android.com | 5119bdb | 2009-06-12 21:27:03 +0000 | [diff] [blame] | 93 | */ |
reed@android.com | 3c9b2a4 | 2009-08-27 19:28:37 +0000 | [diff] [blame] | 94 | kConstInY32_Flag = 0x08, |
reed@google.com | 7c2f27d | 2011-03-07 19:29:00 +0000 | [diff] [blame] | 95 | |
reed@android.com | 3c9b2a4 | 2009-08-27 19:28:37 +0000 | [diff] [blame] | 96 | /** same as kConstInY32_Flag, but is set if this is true for shadeSpan16 |
| 97 | which may not always be the case, since shadeSpan16 may be |
| 98 | predithered, which would mean it was not const in Y, even though |
| 99 | the 32bit shadeSpan() would be const. |
| 100 | */ |
| 101 | kConstInY16_Flag = 0x10 |
reed@android.com | 8a1c16f | 2008-12-17 15:59:43 +0000 | [diff] [blame] | 102 | }; |
| 103 | |
reed@google.com | ad91799 | 2011-04-11 19:01:12 +0000 | [diff] [blame] | 104 | /** |
| 105 | * Called sometimes before drawing with this shader. Return the type of |
| 106 | * alpha your shader will return. The default implementation returns 0. |
| 107 | * Your subclass should override if it can (even sometimes) report a |
| 108 | * non-zero value, since that will enable various blitters to perform |
| 109 | * faster. |
| 110 | */ |
reed@android.com | 8a1c16f | 2008-12-17 15:59:43 +0000 | [diff] [blame] | 111 | virtual uint32_t getFlags() { return 0; } |
| 112 | |
reed@google.com | ad91799 | 2011-04-11 19:01:12 +0000 | [diff] [blame] | 113 | /** |
junov@chromium.org | b6e1619 | 2011-12-09 15:48:03 +0000 | [diff] [blame] | 114 | * Returns true if the shader is guaranteed to produce only opaque |
| 115 | * colors, subject to the SkPaint using the shader to apply an opaque |
| 116 | * alpha value. Subclasses should override this to allow some |
| 117 | * optimizations. isOpaque() can be called at any time, unlike getFlags, |
| 118 | * which only works properly when the context is set. |
| 119 | */ |
| 120 | virtual bool isOpaque() const { return false; } |
| 121 | |
| 122 | /** |
reed@google.com | ad91799 | 2011-04-11 19:01:12 +0000 | [diff] [blame] | 123 | * Return the alpha associated with the data returned by shadeSpan16(). If |
| 124 | * kHasSpan16_Flag is not set, this value is meaningless. |
| 125 | */ |
reed@android.com | 8a1c16f | 2008-12-17 15:59:43 +0000 | [diff] [blame] | 126 | virtual uint8_t getSpan16Alpha() const { return fPaintAlpha; } |
reed@google.com | 7c2f27d | 2011-03-07 19:29:00 +0000 | [diff] [blame] | 127 | |
reed@google.com | ad91799 | 2011-04-11 19:01:12 +0000 | [diff] [blame] | 128 | /** |
| 129 | * Called once before drawing, with the current paint and device matrix. |
| 130 | * Return true if your shader supports these parameters, or false if not. |
| 131 | * If false is returned, nothing will be drawn. |
| 132 | */ |
reed@android.com | 3c9b2a4 | 2009-08-27 19:28:37 +0000 | [diff] [blame] | 133 | virtual bool setContext(const SkBitmap& device, const SkPaint& paint, |
| 134 | const SkMatrix& matrix); |
reed@android.com | 8a1c16f | 2008-12-17 15:59:43 +0000 | [diff] [blame] | 135 | |
reed@google.com | ad91799 | 2011-04-11 19:01:12 +0000 | [diff] [blame] | 136 | /** |
| 137 | * Called for each span of the object being drawn. Your subclass should |
| 138 | * set the appropriate colors (with premultiplied alpha) that correspond |
| 139 | * to the specified device coordinates. |
| 140 | */ |
reed@android.com | 3c9b2a4 | 2009-08-27 19:28:37 +0000 | [diff] [blame] | 141 | virtual void shadeSpan(int x, int y, SkPMColor[], int count) = 0; |
reed@google.com | ad91799 | 2011-04-11 19:01:12 +0000 | [diff] [blame] | 142 | |
| 143 | /** |
| 144 | * Called only for 16bit devices when getFlags() returns |
| 145 | * kOpaqueAlphaFlag | kHasSpan16_Flag |
| 146 | */ |
reed@android.com | 3c9b2a4 | 2009-08-27 19:28:37 +0000 | [diff] [blame] | 147 | virtual void shadeSpan16(int x, int y, uint16_t[], int count); |
reed@google.com | ad91799 | 2011-04-11 19:01:12 +0000 | [diff] [blame] | 148 | |
| 149 | /** |
| 150 | * Similar to shadeSpan, but only returns the alpha-channel for a span. |
| 151 | * The default implementation calls shadeSpan() and then extracts the alpha |
| 152 | * values from the returned colors. |
| 153 | */ |
reed@android.com | 3c9b2a4 | 2009-08-27 19:28:37 +0000 | [diff] [blame] | 154 | virtual void shadeSpanAlpha(int x, int y, uint8_t alpha[], int count); |
reed@android.com | 8a1c16f | 2008-12-17 15:59:43 +0000 | [diff] [blame] | 155 | |
reed@google.com | ad91799 | 2011-04-11 19:01:12 +0000 | [diff] [blame] | 156 | /** |
| 157 | * Helper function that returns true if this shader's shadeSpan16() method |
| 158 | * can be called. |
| 159 | */ |
reed@android.com | 3c9b2a4 | 2009-08-27 19:28:37 +0000 | [diff] [blame] | 160 | bool canCallShadeSpan16() { |
reed@android.com | 8a1c16f | 2008-12-17 15:59:43 +0000 | [diff] [blame] | 161 | return SkShader::CanCallShadeSpan16(this->getFlags()); |
| 162 | } |
| 163 | |
reed@google.com | ad91799 | 2011-04-11 19:01:12 +0000 | [diff] [blame] | 164 | /** |
| 165 | * Helper to check the flags to know if it is legal to call shadeSpan16() |
| 166 | */ |
reed@android.com | 8a1c16f | 2008-12-17 15:59:43 +0000 | [diff] [blame] | 167 | static bool CanCallShadeSpan16(uint32_t flags) { |
| 168 | return (flags & kHasSpan16_Flag) != 0; |
| 169 | } |
| 170 | |
reed@google.com | ad91799 | 2011-04-11 19:01:12 +0000 | [diff] [blame] | 171 | /** |
| 172 | * Called before a session using the shader begins. Some shaders override |
| 173 | * this to defer some of their work (like calling bitmap.lockPixels()). |
| 174 | * Must be balanced by a call to endSession. |
| 175 | */ |
reed@android.com | 8a1c16f | 2008-12-17 15:59:43 +0000 | [diff] [blame] | 176 | virtual void beginSession(); |
| 177 | virtual void endSession(); |
reed@google.com | 7c2f27d | 2011-03-07 19:29:00 +0000 | [diff] [blame] | 178 | |
reed@android.com | f2b98d6 | 2010-12-20 18:26:13 +0000 | [diff] [blame] | 179 | /** |
| 180 | Gives method bitmap should be read to implement a shader. |
| 181 | Also determines number and interpretation of "extra" parameters returned |
| 182 | by asABitmap |
| 183 | */ |
| 184 | enum BitmapType { |
| 185 | kNone_BitmapType, //<! Shader is not represented as a bitmap |
reed@google.com | 7c2f27d | 2011-03-07 19:29:00 +0000 | [diff] [blame] | 186 | kDefault_BitmapType,//<! Access bitmap using local coords transformed |
reed@android.com | f2b98d6 | 2010-12-20 18:26:13 +0000 | [diff] [blame] | 187 | // by matrix. No extras |
reed@google.com | 7c2f27d | 2011-03-07 19:29:00 +0000 | [diff] [blame] | 188 | kRadial_BitmapType, //<! Access bitmap by transforming local coordinates |
| 189 | // by the matrix and taking the distance of result |
| 190 | // from (0,0) as bitmap column. Bitmap is 1 pixel |
reed@android.com | f2b98d6 | 2010-12-20 18:26:13 +0000 | [diff] [blame] | 191 | // tall. No extras |
reed@google.com | 7c2f27d | 2011-03-07 19:29:00 +0000 | [diff] [blame] | 192 | kSweep_BitmapType, //<! Access bitmap by transforming local coordinates |
reed@android.com | f2b98d6 | 2010-12-20 18:26:13 +0000 | [diff] [blame] | 193 | // by the matrix and taking the angle of result |
| 194 | // to (0,0) as bitmap x coord, where angle = 0 is |
reed@google.com | 7c2f27d | 2011-03-07 19:29:00 +0000 | [diff] [blame] | 195 | // bitmap left edge of bitmap = 2pi is the |
reed@android.com | f2b98d6 | 2010-12-20 18:26:13 +0000 | [diff] [blame] | 196 | // right edge. Bitmap is 1 pixel tall. No extras |
vandebo@chromium.org | d3ae779 | 2011-02-24 00:21:06 +0000 | [diff] [blame] | 197 | kTwoPointRadial_BitmapType, |
reed@google.com | 7c2f27d | 2011-03-07 19:29:00 +0000 | [diff] [blame] | 198 | //<! Matrix transforms to space where (0,0) is |
reed@android.com | f2b98d6 | 2010-12-20 18:26:13 +0000 | [diff] [blame] | 199 | // the center of the starting circle. The second |
reed@google.com | 7c2f27d | 2011-03-07 19:29:00 +0000 | [diff] [blame] | 200 | // circle will be centered (x, 0) where x may be |
| 201 | // 0. The post-matrix space is normalized such |
reed@android.com | f2b98d6 | 2010-12-20 18:26:13 +0000 | [diff] [blame] | 202 | // that 1 is the second radius - first radius. |
| 203 | // Three extra parameters are returned: |
reed@google.com | 7c2f27d | 2011-03-07 19:29:00 +0000 | [diff] [blame] | 204 | // 0: x-offset of second circle center |
reed@android.com | f2b98d6 | 2010-12-20 18:26:13 +0000 | [diff] [blame] | 205 | // to first. |
reed@google.com | 7c2f27d | 2011-03-07 19:29:00 +0000 | [diff] [blame] | 206 | // 1: radius of first circle in post-matrix |
reed@android.com | f2b98d6 | 2010-12-20 18:26:13 +0000 | [diff] [blame] | 207 | // space |
| 208 | // 2: the second radius minus the first radius |
reed@google.com | 7c2f27d | 2011-03-07 19:29:00 +0000 | [diff] [blame] | 209 | // in pre-transformed space. |
vandebo@chromium.org | d3ae779 | 2011-02-24 00:21:06 +0000 | [diff] [blame] | 210 | |
| 211 | kLast_BitmapType = kTwoPointRadial_BitmapType |
reed@android.com | f2b98d6 | 2010-12-20 18:26:13 +0000 | [diff] [blame] | 212 | }; |
reed@android.com | 8a1c16f | 2008-12-17 15:59:43 +0000 | [diff] [blame] | 213 | /** Optional methods for shaders that can pretend to be a bitmap/texture |
reed@google.com | 7c2f27d | 2011-03-07 19:29:00 +0000 | [diff] [blame] | 214 | to play along with opengl. Default just returns kNone_BitmapType and |
reed@android.com | f2b98d6 | 2010-12-20 18:26:13 +0000 | [diff] [blame] | 215 | ignores the out parameters. |
| 216 | |
| 217 | @param outTexture if non-NULL will be the bitmap representing the shader |
| 218 | after return. |
| 219 | @param outMatrix if non-NULL will be the matrix to apply to vertices |
| 220 | to access the bitmap after return. |
| 221 | @param xy if non-NULL will be the tile modes that should be |
| 222 | used to access the bitmap after return. |
| 223 | @param twoPointRadialParams Two extra return values needed for two point |
| 224 | radial bitmaps. The first is the x-offset of |
| 225 | the second point and the second is the radius |
| 226 | about the first point. |
reed@android.com | 8a1c16f | 2008-12-17 15:59:43 +0000 | [diff] [blame] | 227 | */ |
reed@android.com | f2b98d6 | 2010-12-20 18:26:13 +0000 | [diff] [blame] | 228 | virtual BitmapType asABitmap(SkBitmap* outTexture, SkMatrix* outMatrix, |
reed@google.com | ad91799 | 2011-04-11 19:01:12 +0000 | [diff] [blame] | 229 | TileMode xy[2], SkScalar* twoPointRadialParams) const; |
reed@android.com | 8a1c16f | 2008-12-17 15:59:43 +0000 | [diff] [blame] | 230 | |
vandebo@chromium.org | d3ae779 | 2011-02-24 00:21:06 +0000 | [diff] [blame] | 231 | /** |
| 232 | * If the shader subclass can be represented as a gradient, asAGradient |
| 233 | * returns the matching GradientType enum (or kNone_GradientType if it |
| 234 | * cannot). Also, if info is not null, asAGradient populates info with |
| 235 | * the relevant (see below) parameters for the gradient. fColorCount |
| 236 | * is both an input and output parameter. On input, it indicates how |
| 237 | * many entries in fColors and fColorOffsets can be used, if they are |
| 238 | * non-NULL. After asAGradient has run, fColorCount indicates how |
| 239 | * many color-offset pairs there are in the gradient. If there is |
| 240 | * insufficient space to store all of the color-offset pairs, fColors |
| 241 | * and fColorOffsets will not be altered. fColorOffsets specifies |
| 242 | * where on the range of 0 to 1 to transition to the given color. |
| 243 | * The meaning of fPoint and fRadius is dependant on the type of gradient. |
| 244 | * |
| 245 | * None: |
| 246 | * info is ignored. |
| 247 | * Color: |
| 248 | * fColorOffsets[0] is meaningless. |
| 249 | * Linear: |
| 250 | * fPoint[0] and fPoint[1] are the end-points of the gradient |
| 251 | * Radial: |
| 252 | * fPoint[0] and fRadius[0] are the center and radius |
| 253 | * Radial2: |
| 254 | * fPoint[0] and fRadius[0] are the center and radius of the 1st circle |
| 255 | * fPoint[1] and fRadius[1] are the center and radius of the 2nd circle |
| 256 | * Sweep: |
| 257 | * fPoint[0] is the center of the sweep. |
| 258 | */ |
| 259 | |
| 260 | enum GradientType { |
| 261 | kNone_GradientType, |
| 262 | kColor_GradientType, |
| 263 | kLinear_GradientType, |
| 264 | kRadial_GradientType, |
| 265 | kRadial2_GradientType, |
| 266 | kSweep_GradientType, |
| 267 | kLast_GradientType = kSweep_GradientType |
| 268 | }; |
| 269 | |
| 270 | struct GradientInfo { |
| 271 | int fColorCount; //!< In-out parameter, specifies passed size |
| 272 | // of fColors/fColorOffsets on input, and |
| 273 | // actual number of colors/offsets on |
| 274 | // output. |
| 275 | SkColor* fColors; //!< The colors in the gradient. |
| 276 | SkScalar* fColorOffsets; //!< The unit offset for color transitions. |
| 277 | SkPoint fPoint[2]; //!< Type specific, see above. |
| 278 | SkScalar fRadius[2]; //!< Type specific, see above. |
| 279 | TileMode fTileMode; //!< The tile mode used. |
| 280 | }; |
| 281 | |
| 282 | virtual GradientType asAGradient(GradientInfo* info) const; |
| 283 | |
reed@android.com | 8a1c16f | 2008-12-17 15:59:43 +0000 | [diff] [blame] | 284 | ////////////////////////////////////////////////////////////////////////// |
| 285 | // Factory methods for stock shaders |
| 286 | |
| 287 | /** Call this to create a new shader that will draw with the specified bitmap. |
| 288 | @param src The bitmap to use inside the shader |
| 289 | @param tmx The tiling mode to use when sampling the bitmap in the x-direction. |
| 290 | @param tmy The tiling mode to use when sampling the bitmap in the y-direction. |
| 291 | @return Returns a new shader object. Note: this function never returns null. |
| 292 | */ |
| 293 | static SkShader* CreateBitmapShader(const SkBitmap& src, |
| 294 | TileMode tmx, TileMode tmy); |
| 295 | |
tomhudson@google.com | 1341304 | 2011-10-03 16:01:10 +0000 | [diff] [blame] | 296 | virtual void flatten(SkFlattenableWriteBuffer& ) SK_OVERRIDE; |
reed@android.com | 8a1c16f | 2008-12-17 15:59:43 +0000 | [diff] [blame] | 297 | protected: |
| 298 | enum MatrixClass { |
| 299 | kLinear_MatrixClass, // no perspective |
| 300 | kFixedStepInX_MatrixClass, // fast perspective, need to call fixedStepInX() each scanline |
| 301 | kPerspective_MatrixClass // slow perspective, need to mappoints each pixel |
| 302 | }; |
| 303 | static MatrixClass ComputeMatrixClass(const SkMatrix&); |
| 304 | |
| 305 | // These can be called by your subclass after setContext() has been called |
| 306 | uint8_t getPaintAlpha() const { return fPaintAlpha; } |
| 307 | SkBitmap::Config getDeviceConfig() const { return (SkBitmap::Config)fDeviceConfig; } |
| 308 | const SkMatrix& getTotalInverse() const { return fTotalInverse; } |
| 309 | MatrixClass getInverseClass() const { return (MatrixClass)fTotalInverseClass; } |
| 310 | |
| 311 | SkShader(SkFlattenableReadBuffer& ); |
| 312 | private: |
| 313 | SkMatrix* fLocalMatrix; |
| 314 | SkMatrix fTotalInverse; |
| 315 | uint8_t fPaintAlpha; |
| 316 | uint8_t fDeviceConfig; |
| 317 | uint8_t fTotalInverseClass; |
| 318 | SkDEBUGCODE(SkBool8 fInSession;) |
| 319 | |
| 320 | static SkShader* CreateBitmapShader(const SkBitmap& src, |
| 321 | TileMode, TileMode, |
| 322 | void* storage, size_t storageSize); |
| 323 | friend class SkAutoBitmapShaderInstall; |
| 324 | typedef SkFlattenable INHERITED; |
| 325 | }; |
| 326 | |
| 327 | #endif |
| 328 | |