gfx/thebes/gfxBlur.h

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*-
   2  * This Source Code Form is subject to the terms of the Mozilla Public
   3  * License, v. 2.0. If a copy of the MPL was not distributed with this
   4  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   5
   6 #ifndef GFX_BLUR_H
   7 #define GFX_BLUR_H
   8
   9 #include "gfxTypes.h"
  10 #include "gfxRect.h"
  11 #include "nsSize.h"
  12 #include "gfxPoint.h"
  13 #include "mozilla/RefPtr.h"
  14 #include "mozilla/gfx/Blur.h"
  15
  16 class gfxContext;
  17
  18 namespace mozilla {
  19 namespace gfx {
  20 struct sRGBColor;
  21 struct RectCornerRadii;
  22 class SourceSurface;
  23 class DrawTarget;
  24 }  // namespace gfx
  25 }  // namespace mozilla
  26
  27 /**
  28  * Implementation of a triple box blur approximation of a Gaussian blur.
  29  *
  30  * A Gaussian blur is good for blurring because, when done independently
  31  * in the horizontal and vertical directions, it matches the result that
  32  * would be obtained using a different (rotated) set of axes.  A triple
  33  * box blur is a very close approximation of a Gaussian.
  34  *
  35  * Creates an 8-bit alpha channel context for callers to draw in,
  36  * spreads the contents of that context, blurs the contents, and applies
  37  * it as an alpha mask on a different existing context.
  38  *
  39  * A spread N makes each output pixel the maximum value of all source
  40  * pixels within a square of side length 2N+1 centered on the output pixel.
  41  *
  42  * A temporary surface is created in the Init function. The caller then draws
  43  * any desired content onto the context acquired through GetContext, and lastly
  44  * calls Paint to apply the blurred content as an alpha mask.
  45  */
  46 class gfxAlphaBoxBlur final {
  47   typedef mozilla::gfx::sRGBColor sRGBColor;
  48   typedef mozilla::gfx::DrawTarget DrawTarget;
  49   typedef mozilla::gfx::RectCornerRadii RectCornerRadii;
  50
  51  public:
  52   gfxAlphaBoxBlur() = default;
  53
  54   ~gfxAlphaBoxBlur();
  55
  56   /**
  57    * Constructs a box blur and initializes the temporary surface.
  58    *
  59    * @param aDestinationCtx The destination to blur to.
  60    *
  61    * @param aRect The coordinates of the surface to create in device units.
  62    *
  63    * @param aBlurRadius The blur radius in pixels.  This is the radius of
  64    *   the entire (triple) kernel function.  Each individual box blur has
  65    *   radius approximately 1/3 this value, or diameter approximately 2/3
  66    *   this value.  This parameter should nearly always be computed using
  67    *   CalculateBlurRadius, below.
  68    *
  69    * @param aDirtyRect A pointer to a dirty rect, measured in device units,
  70    *  if available. This will be used for optimizing the blur operation. It
  71    *  is safe to pass nullptr here.
  72    *
  73    * @param aSkipRect A pointer to a rect, measured in device units, that
  74    *  represents an area where blurring is unnecessary and shouldn't be done
  75    *  for speed reasons. It is safe to pass nullptr here.
  76    *
  77    * @param aUseHardwareAccel Flag to state whether or not we can use hardware
  78    *  acceleration to speed up this blur.
  79    */
  80   mozilla::UniquePtr<gfxContext> Init(
  81       gfxContext* aDestinationCtx, const gfxRect& aRect,
  82       const mozilla::gfx::IntSize& aSpreadRadius,
  83       const mozilla::gfx::IntSize& aBlurRadius, const gfxRect* aDirtyRect,
  84       const gfxRect* aSkipRect, bool aUseHardwareAccel = true);
  85
  86   already_AddRefed<DrawTarget> InitDrawTarget(
  87       const mozilla::gfx::DrawTarget* aReferenceDT,
  88       const mozilla::gfx::Rect& aRect,
  89       const mozilla::gfx::IntSize& aSpreadRadius,
  90       const mozilla::gfx::IntSize& aBlurRadius,
  91       const mozilla::gfx::Rect* aDirtyRect = nullptr,
  92       const mozilla::gfx::Rect* aSkipRect = nullptr,
  93       bool aUseHardwareAccel = true);
  94
  95   /**
  96    * Performs the blur and optionally colors the result if aShadowColor is not
  97    * null.
  98    */
  99   already_AddRefed<mozilla::gfx::SourceSurface> DoBlur(
 100       const mozilla::gfx::sRGBColor* aShadowColor = nullptr,
 101       mozilla::gfx::IntPoint* aOutTopLeft = nullptr);
 102
 103   /**
 104    * Does the actual blurring/spreading and mask applying. Users of this
 105    * object must have drawn whatever they want to be blurred onto the internal
 106    * gfxContext returned by GetContext before calling this.
 107    *
 108    * @param aDestinationCtx The graphics context on which to apply the
 109    *  blurred mask.
 110    */
 111   void Paint(gfxContext* aDestinationCtx);
 112
 113   /**
 114    * Calculates a blur radius that, when used with box blur, approximates
 115    * a Gaussian blur with the given standard deviation.  The result of
 116    * this function should be used as the aBlurRadius parameter to Init,
 117    * above.
 118    */
 119   static mozilla::gfx::IntSize CalculateBlurRadius(
 120       const gfxPoint& aStandardDeviation);
 121
 122   /**
 123    * Blurs a coloured rectangle onto aDestinationCtx. This is equivalent
 124    * to calling Init(), drawing a rectangle onto the returned surface
 125    * and then calling Paint, but may let us optimize better in the
 126    * backend.
 127    *
 128    * @param aDestinationCtx      The destination to blur to.
 129    * @param aRect                The rectangle to blur in device pixels.
 130    * @param aCornerRadii         Corner radii for aRect, if it is a rounded
 131    *                             rectangle.
 132    * @param aBlurRadius          The standard deviation of the blur.
 133    * @param aShadowColor         The color to draw the blurred shadow.
 134    * @param aDirtyRect           An area in device pixels that is dirty and
 135    * needs to be redrawn.
 136    * @param aSkipRect            An area in device pixels to avoid blurring
 137    * over, to prevent unnecessary work.
 138    */
 139   static void BlurRectangle(gfxContext* aDestinationCtx, const gfxRect& aRect,
 140                             const RectCornerRadii* aCornerRadii,
 141                             const gfxPoint& aBlurStdDev,
 142                             const sRGBColor& aShadowColor,
 143                             const gfxRect& aDirtyRect,
 144                             const gfxRect& aSkipRect);
 145
 146   static void ShutdownBlurCache();
 147
 148   /***
 149    * Blurs an inset box shadow according to a given path.
 150    * This is equivalent to calling Init(), drawing the inset path,
 151    * and calling paint. Do not call Init() if using this method.
 152    *
 153    * @param aDestinationCtx     The destination to blur to.
 154    * @param aDestinationRect    The destination rect in device pixels
 155    * @param aShadowClipRect     The destiniation inner rect of the
 156    *                            inset path in device pixels.
 157    * @param aBlurRadius         The standard deviation of the blur.
 158    * @param aShadowColor        The color of the blur.
 159    * @param aInnerClipRadii     Corner radii for the inside rect if it is a
 160    *                            rounded rect.
 161    * @param aSkipRect           An area in device pixels we don't have to
 162    *                            paint in.
 163    */
 164   void BlurInsetBox(gfxContext* aDestinationCtx,
 165                     const mozilla::gfx::Rect& aDestinationRect,
 166                     const mozilla::gfx::Rect& aShadowClipRect,
 167                     const mozilla::gfx::IntSize& aBlurRadius,
 168                     const mozilla::gfx::sRGBColor& aShadowColor,
 169                     const RectCornerRadii* aInnerClipRadii,
 170                     const mozilla::gfx::Rect& aSkipRect,
 171                     const mozilla::gfx::Point& aShadowOffset);
 172
 173  protected:
 174   already_AddRefed<mozilla::gfx::SourceSurface> GetInsetBlur(
 175       const mozilla::gfx::Rect& aOuterRect,
 176       const mozilla::gfx::Rect& aWhitespaceRect, bool aIsDestRect,
 177       const mozilla::gfx::sRGBColor& aShadowColor,
 178       const mozilla::gfx::IntSize& aBlurRadius,
 179       const RectCornerRadii* aInnerClipRadii, DrawTarget* aDestDrawTarget,
 180       bool aMirrorCorners);
 181
 182   /**
 183    * The DrawTarget of the temporary alpha surface.
 184    */
 185   RefPtr<DrawTarget> mDrawTarget;
 186
 187   /**
 188    * The temporary alpha surface.
 189    */
 190   uint8_t* mData = nullptr;
 191
 192   /**
 193    * The object that actually does the blurring for us.
 194    */
 195   mozilla::gfx::AlphaBoxBlur mBlur;
 196
 197   /**
 198    * Indicates using DrawTarget-accelerated blurs.
 199    */
 200   bool mAccelerated = false;
 201 };
 202
 203 #endif /* GFX_BLUR_H */