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               bool aOrientationSwapsWidthAndHeight = false);
 114
 115   /**
 116    * Mark this imgFrame as aborted. This informs the imgFrame that if it isn't
 117    * completely decoded now, it never will be.
 118    *
 119    * You must always call either Finish() or Abort() before releasing the last
 120    * RawAccessFrameRef pointing to an imgFrame.
 121    */
 122   void Abort();
 123
 124   /**
 125    * Returns true if this imgFrame has been aborted.
 126    */
 127   bool IsAborted() const;
 128
 129   /**
 130    * Returns true if this imgFrame is completely decoded.
 131    */
 132   bool IsFinished() const;
 133
 134   /**
 135    * Blocks until this imgFrame is either completely decoded, or is marked as
 136    * aborted.
 137    *
 138    * Note that calling this on the main thread _blocks the main thread_. Be very
 139    * careful in your use of this method to avoid excessive main thread jank or
 140    * deadlock.
 141    */
 142   void WaitUntilFinished() const;
 143
 144   /**
 145    * Returns the number of bytes per pixel this imgFrame requires.
 146    */
 147   uint32_t GetBytesPerPixel() const { return 4; }
 148
 149   const IntSize& GetSize() const { return mImageSize; }
 150   IntRect GetRect() const { return IntRect(IntPoint(0, 0), mImageSize); }
 151   const IntRect& GetBlendRect() const { return mBlendRect; }
 152   IntRect GetBoundedBlendRect() const {
 153     return mBlendRect.Intersect(GetRect());
 154   }
 155   nsIntRect GetDecodedRect() const {
 156     MonitorAutoLock lock(mMonitor);
 157     return mDecoded;
 158   }
 159   FrameTimeout GetTimeout() const { return mTimeout; }
 160   BlendMethod GetBlendMethod() const { return mBlendMethod; }
 161   DisposalMethod GetDisposalMethod() const { return mDisposalMethod; }
 162   bool FormatHasAlpha() const { return mFormat == SurfaceFormat::OS_RGBA; }
 163   void GetImageData(uint8_t** aData, uint32_t* length) const;
 164   uint8_t* GetImageData() const;
 165
 166   const IntRect& GetDirtyRect() const { return mDirtyRect; }
 167   void SetDirtyRect(const IntRect& aDirtyRect) { mDirtyRect = aDirtyRect; }
 168
 169   void FinalizeSurface();
 170   already_AddRefed<SourceSurface> GetSourceSurface();
 171
 172   struct AddSizeOfCbData : public SourceSurface::SizeOfInfo {
 173     AddSizeOfCbData()
 174         : SourceSurface::SizeOfInfo(), mIndex(0), mFinished(false) {}
 175
 176     size_t mIndex;
 177     bool mFinished;
 178   };
 179
 180   typedef std::function<void(AddSizeOfCbData& aMetadata)> AddSizeOfCb;
 181
 182   void AddSizeOfExcludingThis(MallocSizeOf aMallocSizeOf,
 183                               const AddSizeOfCb& aCallback) const;
 184
 185  private:  // methods
 186   ~imgFrame();
 187
 188   bool AreAllPixelsWritten() const MOZ_REQUIRES(mMonitor);
 189   nsresult ImageUpdatedInternal(const nsIntRect& aUpdateRect);
 190   void GetImageDataInternal(uint8_t** aData, uint32_t* length) const;
 191   uint32_t GetImageBytesPerRow() const;
 192   uint32_t GetImageDataLength() const;
 193   void FinalizeSurfaceInternal();
 194   already_AddRefed<SourceSurface> GetSourceSurfaceInternal();
 195
 196   struct SurfaceWithFormat {
 197     RefPtr<gfxDrawable> mDrawable;
 198     SurfaceFormat mFormat;
 199     SurfaceWithFormat() : mFormat(SurfaceFormat::UNKNOWN) {}
 200     SurfaceWithFormat(gfxDrawable* aDrawable, SurfaceFormat aFormat)
 201         : mDrawable(aDrawable), mFormat(aFormat) {}
 202     SurfaceWithFormat(SurfaceWithFormat&& aOther)
 203         : mDrawable(std::move(aOther.mDrawable)), mFormat(aOther.mFormat) {}
 204     SurfaceWithFormat& operator=(SurfaceWithFormat&& aOther) {
 205       mDrawable = std::move(aOther.mDrawable);
 206       mFormat = aOther.mFormat;
 207       return *this;
 208     }
 209     SurfaceWithFormat& operator=(const SurfaceWithFormat& aOther) = delete;
 210     SurfaceWithFormat(const SurfaceWithFormat& aOther) = delete;
 211     bool IsValid() { return !!mDrawable; }
 212   };
 213
 214   SurfaceWithFormat SurfaceForDrawing(bool aDoPartialDecode, bool aDoTile,
 215                                       ImageRegion& aRegion,
 216                                       SourceSurface* aSurface);
 217
 218  private:  // data
 219   friend class DrawableFrameRef;
 220   friend class RawAccessFrameRef;
 221   friend class UnlockImageDataRunnable;
 222
 223   //////////////////////////////////////////////////////////////////////////////
 224   // Thread-safe mutable data, protected by mMonitor.
 225   //////////////////////////////////////////////////////////////////////////////
 226
 227   mutable Monitor mMonitor;
 228
 229   /**
 230    * Used for rasterized images, this contains the raw pixel data.
 231    */
 232   RefPtr<SourceSurfaceSharedData> mRawSurface MOZ_GUARDED_BY(mMonitor);
 233   RefPtr<SourceSurfaceSharedData> mBlankRawSurface MOZ_GUARDED_BY(mMonitor);
 234
 235   /**
 236    * Used for vector images that were not rasterized directly. This might be a
 237    * blob recording or native surface.
 238    */
 239   RefPtr<SourceSurface> mOptSurface MOZ_GUARDED_BY(mMonitor);
 240
 241   nsIntRect mDecoded MOZ_GUARDED_BY(mMonitor);
 242
 243   bool mAborted MOZ_GUARDED_BY(mMonitor);
 244   bool mFinished MOZ_GUARDED_BY(mMonitor);
 245   bool mShouldRecycle MOZ_GUARDED_BY(mMonitor);
 246
 247   //////////////////////////////////////////////////////////////////////////////
 248   // Effectively const data, only mutated in the Init methods.
 249   //////////////////////////////////////////////////////////////////////////////
 250
 251   //! The size of the buffer we are decoding to.
 252   IntSize mImageSize;
 253
 254   //! The contents for the frame, as represented in the encoded image. This may
 255   //! differ from mImageSize because it may be a partial frame. For the first
 256   //! frame, this means we need to shift the data in place, and for animated
 257   //! frames, it likely need to combine with a previous frame to get the full
 258   //! contents.
 259   IntRect mBlendRect;
 260
 261   //! This is the region that has changed between this frame and the previous
 262   //! frame of an animation. For the first frame, this will be the same as
 263   //! mFrameRect.
 264   IntRect mDirtyRect;
 265
 266   //! The timeout for this frame.
 267   FrameTimeout mTimeout;
 268
 269   DisposalMethod mDisposalMethod;
 270   BlendMethod mBlendMethod;
 271   SurfaceFormat mFormat;
 272
 273   bool mNonPremult;
 274 };
 275
 276 /**
 277  * A reference to an imgFrame that holds the imgFrame's surface in memory,
 278  * allowing drawing. If you have a DrawableFrameRef |ref| and |if (ref)| returns
 279  * true, then calls to Draw() and GetSourceSurface() are guaranteed to succeed.
 280  */
 281 class DrawableFrameRef final {
 282   typedef gfx::DataSourceSurface DataSourceSurface;
 283
 284  public:
 285   DrawableFrameRef() {}
 286
 287   explicit DrawableFrameRef(imgFrame* aFrame) : mFrame(aFrame) {
 288     MOZ_ASSERT(aFrame);
 289     MonitorAutoLock lock(aFrame->mMonitor);
 290
 291     if (aFrame->mRawSurface) {
 292       mRef.emplace(aFrame->mRawSurface, DataSourceSurface::READ);
 293       if (!mRef->IsMapped()) {
 294         mFrame = nullptr;
 295         mRef.reset();
 296       }
 297     } else if (!aFrame->mOptSurface || !aFrame->mOptSurface->IsValid()) {
 298       // The optimized surface has become invalid, so we need to redecode.
 299       // For example, on Windows, there may have been a device reset, and
 300       // all D2D surfaces now need to be recreated.
 301       mFrame = nullptr;
 302     }
 303   }
 304
 305   DrawableFrameRef(DrawableFrameRef&& aOther)
 306       : mFrame(std::move(aOther.mFrame)), mRef(std::move(aOther.mRef)) {}
 307
 308   DrawableFrameRef& operator=(DrawableFrameRef&& aOther) {
 309     MOZ_ASSERT(this != &aOther, "Self-moves are prohibited");
 310     mFrame = std::move(aOther.mFrame);
 311     mRef = std::move(aOther.mRef);
 312     return *this;
 313   }
 314
 315   explicit operator bool() const { return bool(mFrame); }
 316
 317   imgFrame* operator->() {
 318     MOZ_ASSERT(mFrame);
 319     return mFrame;
 320   }
 321
 322   const imgFrame* operator->() const {
 323     MOZ_ASSERT(mFrame);
 324     return mFrame;
 325   }
 326
 327   imgFrame* get() { return mFrame; }
 328   const imgFrame* get() const { return mFrame; }
 329
 330   void reset() {
 331     mFrame = nullptr;
 332     mRef.reset();
 333   }
 334
 335  private:
 336   DrawableFrameRef(const DrawableFrameRef& aOther) = delete;
 337   DrawableFrameRef& operator=(const DrawableFrameRef& aOther) = delete;
 338
 339   RefPtr<imgFrame> mFrame;
 340   Maybe<DataSourceSurface::ScopedMap> mRef;
 341 };
 342
 343 /**
 344  * A reference to an imgFrame that holds the imgFrame's surface in memory in a
 345  * format appropriate for access as raw data. If you have a RawAccessFrameRef
 346  * |ref| and |if (ref)| is true, then calls to GetImageData() is guaranteed to
 347  * succeed. This guarantee is stronger than DrawableFrameRef, so everything that
 348  * a valid DrawableFrameRef guarantees is also guaranteed by a valid
 349  * RawAccessFrameRef.
 350  *
 351  * This may be considerably more expensive than is necessary just for drawing,
 352  * so only use this when you need to read or write the raw underlying image data
 353  * that the imgFrame holds.
 354  *
 355  * Once all an imgFrame's RawAccessFrameRefs go out of scope, new
 356  * RawAccessFrameRefs cannot be created.
 357  */
 358 class RawAccessFrameRef final {
 359  public:
 360   RawAccessFrameRef() : mData(nullptr) {}
 361
 362   explicit RawAccessFrameRef(imgFrame* aFrame)
 363       : mFrame(aFrame), mData(nullptr) {
 364     MOZ_ASSERT(mFrame, "Need a frame");
 365
 366     mData = mFrame->GetImageData();
 367     if (!mData) {
 368       mFrame = nullptr;
 369     }
 370   }
 371
 372   RawAccessFrameRef(RawAccessFrameRef&& aOther)
 373       : mFrame(std::move(aOther.mFrame)), mData(aOther.mData) {
 374     aOther.mData = nullptr;
 375   }
 376
 377   ~RawAccessFrameRef() {}
 378
 379   RawAccessFrameRef& operator=(RawAccessFrameRef&& aOther) {
 380     MOZ_ASSERT(this != &aOther, "Self-moves are prohibited");
 381
 382     mFrame = std::move(aOther.mFrame);
 383     mData = aOther.mData;
 384     aOther.mData = nullptr;
 385
 386     return *this;
 387   }
 388
 389   explicit operator bool() const { return bool(mFrame); }
 390
 391   imgFrame* operator->() {
 392     MOZ_ASSERT(mFrame);
 393     return mFrame.get();
 394   }
 395
 396   const imgFrame* operator->() const {
 397     MOZ_ASSERT(mFrame);
 398     return mFrame;
 399   }
 400
 401   imgFrame* get() { return mFrame; }
 402   const imgFrame* get() const { return mFrame; }
 403
 404   void reset() {
 405     mFrame = nullptr;
 406     mData = nullptr;
 407   }
 408
 409   uint8_t* Data() const { return mData; }
 410
 411  private:
 412   RawAccessFrameRef(const RawAccessFrameRef& aOther) = delete;
 413   RawAccessFrameRef& operator=(const RawAccessFrameRef& aOther) = delete;
 414
 415   RefPtr<imgFrame> mFrame;
 416   uint8_t* mData;
 417 };
 418
 419 }  // namespace image
 420 }  // namespace mozilla
 421
 422 #endif  // mozilla_image_imgFrame_h