gfx/layers/ThebesLayerBuffer.h

   1 /* -*- Mode: C++; tab-width: 20; indent-tabs-mode: nil; c-basic-offset: 2 -*-
   2  * ***** BEGIN LICENSE BLOCK *****
   3  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
   4  *
   5  * The contents of this file are subject to the Mozilla Public License Version
   6  * 1.1 (the "License"); you may not use this file except in compliance with
   7  * the License. You may obtain a copy of the License at
   8  * http://www.mozilla.org/MPL/
   9  *
  10  * Software distributed under the License is distributed on an "AS IS" basis,
  11  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  12  * for the specific language governing rights and limitations under the
  13  * License.
  14  *
  15  * The Original Code is Mozilla Corporation code.
  16  *
  17  * The Initial Developer of the Original Code is Mozilla Foundation.
  18  * Portions created by the Initial Developer are Copyright (C) 2010
  19  * the Initial Developer. All Rights Reserved.
  20  *
  21  * Contributor(s):
  22  *   Robert O'Callahan <robert@ocallahan.org>
  23  *
  24  * Alternatively, the contents of this file may be used under the terms of
  25  * either the GNU General Public License Version 2 or later (the "GPL"), or
  26  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  27  * in which case the provisions of the GPL or the LGPL are applicable instead
  28  * of those above. If you wish to allow use of your version of this file only
  29  * under the terms of either the GPL or the LGPL, and not to allow others to
  30  * use your version of this file under the terms of the MPL, indicate your
  31  * decision by deleting the provisions above and replace them with the notice
  32  * and other provisions required by the GPL or the LGPL. If you do not delete
  33  * the provisions above, a recipient may use your version of this file under
  34  * the terms of any one of the MPL, the GPL or the LGPL.
  35  *
  36  * ***** END LICENSE BLOCK ***** */
  37
  38 #ifndef THEBESLAYERBUFFER_H_
  39 #define THEBESLAYERBUFFER_H_
  40
  41 #include "gfxContext.h"
  42 #include "gfxASurface.h"
  43 #include "nsRegion.h"
  44
  45 namespace mozilla {
  46 namespace layers {
  47
  48 class ThebesLayer;
  49
  50 /**
  51  * This class encapsulates the buffer used to retain ThebesLayer contents,
  52  * i.e., the contents of the layer's GetVisibleRegion().
  53  *
  54  * This is a cairo/Thebes surface, but with a literal twist. Scrolling
  55  * causes the layer's visible region to move. We want to keep
  56  * reusing the same surface if the region size hasn't changed, but we don't
  57  * want to keep moving the contents of the surface around in memory. So
  58  * we use a trick.
  59  * Consider just the vertical case, and suppose the buffer is H pixels
  60  * high and we're scrolling down by N pixels. Instead of copying the
  61  * buffer contents up by N pixels, we leave the buffer contents in place,
  62  * and paint content rows H to H+N-1 into rows 0 to N-1 of the buffer.
  63  * Then we can refresh the screen by painting rows N to H-1 of the buffer
  64  * at row 0 on the screen, and then painting rows 0 to N-1 of the buffer
  65  * at row H-N on the screen.
  66  * mBufferRotation.y would be N in this example.
  67  */
  68 class ThebesLayerBuffer {
  69 public:
  70   typedef gfxASurface::gfxContentType ContentType;
  71
  72   /**
  73    * Controls the size of the backing buffer of this.
  74    * - SizedToVisibleBounds: the backing buffer is exactly the same
  75    *   size as the bounds of ThebesLayer's visible region
  76    * - ContainsVisibleBounds: the backing buffer is large enough to
  77    *   fit visible bounds.  May be larger.
  78    */
  79   enum BufferSizePolicy {
  80     SizedToVisibleBounds,
  81     ContainsVisibleBounds
  82   };
  83
  84   ThebesLayerBuffer(BufferSizePolicy aBufferSizePolicy)
  85     : mBufferDims(0,0)
  86     , mBufferRotation(0,0)
  87     , mBufferSizePolicy(aBufferSizePolicy)
  88   {
  89     MOZ_COUNT_CTOR(ThebesLayerBuffer);
  90   }
  91   virtual ~ThebesLayerBuffer()
  92   {
  93     MOZ_COUNT_DTOR(ThebesLayerBuffer);
  94   }
  95
  96   /**
  97    * Wipe out all retained contents. Call this when the entire
  98    * buffer becomes invalid.
  99    */
 100   void Clear()
 101   {
 102     mBuffer = nsnull;
 103     mBufferDims.SizeTo(0, 0);
 104     mBufferRect.Empty();
 105   }
 106
 107   /**
 108    * This is returned by BeginPaint. The caller should draw into mContext.
 109    * mRegionToDraw must be drawn. mRegionToInvalidate has been invalidated
 110    * by ThebesLayerBuffer and must be redrawn on the screen.
 111    * mRegionToInvalidate is set when the buffer has changed from
 112    * opaque to transparent or vice versa, since the details of rendering can
 113    * depend on the buffer type.
 114    */
 115   struct PaintState {
 116     nsRefPtr<gfxContext> mContext;
 117     nsIntRegion mRegionToDraw;
 118     nsIntRegion mRegionToInvalidate;
 119   };
 120
 121   /**
 122    * Start a drawing operation. This returns a PaintState describing what
 123    * needs to be drawn to bring the buffer up to date in the visible region.
 124    * This queries aLayer to get the currently valid and visible regions.
 125    * The returned mContext may be null if mRegionToDraw is empty.
 126    * Otherwise it must not be null.
 127    * mRegionToInvalidate will contain mRegionToDraw.
 128    */
 129   PaintState BeginPaint(ThebesLayer* aLayer, ContentType aContentType,
 130                         float aXResolution, float aYResolution);
 131
 132   /**
 133    * Return a new surface of |aSize| and |aType|.
 134    */
 135   virtual already_AddRefed<gfxASurface>
 136   CreateBuffer(ContentType aType, const nsIntSize& aSize) = 0;
 137
 138   /**
 139    * Get the underlying buffer, if any. This is useful because we can pass
 140    * in the buffer as the default "reference surface" if there is one.
 141    * Don't use it for anything else!
 142    */
 143   gfxASurface* GetBuffer() { return mBuffer; }
 144
 145 protected:
 146   enum XSide {
 147     LEFT, RIGHT
 148   };
 149   enum YSide {
 150     TOP, BOTTOM
 151   };
 152   nsIntRect GetQuadrantRectangle(XSide aXSide, YSide aYSide);
 153   void DrawBufferQuadrant(gfxContext* aTarget, XSide aXSide, YSide aYSide,
 154                           float aOpacity, float aXRes, float aYRes);
 155   void DrawBufferWithRotation(gfxContext* aTarget, float aOpacity,
 156                               float aXRes, float aYRes);
 157
 158   /**
 159    * |BufferRect()| is the rect of device pixels that this
 160    * ThebesLayerBuffer covers.  That is what DrawBufferWithRotation()
 161    * will paint when it's called.
 162    *
 163    * |BufferDims()| is the actual dimensions of the underlying surface
 164    * maintained by this, also in device pixels.  It is *not*
 165    * necessarily true that |BufferRect().Size() == BufferDims()|.
 166    * They may differ if a ThebesLayer is drawn at a non-1.0
 167    * resolution.
 168    */
 169   const nsIntSize& BufferDims() const { return mBufferDims; }
 170   const nsIntRect& BufferRect() const { return mBufferRect; }
 171   const nsIntPoint& BufferRotation() const { return mBufferRotation; }
 172
 173   already_AddRefed<gfxASurface>
 174   SetBuffer(gfxASurface* aBuffer, const nsIntSize& aBufferDims,
 175             const nsIntRect& aBufferRect, const nsIntPoint& aBufferRotation)
 176   {
 177     nsRefPtr<gfxASurface> tmp = mBuffer.forget();
 178     mBuffer = aBuffer;
 179     mBufferDims = aBufferDims;
 180     mBufferRect = aBufferRect;
 181     mBufferRotation = aBufferRotation;
 182     return tmp.forget();
 183   }
 184
 185   /**
 186    * Get a context at the specified resolution for updating |aBounds|,
 187    * which must be contained within a single quadrant.
 188    */
 189   already_AddRefed<gfxContext>
 190   GetContextForQuadrantUpdate(const nsIntRect& aBounds,
 191                               float aXResolution, float aYResolution);
 192
 193 private:
 194   PRBool BufferSizeOkFor(const nsIntSize& aSize)
 195   {
 196     return (aSize == mBufferDims ||
 197             (SizedToVisibleBounds != mBufferSizePolicy &&
 198              aSize < mBufferDims));
 199   }
 200
 201   nsRefPtr<gfxASurface> mBuffer;
 202   /**
 203    * The actual dimensions of mBuffer.  For the ContainsVisibleBounds
 204    * policy or with resolution-scaled drawing, mBufferDims might be
 205    * different than mBufferRect.Size().
 206    */
 207   nsIntSize             mBufferDims;
 208   /** The area of the ThebesLayer that is covered by the buffer as a whole */
 209   nsIntRect             mBufferRect;
 210   /**
 211    * The x and y rotation of the buffer. Conceptually the buffer
 212    * has its origin translated to mBufferRect.TopLeft() - mBufferRotation,
 213    * is tiled to fill the plane, and the result is clipped to mBufferRect.
 214    * So the pixel at mBufferRotation within the buffer is what gets painted at
 215    * mBufferRect.TopLeft().
 216    * This is "rotation" in the sense of rotating items in a linear buffer,
 217    * where items falling off the end of the buffer are returned to the
 218    * buffer at the other end, not 2D rotation!
 219    */
 220   nsIntPoint            mBufferRotation;
 221   BufferSizePolicy      mBufferSizePolicy;
 222 };
 223
 224 }
 225 }
 226
 227 #endif /* THEBESLAYERBUFFER_H_ */