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   already_AddRefed<gfxContext> Init(gfxContext* aDestinationCtx,
  81                                     const gfxRect& aRect,
  82                                     const mozilla::gfx::IntSize& aSpreadRadius,
  83                                     const mozilla::gfx::IntSize& aBlurRadius,
  84                                     const gfxRect* aDirtyRect,
  85                                     const gfxRect* aSkipRect,
  86                                     bool aUseHardwareAccel = true);
  87
  88   already_AddRefed<DrawTarget> InitDrawTarget(
  89       const mozilla::gfx::DrawTarget* aReferenceDT,
  90       const mozilla::gfx::Rect& aRect,
  91       const mozilla::gfx::IntSize& aSpreadRadius,
  92       const mozilla::gfx::IntSize& aBlurRadius,
  93       const mozilla::gfx::Rect* aDirtyRect = nullptr,
  94       const mozilla::gfx::Rect* aSkipRect = nullptr,
  95       bool aUseHardwareAccel = true);
  96
  97   /**
  98    * Performs the blur and optionally colors the result if aShadowColor is not
  99    * null.
 100    */
 101   already_AddRefed<mozilla::gfx::SourceSurface> DoBlur(
 102       const mozilla::gfx::sRGBColor* aShadowColor = nullptr,
 103       mozilla::gfx::IntPoint* aOutTopLeft = nullptr);
 104
 105   /**
 106    * Does the actual blurring/spreading and mask applying. Users of this
 107    * object must have drawn whatever they want to be blurred onto the internal
 108    * gfxContext returned by GetContext before calling this.
 109    *
 110    * @param aDestinationCtx The graphics context on which to apply the
 111    *  blurred mask.
 112    */
 113   void Paint(gfxContext* aDestinationCtx);
 114
 115   /**
 116    * Calculates a blur radius that, when used with box blur, approximates
 117    * a Gaussian blur with the given standard deviation.  The result of
 118    * this function should be used as the aBlurRadius parameter to Init,
 119    * above.
 120    */
 121   static mozilla::gfx::IntSize CalculateBlurRadius(
 122       const gfxPoint& aStandardDeviation);
 123
 124   /**
 125    * Blurs a coloured rectangle onto aDestinationCtx. This is equivalent
 126    * to calling Init(), drawing a rectangle onto the returned surface
 127    * and then calling Paint, but may let us optimize better in the
 128    * backend.
 129    *
 130    * @param aDestinationCtx      The destination to blur to.
 131    * @param aRect                The rectangle to blur in device pixels.
 132    * @param aCornerRadii         Corner radii for aRect, if it is a rounded
 133    *                             rectangle.
 134    * @param aBlurRadius          The standard deviation of the blur.
 135    * @param aShadowColor         The color to draw the blurred shadow.
 136    * @param aDirtyRect           An area in device pixels that is dirty and
 137    * needs to be redrawn.
 138    * @param aSkipRect            An area in device pixels to avoid blurring
 139    * over, to prevent unnecessary work.
 140    */
 141   static void BlurRectangle(gfxContext* aDestinationCtx, const gfxRect& aRect,
 142                             const RectCornerRadii* aCornerRadii,
 143                             const gfxPoint& aBlurStdDev,
 144                             const sRGBColor& aShadowColor,
 145                             const gfxRect& aDirtyRect,
 146                             const gfxRect& aSkipRect);
 147
 148   static void ShutdownBlurCache();
 149
 150   /***
 151    * Blurs an inset box shadow according to a given path.
 152    * This is equivalent to calling Init(), drawing the inset path,
 153    * and calling paint. Do not call Init() if using this method.
 154    *
 155    * @param aDestinationCtx     The destination to blur to.
 156    * @param aDestinationRect    The destination rect in device pixels
 157    * @param aShadowClipRect     The destiniation inner rect of the
 158    *                            inset path in device pixels.
 159    * @param aBlurRadius         The standard deviation of the blur.
 160    * @param aShadowColor        The color of the blur.
 161    * @param aInnerClipRadii     Corner radii for the inside rect if it is a
 162    *                            rounded rect.
 163    * @param aSkipRect           An area in device pixels we don't have to
 164    *                            paint in.
 165    */
 166   void BlurInsetBox(gfxContext* aDestinationCtx,
 167                     const mozilla::gfx::Rect& aDestinationRect,
 168                     const mozilla::gfx::Rect& aShadowClipRect,
 169                     const mozilla::gfx::IntSize& aBlurRadius,
 170                     const mozilla::gfx::sRGBColor& aShadowColor,
 171                     const RectCornerRadii* aInnerClipRadii,
 172                     const mozilla::gfx::Rect& aSkipRect,
 173                     const mozilla::gfx::Point& aShadowOffset);
 174
 175  protected:
 176   already_AddRefed<mozilla::gfx::SourceSurface> GetInsetBlur(
 177       const mozilla::gfx::Rect& aOuterRect,
 178       const mozilla::gfx::Rect& aWhitespaceRect, bool aIsDestRect,
 179       const mozilla::gfx::sRGBColor& aShadowColor,
 180       const mozilla::gfx::IntSize& aBlurRadius,
 181       const RectCornerRadii* aInnerClipRadii, DrawTarget* aDestDrawTarget,
 182       bool aMirrorCorners);
 183
 184   /**
 185    * The DrawTarget of the temporary alpha surface.
 186    */
 187   RefPtr<DrawTarget> mDrawTarget;
 188
 189   /**
 190    * The temporary alpha surface.
 191    */
 192   uint8_t* mData = nullptr;
 193
 194   /**
 195    * The object that actually does the blurring for us.
 196    */
 197   mozilla::gfx::AlphaBoxBlur mBlur;
 198
 199   /**
 200    * Indicates using DrawTarget-accelerated blurs.
 201    */
 202   bool mAccelerated = false;
 203 };
 204
 205 #endif /* GFX_BLUR_H */