• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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 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 class GrContext;
21 class GrEffectRef;
22 
23 /** \class SkShader
24  *
25  *  Shaders specify the source color(s) for what is being drawn. If a paint
26  *  has no shader, then the paint's color is used. If the paint has a
27  *  shader, then the shader's color(s) are use instead, but they are
28  *  modulated by the paint's alpha. This makes it easy to create a shader
29  *  once (e.g. bitmap tiling or gradient) and then change its transparency
30  *  w/o having to modify the original shader... only the paint's alpha needs
31  *  to be modified.
32  */
33 class SK_API SkShader : public SkFlattenable {
34 public:
35     SK_DECLARE_INST_COUNT(SkShader)
36 
37     SkShader();
38     virtual ~SkShader();
39 
40     /**
41      * Returns true if the local matrix is not an identity matrix.
42      */
hasLocalMatrix()43     bool hasLocalMatrix() const { return !fLocalMatrix.isIdentity(); }
44 
45     /**
46      *  Returns the local matrix.
47      */
getLocalMatrix()48     const SkMatrix& getLocalMatrix() const { return fLocalMatrix; }
49 
50     /**
51      *  Set the shader's local matrix.
52      *  @param localM   The shader's new local matrix.
53      */
setLocalMatrix(const SkMatrix & localM)54     void setLocalMatrix(const SkMatrix& localM) { fLocalMatrix = localM; }
55 
56     /**
57      *  Reset the shader's local matrix to identity.
58      */
resetLocalMatrix()59     void resetLocalMatrix() { fLocalMatrix.reset(); }
60 
61     enum TileMode {
62         /** replicate the edge color if the shader draws outside of its
63          *  original bounds
64          */
65         kClamp_TileMode,
66 
67         /** repeat the shader's image horizontally and vertically */
68         kRepeat_TileMode,
69 
70         /** repeat the shader's image horizontally and vertically, alternating
71          *  mirror images so that adjacent images always seam
72          */
73         kMirror_TileMode,
74 
75 #if 0
76         /** only draw within the original domain, return 0 everywhere else */
77         kDecal_TileMode,
78 #endif
79 
80         kTileModeCount
81     };
82 
83     // override these in your subclass
84 
85     enum Flags {
86         //!< set if all of the colors will be opaque
87         kOpaqueAlpha_Flag  = 0x01,
88 
89         //! set if this shader's shadeSpan16() method can be called
90         kHasSpan16_Flag = 0x02,
91 
92         /** Set this bit if the shader's native data type is instrinsically 16
93             bit, meaning that calling the 32bit shadeSpan() entry point will
94             mean the the impl has to up-sample 16bit data into 32bit. Used as a
95             a means of clearing a dither request if the it will have no effect
96         */
97         kIntrinsicly16_Flag = 0x04,
98 
99         /** set (after setContext) if the spans only vary in X (const in Y).
100             e.g. an Nx1 bitmap that is being tiled in Y, or a linear-gradient
101             that varies from left-to-right. This flag specifies this for
102             shadeSpan().
103          */
104         kConstInY32_Flag = 0x08,
105 
106         /** same as kConstInY32_Flag, but is set if this is true for shadeSpan16
107             which may not always be the case, since shadeSpan16 may be
108             predithered, which would mean it was not const in Y, even though
109             the 32bit shadeSpan() would be const.
110          */
111         kConstInY16_Flag = 0x10
112     };
113 
114     /**
115      *  Called sometimes before drawing with this shader. Return the type of
116      *  alpha your shader will return. The default implementation returns 0.
117      *  Your subclass should override if it can (even sometimes) report a
118      *  non-zero value, since that will enable various blitters to perform
119      *  faster.
120      */
getFlags()121     virtual uint32_t getFlags() { return 0; }
122 
123     /**
124      *  Returns true if the shader is guaranteed to produce only opaque
125      *  colors, subject to the SkPaint using the shader to apply an opaque
126      *  alpha value. Subclasses should override this to allow some
127      *  optimizations.  isOpaque() can be called at any time, unlike getFlags,
128      *  which only works properly when the context is set.
129      */
isOpaque()130     virtual bool isOpaque() const { return false; }
131 
132     /**
133      *  Return the alpha associated with the data returned by shadeSpan16(). If
134      *  kHasSpan16_Flag is not set, this value is meaningless.
135      */
getSpan16Alpha()136     virtual uint8_t getSpan16Alpha() const { return fPaintAlpha; }
137 
138     /**
139      *  Called once before drawing, with the current paint and device matrix.
140      *  Return true if your shader supports these parameters, or false if not.
141      *  If false is returned, nothing will be drawn. If true is returned, then
142      *  a balancing call to endContext() will be made before the next call to
143      *  setContext.
144      *
145      *  Subclasses should be sure to call their INHERITED::setContext() if they
146      *  override this method.
147      */
148     virtual bool setContext(const SkBitmap& device, const SkPaint& paint,
149                             const SkMatrix& matrix);
150 
151     /**
152      *  Assuming setContext returned true, endContext() will be called when
153      *  the draw using the shader has completed. It is an error for setContext
154      *  to be called twice w/o an intervening call to endContext().
155      *
156      *  Subclasses should be sure to call their INHERITED::endContext() if they
157      *  override this method.
158      */
159     virtual void endContext();
160 
161     SkDEBUGCODE(bool setContextHasBeenCalled() const { return SkToBool(fInSetContext); })
162 
163     /**
164      *  Called for each span of the object being drawn. Your subclass should
165      *  set the appropriate colors (with premultiplied alpha) that correspond
166      *  to the specified device coordinates.
167      */
168     virtual void shadeSpan(int x, int y, SkPMColor[], int count) = 0;
169 
170     typedef void (*ShadeProc)(void* ctx, int x, int y, SkPMColor[], int count);
171     virtual ShadeProc asAShadeProc(void** ctx);
172 
173     /**
174      *  Called only for 16bit devices when getFlags() returns
175      *  kOpaqueAlphaFlag | kHasSpan16_Flag
176      */
177     virtual void shadeSpan16(int x, int y, uint16_t[], int count);
178 
179     /**
180      *  Similar to shadeSpan, but only returns the alpha-channel for a span.
181      *  The default implementation calls shadeSpan() and then extracts the alpha
182      *  values from the returned colors.
183      */
184     virtual void shadeSpanAlpha(int x, int y, uint8_t alpha[], int count);
185 
186     /**
187      *  Helper function that returns true if this shader's shadeSpan16() method
188      *  can be called.
189      */
canCallShadeSpan16()190     bool canCallShadeSpan16() {
191         return SkShader::CanCallShadeSpan16(this->getFlags());
192     }
193 
194     /**
195      *  Helper to check the flags to know if it is legal to call shadeSpan16()
196      */
CanCallShadeSpan16(uint32_t flags)197     static bool CanCallShadeSpan16(uint32_t flags) {
198         return (flags & kHasSpan16_Flag) != 0;
199     }
200 
201     /**
202      Gives method bitmap should be read to implement a shader.
203      Also determines number and interpretation of "extra" parameters returned
204      by asABitmap
205      */
206     enum BitmapType {
207         kNone_BitmapType,   //<! Shader is not represented as a bitmap
208         kDefault_BitmapType,//<! Access bitmap using local coords transformed
209                             //   by matrix. No extras
210         kRadial_BitmapType, //<! Access bitmap by transforming local coordinates
211                             //   by the matrix and taking the distance of result
212                             //   from  (0,0) as bitmap column. Bitmap is 1 pixel
213                             //   tall. No extras
214         kSweep_BitmapType,  //<! Access bitmap by transforming local coordinates
215                             //   by the matrix and taking the angle of result
216                             //   to (0,0) as bitmap x coord, where angle = 0 is
217                             //   bitmap left edge of bitmap = 2pi is the
218                             //   right edge. Bitmap is 1 pixel tall. No extras
219         kTwoPointRadial_BitmapType,
220                             //<! Matrix transforms to space where (0,0) is
221                             //   the center of the starting circle.  The second
222                             //   circle will be centered (x, 0) where x  may be
223                             //   0. The post-matrix space is normalized such
224                             //   that 1 is the second radius - first radius.
225                             //   Three extra parameters are returned:
226                             //      0: x-offset of second circle center
227                             //         to first.
228                             //      1: radius of first circle in post-matrix
229                             //         space
230                             //      2: the second radius minus the first radius
231                             //         in pre-transformed space.
232         kTwoPointConical_BitmapType,
233                             //<! Matrix transforms to space where (0,0) is
234                             //   the center of the starting circle.  The second
235                             //   circle will be centered (x, 0) where x  may be
236                             //   0.
237                             //   Three extra parameters are returned:
238                             //      0: x-offset of second circle center
239                             //         to first.
240                             //      1: radius of first circle
241                             //      2: the second radius minus the first radius
242         kLinear_BitmapType, //<! Access bitmap using local coords transformed
243                             //   by matrix. No extras
244 
245        kLast_BitmapType = kLinear_BitmapType
246     };
247     /** Optional methods for shaders that can pretend to be a bitmap/texture
248         to play along with opengl. Default just returns kNone_BitmapType and
249         ignores the out parameters.
250 
251         @param outTexture if non-NULL will be the bitmap representing the shader
252                           after return.
253         @param outMatrix  if non-NULL will be the matrix to apply to vertices
254                           to access the bitmap after return.
255         @param xy         if non-NULL will be the tile modes that should be
256                           used to access the bitmap after return.
257         @param twoPointRadialParams Two extra return values needed for two point
258                                     radial bitmaps. The first is the x-offset of
259                                     the second point and the second is the radius
260                                     about the first point.
261     */
262     virtual BitmapType asABitmap(SkBitmap* outTexture, SkMatrix* outMatrix,
263                          TileMode xy[2]) const;
264 
265     /**
266      *  If the shader subclass can be represented as a gradient, asAGradient
267      *  returns the matching GradientType enum (or kNone_GradientType if it
268      *  cannot). Also, if info is not null, asAGradient populates info with
269      *  the relevant (see below) parameters for the gradient.  fColorCount
270      *  is both an input and output parameter.  On input, it indicates how
271      *  many entries in fColors and fColorOffsets can be used, if they are
272      *  non-NULL.  After asAGradient has run, fColorCount indicates how
273      *  many color-offset pairs there are in the gradient.  If there is
274      *  insufficient space to store all of the color-offset pairs, fColors
275      *  and fColorOffsets will not be altered.  fColorOffsets specifies
276      *  where on the range of 0 to 1 to transition to the given color.
277      *  The meaning of fPoint and fRadius is dependant on the type of gradient.
278      *
279      *  None:
280      *      info is ignored.
281      *  Color:
282      *      fColorOffsets[0] is meaningless.
283      *  Linear:
284      *      fPoint[0] and fPoint[1] are the end-points of the gradient
285      *  Radial:
286      *      fPoint[0] and fRadius[0] are the center and radius
287      *  Radial2:
288      *      fPoint[0] and fRadius[0] are the center and radius of the 1st circle
289      *      fPoint[1] and fRadius[1] are the center and radius of the 2nd circle
290      *  Sweep:
291      *      fPoint[0] is the center of the sweep.
292      */
293 
294     enum GradientType {
295         kNone_GradientType,
296         kColor_GradientType,
297         kLinear_GradientType,
298         kRadial_GradientType,
299         kRadial2_GradientType,
300         kSweep_GradientType,
301         kConical_GradientType,
302         kLast_GradientType = kConical_GradientType
303     };
304 
305     struct GradientInfo {
306         int         fColorCount;    //!< In-out parameter, specifies passed size
307                                     //   of fColors/fColorOffsets on input, and
308                                     //   actual number of colors/offsets on
309                                     //   output.
310         SkColor*    fColors;        //!< The colors in the gradient.
311         SkScalar*   fColorOffsets;  //!< The unit offset for color transitions.
312         SkPoint     fPoint[2];      //!< Type specific, see above.
313         SkScalar    fRadius[2];     //!< Type specific, see above.
314         TileMode    fTileMode;      //!< The tile mode used.
315     };
316 
317     virtual GradientType asAGradient(GradientInfo* info) const;
318 
319     /**
320      *  If the shader subclass has a GrEffect implementation, this installs an effect on the stage.
321      *  The GrContext may be used by the effect to create textures. The GPU device does not call
322      *  setContext. Instead we pass the paint here in case the shader needs paint info.
323      */
324     virtual GrEffectRef* asNewEffect(GrContext* context, const SkPaint& paint) const;
325 
326     //////////////////////////////////////////////////////////////////////////
327     //  Factory methods for stock shaders
328 
329     /** Call this to create a new shader that will draw with the specified bitmap.
330      *
331      *  If the bitmap cannot be used (e.g. has no pixels, or its dimensions
332      *  exceed implementation limits (currently at 64K - 1)) then SkEmptyShader
333      *  may be returned.
334      *
335      *  @param src  The bitmap to use inside the shader
336      *  @param tmx  The tiling mode to use when sampling the bitmap in the x-direction.
337      *  @param tmy  The tiling mode to use when sampling the bitmap in the y-direction.
338      *  @return     Returns a new shader object. Note: this function never returns null.
339     */
340     static SkShader* CreateBitmapShader(const SkBitmap& src,
341                                         TileMode tmx, TileMode tmy);
342 
343     SkDEVCODE(virtual void toString(SkString* str) const;)
344 
345 protected:
346     enum MatrixClass {
347         kLinear_MatrixClass,            // no perspective
348         kFixedStepInX_MatrixClass,      // fast perspective, need to call fixedStepInX() each scanline
349         kPerspective_MatrixClass        // slow perspective, need to mappoints each pixel
350     };
351     static MatrixClass ComputeMatrixClass(const SkMatrix&);
352 
353     // These can be called by your subclass after setContext() has been called
getPaintAlpha()354     uint8_t             getPaintAlpha() const { return fPaintAlpha; }
getDeviceConfig()355     SkBitmap::Config    getDeviceConfig() const { return (SkBitmap::Config)fDeviceConfig; }
getTotalInverse()356     const SkMatrix&     getTotalInverse() const { return fTotalInverse; }
getInverseClass()357     MatrixClass         getInverseClass() const { return (MatrixClass)fTotalInverseClass; }
358 
359     SkShader(SkFlattenableReadBuffer& );
360     virtual void flatten(SkFlattenableWriteBuffer&) const SK_OVERRIDE;
361 private:
362     SkMatrix            fLocalMatrix;
363     SkMatrix            fTotalInverse;
364     uint8_t             fPaintAlpha;
365     uint8_t             fDeviceConfig;
366     uint8_t             fTotalInverseClass;
367     SkDEBUGCODE(SkBool8 fInSetContext;)
368 
369     static SkShader* CreateBitmapShader(const SkBitmap& src,
370                                         TileMode, TileMode,
371                                         void* storage, size_t storageSize);
372     friend class SkAutoBitmapShaderInstall;
373     typedef SkFlattenable INHERITED;
374 };
375 
376 #endif
377