src/third_party/skia/include/core/SkShader.h

   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 GrEffect;
  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     protected:
 189         // Reference to shader, so we don't have to dupe information.
 190         const SkShader& fShader;
 191
 192         enum MatrixClass {
 193             kLinear_MatrixClass,            // no perspective
 194             kFixedStepInX_MatrixClass,      // fast perspective, need to call fixedStepInX() each
 195                                             // scanline
 196             kPerspective_MatrixClass        // slow perspective, need to mappoints each pixel
 197         };
 198         static MatrixClass ComputeMatrixClass(const SkMatrix&);
 199
 200         uint8_t         getPaintAlpha() const { return fPaintAlpha; }
 201         const SkMatrix& getTotalInverse() const { return fTotalInverse; }
 202         MatrixClass     getInverseClass() const { return (MatrixClass)fTotalInverseClass; }
 203         const SkMatrix& getCTM() const { return fCTM; }
 204     private:
 205         SkMatrix    fCTM;
 206         SkMatrix    fTotalInverse;
 207         uint8_t     fPaintAlpha;
 208         uint8_t     fTotalInverseClass;
 209
 210         typedef SkNoncopyable INHERITED;
 211     };
 212
 213     /**
 214      *  Create the actual object that does the shading.
 215      *  Size of storage must be >= contextSize.
 216      */
 217     Context* createContext(const ContextRec&, void* storage) const;
 218
 219     /**
 220      *  Return the size of a Context returned by createContext.
 221      *
 222      *  Override this if your subclass overrides createContext, to return the correct size of
 223      *  your subclass' context.
 224      */
 225     virtual size_t contextSize() const;
 226
 227     /**
 228      *  Helper to check the flags to know if it is legal to call shadeSpan16()
 229      */
 230     static bool CanCallShadeSpan16(uint32_t flags) {
 231         return (flags & kHasSpan16_Flag) != 0;
 232     }
 233
 234     /**
 235      Gives method bitmap should be read to implement a shader.
 236      Also determines number and interpretation of "extra" parameters returned
 237      by asABitmap
 238      */
 239     enum BitmapType {
 240         kNone_BitmapType,   //<! Shader is not represented as a bitmap
 241         kDefault_BitmapType,//<! Access bitmap using local coords transformed
 242                             //   by matrix. No extras
 243         kRadial_BitmapType, //<! Access bitmap by transforming local coordinates
 244                             //   by the matrix and taking the distance of result
 245                             //   from  (0,0) as bitmap column. Bitmap is 1 pixel
 246                             //   tall. No extras
 247         kSweep_BitmapType,  //<! Access bitmap by transforming local coordinates
 248                             //   by the matrix and taking the angle of result
 249                             //   to (0,0) as bitmap x coord, where angle = 0 is
 250                             //   bitmap left edge of bitmap = 2pi is the
 251                             //   right edge. Bitmap is 1 pixel tall. No extras
 252         kTwoPointRadial_BitmapType,
 253                             //<! Matrix transforms to space where (0,0) is
 254                             //   the center of the starting circle.  The second
 255                             //   circle will be centered (x, 0) where x  may be
 256                             //   0. The post-matrix space is normalized such
 257                             //   that 1 is the second radius - first radius.
 258                             //   Three extra parameters are returned:
 259                             //      0: x-offset of second circle center
 260                             //         to first.
 261                             //      1: radius of first circle in post-matrix
 262                             //         space
 263                             //      2: the second radius minus the first radius
 264                             //         in pre-transformed space.
 265         kTwoPointConical_BitmapType,
 266                             //<! Matrix transforms to space where (0,0) is
 267                             //   the center of the starting circle.  The second
 268                             //   circle will be centered (x, 0) where x  may be
 269                             //   0.
 270                             //   Three extra parameters are returned:
 271                             //      0: x-offset of second circle center
 272                             //         to first.
 273                             //      1: radius of first circle
 274                             //      2: the second radius minus the first radius
 275         kLinear_BitmapType, //<! Access bitmap using local coords transformed
 276                             //   by matrix. No extras
 277
 278        kLast_BitmapType = kLinear_BitmapType
 279     };
 280     /** Optional methods for shaders that can pretend to be a bitmap/texture
 281         to play along with opengl. Default just returns kNone_BitmapType and
 282         ignores the out parameters.
 283
 284         @param outTexture if non-NULL will be the bitmap representing the shader
 285                           after return.
 286         @param outMatrix  if non-NULL will be the matrix to apply to vertices
 287                           to access the bitmap after return.
 288         @param xy         if non-NULL will be the tile modes that should be
 289                           used to access the bitmap after return.
 290         @param twoPointRadialParams Two extra return values needed for two point
 291                                     radial bitmaps. The first is the x-offset of
 292                                     the second point and the second is the radius
 293                                     about the first point.
 294     */
 295     virtual BitmapType asABitmap(SkBitmap* outTexture, SkMatrix* outMatrix,
 296                          TileMode xy[2]) const;
 297
 298     /**
 299      *  If the shader subclass can be represented as a gradient, asAGradient
 300      *  returns the matching GradientType enum (or kNone_GradientType if it
 301      *  cannot). Also, if info is not null, asAGradient populates info with
 302      *  the relevant (see below) parameters for the gradient.  fColorCount
 303      *  is both an input and output parameter.  On input, it indicates how
 304      *  many entries in fColors and fColorOffsets can be used, if they are
 305      *  non-NULL.  After asAGradient has run, fColorCount indicates how
 306      *  many color-offset pairs there are in the gradient.  If there is
 307      *  insufficient space to store all of the color-offset pairs, fColors
 308      *  and fColorOffsets will not be altered.  fColorOffsets specifies
 309      *  where on the range of 0 to 1 to transition to the given color.
 310      *  The meaning of fPoint and fRadius is dependant on the type of gradient.
 311      *
 312      *  None:
 313      *      info is ignored.
 314      *  Color:
 315      *      fColorOffsets[0] is meaningless.
 316      *  Linear:
 317      *      fPoint[0] and fPoint[1] are the end-points of the gradient
 318      *  Radial:
 319      *      fPoint[0] and fRadius[0] are the center and radius
 320      *  Radial2:
 321      *      fPoint[0] and fRadius[0] are the center and radius of the 1st circle
 322      *      fPoint[1] and fRadius[1] are the center and radius of the 2nd circle
 323      *  Sweep:
 324      *      fPoint[0] is the center of the sweep.
 325      */
 326
 327     enum GradientType {
 328         kNone_GradientType,
 329         kColor_GradientType,
 330         kLinear_GradientType,
 331         kRadial_GradientType,
 332         kRadial2_GradientType,
 333         kSweep_GradientType,
 334         kConical_GradientType,
 335         kLast_GradientType = kConical_GradientType
 336     };
 337
 338     struct GradientInfo {
 339         int         fColorCount;    //!< In-out parameter, specifies passed size
 340                                     //   of fColors/fColorOffsets on input, and
 341                                     //   actual number of colors/offsets on
 342                                     //   output.
 343         SkColor*    fColors;        //!< The colors in the gradient.
 344         SkScalar*   fColorOffsets;  //!< The unit offset for color transitions.
 345         SkPoint     fPoint[2];      //!< Type specific, see above.
 346         SkScalar    fRadius[2];     //!< Type specific, see above.
 347         TileMode    fTileMode;      //!< The tile mode used.
 348         uint32_t    fGradientFlags; //!< see SkGradientShader::Flags
 349     };
 350
 351     virtual GradientType asAGradient(GradientInfo* info) const;
 352
 353     /**
 354      *  If the shader subclass is composed of two shaders, return true, and if rec is not NULL,
 355      *  fill it out with info about the shader.
 356      *
 357      *  These are bare pointers; the ownership and reference count are unchanged.
 358      */
 359
 360     struct ComposeRec {
 361         const SkShader*     fShaderA;
 362         const SkShader*     fShaderB;
 363         const SkXfermode*   fMode;
 364     };
 365
 366     virtual bool asACompose(ComposeRec* rec) const { return false; }
 367
 368
 369     /**
 370      *  Returns true if the shader subclass succeeds in creating an effect or if none is required.
 371      *  False is returned if it fails or if there is not an implementation of this method in the
 372      *  shader subclass.
 373      *
 374      *  On success an implementation of this method must inspect the SkPaint and set paintColor to
 375      *  the color the effect expects as its input color. If the SkShader wishes to emit a solid
 376      *  color then it should set paintColor to that color and not create an effect. Note that
 377      *  GrColor is always premul. The common patterns are to convert paint's SkColor to GrColor or
 378      *  to extract paint's alpha and replicate it to all channels in paintColor. Upon failure
 379      *  paintColor should not be modified. It is not recommended to specialize the effect to
 380      *  the paint's color as then many GPU shaders may be generated.
 381      *
 382      *  The GrContext may be used by the effect to create textures. The GPU device does not
 383      *  call createContext. Instead we pass the SkPaint here in case the shader needs paint info.
 384      */
 385     virtual bool asNewEffect(GrContext* context, const SkPaint& paint,
 386                              const SkMatrix* localMatrixOrNull, GrColor* paintColor,
 387                              GrEffect** effect) const;
 388
 389 #ifdef SK_BUILD_FOR_ANDROID_FRAMEWORK
 390     /**
 391      *  If the shader is a custom shader which has data the caller might want, call this function
 392      *  to get that data.
 393      */
 394     virtual bool asACustomShader(void** customData) const { return false; }
 395 #endif
 396
 397     //////////////////////////////////////////////////////////////////////////
 398     //  Factory methods for stock shaders
 399
 400     /**
 401      *  Call this to create a new "empty" shader, that will not draw anything.
 402      */
 403     static SkShader* CreateEmptyShader();
 404
 405     /** Call this to create a new shader that will draw with the specified bitmap.
 406      *
 407      *  If the bitmap cannot be used (e.g. has no pixels, or its dimensions
 408      *  exceed implementation limits (currently at 64K - 1)) then SkEmptyShader
 409      *  may be returned.
 410      *
 411      *  If the src is kA8_Config then that mask will be colorized using the color on
 412      *  the paint.
 413      *
 414      *  @param src  The bitmap to use inside the shader
 415      *  @param tmx  The tiling mode to use when sampling the bitmap in the x-direction.
 416      *  @param tmy  The tiling mode to use when sampling the bitmap in the y-direction.
 417      *  @return     Returns a new shader object. Note: this function never returns null.
 418     */
 419     static SkShader* CreateBitmapShader(const SkBitmap& src,
 420                                         TileMode tmx, TileMode tmy,
 421                                         const SkMatrix* localMatrix = NULL);
 422
 423     /** Call this to create a new shader that will draw with the specified picture.
 424      *
 425      *  @param src  The picture to use inside the shader (if not NULL, its ref count
 426      *              is incremented). The SkPicture must not be changed after
 427      *              successfully creating a picture shader.
 428      *              FIXME: src cannot be const due to SkCanvas::drawPicture
 429      *  @param tmx  The tiling mode to use when sampling the bitmap in the x-direction.
 430      *  @param tmy  The tiling mode to use when sampling the bitmap in the y-direction.
 431      *  @param tile The tile rectangle in picture coordinates: this represents the subset
 432      *              (or superset) of the picture used when building a tile. It is not
 433      *              affected by localMatrix and does not imply scaling (only translation
 434      *              and cropping). If null, the tile rect is considered equal to the picture
 435      *              bounds.
 436      *  @return     Returns a new shader object. Note: this function never returns null.
 437     */
 438     static SkShader* CreatePictureShader(SkPicture* src,
 439                                          TileMode tmx, TileMode tmy,
 440                                          const SkMatrix* localMatrix,
 441                                          const SkRect* tile);
 442
 443     /**
 444      *  Return a shader that will apply the specified localMatrix to the proxy shader.
 445      *  The specified matrix will be applied before any matrix associated with the proxy.
 446      *
 447      *  Note: ownership of the proxy is not transferred (though a ref is taken).
 448      */
 449     static SkShader* CreateLocalMatrixShader(SkShader* proxy, const SkMatrix& localMatrix);
 450
 451     /**
 452      *  If this shader can be represented by another shader + a localMatrix, return that shader
 453      *  and, if not NULL, the localMatrix. If not, return NULL and ignore the localMatrix parameter.
 454      *
 455      *  Note: the returned shader (if not NULL) will have been ref'd, and it is the responsibility
 456      *  of the caller to balance that with unref() when they are done.
 457      */
 458     virtual SkShader* refAsALocalMatrixShader(SkMatrix* localMatrix) const;
 459
 460     SK_TO_STRING_VIRT()
 461     SK_DEFINE_FLATTENABLE_TYPE(SkShader)
 462
 463 protected:
 464     SkShader(SkReadBuffer& );
 465     virtual void flatten(SkWriteBuffer&) const SK_OVERRIDE;
 466
 467     bool computeTotalInverse(const ContextRec&, SkMatrix* totalInverse) const;
 468
 469     /**
 470      *  Your subclass must also override contextSize() if it overrides onCreateContext().
 471      *  Base class impl returns NULL.
 472      */
 473     virtual Context* onCreateContext(const ContextRec&, void* storage) const;
 474
 475 private:
 476     // This is essentially const, but not officially so it can be modified in
 477     // constructors.
 478     SkMatrix fLocalMatrix;
 479
 480     // So the SkLocalMatrixShader can whack fLocalMatrix in its SkReadBuffer constructor.
 481     friend class SkLocalMatrixShader;
 482
 483     typedef SkFlattenable INHERITED;
 484 };
 485
 486 #endif