Home | History | Annotate | Download | only in core
      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 SkBitmap;
     18 class SkBlitter;
     19 class SkBounder;
     20 class SkMatrix;
     21 class SkPath;
     22 class SkRasterClip;
     23 class SkRRect;
     24 
     25 /** \class SkMaskFilter
     26 
     27     SkMaskFilter is the base class for object that perform transformations on
     28     an alpha-channel mask before drawing it. A subclass of SkMaskFilter may be
     29     installed into a SkPaint. Once there, each time a primitive is drawn, it
     30     is first scan converted into a SkMask::kA8_Format mask, and handed to the
     31     filter, calling its filterMask() method. If this returns true, then the
     32     new mask is used to render into the device.
     33 
     34     Blur and emboss are implemented as subclasses of SkMaskFilter.
     35 */
     36 class SK_API SkMaskFilter : public SkFlattenable {
     37 public:
     38     SK_DECLARE_INST_COUNT(SkMaskFilter)
     39 
     40     SkMaskFilter() {}
     41 
     42     /** Returns the format of the resulting mask that this subclass will return
     43         when its filterMask() method is called.
     44     */
     45     virtual SkMask::Format getFormat() const = 0;
     46 
     47     /** Create a new mask by filter the src mask.
     48         If src.fImage == null, then do not allocate or create the dst image
     49         but do fill out the other fields in dstMask.
     50         If you do allocate a dst image, use SkMask::AllocImage()
     51         If this returns false, dst mask is ignored.
     52         @param  dst the result of the filter. If src.fImage == null, dst should not allocate its image
     53         @param src the original image to be filtered.
     54         @param matrix the CTM
     55         @param margin   if not null, return the buffer dx/dy need when calculating the effect. Used when
     56                         drawing a clipped object to know how much larger to allocate the src before
     57                         applying the filter. If returning false, ignore this parameter.
     58         @return true if the dst mask was correctly created.
     59     */
     60     virtual bool filterMask(SkMask* dst, const SkMask& src, const SkMatrix&,
     61                             SkIPoint* margin) const;
     62 
     63 #if SK_SUPPORT_GPU
     64     /**
     65      *  Returns true if the filter can be expressed a single-pass
     66      *  GrEffect, used to process this filter on the GPU, or false if
     67      *  not.
     68      *
     69      *  If effect is non-NULL, a new GrEffect instance is stored
     70      *  in it.  The caller assumes ownership of the stage, and it is up to the
     71      *  caller to unref it.
     72      */
     73     virtual bool asNewEffect(GrEffectRef** effect, GrTexture*) const;
     74 
     75     /**
     76      *  Returns true if the filter can be processed on the GPU.  This is most
     77      *  often used for multi-pass effects, where intermediate results must be
     78      *  rendered to textures.  For single-pass effects, use asNewEffect().
     79      *
     80      *  'maskRect' returns the device space portion of the mask the the filter
     81      *  needs. The mask passed into 'filterMaskGPU' should have the same extent
     82      *  as 'maskRect' but be translated to the upper-left corner of the mask
     83      *  (i.e., (maskRect.fLeft, maskRect.fTop) appears at (0, 0) in the mask).
     84      */
     85     virtual bool canFilterMaskGPU(const SkRect& devBounds,
     86                                   const SkIRect& clipBounds,
     87                                   const SkMatrix& ctm,
     88                                   SkRect* maskRect) const;
     89 
     90     /**
     91      *  Perform this mask filter on the GPU.  This is most often used for
     92      *  multi-pass effects, where intermediate results must be rendered to
     93      *  textures.  For single-pass effects, use asNewEffect().  'src' is the
     94      *  source image for processing, as a texture-backed bitmap.  'result' is
     95      *  the destination bitmap, which should contain a texture-backed pixelref
     96      *  on success. 'maskRect' should be the rect returned from canFilterMaskGPU.
     97      */
     98     bool filterMaskGPU(GrContext* context,
     99                        const SkBitmap& src,
    100                        const SkRect& maskRect,
    101                        SkBitmap* result) const;
    102 
    103     /**
    104      *  This flavor of 'filterMaskGPU' provides a more direct means of accessing
    105      *  the filtering capabilities. Setting 'canOverwriteSrc' can allow some
    106      *  filters to skip the allocation of an additional texture.
    107      */
    108     virtual bool filterMaskGPU(GrTexture* src,
    109                                const SkRect& maskRect,
    110                                GrTexture** result,
    111                                bool canOverwriteSrc) const;
    112 #endif
    113 
    114     /**
    115      * The fast bounds function is used to enable the paint to be culled early
    116      * in the drawing pipeline. This function accepts the current bounds of the
    117      * paint as its src param and the filter adjust those bounds using its
    118      * current mask and returns the result using the dest param. Callers are
    119      * allowed to provide the same struct for both src and dest so each
    120      * implementation must accomodate that behavior.
    121      *
    122      *  The default impl calls filterMask with the src mask having no image,
    123      *  but subclasses may override this if they can compute the rect faster.
    124      */
    125     virtual void computeFastBounds(const SkRect& src, SkRect* dest) const;
    126 
    127     SkDEVCODE(virtual void toString(SkString* str) const = 0;)
    128 
    129 protected:
    130     // empty for now, but lets get our subclass to remember to init us for the future
    131     SkMaskFilter(SkFlattenableReadBuffer& buffer) : INHERITED(buffer) {}
    132 
    133     enum FilterReturn {
    134         kFalse_FilterReturn,
    135         kTrue_FilterReturn,
    136         kUnimplemented_FilterReturn
    137     };
    138 
    139     struct NinePatch {
    140         SkMask      fMask;      // fBounds must have [0,0] in its top-left
    141         SkIRect     fOuterRect; // width/height must be >= fMask.fBounds'
    142         SkIPoint    fCenter;    // identifies center row/col for stretching
    143     };
    144 
    145     /**
    146      *  Override if your subclass can filter a rect, and return the answer as
    147      *  a ninepatch mask to be stretched over the returned outerRect. On success
    148      *  return kTrue_FilterReturn. On failure (e.g. out of memory) return
    149      *  kFalse_FilterReturn. If the normal filterMask() entry-point should be
    150      *  called (the default) return kUnimplemented_FilterReturn.
    151      *
    152      *  By convention, the caller will take the center rol/col from the returned
    153      *  mask as the slice it can replicate horizontally and vertically as we
    154      *  stretch the mask to fit inside outerRect. It is an error for outerRect
    155      *  to be smaller than the mask's bounds. This would imply that the width
    156      *  and height of the mask should be odd. This is not required, just that
    157      *  the caller will call mask.fBounds.centerX() and centerY() to find the
    158      *  strips that will be replicated.
    159      */
    160     virtual FilterReturn filterRectsToNine(const SkRect[], int count,
    161                                            const SkMatrix&,
    162                                            const SkIRect& clipBounds,
    163                                            NinePatch*) const;
    164     /**
    165      *  Similar to filterRectsToNine, except it performs the work on a round rect.
    166      */
    167     virtual FilterReturn filterRRectToNine(const SkRRect&, const SkMatrix&,
    168                                            const SkIRect& clipBounds,
    169                                            NinePatch*) const;
    170 
    171 private:
    172     friend class SkDraw;
    173 
    174     /** Helper method that, given a path in device space, will rasterize it into a kA8_Format mask
    175      and then call filterMask(). If this returns true, the specified blitter will be called
    176      to render that mask. Returns false if filterMask() returned false.
    177      This method is not exported to java.
    178      */
    179     bool filterPath(const SkPath& devPath, const SkMatrix& devMatrix,
    180                     const SkRasterClip&, SkBounder*, SkBlitter* blitter,
    181                     SkPaint::Style style) const;
    182 
    183     /** Helper method that, given a roundRect in device space, will rasterize it into a kA8_Format
    184      mask and then call filterMask(). If this returns true, the specified blitter will be called
    185      to render that mask. Returns false if filterMask() returned false.
    186      */
    187     bool filterRRect(const SkRRect& devRRect, const SkMatrix& devMatrix,
    188                      const SkRasterClip&, SkBounder*, SkBlitter* blitter,
    189                      SkPaint::Style style) const;
    190 
    191     typedef SkFlattenable INHERITED;
    192 };
    193 
    194 #endif
    195