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