image/imgFrame.h

   1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*-
   2  *
   3  * This Source Code Form is subject to the terms of the Mozilla Public
   4  * License, v. 2.0. If a copy of the MPL was not distributed with this
   5  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   6
   7 #ifndef mozilla_image_imgFrame_h
   8 #define mozilla_image_imgFrame_h
   9
  10 #include <functional>
  11 #include <utility>
  12
  13 #include "AnimationParams.h"
  14 #include "MainThreadUtils.h"
  15 #include "gfxDrawable.h"
  16 #include "mozilla/layers/SourceSurfaceSharedData.h"
  17 #include "mozilla/Maybe.h"
  18 #include "mozilla/MemoryReporting.h"
  19 #include "mozilla/Monitor.h"
  20 #include "nsRect.h"
  21
  22 namespace mozilla {
  23 namespace image {
  24
  25 class ImageRegion;
  26 class DrawableFrameRef;
  27 class RawAccessFrameRef;
  28
  29 enum class Opacity : uint8_t { FULLY_OPAQUE, SOME_TRANSPARENCY };
  30
  31 class imgFrame {
  32   typedef gfx::SourceSurfaceSharedData SourceSurfaceSharedData;
  33   typedef gfx::DrawTarget DrawTarget;
  34   typedef gfx::SamplingFilter SamplingFilter;
  35   typedef gfx::IntPoint IntPoint;
  36   typedef gfx::IntRect IntRect;
  37   typedef gfx::IntSize IntSize;
  38   typedef gfx::SourceSurface SourceSurface;
  39   typedef gfx::SurfaceFormat SurfaceFormat;
  40
  41  public:
  42   MOZ_DECLARE_REFCOUNTED_TYPENAME(imgFrame)
  43   NS_INLINE_DECL_THREADSAFE_REFCOUNTING(imgFrame)
  44
  45   imgFrame();
  46
  47   /**
  48    * Initialize this imgFrame with an empty surface and prepare it for being
  49    * written to by a decoder.
  50    *
  51    * This is appropriate for use with decoded images, but it should not be used
  52    * when drawing content into an imgFrame, as it may use a different graphics
  53    * backend than normal content drawing.
  54    */
  55   nsresult InitForDecoder(const nsIntSize& aImageSize, SurfaceFormat aFormat,
  56                           bool aNonPremult,
  57                           const Maybe<AnimationParams>& aAnimParams,
  58                           bool aShouldRecycle);
  59
  60   /**
  61    * Reinitialize this imgFrame with the new parameters, but otherwise retain
  62    * the underlying buffer.
  63    *
  64    * This is appropriate for use with animated images, where the decoder was
  65    * given an IDecoderFrameRecycler object which may yield a recycled imgFrame
  66    * that was discarded to save memory.
  67    */
  68   nsresult InitForDecoderRecycle(const AnimationParams& aAnimParams);
  69
  70   /**
  71    * Initialize this imgFrame with a new surface and draw the provided
  72    * gfxDrawable into it.
  73    *
  74    * This is appropriate to use when drawing content into an imgFrame, as it
  75    * uses the same graphics backend as normal content drawing. The downside is
  76    * that the underlying surface may not be stored in a volatile buffer on all
  77    * platforms, and raw access to the surface (using RawAccessRef()) may be much
  78    * more expensive than in the InitForDecoder() case.
  79    *
  80    * aBackend specifies the DrawTarget backend type this imgFrame is supposed
  81    *          to be drawn to.
  82    */
  83   nsresult InitWithDrawable(gfxDrawable* aDrawable, const nsIntSize& aSize,
  84                             const SurfaceFormat aFormat,
  85                             SamplingFilter aSamplingFilter,
  86                             uint32_t aImageFlags, gfx::BackendType aBackend);
  87
  88   DrawableFrameRef DrawableRef();
  89
  90   /**
  91    * Create a RawAccessFrameRef for the frame.
  92    */
  93   RawAccessFrameRef RawAccessRef();
  94
  95   bool Draw(gfxContext* aContext, const ImageRegion& aRegion,
  96             SamplingFilter aSamplingFilter, uint32_t aImageFlags,
  97             float aOpacity);
  98
  99   nsresult ImageUpdated(const nsIntRect& aUpdateRect);
 100
 101   /**
 102    * Mark this imgFrame as completely decoded, and set final options.
 103    *
 104    * You must always call either Finish() or Abort() before releasing the last
 105    * RawAccessFrameRef pointing to an imgFrame.
 106    *
 107    * @param aFrameOpacity    Whether this imgFrame is opaque.
 108    * @param aFinalize        Finalize the underlying surface (e.g. so that it
 109    *                         may be marked as read only if possible).
 110    */
 111   void Finish(Opacity aFrameOpacity = Opacity::SOME_TRANSPARENCY,
 112               bool aFinalize = true);
 113
 114   /**
 115    * Mark this imgFrame as aborted. This informs the imgFrame that if it isn't
 116    * completely decoded now, it never will be.
 117    *
 118    * You must always call either Finish() or Abort() before releasing the last
 119    * RawAccessFrameRef pointing to an imgFrame.
 120    */
 121   void Abort();
 122
 123   /**
 124    * Returns true if this imgFrame has been aborted.
 125    */
 126   bool IsAborted() const;
 127
 128   /**
 129    * Returns true if this imgFrame is completely decoded.
 130    */
 131   bool IsFinished() const;
 132
 133   /**
 134    * Blocks until this imgFrame is either completely decoded, or is marked as
 135    * aborted.
 136    *
 137    * Note that calling this on the main thread _blocks the main thread_. Be very
 138    * careful in your use of this method to avoid excessive main thread jank or
 139    * deadlock.
 140    */
 141   void WaitUntilFinished() const;
 142
 143   /**
 144    * Returns the number of bytes per pixel this imgFrame requires.
 145    */
 146   uint32_t GetBytesPerPixel() const { return 4; }
 147
 148   const IntSize& GetSize() const { return mImageSize; }
 149   IntRect GetRect() const { return IntRect(IntPoint(0, 0), mImageSize); }
 150   const IntRect& GetBlendRect() const { return mBlendRect; }
 151   IntRect GetBoundedBlendRect() const {
 152     return mBlendRect.Intersect(GetRect());
 153   }
 154   FrameTimeout GetTimeout() const { return mTimeout; }
 155   BlendMethod GetBlendMethod() const { return mBlendMethod; }
 156   DisposalMethod GetDisposalMethod() const { return mDisposalMethod; }
 157   bool FormatHasAlpha() const { return mFormat == SurfaceFormat::OS_RGBA; }
 158   void GetImageData(uint8_t** aData, uint32_t* length) const;
 159   uint8_t* GetImageData() const;
 160
 161   const IntRect& GetDirtyRect() const { return mDirtyRect; }
 162   void SetDirtyRect(const IntRect& aDirtyRect) { mDirtyRect = aDirtyRect; }
 163
 164   void FinalizeSurface();
 165   already_AddRefed<SourceSurface> GetSourceSurface();
 166
 167   struct AddSizeOfCbData : public SourceSurface::SizeOfInfo {
 168     AddSizeOfCbData()
 169         : SourceSurface::SizeOfInfo(), mIndex(0), mFinished(false) {}
 170
 171     size_t mIndex;
 172     bool mFinished;
 173   };
 174
 175   typedef std::function<void(AddSizeOfCbData& aMetadata)> AddSizeOfCb;
 176
 177   void AddSizeOfExcludingThis(MallocSizeOf aMallocSizeOf,
 178                               const AddSizeOfCb& aCallback) const;
 179
 180  private:  // methods
 181   ~imgFrame();
 182
 183   bool AreAllPixelsWritten() const;
 184   nsresult ImageUpdatedInternal(const nsIntRect& aUpdateRect);
 185   void GetImageDataInternal(uint8_t** aData, uint32_t* length) const;
 186   uint32_t GetImageBytesPerRow() const;
 187   uint32_t GetImageDataLength() const;
 188   void FinalizeSurfaceInternal();
 189   already_AddRefed<SourceSurface> GetSourceSurfaceInternal();
 190
 191   struct SurfaceWithFormat {
 192     RefPtr<gfxDrawable> mDrawable;
 193     SurfaceFormat mFormat;
 194     SurfaceWithFormat() : mFormat(SurfaceFormat::UNKNOWN) {}
 195     SurfaceWithFormat(gfxDrawable* aDrawable, SurfaceFormat aFormat)
 196         : mDrawable(aDrawable), mFormat(aFormat) {}
 197     SurfaceWithFormat(SurfaceWithFormat&& aOther)
 198         : mDrawable(std::move(aOther.mDrawable)), mFormat(aOther.mFormat) {}
 199     SurfaceWithFormat& operator=(SurfaceWithFormat&& aOther) {
 200       mDrawable = std::move(aOther.mDrawable);
 201       mFormat = aOther.mFormat;
 202       return *this;
 203     }
 204     SurfaceWithFormat& operator=(const SurfaceWithFormat& aOther) = delete;
 205     SurfaceWithFormat(const SurfaceWithFormat& aOther) = delete;
 206     bool IsValid() { return !!mDrawable; }
 207   };
 208
 209   SurfaceWithFormat SurfaceForDrawing(bool aDoPartialDecode, bool aDoTile,
 210                                       ImageRegion& aRegion,
 211                                       SourceSurface* aSurface);
 212
 213  private:  // data
 214   friend class DrawableFrameRef;
 215   friend class RawAccessFrameRef;
 216   friend class UnlockImageDataRunnable;
 217
 218   //////////////////////////////////////////////////////////////////////////////
 219   // Thread-safe mutable data, protected by mMonitor.
 220   //////////////////////////////////////////////////////////////////////////////
 221
 222   mutable Monitor mMonitor;
 223
 224   /**
 225    * Used for rasterized images, this contains the raw pixel data.
 226    */
 227   RefPtr<SourceSurfaceSharedData> mRawSurface;
 228   RefPtr<SourceSurfaceSharedData> mBlankRawSurface;
 229
 230   /**
 231    * Used for vector images that were not rasterized directly. This might be a
 232    * blob recording or native surface.
 233    */
 234   RefPtr<SourceSurface> mOptSurface;
 235
 236   nsIntRect mDecoded;
 237
 238   bool mAborted;
 239   bool mFinished;
 240   bool mShouldRecycle;
 241
 242   //////////////////////////////////////////////////////////////////////////////
 243   // Effectively const data, only mutated in the Init methods.
 244   //////////////////////////////////////////////////////////////////////////////
 245
 246   //! The size of the buffer we are decoding to.
 247   IntSize mImageSize;
 248
 249   //! The contents for the frame, as represented in the encoded image. This may
 250   //! differ from mImageSize because it may be a partial frame. For the first
 251   //! frame, this means we need to shift the data in place, and for animated
 252   //! frames, it likely need to combine with a previous frame to get the full
 253   //! contents.
 254   IntRect mBlendRect;
 255
 256   //! This is the region that has changed between this frame and the previous
 257   //! frame of an animation. For the first frame, this will be the same as
 258   //! mFrameRect.
 259   IntRect mDirtyRect;
 260
 261   //! The timeout for this frame.
 262   FrameTimeout mTimeout;
 263
 264   DisposalMethod mDisposalMethod;
 265   BlendMethod mBlendMethod;
 266   SurfaceFormat mFormat;
 267
 268   bool mNonPremult;
 269 };
 270
 271 /**
 272  * A reference to an imgFrame that holds the imgFrame's surface in memory,
 273  * allowing drawing. If you have a DrawableFrameRef |ref| and |if (ref)| returns
 274  * true, then calls to Draw() and GetSourceSurface() are guaranteed to succeed.
 275  */
 276 class DrawableFrameRef final {
 277   typedef gfx::DataSourceSurface DataSourceSurface;
 278
 279  public:
 280   DrawableFrameRef() {}
 281
 282   explicit DrawableFrameRef(imgFrame* aFrame) : mFrame(aFrame) {
 283     MOZ_ASSERT(aFrame);
 284     MonitorAutoLock lock(aFrame->mMonitor);
 285
 286     if (aFrame->mRawSurface) {
 287       mRef.emplace(aFrame->mRawSurface, DataSourceSurface::READ);
 288       if (!mRef->IsMapped()) {
 289         mFrame = nullptr;
 290         mRef.reset();
 291       }
 292     } else if (!aFrame->mOptSurface || !aFrame->mOptSurface->IsValid()) {
 293       // The optimized surface has become invalid, so we need to redecode.
 294       // For example, on Windows, there may have been a device reset, and
 295       // all D2D surfaces now need to be recreated.
 296       mFrame = nullptr;
 297     }
 298   }
 299
 300   DrawableFrameRef(DrawableFrameRef&& aOther)
 301       : mFrame(std::move(aOther.mFrame)), mRef(std::move(aOther.mRef)) {}
 302
 303   DrawableFrameRef& operator=(DrawableFrameRef&& aOther) {
 304     MOZ_ASSERT(this != &aOther, "Self-moves are prohibited");
 305     mFrame = std::move(aOther.mFrame);
 306     mRef = std::move(aOther.mRef);
 307     return *this;
 308   }
 309
 310   explicit operator bool() const { return bool(mFrame); }
 311
 312   imgFrame* operator->() {
 313     MOZ_ASSERT(mFrame);
 314     return mFrame;
 315   }
 316
 317   const imgFrame* operator->() const {
 318     MOZ_ASSERT(mFrame);
 319     return mFrame;
 320   }
 321
 322   imgFrame* get() { return mFrame; }
 323   const imgFrame* get() const { return mFrame; }
 324
 325   void reset() {
 326     mFrame = nullptr;
 327     mRef.reset();
 328   }
 329
 330  private:
 331   DrawableFrameRef(const DrawableFrameRef& aOther) = delete;
 332   DrawableFrameRef& operator=(const DrawableFrameRef& aOther) = delete;
 333
 334   RefPtr<imgFrame> mFrame;
 335   Maybe<DataSourceSurface::ScopedMap> mRef;
 336 };
 337
 338 /**
 339  * A reference to an imgFrame that holds the imgFrame's surface in memory in a
 340  * format appropriate for access as raw data. If you have a RawAccessFrameRef
 341  * |ref| and |if (ref)| is true, then calls to GetImageData() is guaranteed to
 342  * succeed. This guarantee is stronger than DrawableFrameRef, so everything that
 343  * a valid DrawableFrameRef guarantees is also guaranteed by a valid
 344  * RawAccessFrameRef.
 345  *
 346  * This may be considerably more expensive than is necessary just for drawing,
 347  * so only use this when you need to read or write the raw underlying image data
 348  * that the imgFrame holds.
 349  *
 350  * Once all an imgFrame's RawAccessFrameRefs go out of scope, new
 351  * RawAccessFrameRefs cannot be created.
 352  */
 353 class RawAccessFrameRef final {
 354  public:
 355   RawAccessFrameRef() : mData(nullptr) {}
 356
 357   explicit RawAccessFrameRef(imgFrame* aFrame)
 358       : mFrame(aFrame), mData(nullptr) {
 359     MOZ_ASSERT(mFrame, "Need a frame");
 360
 361     mData = mFrame->GetImageData();
 362     if (!mData) {
 363       mFrame = nullptr;
 364     }
 365   }
 366
 367   RawAccessFrameRef(RawAccessFrameRef&& aOther)
 368       : mFrame(std::move(aOther.mFrame)), mData(aOther.mData) {
 369     aOther.mData = nullptr;
 370   }
 371
 372   ~RawAccessFrameRef() {}
 373
 374   RawAccessFrameRef& operator=(RawAccessFrameRef&& aOther) {
 375     MOZ_ASSERT(this != &aOther, "Self-moves are prohibited");
 376
 377     mFrame = std::move(aOther.mFrame);
 378     mData = aOther.mData;
 379     aOther.mData = nullptr;
 380
 381     return *this;
 382   }
 383
 384   explicit operator bool() const { return bool(mFrame); }
 385
 386   imgFrame* operator->() {
 387     MOZ_ASSERT(mFrame);
 388     return mFrame.get();
 389   }
 390
 391   const imgFrame* operator->() const {
 392     MOZ_ASSERT(mFrame);
 393     return mFrame;
 394   }
 395
 396   imgFrame* get() { return mFrame; }
 397   const imgFrame* get() const { return mFrame; }
 398
 399   void reset() {
 400     mFrame = nullptr;
 401     mData = nullptr;
 402   }
 403
 404   uint8_t* Data() const { return mData; }
 405
 406  private:
 407   RawAccessFrameRef(const RawAccessFrameRef& aOther) = delete;
 408   RawAccessFrameRef& operator=(const RawAccessFrameRef& aOther) = delete;
 409
 410   RefPtr<imgFrame> mFrame;
 411   uint8_t* mData;
 412 };
 413
 414 }  // namespace image
 415 }  // namespace mozilla
 416
 417 #endif  // mozilla_image_imgFrame_h