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