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

   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 "SkFlattenable.h"
  14 #include "SkMask.h"
  15 #include "SkPaint.h"
  16
  17 class GrContext;
  18 class SkBitmap;
  19 class SkBlitter;
  20 class SkBounder;
  21 class SkMatrix;
  22 class SkPath;
  23 class SkRasterClip;
  24 class SkRRect;
  25
  26 /** \class SkMaskFilter
  27
  28     SkMaskFilter is the base class for object that perform transformations on
  29     an alpha-channel mask before drawing it. A subclass of SkMaskFilter may be
  30     installed into a SkPaint. Once there, each time a primitive is drawn, it
  31     is first scan converted into a SkMask::kA8_Format mask, and handed to the
  32     filter, calling its filterMask() method. If this returns true, then the
  33     new mask is used to render into the device.
  34
  35     Blur and emboss are implemented as subclasses of SkMaskFilter.
  36 */
  37 class SK_API SkMaskFilter : public SkFlattenable {
  38 public:
  39     SK_DECLARE_INST_COUNT(SkMaskFilter)
  40
  41     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      * This function is used to implement filters that require an explicit src mask. It should only
  98      * be called if canFilterMaskGPU returned true and the maskRect param should be the output from
  99      * that call. canOverwriteSrc indicates whether the implementation may treat src as a scratch
 100      * texture and overwrite its contents. When true it is also legal to return src as the result.
 101      * Implementations are free to get the GrContext from the src texture in order to create
 102      * additional textures and perform multiple passes.
 103      */
 104     virtual bool filterMaskGPU(GrTexture* src,
 105                                const SkMatrix& ctm,
 106                                const SkRect& maskRect,
 107                                GrTexture** result,
 108                                bool canOverwriteSrc) const;
 109 #endif
 110
 111     /**
 112      * The fast bounds function is used to enable the paint to be culled early
 113      * in the drawing pipeline. This function accepts the current bounds of the
 114      * paint as its src param and the filter adjust those bounds using its
 115      * current mask and returns the result using the dest param. Callers are
 116      * allowed to provide the same struct for both src and dest so each
 117      * implementation must accomodate that behavior.
 118      *
 119      *  The default impl calls filterMask with the src mask having no image,
 120      *  but subclasses may override this if they can compute the rect faster.
 121      */
 122     virtual void computeFastBounds(const SkRect& src, SkRect* dest) const;
 123
 124     SkDEVCODE(virtual void toString(SkString* str) const = 0;)
 125     SK_DEFINE_FLATTENABLE_TYPE(SkMaskFilter)
 126
 127 protected:
 128     // empty for now, but lets get our subclass to remember to init us for the future
 129     SkMaskFilter(SkFlattenableReadBuffer& buffer) : INHERITED(buffer) {}
 130
 131     enum FilterReturn {
 132         kFalse_FilterReturn,
 133         kTrue_FilterReturn,
 134         kUnimplemented_FilterReturn
 135     };
 136
 137     struct NinePatch {
 138         SkMask      fMask;      // fBounds must have [0,0] in its top-left
 139         SkIRect     fOuterRect; // width/height must be >= fMask.fBounds'
 140         SkIPoint    fCenter;    // identifies center row/col for stretching
 141     };
 142
 143     /**
 144      *  Override if your subclass can filter a rect, and return the answer as
 145      *  a ninepatch mask to be stretched over the returned outerRect. On success
 146      *  return kTrue_FilterReturn. On failure (e.g. out of memory) return
 147      *  kFalse_FilterReturn. If the normal filterMask() entry-point should be
 148      *  called (the default) return kUnimplemented_FilterReturn.
 149      *
 150      *  By convention, the caller will take the center rol/col from the returned
 151      *  mask as the slice it can replicate horizontally and vertically as we
 152      *  stretch the mask to fit inside outerRect. It is an error for outerRect
 153      *  to be smaller than the mask's bounds. This would imply that the width
 154      *  and height of the mask should be odd. This is not required, just that
 155      *  the caller will call mask.fBounds.centerX() and centerY() to find the
 156      *  strips that will be replicated.
 157      */
 158     virtual FilterReturn filterRectsToNine(const SkRect[], int count,
 159                                            const SkMatrix&,
 160                                            const SkIRect& clipBounds,
 161                                            NinePatch*) const;
 162     /**
 163      *  Similar to filterRectsToNine, except it performs the work on a round rect.
 164      */
 165     virtual FilterReturn filterRRectToNine(const SkRRect&, const SkMatrix&,
 166                                            const SkIRect& clipBounds,
 167                                            NinePatch*) const;
 168
 169 private:
 170     friend class SkDraw;
 171
 172     /** Helper method that, given a path in device space, will rasterize it into a kA8_Format mask
 173      and then call filterMask(). If this returns true, the specified blitter will be called
 174      to render that mask. Returns false if filterMask() returned false.
 175      This method is not exported to java.
 176      */
 177     bool filterPath(const SkPath& devPath, const SkMatrix& devMatrix,
 178                     const SkRasterClip&, SkBounder*, SkBlitter* blitter,
 179                     SkPaint::Style style) const;
 180
 181     /** Helper method that, given a roundRect in device space, will rasterize it into a kA8_Format
 182      mask and then call filterMask(). If this returns true, the specified blitter will be called
 183      to render that mask. Returns false if filterMask() returned false.
 184      */
 185     bool filterRRect(const SkRRect& devRRect, const SkMatrix& devMatrix,
 186                      const SkRasterClip&, SkBounder*, SkBlitter* blitter,
 187                      SkPaint::Style style) const;
 188
 189     typedef SkFlattenable INHERITED;
 190 };
 191
 192 #endif