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 "mozilla/Maybe.h"
  11 #include "mozilla/MemoryReporting.h"
  12 #include "mozilla/Monitor.h"
  13 #include "mozilla/Move.h"
  14 #include "AnimationParams.h"
  15 #include "gfxDrawable.h"
  16 #include "imgIContainer.h"
  17 #include "MainThreadUtils.h"
  18
  19 namespace mozilla {
  20 namespace image {
  21
  22 class ImageRegion;
  23 class DrawableFrameRef;
  24 class RawAccessFrameRef;
  25
  26 enum class Opacity : uint8_t { FULLY_OPAQUE, SOME_TRANSPARENCY };
  27
  28 class imgFrame {
  29   typedef gfx::Color Color;
  30   typedef gfx::DataSourceSurface DataSourceSurface;
  31   typedef gfx::DrawTarget DrawTarget;
  32   typedef gfx::SamplingFilter SamplingFilter;
  33   typedef gfx::IntPoint IntPoint;
  34   typedef gfx::IntRect IntRect;
  35   typedef gfx::IntSize IntSize;
  36   typedef gfx::SourceSurface SourceSurface;
  37   typedef gfx::SurfaceFormat SurfaceFormat;
  38
  39  public:
  40   MOZ_DECLARE_REFCOUNTED_TYPENAME(imgFrame)
  41   NS_INLINE_DECL_THREADSAFE_REFCOUNTING(imgFrame)
  42
  43   imgFrame();
  44
  45   /**
  46    * Initialize this imgFrame with an empty surface and prepare it for being
  47    * written to by a decoder.
  48    *
  49    * This is appropriate for use with decoded images, but it should not be used
  50    * when drawing content into an imgFrame, as it may use a different graphics
  51    * backend than normal content drawing.
  52    */
  53   nsresult InitForDecoder(const nsIntSize& aImageSize, SurfaceFormat aFormat,
  54                           bool aNonPremult,
  55                           const Maybe<AnimationParams>& aAnimParams,
  56                           bool aShouldRecycle);
  57
  58   /**
  59    * Reinitialize this imgFrame with the new parameters, but otherwise retain
  60    * the underlying buffer.
  61    *
  62    * This is appropriate for use with animated images, where the decoder was
  63    * given an IDecoderFrameRecycler object which may yield a recycled imgFrame
  64    * that was discarded to save memory.
  65    */
  66   nsresult InitForDecoderRecycle(const AnimationParams& aAnimParams);
  67
  68   /**
  69    * Initialize this imgFrame with a new surface and draw the provided
  70    * gfxDrawable into it.
  71    *
  72    * This is appropriate to use when drawing content into an imgFrame, as it
  73    * uses the same graphics backend as normal content drawing. The downside is
  74    * that the underlying surface may not be stored in a volatile buffer on all
  75    * platforms, and raw access to the surface (using RawAccessRef()) may be much
  76    * more expensive than in the InitForDecoder() case.
  77    *
  78    * aBackend specifies the DrawTarget backend type this imgFrame is supposed
  79    *          to be drawn to.
  80    */
  81   nsresult InitWithDrawable(gfxDrawable* aDrawable, const nsIntSize& aSize,
  82                             const SurfaceFormat aFormat,
  83                             SamplingFilter aSamplingFilter,
  84                             uint32_t aImageFlags, gfx::BackendType aBackend);
  85
  86   DrawableFrameRef DrawableRef();
  87
  88   /**
  89    * Create a RawAccessFrameRef for the frame.
  90    *
  91    * @param aOnlyFinished If true, only return a valid RawAccessFrameRef if
  92    *                      imgFrame::Finish has been called.
  93    */
  94   RawAccessFrameRef RawAccessRef(bool aOnlyFinished = false);
  95
  96   /**
  97    * Make this imgFrame permanently available for raw access.
  98    *
  99    * This is irrevocable, and should be avoided whenever possible, since it
 100    * prevents this imgFrame from being optimized and makes it impossible for its
 101    * volatile buffer to be freed.
 102    *
 103    * It is an error to call this without already holding a RawAccessFrameRef to
 104    * this imgFrame.
 105    */
 106   void SetRawAccessOnly();
 107
 108   bool Draw(gfxContext* aContext, const ImageRegion& aRegion,
 109             SamplingFilter aSamplingFilter, uint32_t aImageFlags,
 110             float aOpacity);
 111
 112   nsresult ImageUpdated(const nsIntRect& aUpdateRect);
 113
 114   /**
 115    * Mark this imgFrame as completely decoded, and set final options.
 116    *
 117    * You must always call either Finish() or Abort() before releasing the last
 118    * RawAccessFrameRef pointing to an imgFrame.
 119    *
 120    * @param aFrameOpacity    Whether this imgFrame is opaque.
 121    * @param aFinalize        Finalize the underlying surface (e.g. so that it
 122    *                         may be marked as read only if possible).
 123    */
 124   void Finish(Opacity aFrameOpacity = Opacity::SOME_TRANSPARENCY,
 125               bool aFinalize = true);
 126
 127   /**
 128    * Mark this imgFrame as aborted. This informs the imgFrame that if it isn't
 129    * completely decoded now, it never will be.
 130    *
 131    * You must always call either Finish() or Abort() before releasing the last
 132    * RawAccessFrameRef pointing to an imgFrame.
 133    */
 134   void Abort();
 135
 136   /**
 137    * Returns true if this imgFrame has been aborted.
 138    */
 139   bool IsAborted() const;
 140
 141   /**
 142    * Returns true if this imgFrame is completely decoded.
 143    */
 144   bool IsFinished() const;
 145
 146   /**
 147    * Blocks until this imgFrame is either completely decoded, or is marked as
 148    * aborted.
 149    *
 150    * Note that calling this on the main thread _blocks the main thread_. Be very
 151    * careful in your use of this method to avoid excessive main thread jank or
 152    * deadlock.
 153    */
 154   void WaitUntilFinished() const;
 155
 156   /**
 157    * Returns the number of bytes per pixel this imgFrame requires.  This is a
 158    * worst-case value that does not take into account the effects of format
 159    * changes caused by Optimize(), since an imgFrame is not optimized throughout
 160    * its lifetime.
 161    */
 162   uint32_t GetBytesPerPixel() const { return 4; }
 163
 164   const IntSize& GetSize() const { return mImageSize; }
 165   IntRect GetRect() const { return IntRect(IntPoint(0, 0), mImageSize); }
 166   const IntRect& GetBlendRect() const { return mBlendRect; }
 167   IntRect GetBoundedBlendRect() const {
 168     return mBlendRect.Intersect(GetRect());
 169   }
 170   FrameTimeout GetTimeout() const { return mTimeout; }
 171   BlendMethod GetBlendMethod() const { return mBlendMethod; }
 172   DisposalMethod GetDisposalMethod() const { return mDisposalMethod; }
 173   bool FormatHasAlpha() const { return mFormat == SurfaceFormat::B8G8R8A8; }
 174   void GetImageData(uint8_t** aData, uint32_t* length) const;
 175   uint8_t* GetImageData() const;
 176
 177   const IntRect& GetDirtyRect() const { return mDirtyRect; }
 178   void SetDirtyRect(const IntRect& aDirtyRect) { mDirtyRect = aDirtyRect; }
 179
 180   void SetOptimizable();
 181
 182   void FinalizeSurface();
 183   already_AddRefed<SourceSurface> GetSourceSurface();
 184
 185   struct AddSizeOfCbData {
 186     AddSizeOfCbData()
 187         : heap(0), nonHeap(0), handles(0), index(0), externalId(0) {}
 188
 189     size_t heap;
 190     size_t nonHeap;
 191     size_t handles;
 192     size_t index;
 193     uint64_t externalId;
 194   };
 195
 196   typedef std::function<void(AddSizeOfCbData& aMetadata)> AddSizeOfCb;
 197
 198   void AddSizeOfExcludingThis(MallocSizeOf aMallocSizeOf,
 199                               const AddSizeOfCb& aCallback) const;
 200
 201  private:  // methods
 202   ~imgFrame();
 203
 204   /**
 205    * Used when the caller desires raw access to the underlying frame buffer.
 206    * If the locking succeeds, the data pointer to the start of the buffer is
 207    * returned, else it returns nullptr.
 208    *
 209    * @param aOnlyFinished If true, only attempt to lock if imgFrame::Finish has
 210    *                      been called.
 211    */
 212   uint8_t* LockImageData(bool aOnlyFinished);
 213   nsresult UnlockImageData();
 214   nsresult Optimize(gfx::DrawTarget* aTarget);
 215
 216   void AssertImageDataLocked() const;
 217
 218   bool AreAllPixelsWritten() const;
 219   nsresult ImageUpdatedInternal(const nsIntRect& aUpdateRect);
 220   void GetImageDataInternal(uint8_t** aData, uint32_t* length) const;
 221   uint32_t GetImageBytesPerRow() const;
 222   uint32_t GetImageDataLength() const;
 223   void FinalizeSurfaceInternal();
 224
 225   /**
 226    * @param aTemporary  If true, it will assume the caller does not require a
 227    *                    wrapping RecycleSourceSurface to protect the underlying
 228    *                    surface from recycling. The reference to the surface
 229    *                    must be freed before releasing the main thread context.
 230    */
 231   already_AddRefed<SourceSurface> GetSourceSurfaceInternal(bool aTemporary);
 232
 233   struct SurfaceWithFormat {
 234     RefPtr<gfxDrawable> mDrawable;
 235     SurfaceFormat mFormat;
 236     SurfaceWithFormat() : mFormat(SurfaceFormat::UNKNOWN) {}
 237     SurfaceWithFormat(gfxDrawable* aDrawable, SurfaceFormat aFormat)
 238         : mDrawable(aDrawable), mFormat(aFormat) {}
 239     SurfaceWithFormat(SurfaceWithFormat&& aOther)
 240         : mDrawable(std::move(aOther.mDrawable)), mFormat(aOther.mFormat) {}
 241     SurfaceWithFormat& operator=(SurfaceWithFormat&& aOther) {
 242       mDrawable = std::move(aOther.mDrawable);
 243       mFormat = aOther.mFormat;
 244       return *this;
 245     }
 246     SurfaceWithFormat& operator=(const SurfaceWithFormat& aOther) = delete;
 247     SurfaceWithFormat(const SurfaceWithFormat& aOther) = delete;
 248     bool IsValid() { return !!mDrawable; }
 249   };
 250
 251   SurfaceWithFormat SurfaceForDrawing(bool aDoPartialDecode, bool aDoTile,
 252                                       ImageRegion& aRegion,
 253                                       SourceSurface* aSurface);
 254
 255  private:  // data
 256   friend class DrawableFrameRef;
 257   friend class RawAccessFrameRef;
 258   friend class RecyclingSourceSurface;
 259   friend class UnlockImageDataRunnable;
 260
 261   //////////////////////////////////////////////////////////////////////////////
 262   // Thread-safe mutable data, protected by mMonitor.
 263   //////////////////////////////////////////////////////////////////////////////
 264
 265   mutable Monitor mMonitor;
 266
 267   /**
 268    * Surface which contains either a weak or a strong reference to its
 269    * underlying data buffer. If it is a weak reference, and there are no strong
 270    * references, the buffer may be released due to events such as low memory.
 271    */
 272   RefPtr<DataSourceSurface> mRawSurface;
 273   RefPtr<DataSourceSurface> mBlankRawSurface;
 274
 275   /**
 276    * Refers to the same data as mRawSurface, but when set, it guarantees that
 277    * we hold a strong reference to the underlying data buffer.
 278    */
 279   RefPtr<DataSourceSurface> mLockedSurface;
 280   RefPtr<DataSourceSurface> mBlankLockedSurface;
 281
 282   /**
 283    * Optimized copy of mRawSurface for the DrawTarget that will render it. This
 284    * is unused if the DrawTarget is able to render DataSourceSurface buffers
 285    * directly.
 286    */
 287   RefPtr<SourceSurface> mOptSurface;
 288
 289   nsIntRect mDecoded;
 290
 291   //! Number of RawAccessFrameRefs currently alive for this imgFrame.
 292   int16_t mLockCount;
 293
 294   //! Number of RecyclingSourceSurface's currently alive for this imgFrame.
 295   int16_t mRecycleLockCount;
 296
 297   bool mAborted;
 298   bool mFinished;
 299   bool mOptimizable;
 300   bool mShouldRecycle;
 301
 302   //////////////////////////////////////////////////////////////////////////////
 303   // Effectively const data, only mutated in the Init methods.
 304   //////////////////////////////////////////////////////////////////////////////
 305
 306   //! The size of the buffer we are decoding to.
 307   IntSize mImageSize;
 308
 309   //! The contents for the frame, as represented in the encoded image. This may
 310   //! differ from mImageSize because it may be a partial frame. For the first
 311   //! frame, this means we need to shift the data in place, and for animated
 312   //! frames, it likely need to combine with a previous frame to get the full
 313   //! contents.
 314   IntRect mBlendRect;
 315
 316   //! This is the region that has changed between this frame and the previous
 317   //! frame of an animation. For the first frame, this will be the same as
 318   //! mFrameRect.
 319   IntRect mDirtyRect;
 320
 321   //! The timeout for this frame.
 322   FrameTimeout mTimeout;
 323
 324   DisposalMethod mDisposalMethod;
 325   BlendMethod mBlendMethod;
 326   SurfaceFormat mFormat;
 327
 328   bool mNonPremult;
 329 };
 330
 331 /**
 332  * A reference to an imgFrame that holds the imgFrame's surface in memory,
 333  * allowing drawing. If you have a DrawableFrameRef |ref| and |if (ref)| returns
 334  * true, then calls to Draw() and GetSourceSurface() are guaranteed to succeed.
 335  */
 336 class DrawableFrameRef final {
 337   typedef gfx::DataSourceSurface DataSourceSurface;
 338
 339  public:
 340   DrawableFrameRef() {}
 341
 342   explicit DrawableFrameRef(imgFrame* aFrame) : mFrame(aFrame) {
 343     MOZ_ASSERT(aFrame);
 344     MonitorAutoLock lock(aFrame->mMonitor);
 345
 346     if (aFrame->mRawSurface) {
 347       mRef.emplace(aFrame->mRawSurface, DataSourceSurface::READ);
 348       if (!mRef->IsMapped()) {
 349         mFrame = nullptr;
 350         mRef.reset();
 351       }
 352     } else {
 353       MOZ_ASSERT(aFrame->mOptSurface);
 354     }
 355   }
 356
 357   DrawableFrameRef(DrawableFrameRef&& aOther)
 358       : mFrame(aOther.mFrame.forget()), mRef(std::move(aOther.mRef)) {}
 359
 360   DrawableFrameRef& operator=(DrawableFrameRef&& aOther) {
 361     MOZ_ASSERT(this != &aOther, "Self-moves are prohibited");
 362     mFrame = aOther.mFrame.forget();
 363     mRef = std::move(aOther.mRef);
 364     return *this;
 365   }
 366
 367   explicit operator bool() const { return bool(mFrame); }
 368
 369   imgFrame* operator->() {
 370     MOZ_ASSERT(mFrame);
 371     return mFrame;
 372   }
 373
 374   const imgFrame* operator->() const {
 375     MOZ_ASSERT(mFrame);
 376     return mFrame;
 377   }
 378
 379   imgFrame* get() { return mFrame; }
 380   const imgFrame* get() const { return mFrame; }
 381
 382   void reset() {
 383     mFrame = nullptr;
 384     mRef.reset();
 385   }
 386
 387  private:
 388   DrawableFrameRef(const DrawableFrameRef& aOther) = delete;
 389   DrawableFrameRef& operator=(const DrawableFrameRef& aOther) = delete;
 390
 391   RefPtr<imgFrame> mFrame;
 392   Maybe<DataSourceSurface::ScopedMap> mRef;
 393 };
 394
 395 /**
 396  * A reference to an imgFrame that holds the imgFrame's surface in memory in a
 397  * format appropriate for access as raw data. If you have a RawAccessFrameRef
 398  * |ref| and |if (ref)| is true, then calls to GetImageData() is guaranteed to
 399  * succeed. This guarantee is stronger than DrawableFrameRef, so everything that
 400  * a valid DrawableFrameRef guarantees is also guaranteed by a valid
 401  * RawAccessFrameRef.
 402  *
 403  * This may be considerably more expensive than is necessary just for drawing,
 404  * so only use this when you need to read or write the raw underlying image data
 405  * that the imgFrame holds.
 406  *
 407  * Once all an imgFrame's RawAccessFrameRefs go out of scope, new
 408  * RawAccessFrameRefs cannot be created.
 409  */
 410 class RawAccessFrameRef final {
 411  public:
 412   RawAccessFrameRef() : mData(nullptr) {}
 413
 414   explicit RawAccessFrameRef(imgFrame* aFrame, bool aOnlyFinished)
 415       : mFrame(aFrame), mData(nullptr) {
 416     MOZ_ASSERT(mFrame, "Need a frame");
 417
 418     mData = mFrame->LockImageData(aOnlyFinished);
 419     if (!mData) {
 420       mFrame = nullptr;
 421     }
 422   }
 423
 424   RawAccessFrameRef(RawAccessFrameRef&& aOther)
 425       : mFrame(aOther.mFrame.forget()), mData(aOther.mData) {
 426     aOther.mData = nullptr;
 427   }
 428
 429   ~RawAccessFrameRef() {
 430     if (mFrame) {
 431       mFrame->UnlockImageData();
 432     }
 433   }
 434
 435   RawAccessFrameRef& operator=(RawAccessFrameRef&& aOther) {
 436     MOZ_ASSERT(this != &aOther, "Self-moves are prohibited");
 437
 438     if (mFrame) {
 439       mFrame->UnlockImageData();
 440     }
 441
 442     mFrame = aOther.mFrame.forget();
 443     mData = aOther.mData;
 444     aOther.mData = nullptr;
 445
 446     return *this;
 447   }
 448
 449   explicit operator bool() const { return bool(mFrame); }
 450
 451   imgFrame* operator->() {
 452     MOZ_ASSERT(mFrame);
 453     return mFrame.get();
 454   }
 455
 456   const imgFrame* operator->() const {
 457     MOZ_ASSERT(mFrame);
 458     return mFrame;
 459   }
 460
 461   imgFrame* get() { return mFrame; }
 462   const imgFrame* get() const { return mFrame; }
 463
 464   void reset() {
 465     if (mFrame) {
 466       mFrame->UnlockImageData();
 467     }
 468     mFrame = nullptr;
 469     mData = nullptr;
 470   }
 471
 472   uint8_t* Data() const { return mData; }
 473
 474  private:
 475   RawAccessFrameRef(const RawAccessFrameRef& aOther) = delete;
 476   RawAccessFrameRef& operator=(const RawAccessFrameRef& aOther) = delete;
 477
 478   RefPtr<imgFrame> mFrame;
 479   uint8_t* mData;
 480 };
 481
 482 }  // namespace image
 483 }  // namespace mozilla
 484
 485 #endif  // mozilla_image_imgFrame_h