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