1 /* 2 * Copyright 2006 The Android Open Source Project 3 * 4 * Use of this source code is governed by a BSD-style license that can be 5 * found in the LICENSE file. 6 */ 7 8 9 #ifndef SkShader_DEFINED 10 #define SkShader_DEFINED 11 12 #include "SkBitmap.h" 13 #include "SkFlattenable.h" 14 #include "SkMask.h" 15 #include "SkMatrix.h" 16 #include "SkPaint.h" 17 #include "../gpu/GrColor.h" 18 19 class SkPath; 20 class SkPicture; 21 class SkXfermode; 22 class GrContext; 23 class GrFragmentProcessor; 24 25 /** \class SkShader 26 * 27 * Shaders specify the source color(s) for what is being drawn. If a paint 28 * has no shader, then the paint's color is used. If the paint has a 29 * shader, then the shader's color(s) are use instead, but they are 30 * modulated by the paint's alpha. This makes it easy to create a shader 31 * once (e.g. bitmap tiling or gradient) and then change its transparency 32 * w/o having to modify the original shader... only the paint's alpha needs 33 * to be modified. 34 */ 35 class SK_API SkShader : public SkFlattenable { 36 public: 37 SK_DECLARE_INST_COUNT(SkShader) 38 39 SkShader(const SkMatrix* localMatrix = NULL); 40 virtual ~SkShader(); 41 42 /** 43 * Returns the local matrix. 44 * 45 * FIXME: This can be incorrect for a Shader with its own local matrix 46 * that is also wrapped via CreateLocalMatrixShader. 47 */ 48 const SkMatrix& getLocalMatrix() const { return fLocalMatrix; } 49 50 /** 51 * Returns true if the local matrix is not an identity matrix. 52 * 53 * FIXME: This can be incorrect for a Shader with its own local matrix 54 * that is also wrapped via CreateLocalMatrixShader. 55 */ 56 bool hasLocalMatrix() const { return !fLocalMatrix.isIdentity(); } 57 58 enum TileMode { 59 /** replicate the edge color if the shader draws outside of its 60 * original bounds 61 */ 62 kClamp_TileMode, 63 64 /** repeat the shader's image horizontally and vertically */ 65 kRepeat_TileMode, 66 67 /** repeat the shader's image horizontally and vertically, alternating 68 * mirror images so that adjacent images always seam 69 */ 70 kMirror_TileMode, 71 72 #if 0 73 /** only draw within the original domain, return 0 everywhere else */ 74 kDecal_TileMode, 75 #endif 76 77 kTileModeCount 78 }; 79 80 // override these in your subclass 81 82 enum Flags { 83 //!< set if all of the colors will be opaque 84 kOpaqueAlpha_Flag = 0x01, 85 86 //! set if this shader's shadeSpan16() method can be called 87 kHasSpan16_Flag = 0x02, 88 89 /** Set this bit if the shader's native data type is instrinsically 16 90 bit, meaning that calling the 32bit shadeSpan() entry point will 91 mean the the impl has to up-sample 16bit data into 32bit. Used as a 92 a means of clearing a dither request if the it will have no effect 93 */ 94 kIntrinsicly16_Flag = 0x04, 95 96 /** set if the spans only vary in X (const in Y). 97 e.g. an Nx1 bitmap that is being tiled in Y, or a linear-gradient 98 that varies from left-to-right. This flag specifies this for 99 shadeSpan(). 100 */ 101 kConstInY32_Flag = 0x08, 102 103 /** same as kConstInY32_Flag, but is set if this is true for shadeSpan16 104 which may not always be the case, since shadeSpan16 may be 105 predithered, which would mean it was not const in Y, even though 106 the 32bit shadeSpan() would be const. 107 */ 108 kConstInY16_Flag = 0x10 109 }; 110 111 /** 112 * Returns true if the shader is guaranteed to produce only opaque 113 * colors, subject to the SkPaint using the shader to apply an opaque 114 * alpha value. Subclasses should override this to allow some 115 * optimizations. 116 */ 117 virtual bool isOpaque() const { return false; } 118 119 /** 120 * ContextRec acts as a parameter bundle for creating Contexts. 121 */ 122 struct ContextRec { 123 ContextRec() : fDevice(NULL), fPaint(NULL), fMatrix(NULL), fLocalMatrix(NULL) {} 124 ContextRec(const SkBitmap& device, const SkPaint& paint, const SkMatrix& matrix) 125 : fDevice(&device) 126 , fPaint(&paint) 127 , fMatrix(&matrix) 128 , fLocalMatrix(NULL) {} 129 130 const SkBitmap* fDevice; // the bitmap we are drawing into 131 const SkPaint* fPaint; // the current paint associated with the draw 132 const SkMatrix* fMatrix; // the current matrix in the canvas 133 const SkMatrix* fLocalMatrix; // optional local matrix 134 }; 135 136 class Context : public ::SkNoncopyable { 137 public: 138 Context(const SkShader& shader, const ContextRec&); 139 140 virtual ~Context(); 141 142 /** 143 * Called sometimes before drawing with this shader. Return the type of 144 * alpha your shader will return. The default implementation returns 0. 145 * Your subclass should override if it can (even sometimes) report a 146 * non-zero value, since that will enable various blitters to perform 147 * faster. 148 */ 149 virtual uint32_t getFlags() const { return 0; } 150 151 /** 152 * Return the alpha associated with the data returned by shadeSpan16(). If 153 * kHasSpan16_Flag is not set, this value is meaningless. 154 */ 155 virtual uint8_t getSpan16Alpha() const { return fPaintAlpha; } 156 157 /** 158 * Called for each span of the object being drawn. Your subclass should 159 * set the appropriate colors (with premultiplied alpha) that correspond 160 * to the specified device coordinates. 161 */ 162 virtual void shadeSpan(int x, int y, SkPMColor[], int count) = 0; 163 164 typedef void (*ShadeProc)(void* ctx, int x, int y, SkPMColor[], int count); 165 virtual ShadeProc asAShadeProc(void** ctx); 166 167 /** 168 * Called only for 16bit devices when getFlags() returns 169 * kOpaqueAlphaFlag | kHasSpan16_Flag 170 */ 171 virtual void shadeSpan16(int x, int y, uint16_t[], int count); 172 173 /** 174 * Similar to shadeSpan, but only returns the alpha-channel for a span. 175 * The default implementation calls shadeSpan() and then extracts the alpha 176 * values from the returned colors. 177 */ 178 virtual void shadeSpanAlpha(int x, int y, uint8_t alpha[], int count); 179 180 /** 181 * Helper function that returns true if this shader's shadeSpan16() method 182 * can be called. 183 */ 184 bool canCallShadeSpan16() { 185 return SkShader::CanCallShadeSpan16(this->getFlags()); 186 } 187 188 // Notification from blitter::blitMask in case we need to see the non-alpha channels 189 virtual void set3DMask(const SkMask*) {} 190 191 protected: 192 // Reference to shader, so we don't have to dupe information. 193 const SkShader& fShader; 194 195 enum MatrixClass { 196 kLinear_MatrixClass, // no perspective 197 kFixedStepInX_MatrixClass, // fast perspective, need to call fixedStepInX() each 198 // scanline 199 kPerspective_MatrixClass // slow perspective, need to mappoints each pixel 200 }; 201 static MatrixClass ComputeMatrixClass(const SkMatrix&); 202 203 uint8_t getPaintAlpha() const { return fPaintAlpha; } 204 const SkMatrix& getTotalInverse() const { return fTotalInverse; } 205 MatrixClass getInverseClass() const { return (MatrixClass)fTotalInverseClass; } 206 const SkMatrix& getCTM() const { return fCTM; } 207 private: 208 SkMatrix fCTM; 209 SkMatrix fTotalInverse; 210 uint8_t fPaintAlpha; 211 uint8_t fTotalInverseClass; 212 213 typedef SkNoncopyable INHERITED; 214 }; 215 216 /** 217 * Create the actual object that does the shading. 218 * Size of storage must be >= contextSize. 219 */ 220 Context* createContext(const ContextRec&, void* storage) const; 221 222 /** 223 * Return the size of a Context returned by createContext. 224 * 225 * Override this if your subclass overrides createContext, to return the correct size of 226 * your subclass' context. 227 */ 228 virtual size_t contextSize() const; 229 230 /** 231 * Helper to check the flags to know if it is legal to call shadeSpan16() 232 */ 233 static bool CanCallShadeSpan16(uint32_t flags) { 234 return (flags & kHasSpan16_Flag) != 0; 235 } 236 237 /** 238 Gives method bitmap should be read to implement a shader. 239 Also determines number and interpretation of "extra" parameters returned 240 by asABitmap 241 */ 242 enum BitmapType { 243 kNone_BitmapType, //<! Shader is not represented as a bitmap 244 kDefault_BitmapType,//<! Access bitmap using local coords transformed 245 // by matrix. No extras 246 kRadial_BitmapType, //<! Access bitmap by transforming local coordinates 247 // by the matrix and taking the distance of result 248 // from (0,0) as bitmap column. Bitmap is 1 pixel 249 // tall. No extras 250 kSweep_BitmapType, //<! Access bitmap by transforming local coordinates 251 // by the matrix and taking the angle of result 252 // to (0,0) as bitmap x coord, where angle = 0 is 253 // bitmap left edge of bitmap = 2pi is the 254 // right edge. Bitmap is 1 pixel tall. No extras 255 kTwoPointRadial_BitmapType, 256 //<! Matrix transforms to space where (0,0) is 257 // the center of the starting circle. The second 258 // circle will be centered (x, 0) where x may be 259 // 0. The post-matrix space is normalized such 260 // that 1 is the second radius - first radius. 261 // Three extra parameters are returned: 262 // 0: x-offset of second circle center 263 // to first. 264 // 1: radius of first circle in post-matrix 265 // space 266 // 2: the second radius minus the first radius 267 // in pre-transformed space. 268 kTwoPointConical_BitmapType, 269 //<! Matrix transforms to space where (0,0) is 270 // the center of the starting circle. The second 271 // circle will be centered (x, 0) where x may be 272 // 0. 273 // Three extra parameters are returned: 274 // 0: x-offset of second circle center 275 // to first. 276 // 1: radius of first circle 277 // 2: the second radius minus the first radius 278 kLinear_BitmapType, //<! Access bitmap using local coords transformed 279 // by matrix. No extras 280 281 kLast_BitmapType = kLinear_BitmapType 282 }; 283 /** Optional methods for shaders that can pretend to be a bitmap/texture 284 to play along with opengl. Default just returns kNone_BitmapType and 285 ignores the out parameters. 286 287 @param outTexture if non-NULL will be the bitmap representing the shader 288 after return. 289 @param outMatrix if non-NULL will be the matrix to apply to vertices 290 to access the bitmap after return. 291 @param xy if non-NULL will be the tile modes that should be 292 used to access the bitmap after return. 293 @param twoPointRadialParams Two extra return values needed for two point 294 radial bitmaps. The first is the x-offset of 295 the second point and the second is the radius 296 about the first point. 297 */ 298 virtual BitmapType asABitmap(SkBitmap* outTexture, SkMatrix* outMatrix, 299 TileMode xy[2]) const; 300 301 /** 302 * If the shader subclass can be represented as a gradient, asAGradient 303 * returns the matching GradientType enum (or kNone_GradientType if it 304 * cannot). Also, if info is not null, asAGradient populates info with 305 * the relevant (see below) parameters for the gradient. fColorCount 306 * is both an input and output parameter. On input, it indicates how 307 * many entries in fColors and fColorOffsets can be used, if they are 308 * non-NULL. After asAGradient has run, fColorCount indicates how 309 * many color-offset pairs there are in the gradient. If there is 310 * insufficient space to store all of the color-offset pairs, fColors 311 * and fColorOffsets will not be altered. fColorOffsets specifies 312 * where on the range of 0 to 1 to transition to the given color. 313 * The meaning of fPoint and fRadius is dependant on the type of gradient. 314 * 315 * None: 316 * info is ignored. 317 * Color: 318 * fColorOffsets[0] is meaningless. 319 * Linear: 320 * fPoint[0] and fPoint[1] are the end-points of the gradient 321 * Radial: 322 * fPoint[0] and fRadius[0] are the center and radius 323 * Radial2: 324 * fPoint[0] and fRadius[0] are the center and radius of the 1st circle 325 * fPoint[1] and fRadius[1] are the center and radius of the 2nd circle 326 * Sweep: 327 * fPoint[0] is the center of the sweep. 328 */ 329 330 enum GradientType { 331 kNone_GradientType, 332 kColor_GradientType, 333 kLinear_GradientType, 334 kRadial_GradientType, 335 kRadial2_GradientType, 336 kSweep_GradientType, 337 kConical_GradientType, 338 kLast_GradientType = kConical_GradientType 339 }; 340 341 struct GradientInfo { 342 int fColorCount; //!< In-out parameter, specifies passed size 343 // of fColors/fColorOffsets on input, and 344 // actual number of colors/offsets on 345 // output. 346 SkColor* fColors; //!< The colors in the gradient. 347 SkScalar* fColorOffsets; //!< The unit offset for color transitions. 348 SkPoint fPoint[2]; //!< Type specific, see above. 349 SkScalar fRadius[2]; //!< Type specific, see above. 350 TileMode fTileMode; //!< The tile mode used. 351 uint32_t fGradientFlags; //!< see SkGradientShader::Flags 352 }; 353 354 virtual GradientType asAGradient(GradientInfo* info) const; 355 356 /** 357 * If the shader subclass is composed of two shaders, return true, and if rec is not NULL, 358 * fill it out with info about the shader. 359 * 360 * These are bare pointers; the ownership and reference count are unchanged. 361 */ 362 363 struct ComposeRec { 364 const SkShader* fShaderA; 365 const SkShader* fShaderB; 366 const SkXfermode* fMode; 367 }; 368 369 virtual bool asACompose(ComposeRec* rec) const { return false; } 370 371 372 /** 373 * Returns true if the shader subclass succeeds in creating an effect or if none is required. 374 * False is returned if it fails or if there is not an implementation of this method in the 375 * shader subclass. 376 * 377 * On success an implementation of this method must inspect the SkPaint and set paintColor to 378 * the color the effect expects as its input color. If the SkShader wishes to emit a solid 379 * color then it should set paintColor to that color and not create an effect. Note that 380 * GrColor is always premul. The common patterns are to convert paint's SkColor to GrColor or 381 * to extract paint's alpha and replicate it to all channels in paintColor. Upon failure 382 * paintColor should not be modified. It is not recommended to specialize the effect to 383 * the paint's color as then many GPU shaders may be generated. 384 * 385 * The GrContext may be used by the effect to create textures. The GPU device does not 386 * call createContext. Instead we pass the SkPaint here in case the shader needs paint info. 387 */ 388 virtual bool asFragmentProcessor(GrContext*, const SkPaint&, const SkMatrix*, GrColor*, 389 GrFragmentProcessor**) const; 390 391 /** 392 * If the shader can represent its "average" luminance in a single color, return true and 393 * if color is not NULL, return that color. If it cannot, return false and ignore the color 394 * parameter. 395 * 396 * Note: if this returns true, the returned color will always be opaque, as only the RGB 397 * components are used to compute luminance. 398 */ 399 bool asLuminanceColor(SkColor*) const; 400 401 #ifdef SK_BUILD_FOR_ANDROID_FRAMEWORK 402 /** 403 * If the shader is a custom shader which has data the caller might want, call this function 404 * to get that data. 405 */ 406 virtual bool asACustomShader(void** customData) const { return false; } 407 #endif 408 409 ////////////////////////////////////////////////////////////////////////// 410 // Factory methods for stock shaders 411 412 /** 413 * Call this to create a new "empty" shader, that will not draw anything. 414 */ 415 static SkShader* CreateEmptyShader(); 416 417 /** 418 * Call this to create a new shader that just draws the specified color. This should always 419 * draw the same as a paint with this color (and no shader). 420 */ 421 static SkShader* CreateColorShader(SkColor); 422 423 /** Call this to create a new shader that will draw with the specified bitmap. 424 * 425 * If the bitmap cannot be used (e.g. has no pixels, or its dimensions 426 * exceed implementation limits (currently at 64K - 1)) then SkEmptyShader 427 * may be returned. 428 * 429 * If the src is kA8_Config then that mask will be colorized using the color on 430 * the paint. 431 * 432 * @param src The bitmap to use inside the shader 433 * @param tmx The tiling mode to use when sampling the bitmap in the x-direction. 434 * @param tmy The tiling mode to use when sampling the bitmap in the y-direction. 435 * @return Returns a new shader object. Note: this function never returns null. 436 */ 437 static SkShader* CreateBitmapShader(const SkBitmap& src, 438 TileMode tmx, TileMode tmy, 439 const SkMatrix* localMatrix = NULL); 440 441 /** Call this to create a new shader that will draw with the specified picture. 442 * 443 * @param src The picture to use inside the shader (if not NULL, its ref count 444 * is incremented). The SkPicture must not be changed after 445 * successfully creating a picture shader. 446 * FIXME: src cannot be const due to SkCanvas::drawPicture 447 * @param tmx The tiling mode to use when sampling the bitmap in the x-direction. 448 * @param tmy The tiling mode to use when sampling the bitmap in the y-direction. 449 * @param tile The tile rectangle in picture coordinates: this represents the subset 450 * (or superset) of the picture used when building a tile. It is not 451 * affected by localMatrix and does not imply scaling (only translation 452 * and cropping). If null, the tile rect is considered equal to the picture 453 * bounds. 454 * @return Returns a new shader object. Note: this function never returns null. 455 */ 456 static SkShader* CreatePictureShader(SkPicture* src, 457 TileMode tmx, TileMode tmy, 458 const SkMatrix* localMatrix, 459 const SkRect* tile); 460 461 /** 462 * Return a shader that will apply the specified localMatrix to the proxy shader. 463 * The specified matrix will be applied before any matrix associated with the proxy. 464 * 465 * Note: ownership of the proxy is not transferred (though a ref is taken). 466 */ 467 static SkShader* CreateLocalMatrixShader(SkShader* proxy, const SkMatrix& localMatrix); 468 469 /** 470 * If this shader can be represented by another shader + a localMatrix, return that shader 471 * and, if not NULL, the localMatrix. If not, return NULL and ignore the localMatrix parameter. 472 * 473 * Note: the returned shader (if not NULL) will have been ref'd, and it is the responsibility 474 * of the caller to balance that with unref() when they are done. 475 */ 476 virtual SkShader* refAsALocalMatrixShader(SkMatrix* localMatrix) const; 477 478 SK_TO_STRING_VIRT() 479 SK_DEFINE_FLATTENABLE_TYPE(SkShader) 480 481 protected: 482 #ifdef SK_SUPPORT_LEGACY_DEEPFLATTENING 483 SkShader(SkReadBuffer& ); 484 #endif 485 virtual void flatten(SkWriteBuffer&) const SK_OVERRIDE; 486 487 bool computeTotalInverse(const ContextRec&, SkMatrix* totalInverse) const; 488 489 /** 490 * Your subclass must also override contextSize() if it overrides onCreateContext(). 491 * Base class impl returns NULL. 492 */ 493 virtual Context* onCreateContext(const ContextRec&, void* storage) const; 494 495 virtual bool onAsLuminanceColor(SkColor*) const { 496 return false; 497 } 498 private: 499 // This is essentially const, but not officially so it can be modified in 500 // constructors. 501 SkMatrix fLocalMatrix; 502 503 // So the SkLocalMatrixShader can whack fLocalMatrix in its SkReadBuffer constructor. 504 friend class SkLocalMatrixShader; 505 506 typedef SkFlattenable INHERITED; 507 }; 508 509 #endif 510
