michael@0: /*
michael@0:  * Copyright 2006 The Android Open Source Project
michael@0:  *
michael@0:  * Use of this source code is governed by a BSD-style license that can be
michael@0:  * found in the LICENSE file.
michael@0:  */
michael@0: 
michael@0: 
michael@0: #ifndef SkShader_DEFINED
michael@0: #define SkShader_DEFINED
michael@0: 
michael@0: #include "SkBitmap.h"
michael@0: #include "SkFlattenable.h"
michael@0: #include "SkMask.h"
michael@0: #include "SkMatrix.h"
michael@0: #include "SkPaint.h"
michael@0: 
michael@0: class SkPath;
michael@0: class GrContext;
michael@0: class GrEffectRef;
michael@0: 
michael@0: /** \class SkShader
michael@0:  *
michael@0:  *  Shaders specify the source color(s) for what is being drawn. If a paint
michael@0:  *  has no shader, then the paint's color is used. If the paint has a
michael@0:  *  shader, then the shader's color(s) are use instead, but they are
michael@0:  *  modulated by the paint's alpha. This makes it easy to create a shader
michael@0:  *  once (e.g. bitmap tiling or gradient) and then change its transparency
michael@0:  *  w/o having to modify the original shader... only the paint's alpha needs
michael@0:  *  to be modified.
michael@0:  */
michael@0: class SK_API SkShader : public SkFlattenable {
michael@0: public:
michael@0:     SK_DECLARE_INST_COUNT(SkShader)
michael@0: 
michael@0:     SkShader();
michael@0:     virtual ~SkShader();
michael@0: 
michael@0:     /**
michael@0:      * Returns true if the local matrix is not an identity matrix.
michael@0:      */
michael@0:     bool hasLocalMatrix() const { return !fLocalMatrix.isIdentity(); }
michael@0: 
michael@0:     /**
michael@0:      *  Returns the local matrix.
michael@0:      */
michael@0:     const SkMatrix& getLocalMatrix() const { return fLocalMatrix; }
michael@0: 
michael@0:     /**
michael@0:      *  Set the shader's local matrix.
michael@0:      *  @param localM   The shader's new local matrix.
michael@0:      */
michael@0:     void setLocalMatrix(const SkMatrix& localM) { fLocalMatrix = localM; }
michael@0: 
michael@0:     /**
michael@0:      *  Reset the shader's local matrix to identity.
michael@0:      */
michael@0:     void resetLocalMatrix() { fLocalMatrix.reset(); }
michael@0: 
michael@0:     enum TileMode {
michael@0:         /** replicate the edge color if the shader draws outside of its
michael@0:          *  original bounds
michael@0:          */
michael@0:         kClamp_TileMode,
michael@0: 
michael@0:         /** repeat the shader's image horizontally and vertically */
michael@0:         kRepeat_TileMode,
michael@0: 
michael@0:         /** repeat the shader's image horizontally and vertically, alternating
michael@0:          *  mirror images so that adjacent images always seam
michael@0:          */
michael@0:         kMirror_TileMode,
michael@0: 
michael@0: #if 0
michael@0:         /** only draw within the original domain, return 0 everywhere else */
michael@0:         kDecal_TileMode,
michael@0: #endif
michael@0: 
michael@0:         kTileModeCount
michael@0:     };
michael@0: 
michael@0:     // override these in your subclass
michael@0: 
michael@0:     enum Flags {
michael@0:         //!< set if all of the colors will be opaque
michael@0:         kOpaqueAlpha_Flag  = 0x01,
michael@0: 
michael@0:         //! set if this shader's shadeSpan16() method can be called
michael@0:         kHasSpan16_Flag = 0x02,
michael@0: 
michael@0:         /** Set this bit if the shader's native data type is instrinsically 16
michael@0:             bit, meaning that calling the 32bit shadeSpan() entry point will
michael@0:             mean the the impl has to up-sample 16bit data into 32bit. Used as a
michael@0:             a means of clearing a dither request if the it will have no effect
michael@0:         */
michael@0:         kIntrinsicly16_Flag = 0x04,
michael@0: 
michael@0:         /** set (after setContext) if the spans only vary in X (const in Y).
michael@0:             e.g. an Nx1 bitmap that is being tiled in Y, or a linear-gradient
michael@0:             that varies from left-to-right. This flag specifies this for
michael@0:             shadeSpan().
michael@0:          */
michael@0:         kConstInY32_Flag = 0x08,
michael@0: 
michael@0:         /** same as kConstInY32_Flag, but is set if this is true for shadeSpan16
michael@0:             which may not always be the case, since shadeSpan16 may be
michael@0:             predithered, which would mean it was not const in Y, even though
michael@0:             the 32bit shadeSpan() would be const.
michael@0:          */
michael@0:         kConstInY16_Flag = 0x10
michael@0:     };
michael@0: 
michael@0:     /**
michael@0:      *  Called sometimes before drawing with this shader. Return the type of
michael@0:      *  alpha your shader will return. The default implementation returns 0.
michael@0:      *  Your subclass should override if it can (even sometimes) report a
michael@0:      *  non-zero value, since that will enable various blitters to perform
michael@0:      *  faster.
michael@0:      */
michael@0:     virtual uint32_t getFlags() { return 0; }
michael@0: 
michael@0:     /**
michael@0:      *  Returns true if the shader is guaranteed to produce only opaque
michael@0:      *  colors, subject to the SkPaint using the shader to apply an opaque
michael@0:      *  alpha value. Subclasses should override this to allow some
michael@0:      *  optimizations.  isOpaque() can be called at any time, unlike getFlags,
michael@0:      *  which only works properly when the context is set.
michael@0:      */
michael@0:     virtual bool isOpaque() const { return false; }
michael@0: 
michael@0:     /**
michael@0:      *  Return the alpha associated with the data returned by shadeSpan16(). If
michael@0:      *  kHasSpan16_Flag is not set, this value is meaningless.
michael@0:      */
michael@0:     virtual uint8_t getSpan16Alpha() const { return fPaintAlpha; }
michael@0: 
michael@0:     /**
michael@0:      *  Called once before drawing, with the current paint and device matrix.
michael@0:      *  Return true if your shader supports these parameters, or false if not.
michael@0:      *  If false is returned, nothing will be drawn. If true is returned, then
michael@0:      *  a balancing call to endContext() will be made before the next call to
michael@0:      *  setContext.
michael@0:      *
michael@0:      *  Subclasses should be sure to call their INHERITED::setContext() if they
michael@0:      *  override this method.
michael@0:      */
michael@0:     virtual bool setContext(const SkBitmap& device, const SkPaint& paint,
michael@0:                             const SkMatrix& matrix);
michael@0: 
michael@0:     /**
michael@0:      *  Assuming setContext returned true, endContext() will be called when
michael@0:      *  the draw using the shader has completed. It is an error for setContext
michael@0:      *  to be called twice w/o an intervening call to endContext().
michael@0:      *
michael@0:      *  Subclasses should be sure to call their INHERITED::endContext() if they
michael@0:      *  override this method.
michael@0:      */
michael@0:     virtual void endContext();
michael@0: 
michael@0:     SkDEBUGCODE(bool setContextHasBeenCalled() const { return SkToBool(fInSetContext); })
michael@0: 
michael@0:     /**
michael@0:      *  Called for each span of the object being drawn. Your subclass should
michael@0:      *  set the appropriate colors (with premultiplied alpha) that correspond
michael@0:      *  to the specified device coordinates.
michael@0:      */
michael@0:     virtual void shadeSpan(int x, int y, SkPMColor[], int count) = 0;
michael@0: 
michael@0:     typedef void (*ShadeProc)(void* ctx, int x, int y, SkPMColor[], int count);
michael@0:     virtual ShadeProc asAShadeProc(void** ctx);
michael@0: 
michael@0:     /**
michael@0:      *  Called only for 16bit devices when getFlags() returns
michael@0:      *  kOpaqueAlphaFlag | kHasSpan16_Flag
michael@0:      */
michael@0:     virtual void shadeSpan16(int x, int y, uint16_t[], int count);
michael@0: 
michael@0:     /**
michael@0:      *  Similar to shadeSpan, but only returns the alpha-channel for a span.
michael@0:      *  The default implementation calls shadeSpan() and then extracts the alpha
michael@0:      *  values from the returned colors.
michael@0:      */
michael@0:     virtual void shadeSpanAlpha(int x, int y, uint8_t alpha[], int count);
michael@0: 
michael@0:     /**
michael@0:      *  Helper function that returns true if this shader's shadeSpan16() method
michael@0:      *  can be called.
michael@0:      */
michael@0:     bool canCallShadeSpan16() {
michael@0:         return SkShader::CanCallShadeSpan16(this->getFlags());
michael@0:     }
michael@0: 
michael@0:     /**
michael@0:      *  Helper to check the flags to know if it is legal to call shadeSpan16()
michael@0:      */
michael@0:     static bool CanCallShadeSpan16(uint32_t flags) {
michael@0:         return (flags & kHasSpan16_Flag) != 0;
michael@0:     }
michael@0: 
michael@0:     /**
michael@0:      Gives method bitmap should be read to implement a shader.
michael@0:      Also determines number and interpretation of "extra" parameters returned
michael@0:      by asABitmap
michael@0:      */
michael@0:     enum BitmapType {
michael@0:         kNone_BitmapType,   //<! Shader is not represented as a bitmap
michael@0:         kDefault_BitmapType,//<! Access bitmap using local coords transformed
michael@0:                             //   by matrix. No extras
michael@0:         kRadial_BitmapType, //<! Access bitmap by transforming local coordinates
michael@0:                             //   by the matrix and taking the distance of result
michael@0:                             //   from  (0,0) as bitmap column. Bitmap is 1 pixel
michael@0:                             //   tall. No extras
michael@0:         kSweep_BitmapType,  //<! Access bitmap by transforming local coordinates
michael@0:                             //   by the matrix and taking the angle of result
michael@0:                             //   to (0,0) as bitmap x coord, where angle = 0 is
michael@0:                             //   bitmap left edge of bitmap = 2pi is the
michael@0:                             //   right edge. Bitmap is 1 pixel tall. No extras
michael@0:         kTwoPointRadial_BitmapType,
michael@0:                             //<! Matrix transforms to space where (0,0) is
michael@0:                             //   the center of the starting circle.  The second
michael@0:                             //   circle will be centered (x, 0) where x  may be
michael@0:                             //   0. The post-matrix space is normalized such
michael@0:                             //   that 1 is the second radius - first radius.
michael@0:                             //   Three extra parameters are returned:
michael@0:                             //      0: x-offset of second circle center
michael@0:                             //         to first.
michael@0:                             //      1: radius of first circle in post-matrix
michael@0:                             //         space
michael@0:                             //      2: the second radius minus the first radius
michael@0:                             //         in pre-transformed space.
michael@0:         kTwoPointConical_BitmapType,
michael@0:                             //<! Matrix transforms to space where (0,0) is
michael@0:                             //   the center of the starting circle.  The second
michael@0:                             //   circle will be centered (x, 0) where x  may be
michael@0:                             //   0.
michael@0:                             //   Three extra parameters are returned:
michael@0:                             //      0: x-offset of second circle center
michael@0:                             //         to first.
michael@0:                             //      1: radius of first circle
michael@0:                             //      2: the second radius minus the first radius
michael@0:         kLinear_BitmapType, //<! Access bitmap using local coords transformed
michael@0:                             //   by matrix. No extras
michael@0: 
michael@0:        kLast_BitmapType = kLinear_BitmapType
michael@0:     };
michael@0:     /** Optional methods for shaders that can pretend to be a bitmap/texture
michael@0:         to play along with opengl. Default just returns kNone_BitmapType and
michael@0:         ignores the out parameters.
michael@0: 
michael@0:         @param outTexture if non-NULL will be the bitmap representing the shader
michael@0:                           after return.
michael@0:         @param outMatrix  if non-NULL will be the matrix to apply to vertices
michael@0:                           to access the bitmap after return.
michael@0:         @param xy         if non-NULL will be the tile modes that should be
michael@0:                           used to access the bitmap after return.
michael@0:         @param twoPointRadialParams Two extra return values needed for two point
michael@0:                                     radial bitmaps. The first is the x-offset of
michael@0:                                     the second point and the second is the radius
michael@0:                                     about the first point.
michael@0:     */
michael@0:     virtual BitmapType asABitmap(SkBitmap* outTexture, SkMatrix* outMatrix,
michael@0:                          TileMode xy[2]) const;
michael@0: 
michael@0:     /**
michael@0:      *  If the shader subclass can be represented as a gradient, asAGradient
michael@0:      *  returns the matching GradientType enum (or kNone_GradientType if it
michael@0:      *  cannot). Also, if info is not null, asAGradient populates info with
michael@0:      *  the relevant (see below) parameters for the gradient.  fColorCount
michael@0:      *  is both an input and output parameter.  On input, it indicates how
michael@0:      *  many entries in fColors and fColorOffsets can be used, if they are
michael@0:      *  non-NULL.  After asAGradient has run, fColorCount indicates how
michael@0:      *  many color-offset pairs there are in the gradient.  If there is
michael@0:      *  insufficient space to store all of the color-offset pairs, fColors
michael@0:      *  and fColorOffsets will not be altered.  fColorOffsets specifies
michael@0:      *  where on the range of 0 to 1 to transition to the given color.
michael@0:      *  The meaning of fPoint and fRadius is dependant on the type of gradient.
michael@0:      *
michael@0:      *  None:
michael@0:      *      info is ignored.
michael@0:      *  Color:
michael@0:      *      fColorOffsets[0] is meaningless.
michael@0:      *  Linear:
michael@0:      *      fPoint[0] and fPoint[1] are the end-points of the gradient
michael@0:      *  Radial:
michael@0:      *      fPoint[0] and fRadius[0] are the center and radius
michael@0:      *  Radial2:
michael@0:      *      fPoint[0] and fRadius[0] are the center and radius of the 1st circle
michael@0:      *      fPoint[1] and fRadius[1] are the center and radius of the 2nd circle
michael@0:      *  Sweep:
michael@0:      *      fPoint[0] is the center of the sweep.
michael@0:      */
michael@0: 
michael@0:     enum GradientType {
michael@0:         kNone_GradientType,
michael@0:         kColor_GradientType,
michael@0:         kLinear_GradientType,
michael@0:         kRadial_GradientType,
michael@0:         kRadial2_GradientType,
michael@0:         kSweep_GradientType,
michael@0:         kConical_GradientType,
michael@0:         kLast_GradientType = kConical_GradientType
michael@0:     };
michael@0: 
michael@0:     struct GradientInfo {
michael@0:         int         fColorCount;    //!< In-out parameter, specifies passed size
michael@0:                                     //   of fColors/fColorOffsets on input, and
michael@0:                                     //   actual number of colors/offsets on
michael@0:                                     //   output.
michael@0:         SkColor*    fColors;        //!< The colors in the gradient.
michael@0:         SkScalar*   fColorOffsets;  //!< The unit offset for color transitions.
michael@0:         SkPoint     fPoint[2];      //!< Type specific, see above.
michael@0:         SkScalar    fRadius[2];     //!< Type specific, see above.
michael@0:         TileMode    fTileMode;      //!< The tile mode used.
michael@0:         uint32_t    fGradientFlags; //!< see SkGradientShader::Flags
michael@0:     };
michael@0: 
michael@0:     virtual GradientType asAGradient(GradientInfo* info) const;
michael@0: 
michael@0:     /**
michael@0:      *  If the shader subclass has a GrEffect implementation, this resturns the effect to install.
michael@0:      *  The incoming color to the effect has r=g=b=a all extracted from the SkPaint's alpha.
michael@0:      *  The output color should be the computed SkShader premul color modulated by the incoming
michael@0:      *  color. The GrContext may be used by the effect to create textures. The GPU device does not
michael@0:      *  call setContext. Instead we pass the SkPaint here in case the shader needs paint info.
michael@0:      */
michael@0:     virtual GrEffectRef* asNewEffect(GrContext* context, const SkPaint& paint) const;
michael@0: 
michael@0:     //////////////////////////////////////////////////////////////////////////
michael@0:     //  Factory methods for stock shaders
michael@0: 
michael@0:     /** Call this to create a new shader that will draw with the specified bitmap.
michael@0:      *
michael@0:      *  If the bitmap cannot be used (e.g. has no pixels, or its dimensions
michael@0:      *  exceed implementation limits (currently at 64K - 1)) then SkEmptyShader
michael@0:      *  may be returned.
michael@0:      *
michael@0:      *  If the src is kA8_Config then that mask will be colorized using the color on
michael@0:      *  the paint.
michael@0:      *
michael@0:      *  @param src  The bitmap to use inside the shader
michael@0:      *  @param tmx  The tiling mode to use when sampling the bitmap in the x-direction.
michael@0:      *  @param tmy  The tiling mode to use when sampling the bitmap in the y-direction.
michael@0:      *  @return     Returns a new shader object. Note: this function never returns null.
michael@0:     */
michael@0:     static SkShader* CreateBitmapShader(const SkBitmap& src,
michael@0:                                         TileMode tmx, TileMode tmy);
michael@0: 
michael@0:     SK_TO_STRING_VIRT()
michael@0:     SK_DEFINE_FLATTENABLE_TYPE(SkShader)
michael@0: 
michael@0: protected:
michael@0:     enum MatrixClass {
michael@0:         kLinear_MatrixClass,            // no perspective
michael@0:         kFixedStepInX_MatrixClass,      // fast perspective, need to call fixedStepInX() each scanline
michael@0:         kPerspective_MatrixClass        // slow perspective, need to mappoints each pixel
michael@0:     };
michael@0:     static MatrixClass ComputeMatrixClass(const SkMatrix&);
michael@0: 
michael@0:     // These can be called by your subclass after setContext() has been called
michael@0:     uint8_t             getPaintAlpha() const { return fPaintAlpha; }
michael@0:     const SkMatrix&     getTotalInverse() const { return fTotalInverse; }
michael@0:     MatrixClass         getInverseClass() const { return (MatrixClass)fTotalInverseClass; }
michael@0: 
michael@0:     SkShader(SkReadBuffer& );
michael@0:     virtual void flatten(SkWriteBuffer&) const SK_OVERRIDE;
michael@0: private:
michael@0:     SkMatrix            fLocalMatrix;
michael@0:     SkMatrix            fTotalInverse;
michael@0:     uint8_t             fPaintAlpha;
michael@0:     uint8_t             fTotalInverseClass;
michael@0:     SkDEBUGCODE(SkBool8 fInSetContext;)
michael@0: 
michael@0:     typedef SkFlattenable INHERITED;
michael@0: };
michael@0: 
michael@0: #endif