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 SkMaskFilter_DEFINED
11#define SkMaskFilter_DEFINED
12
13#include "SkBlurTypes.h"
14#include "SkFlattenable.h"
15#include "SkMask.h"
16#include "SkPaint.h"
17
18class GrContext;
19class GrPaint;
20class SkBitmap;
21class SkBlitter;
22class SkMatrix;
23class SkPath;
24class SkRasterClip;
25class SkRRect;
26class SkStrokeRec;
27
28/** \class SkMaskFilter
29
30    SkMaskFilter is the base class for object that perform transformations on
31    an alpha-channel mask before drawing it. A subclass of SkMaskFilter may be
32    installed into a SkPaint. Once there, each time a primitive is drawn, it
33    is first scan converted into a SkMask::kA8_Format mask, and handed to the
34    filter, calling its filterMask() method. If this returns true, then the
35    new mask is used to render into the device.
36
37    Blur and emboss are implemented as subclasses of SkMaskFilter.
38*/
39class SK_API SkMaskFilter : public SkFlattenable {
40public:
41    SK_DECLARE_INST_COUNT(SkMaskFilter)
42
43    /** Returns the format of the resulting mask that this subclass will return
44        when its filterMask() method is called.
45    */
46    virtual SkMask::Format getFormat() const = 0;
47
48    /** Create a new mask by filter the src mask.
49        If src.fImage == null, then do not allocate or create the dst image
50        but do fill out the other fields in dstMask.
51        If you do allocate a dst image, use SkMask::AllocImage()
52        If this returns false, dst mask is ignored.
53        @param  dst the result of the filter. If src.fImage == null, dst should not allocate its image
54        @param src the original image to be filtered.
55        @param matrix the CTM
56        @param margin   if not null, return the buffer dx/dy need when calculating the effect. Used when
57                        drawing a clipped object to know how much larger to allocate the src before
58                        applying the filter. If returning false, ignore this parameter.
59        @return true if the dst mask was correctly created.
60    */
61    virtual bool filterMask(SkMask* dst, const SkMask& src, const SkMatrix&,
62                            SkIPoint* margin) const;
63
64#if SK_SUPPORT_GPU
65    /**
66     *  Returns true if the filter can be expressed a single-pass GrEffect without requiring an
67     *  explicit input mask. Per-pixel, the effect receives the incoming mask's coverage as
68     *  the input color and outputs the filtered covereage value. This means that each pixel's
69     *  filtered coverage must only depend on the unfiltered mask value for that pixel and not on
70     *  surrounding values.
71     *
72     * If effect is non-NULL, a new GrEffect instance is stored in it. The caller assumes ownership
73     * of the effect and must unref it.
74     */
75    virtual bool asNewEffect(GrEffectRef** effect,
76                             GrTexture*,
77                             const SkMatrix& ctm) const;
78
79    /**
80     *  If asNewEffect() fails the filter may be implemented on the GPU by a subclass overriding
81     *  filterMaskGPU (declared below). That code path requires constructing a src mask as input.
82     *  Since that is a potentially expensive operation, the subclass must also override this
83     *  function to indicate whether filterTextureMaskGPU would succeeed if the mask were to be
84     *  created.
85     *
86     *  'maskRect' returns the device space portion of the mask that the filter needs. The mask
87     *  passed into 'filterMaskGPU' should have the same extent as 'maskRect' but be translated
88     *  to the upper-left corner of the mask (i.e., (maskRect.fLeft, maskRect.fTop) appears at
89     *  (0, 0) in the mask).
90     */
91    virtual bool canFilterMaskGPU(const SkRect& devBounds,
92                                  const SkIRect& clipBounds,
93                                  const SkMatrix& ctm,
94                                  SkRect* maskRect) const;
95
96    /**
97     *  Try to directly render the mask filter into the target.  Returns
98     *  true if drawing was successful.
99     */
100    virtual bool directFilterMaskGPU(GrContext* context,
101                                     GrPaint* grp,
102                                     const SkStrokeRec& strokeRec,
103                                     const SkPath& path) const;
104    /**
105     *  Try to directly render a rounded rect mask filter into the target.  Returns
106     *  true if drawing was successful.
107     */
108    virtual bool directFilterRRectMaskGPU(GrContext* context,
109                                          GrPaint* grp,
110                                          const SkStrokeRec& strokeRec,
111                                          const SkRRect& rrect) const;
112
113    /**
114     * This function is used to implement filters that require an explicit src mask. It should only
115     * be called if canFilterMaskGPU returned true and the maskRect param should be the output from
116     * that call. canOverwriteSrc indicates whether the implementation may treat src as a scratch
117     * texture and overwrite its contents. When true it is also legal to return src as the result.
118     * Implementations are free to get the GrContext from the src texture in order to create
119     * additional textures and perform multiple passes.
120     */
121    virtual bool filterMaskGPU(GrTexture* src,
122                               const SkMatrix& ctm,
123                               const SkRect& maskRect,
124                               GrTexture** result,
125                               bool canOverwriteSrc) const;
126#endif
127
128    /**
129     * The fast bounds function is used to enable the paint to be culled early
130     * in the drawing pipeline. This function accepts the current bounds of the
131     * paint as its src param and the filter adjust those bounds using its
132     * current mask and returns the result using the dest param. Callers are
133     * allowed to provide the same struct for both src and dest so each
134     * implementation must accomodate that behavior.
135     *
136     *  The default impl calls filterMask with the src mask having no image,
137     *  but subclasses may override this if they can compute the rect faster.
138     */
139    virtual void computeFastBounds(const SkRect& src, SkRect* dest) const;
140
141    struct BlurRec {
142        SkScalar        fSigma;
143        SkBlurStyle     fStyle;
144        SkBlurQuality   fQuality;
145    };
146    /**
147     *  If this filter can be represented by a BlurRec, return true and (if not null) fill in the
148     *  provided BlurRec parameter. If this effect cannot be represented as a BlurRec, return false
149     *  and ignore the BlurRec parameter.
150     */
151    virtual bool asABlur(BlurRec*) const;
152
153    SK_TO_STRING_PUREVIRT()
154    SK_DEFINE_FLATTENABLE_TYPE(SkMaskFilter)
155
156protected:
157    SkMaskFilter() {}
158    // empty for now, but lets get our subclass to remember to init us for the future
159    SkMaskFilter(SkReadBuffer& buffer) : INHERITED(buffer) {}
160
161    enum FilterReturn {
162        kFalse_FilterReturn,
163        kTrue_FilterReturn,
164        kUnimplemented_FilterReturn
165    };
166
167    struct NinePatch {
168        SkMask      fMask;      // fBounds must have [0,0] in its top-left
169        SkIRect     fOuterRect; // width/height must be >= fMask.fBounds'
170        SkIPoint    fCenter;    // identifies center row/col for stretching
171    };
172
173    /**
174     *  Override if your subclass can filter a rect, and return the answer as
175     *  a ninepatch mask to be stretched over the returned outerRect. On success
176     *  return kTrue_FilterReturn. On failure (e.g. out of memory) return
177     *  kFalse_FilterReturn. If the normal filterMask() entry-point should be
178     *  called (the default) return kUnimplemented_FilterReturn.
179     *
180     *  By convention, the caller will take the center rol/col from the returned
181     *  mask as the slice it can replicate horizontally and vertically as we
182     *  stretch the mask to fit inside outerRect. It is an error for outerRect
183     *  to be smaller than the mask's bounds. This would imply that the width
184     *  and height of the mask should be odd. This is not required, just that
185     *  the caller will call mask.fBounds.centerX() and centerY() to find the
186     *  strips that will be replicated.
187     */
188    virtual FilterReturn filterRectsToNine(const SkRect[], int count,
189                                           const SkMatrix&,
190                                           const SkIRect& clipBounds,
191                                           NinePatch*) const;
192    /**
193     *  Similar to filterRectsToNine, except it performs the work on a round rect.
194     */
195    virtual FilterReturn filterRRectToNine(const SkRRect&, const SkMatrix&,
196                                           const SkIRect& clipBounds,
197                                           NinePatch*) const;
198
199private:
200    friend class SkDraw;
201
202    /** Helper method that, given a path in device space, will rasterize it into a kA8_Format mask
203     and then call filterMask(). If this returns true, the specified blitter will be called
204     to render that mask. Returns false if filterMask() returned false.
205     This method is not exported to java.
206     */
207    bool filterPath(const SkPath& devPath, const SkMatrix& ctm, const SkRasterClip&, SkBlitter*,
208                    SkPaint::Style) const;
209
210    /** Helper method that, given a roundRect in device space, will rasterize it into a kA8_Format
211     mask and then call filterMask(). If this returns true, the specified blitter will be called
212     to render that mask. Returns false if filterMask() returned false.
213     */
214    bool filterRRect(const SkRRect& devRRect, const SkMatrix& ctm, const SkRasterClip&,
215                     SkBlitter*, SkPaint::Style style) const;
216
217    typedef SkFlattenable INHERITED;
218};
219
220#endif
221