image/Decoder.h

   1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* This Source Code Form is subject to the terms of the Mozilla Public
   3  * License, v. 2.0. If a copy of the MPL was not distributed with this
   4  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   5
   6 #ifndef mozilla_image_Decoder_h
   7 #define mozilla_image_Decoder_h
   8
   9 #include "FrameAnimator.h"
  10 #include "RasterImage.h"
  11 #include "mozilla/RefPtr.h"
  12 #include "DecodePool.h"
  13 #include "DecoderFlags.h"
  14 #include "Downscaler.h"
  15 #include "ImageMetadata.h"
  16 #include "Orientation.h"
  17 #include "SourceBuffer.h"
  18 #include "SurfaceFlags.h"
  19
  20 namespace mozilla {
  21
  22 namespace Telemetry {
  23   enum ID : uint32_t;
  24 } // namespace Telemetry
  25
  26 namespace image {
  27
  28 class Decoder : public IResumable
  29 {
  30 public:
  31
  32   explicit Decoder(RasterImage* aImage);
  33
  34   /**
  35    * Initialize an image decoder. Decoders may not be re-initialized.
  36    */
  37   void Init();
  38
  39   /**
  40    * Decodes, reading all data currently available in the SourceBuffer.
  41    *
  42    * If more data is needed, Decode() will schedule @aOnResume to be called when
  43    * more data is available. If @aOnResume is null or unspecified, the default
  44    * implementation resumes decoding on a DecodePool thread. Most callers should
  45    * use the default implementation.
  46    *
  47    * Any errors are reported by setting the appropriate state on the decoder.
  48    */
  49   nsresult Decode(IResumable* aOnResume = nullptr);
  50
  51   /**
  52    * Given a maximum number of bytes we're willing to decode, @aByteLimit,
  53    * returns true if we should attempt to run this decoder synchronously.
  54    */
  55   bool ShouldSyncDecode(size_t aByteLimit);
  56
  57   /**
  58    * Gets the invalidation region accumulated by the decoder so far, and clears
  59    * the decoder's invalidation region. This means that each call to
  60    * TakeInvalidRect() returns only the invalidation region accumulated since
  61    * the last call to TakeInvalidRect().
  62    */
  63   nsIntRect TakeInvalidRect()
  64   {
  65     nsIntRect invalidRect = mInvalidRect;
  66     mInvalidRect.SetEmpty();
  67     return invalidRect;
  68   }
  69
  70   /**
  71    * Gets the progress changes accumulated by the decoder so far, and clears
  72    * them. This means that each call to TakeProgress() returns only the changes
  73    * accumulated since the last call to TakeProgress().
  74    */
  75   Progress TakeProgress()
  76   {
  77     Progress progress = mProgress;
  78     mProgress = NoProgress;
  79     return progress;
  80   }
  81
  82   /**
  83    * Returns true if there's any progress to report.
  84    */
  85   bool HasProgress() const
  86   {
  87     return mProgress != NoProgress || !mInvalidRect.IsEmpty();
  88   }
  89
  90   // We're not COM-y, so we don't get refcounts by default
  91   NS_INLINE_DECL_THREADSAFE_REFCOUNTING(Decoder, override)
  92
  93   // Implement IResumable.
  94   virtual void Resume() override;
  95
  96   /*
  97    * State.
  98    */
  99
 100   /**
 101    * If we're doing a metadata decode, we only decode the image's headers, which
 102    * is enough to determine the image's intrinsic size. A metadata decode is
 103    * enabled by calling SetMetadataDecode() *before* calling Init().
 104    */
 105   void SetMetadataDecode(bool aMetadataDecode)
 106   {
 107     MOZ_ASSERT(!mInitialized, "Shouldn't be initialized yet");
 108     mMetadataDecode = aMetadataDecode;
 109   }
 110   bool IsMetadataDecode() const { return mMetadataDecode; }
 111
 112   /**
 113    * If this decoder supports downscale-during-decode, sets the target size that
 114    * this image should be decoded to.
 115    *
 116    * If the provided size is unacceptable, an error is returned.
 117    *
 118    * Returning NS_OK from this method is a promise that the decoder will decode
 119    * the image to the requested target size unless it encounters an error.
 120    *
 121    * This must be called before Init() is called.
 122    */
 123   nsresult SetTargetSize(const nsIntSize& aSize);
 124
 125   /**
 126    * Set the requested sample size for this decoder. Used to implement the
 127    * -moz-sample-size media fragment.
 128    *
 129    *  XXX(seth): Support for -moz-sample-size will be removed in bug 1120056.
 130    */
 131   virtual void SetSampleSize(int aSampleSize) { }
 132
 133   /**
 134    * Set an iterator to the SourceBuffer which will feed data to this decoder.
 135    *
 136    * This should be called for almost all decoders; the exceptions are the
 137    * contained decoders of an nsICODecoder, which will be fed manually via Write
 138    * instead.
 139    *
 140    * This must be called before Init() is called.
 141    */
 142   void SetIterator(SourceBufferIterator&& aIterator)
 143   {
 144     MOZ_ASSERT(!mInitialized, "Shouldn't be initialized yet");
 145     mIterator.emplace(Move(aIterator));
 146   }
 147
 148   /**
 149    * Should this decoder send partial invalidations?
 150    */
 151   bool ShouldSendPartialInvalidations() const
 152   {
 153     return !(mDecoderFlags & DecoderFlags::IS_REDECODE);
 154   }
 155
 156   /**
 157    * Should we stop decoding after the first frame?
 158    */
 159   bool IsFirstFrameDecode() const
 160   {
 161     return bool(mDecoderFlags & DecoderFlags::FIRST_FRAME_ONLY);
 162   }
 163
 164   size_t BytesDecoded() const { return mBytesDecoded; }
 165
 166   // The amount of time we've spent inside Write() so far for this decoder.
 167   TimeDuration DecodeTime() const { return mDecodeTime; }
 168
 169   // The number of times Write() has been called so far for this decoder.
 170   uint32_t ChunkCount() const { return mChunkCount; }
 171
 172   // The number of frames we have, including anything in-progress. Thus, this
 173   // is only 0 if we haven't begun any frames.
 174   uint32_t GetFrameCount() { return mFrameCount; }
 175
 176   // The number of complete frames we have (ie, not including anything
 177   // in-progress).
 178   uint32_t GetCompleteFrameCount() {
 179     return mInFrame ? mFrameCount - 1 : mFrameCount;
 180   }
 181
 182   // Did we discover that the image we're decoding is animated?
 183   bool HasAnimation() const { return mImageMetadata.HasAnimation(); }
 184
 185   // Error tracking
 186   bool HasError() const { return HasDataError() || HasDecoderError(); }
 187   bool HasDataError() const { return mDataError; }
 188   bool HasDecoderError() const { return NS_FAILED(mFailCode); }
 189   bool ShouldReportError() const { return mShouldReportError; }
 190   nsresult GetDecoderError() const { return mFailCode; }
 191
 192   /// Did we finish decoding enough that calling Decode() again would be useless?
 193   bool GetDecodeDone() const
 194   {
 195     return mDecodeDone || (mMetadataDecode && HasSize()) ||
 196            HasError() || mDataDone;
 197   }
 198
 199   /// Are we in the middle of a frame right now? Used for assertions only.
 200   bool InFrame() const { return mInFrame; }
 201
 202   /// Should we store surfaces created by this decoder in the SurfaceCache?
 203   bool ShouldUseSurfaceCache() const { return bool(mImage); }
 204
 205   /**
 206    * Returns true if this decoder was aborted.
 207    *
 208    * This may happen due to a low-memory condition, or because another decoder
 209    * was racing with this one to decode the same frames with the same flags and
 210    * this decoder lost the race. Either way, this is not a permanent situation
 211    * and does not constitute an error, so we don't report any errors when this
 212    * happens.
 213    */
 214   bool WasAborted() const { return mDecodeAborted; }
 215
 216   enum DecodeStyle {
 217       PROGRESSIVE, // produce intermediate frames representing the partial
 218                    // state of the image
 219       SEQUENTIAL   // decode to final image immediately
 220   };
 221
 222   /**
 223    * Get or set the DecoderFlags that influence the behavior of this decoder.
 224    */
 225   void SetDecoderFlags(DecoderFlags aDecoderFlags)
 226   {
 227     MOZ_ASSERT(!mInitialized);
 228     mDecoderFlags = aDecoderFlags;
 229   }
 230   DecoderFlags GetDecoderFlags() const { return mDecoderFlags; }
 231
 232   /**
 233    * Get or set the SurfaceFlags that select the kind of output this decoder
 234    * will produce.
 235    */
 236   void SetSurfaceFlags(SurfaceFlags aSurfaceFlags)
 237   {
 238     MOZ_ASSERT(!mInitialized);
 239     mSurfaceFlags = aSurfaceFlags;
 240   }
 241   SurfaceFlags GetSurfaceFlags() const { return mSurfaceFlags; }
 242
 243   bool HasSize() const { return mImageMetadata.HasSize(); }
 244
 245   nsIntSize GetSize() const
 246   {
 247     MOZ_ASSERT(HasSize());
 248     return mImageMetadata.GetSize();
 249   }
 250
 251   virtual Telemetry::ID SpeedHistogram();
 252
 253   ImageMetadata& GetImageMetadata() { return mImageMetadata; }
 254
 255   /**
 256    * Returns a weak pointer to the image associated with this decoder.
 257    */
 258   RasterImage* GetImage() const { MOZ_ASSERT(mImage); return mImage.get(); }
 259
 260   RawAccessFrameRef GetCurrentFrameRef()
 261   {
 262     return mCurrentFrame ? mCurrentFrame->RawAccessRef()
 263                          : RawAccessFrameRef();
 264   }
 265
 266   /**
 267    * Writes data to the decoder. Only public for the benefit of nsICODecoder;
 268    * other callers should use Decode().
 269    *
 270    * @param aBuffer buffer containing the data to be written
 271    * @param aCount the number of bytes to write
 272    *
 273    * Any errors are reported by setting the appropriate state on the decoder.
 274    */
 275   void Write(const char* aBuffer, uint32_t aCount);
 276
 277
 278 protected:
 279   friend class nsICODecoder;
 280
 281   virtual ~Decoder();
 282
 283   /*
 284    * Internal hooks. Decoder implementations may override these and
 285    * only these methods.
 286    */
 287   virtual void InitInternal();
 288   virtual void WriteInternal(const char* aBuffer, uint32_t aCount) = 0;
 289   virtual void FinishInternal();
 290   virtual void FinishWithErrorInternal();
 291
 292   /*
 293    * Progress notifications.
 294    */
 295
 296   // Called by decoders when they determine the size of the image. Informs
 297   // the image of its size and sends notifications.
 298   void PostSize(int32_t aWidth,
 299                 int32_t aHeight,
 300                 Orientation aOrientation = Orientation());
 301
 302   // Called by decoders if they determine that the image has transparency.
 303   //
 304   // This should be fired as early as possible to allow observers to do things
 305   // that affect content, so it's necessarily pessimistic - if there's a
 306   // possibility that the image has transparency, for example because its header
 307   // specifies that it has an alpha channel, we fire PostHasTransparency
 308   // immediately. PostFrameStop's aFrameOpacity argument, on the other hand, is
 309   // only used internally to ImageLib. Because PostFrameStop isn't delivered
 310   // until the entire frame has been decoded, decoders may take into account the
 311   // actual contents of the frame and give a more accurate result.
 312   void PostHasTransparency();
 313
 314   // Called by decoders if they determine that the image is animated.
 315   //
 316   // @param aTimeout The time for which the first frame should be shown before
 317   //                 we advance to the next frame.
 318   void PostIsAnimated(int32_t aFirstFrameTimeout);
 319
 320   // Called by decoders when they end a frame. Informs the image, sends
 321   // notifications, and does internal book-keeping.
 322   // Specify whether this frame is opaque as an optimization.
 323   // For animated images, specify the disposal, blend method and timeout for
 324   // this frame.
 325   void PostFrameStop(Opacity aFrameOpacity = Opacity::SOME_TRANSPARENCY,
 326                      DisposalMethod aDisposalMethod = DisposalMethod::KEEP,
 327                      int32_t aTimeout = 0,
 328                      BlendMethod aBlendMethod = BlendMethod::OVER);
 329
 330   /**
 331    * Called by the decoders when they have a region to invalidate. We may not
 332    * actually pass these invalidations on right away.
 333    *
 334    * @param aRect The invalidation rect in the coordinate system of the unscaled
 335    *              image (that is, the image at its intrinsic size).
 336    * @param aRectAtTargetSize If not Nothing(), the invalidation rect in the
 337    *                          coordinate system of the scaled image (that is,
 338    *                          the image at our target decoding size). This must
 339    *                          be supplied if we're downscaling during decode.
 340    */
 341   void PostInvalidation(const nsIntRect& aRect,
 342                         const Maybe<nsIntRect>& aRectAtTargetSize = Nothing());
 343
 344   // Called by the decoders when they have successfully decoded the image. This
 345   // may occur as the result of the decoder getting to the appropriate point in
 346   // the stream, or by us calling FinishInternal().
 347   //
 348   // May not be called mid-frame.
 349   //
 350   // For animated images, specify the loop count. -1 means loop forever, 0
 351   // means a single iteration, stopping on the last frame.
 352   void PostDecodeDone(int32_t aLoopCount = 0);
 353
 354   // Data errors are the fault of the source data, decoder errors are our fault
 355   void PostDataError();
 356   void PostDecoderError(nsresult aFailCode);
 357
 358   /**
 359    * CompleteDecode() finishes up the decoding process after Decode() determines
 360    * that we're finished. It records final progress and does all the cleanup
 361    * that's possible off-main-thread.
 362    */
 363   void CompleteDecode();
 364
 365   /**
 366    * Allocates a new frame, making it our current frame if successful.
 367    *
 368    * The @aFrameNum parameter only exists as a sanity check; it's illegal to
 369    * create a new frame anywhere but immediately after the existing frames.
 370    *
 371    * If a non-paletted frame is desired, pass 0 for aPaletteDepth.
 372    */
 373   nsresult AllocateFrame(uint32_t aFrameNum,
 374                          const nsIntSize& aTargetSize,
 375                          const nsIntRect& aFrameRect,
 376                          gfx::SurfaceFormat aFormat,
 377                          uint8_t aPaletteDepth = 0);
 378
 379   /// Helper method for decoders which only have 'basic' frame allocation needs.
 380   nsresult AllocateBasicFrame() {
 381     nsIntSize size = GetSize();
 382     return AllocateFrame(0, size, nsIntRect(nsIntPoint(), size),
 383                          gfx::SurfaceFormat::B8G8R8A8);
 384   }
 385
 386   RawAccessFrameRef AllocateFrameInternal(uint32_t aFrameNum,
 387                                           const nsIntSize& aTargetSize,
 388                                           const nsIntRect& aFrameRect,
 389                                           gfx::SurfaceFormat aFormat,
 390                                           uint8_t aPaletteDepth,
 391                                           imgFrame* aPreviousFrame);
 392
 393 protected:
 394   Maybe<Downscaler> mDownscaler;
 395
 396   uint8_t* mImageData;  // Pointer to image data in either Cairo or 8bit format
 397   uint32_t mImageDataLength;
 398   uint32_t* mColormap;  // Current colormap to be used in Cairo format
 399   uint32_t mColormapSize;
 400
 401 private:
 402   RefPtr<RasterImage> mImage;
 403   Maybe<SourceBufferIterator> mIterator;
 404   RawAccessFrameRef mCurrentFrame;
 405   ImageMetadata mImageMetadata;
 406   nsIntRect mInvalidRect; // Tracks an invalidation region in the current frame.
 407   Progress mProgress;
 408
 409   uint32_t mFrameCount; // Number of frames, including anything in-progress
 410
 411   nsresult mFailCode;
 412
 413   // Telemetry data for this decoder.
 414   TimeDuration mDecodeTime;
 415   uint32_t mChunkCount;
 416
 417   DecoderFlags mDecoderFlags;
 418   SurfaceFlags mSurfaceFlags;
 419   size_t mBytesDecoded;
 420
 421   bool mInitialized : 1;
 422   bool mMetadataDecode : 1;
 423   bool mInFrame : 1;
 424   bool mDataDone : 1;
 425   bool mDecodeDone : 1;
 426   bool mDataError : 1;
 427   bool mDecodeAborted : 1;
 428   bool mShouldReportError : 1;
 429 };
 430
 431 } // namespace image
 432 } // namespace mozilla
 433
 434 #endif // mozilla_image_Decoder_h