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/Maybe.h"
  12 #include "mozilla/NotNull.h"
  13 #include "mozilla/RefPtr.h"
  14 #include "AnimationParams.h"
  15 #include "DecoderFlags.h"
  16 #include "Downscaler.h"
  17 #include "ImageMetadata.h"
  18 #include "Orientation.h"
  19 #include "SourceBuffer.h"
  20 #include "StreamingLexer.h"
  21 #include "SurfaceFlags.h"
  22
  23 namespace mozilla {
  24
  25 namespace Telemetry {
  26   enum HistogramID : uint32_t;
  27 } // namespace Telemetry
  28
  29 namespace image {
  30
  31 class imgFrame;
  32
  33 struct DecoderFinalStatus final
  34 {
  35   DecoderFinalStatus(bool aWasMetadataDecode,
  36                      bool aFinished,
  37                      bool aHadError,
  38                      bool aShouldReportError)
  39     : mWasMetadataDecode(aWasMetadataDecode)
  40     , mFinished(aFinished)
  41     , mHadError(aHadError)
  42     , mShouldReportError(aShouldReportError)
  43   { }
  44
  45   /// True if this was a metadata decode.
  46   const bool mWasMetadataDecode : 1;
  47
  48   /// True if this decoder finished, whether successfully or due to failure.
  49   const bool mFinished : 1;
  50
  51   /// True if this decoder encountered an error.
  52   const bool mHadError : 1;
  53
  54   /// True if this decoder encountered the kind of error that should be reported
  55   /// to the console.
  56   const bool mShouldReportError : 1;
  57 };
  58
  59 struct DecoderTelemetry final
  60 {
  61   DecoderTelemetry(const Maybe<Telemetry::HistogramID>& aSpeedHistogram,
  62                    size_t aBytesDecoded,
  63                    uint32_t aChunkCount,
  64                    TimeDuration aDecodeTime)
  65     : mSpeedHistogram(aSpeedHistogram)
  66     , mBytesDecoded(aBytesDecoded)
  67     , mChunkCount(aChunkCount)
  68     , mDecodeTime(aDecodeTime)
  69   { }
  70
  71   /// @return our decoder's speed, in KBps.
  72   int32_t Speed() const
  73   {
  74     return mBytesDecoded / (1024 * mDecodeTime.ToSeconds());
  75   }
  76
  77   /// @return our decoder's decode time, in microseconds.
  78   int32_t DecodeTimeMicros() { return mDecodeTime.ToMicroseconds(); }
  79
  80   /// The per-image-format telemetry ID for recording our decoder's speed, or
  81   /// Nothing() if we don't record speed telemetry for this kind of decoder.
  82   const Maybe<Telemetry::HistogramID> mSpeedHistogram;
  83
  84   /// The number of bytes of input our decoder processed.
  85   const size_t mBytesDecoded;
  86
  87   /// The number of chunks our decoder's input was divided into.
  88   const uint32_t mChunkCount;
  89
  90   /// The amount of time our decoder spent inside DoDecode().
  91   const TimeDuration mDecodeTime;
  92 };
  93
  94 class Decoder
  95 {
  96 public:
  97   NS_INLINE_DECL_THREADSAFE_REFCOUNTING(Decoder)
  98
  99   explicit Decoder(RasterImage* aImage);
 100
 101   /**
 102    * Initialize an image decoder. Decoders may not be re-initialized.
 103    *
 104    * @return NS_OK if the decoder could be initialized successfully.
 105    */
 106   nsresult Init();
 107
 108   /**
 109    * Decodes, reading all data currently available in the SourceBuffer.
 110    *
 111    * If more data is needed and @aOnResume is non-null, Decode() will schedule
 112    * @aOnResume to be called when more data is available.
 113    *
 114    * @return a LexerResult which may indicate:
 115    *   - the image has been successfully decoded (TerminalState::SUCCESS), or
 116    *   - the image has failed to decode (TerminalState::FAILURE), or
 117    *   - the decoder is yielding until it gets more data (Yield::NEED_MORE_DATA), or
 118    *   - the decoder is yielding to allow the caller to access intermediate
 119    *     output (Yield::OUTPUT_AVAILABLE).
 120    */
 121   LexerResult Decode(IResumable* aOnResume = nullptr);
 122
 123   /**
 124    * Terminate this decoder in a failure state, just as if the decoder
 125    * implementation had returned TerminalState::FAILURE from DoDecode().
 126    *
 127    * XXX(seth): This method should be removed ASAP; it exists only because
 128    * RasterImage::FinalizeDecoder() requires an actual Decoder object as an
 129    * argument, so we can't simply tell RasterImage a decode failed except via an
 130    * intervening decoder. We'll fix this in bug 1291071.
 131    */
 132   LexerResult TerminateFailure();
 133
 134   /**
 135    * Given a maximum number of bytes we're willing to decode, @aByteLimit,
 136    * returns true if we should attempt to run this decoder synchronously.
 137    */
 138   bool ShouldSyncDecode(size_t aByteLimit);
 139
 140   /**
 141    * Gets the invalidation region accumulated by the decoder so far, and clears
 142    * the decoder's invalidation region. This means that each call to
 143    * TakeInvalidRect() returns only the invalidation region accumulated since
 144    * the last call to TakeInvalidRect().
 145    */
 146   nsIntRect TakeInvalidRect()
 147   {
 148     nsIntRect invalidRect = mInvalidRect;
 149     mInvalidRect.SetEmpty();
 150     return invalidRect;
 151   }
 152
 153   /**
 154    * Gets the progress changes accumulated by the decoder so far, and clears
 155    * them. This means that each call to TakeProgress() returns only the changes
 156    * accumulated since the last call to TakeProgress().
 157    */
 158   Progress TakeProgress()
 159   {
 160     Progress progress = mProgress;
 161     mProgress = NoProgress;
 162     return progress;
 163   }
 164
 165   /**
 166    * Returns true if there's any progress to report.
 167    */
 168   bool HasProgress() const
 169   {
 170     return mProgress != NoProgress || !mInvalidRect.IsEmpty() || mFinishedNewFrame;
 171   }
 172
 173   /*
 174    * State.
 175    */
 176
 177   /**
 178    * If we're doing a metadata decode, we only decode the image's headers, which
 179    * is enough to determine the image's intrinsic size. A metadata decode is
 180    * enabled by calling SetMetadataDecode() *before* calling Init().
 181    */
 182   void SetMetadataDecode(bool aMetadataDecode)
 183   {
 184     MOZ_ASSERT(!mInitialized, "Shouldn't be initialized yet");
 185     mMetadataDecode = aMetadataDecode;
 186   }
 187   bool IsMetadataDecode() const { return mMetadataDecode; }
 188
 189   /**
 190    * Sets the output size of this decoder. If this is smaller than the intrinsic
 191    * size of the image, we'll downscale it while decoding. For memory usage
 192    * reasons, upscaling is forbidden and will trigger assertions in debug
 193    * builds.
 194    *
 195    * Not calling SetOutputSize() means that we should just decode at the
 196    * intrinsic size, whatever it is.
 197    *
 198    * If SetOutputSize() was called, ExplicitOutputSize() can be used to
 199    * determine the value that was passed to it.
 200    *
 201    * This must be called before Init() is called.
 202    */
 203   void SetOutputSize(const gfx::IntSize& aSize);
 204
 205   /**
 206    * @return the output size of this decoder. If this is smaller than the
 207    * intrinsic size, then the image will be downscaled during the decoding
 208    * process.
 209    *
 210    * Illegal to call if HasSize() returns false.
 211    */
 212   gfx::IntSize OutputSize() const { MOZ_ASSERT(HasSize()); return *mOutputSize; }
 213
 214   /**
 215    * @return either the size passed to SetOutputSize() or Nothing(), indicating
 216    * that SetOutputSize() was not explicitly called.
 217    */
 218   Maybe<gfx::IntSize> ExplicitOutputSize() const;
 219
 220   /**
 221    * Sets the expected image size of this decoder. Decoding will fail if this
 222    * does not match.
 223    */
 224   void SetExpectedSize(const gfx::IntSize& aSize)
 225   {
 226     mExpectedSize.emplace(aSize);
 227   }
 228
 229   /**
 230    * Is the image size what was expected, if specified?
 231    */
 232   bool IsExpectedSize() const
 233   {
 234     return mExpectedSize.isNothing() || *mExpectedSize == Size();
 235   }
 236
 237   /**
 238    * Set an iterator to the SourceBuffer which will feed data to this decoder.
 239    * This must always be called before calling Init(). (And only before Init().)
 240    *
 241    * XXX(seth): We should eliminate this method and pass a SourceBufferIterator
 242    * to the various decoder constructors instead.
 243    */
 244   void SetIterator(SourceBufferIterator&& aIterator)
 245   {
 246     MOZ_ASSERT(!mInitialized, "Shouldn't be initialized yet");
 247     mIterator.emplace(std::move(aIterator));
 248   }
 249
 250   SourceBuffer* GetSourceBuffer() const
 251   {
 252     return mIterator->Owner();
 253   }
 254
 255   /**
 256    * Should this decoder send partial invalidations?
 257    */
 258   bool ShouldSendPartialInvalidations() const
 259   {
 260     return !(mDecoderFlags & DecoderFlags::IS_REDECODE);
 261   }
 262
 263   /**
 264    * Should we stop decoding after the first frame?
 265    */
 266   bool IsFirstFrameDecode() const
 267   {
 268     return bool(mDecoderFlags & DecoderFlags::FIRST_FRAME_ONLY);
 269   }
 270
 271   /**
 272    * @return the number of complete animation frames which have been decoded so
 273    * far, if it has changed since the last call to TakeCompleteFrameCount();
 274    * otherwise, returns Nothing().
 275    */
 276   Maybe<uint32_t> TakeCompleteFrameCount();
 277
 278   // The number of frames we have, including anything in-progress. Thus, this
 279   // is only 0 if we haven't begun any frames.
 280   uint32_t GetFrameCount() { return mFrameCount; }
 281
 282   // Did we discover that the image we're decoding is animated?
 283   bool HasAnimation() const { return mImageMetadata.HasAnimation(); }
 284
 285   // Error tracking
 286   bool HasError() const { return mError; }
 287   bool ShouldReportError() const { return mShouldReportError; }
 288
 289   // Finalize frames
 290   void SetFinalizeFrames(bool aFinalize) { mFinalizeFrames = aFinalize; }
 291   bool GetFinalizeFrames() const { return mFinalizeFrames; }
 292
 293   /// Did we finish decoding enough that calling Decode() again would be useless?
 294   bool GetDecodeDone() const
 295   {
 296     return mReachedTerminalState || mDecodeDone ||
 297            (mMetadataDecode && HasSize()) || HasError();
 298   }
 299
 300   /// Are we in the middle of a frame right now? Used for assertions only.
 301   bool InFrame() const { return mInFrame; }
 302
 303   /// Is the image valid if embedded inside an ICO.
 304   virtual bool IsValidICOResource() const
 305   {
 306     return false;
 307   }
 308
 309   /// Type of decoder.
 310   virtual DecoderType GetType() const
 311   {
 312     return DecoderType::UNKNOWN;
 313   }
 314
 315   enum DecodeStyle {
 316       PROGRESSIVE, // produce intermediate frames representing the partial
 317                    // state of the image
 318       SEQUENTIAL   // decode to final image immediately
 319   };
 320
 321   /**
 322    * Get or set the DecoderFlags that influence the behavior of this decoder.
 323    */
 324   void SetDecoderFlags(DecoderFlags aDecoderFlags)
 325   {
 326     MOZ_ASSERT(!mInitialized);
 327     mDecoderFlags = aDecoderFlags;
 328   }
 329   DecoderFlags GetDecoderFlags() const { return mDecoderFlags; }
 330
 331   /**
 332    * Get or set the SurfaceFlags that select the kind of output this decoder
 333    * will produce.
 334    */
 335   void SetSurfaceFlags(SurfaceFlags aSurfaceFlags)
 336   {
 337     MOZ_ASSERT(!mInitialized);
 338     mSurfaceFlags = aSurfaceFlags;
 339   }
 340   SurfaceFlags GetSurfaceFlags() const { return mSurfaceFlags; }
 341
 342   /// @return true if we know the intrinsic size of the image we're decoding.
 343   bool HasSize() const { return mImageMetadata.HasSize(); }
 344
 345   /**
 346    * @return the intrinsic size of the image we're decoding.
 347    *
 348    * Illegal to call if HasSize() returns false.
 349    */
 350   gfx::IntSize Size() const
 351   {
 352     MOZ_ASSERT(HasSize());
 353     return mImageMetadata.GetSize();
 354   }
 355
 356   /**
 357    * @return an IntRect which covers the entire area of this image at its
 358    * intrinsic size, appropriate for use as a frame rect when the image itself
 359    * does not specify one.
 360    *
 361    * Illegal to call if HasSize() returns false.
 362    */
 363   gfx::IntRect FullFrame() const
 364   {
 365     return gfx::IntRect(gfx::IntPoint(), Size());
 366   }
 367
 368   /**
 369    * @return an IntRect which covers the entire area of this image at its size
 370    * after scaling - that is, at its output size.
 371    *
 372    * XXX(seth): This is only used for decoders which are using the old
 373    * Downscaler code instead of SurfacePipe, since the old AllocateFrame() and
 374    * Downscaler APIs required that the frame rect be specified in output space.
 375    * We should remove this once all decoders use SurfacePipe.
 376    *
 377    * Illegal to call if HasSize() returns false.
 378    */
 379   gfx::IntRect FullOutputFrame() const
 380   {
 381     return gfx::IntRect(gfx::IntPoint(), OutputSize());
 382   }
 383
 384   /// @return final status information about this decoder. Should be called
 385   /// after we decide we're not going to run the decoder anymore.
 386   DecoderFinalStatus FinalStatus() const;
 387
 388   /// @return the metadata we collected about this image while decoding.
 389   const ImageMetadata& GetImageMetadata() { return mImageMetadata; }
 390
 391   /// @return performance telemetry we collected while decoding.
 392   DecoderTelemetry Telemetry() const;
 393
 394   /**
 395    * @return a weak pointer to the image associated with this decoder. Illegal
 396    * to call if this decoder is not associated with an image.
 397    */
 398   NotNull<RasterImage*> GetImage() const { return WrapNotNull(mImage.get()); }
 399
 400   /**
 401    * @return a possibly-null weak pointer to the image associated with this
 402    * decoder. May be called even if this decoder is not associated with an
 403    * image.
 404    */
 405   RasterImage* GetImageMaybeNull() const { return mImage.get(); }
 406
 407   RawAccessFrameRef GetCurrentFrameRef()
 408   {
 409     return mCurrentFrame ? mCurrentFrame->RawAccessRef()
 410                          : RawAccessFrameRef();
 411   }
 412
 413   bool HasFrameToTake() const { return mHasFrameToTake; }
 414   void ClearHasFrameToTake() {
 415     MOZ_ASSERT(mHasFrameToTake);
 416     mHasFrameToTake = false;
 417   }
 418
 419 protected:
 420   friend class AutoRecordDecoderTelemetry;
 421   friend class nsICODecoder;
 422   friend class PalettedSurfaceSink;
 423   friend class SurfaceSink;
 424
 425   virtual ~Decoder();
 426
 427   /*
 428    * Internal hooks. Decoder implementations may override these and
 429    * only these methods.
 430    *
 431    * BeforeFinishInternal() can be used to detect if decoding is in an
 432    * incomplete state, e.g. due to file truncation, in which case it should
 433    * return a failing nsresult.
 434    */
 435   virtual nsresult InitInternal();
 436   virtual LexerResult DoDecode(SourceBufferIterator& aIterator,
 437                                IResumable* aOnResume) = 0;
 438   virtual nsresult BeforeFinishInternal();
 439   virtual nsresult FinishInternal();
 440   virtual nsresult FinishWithErrorInternal();
 441
 442   /**
 443    * @return the per-image-format telemetry ID for recording this decoder's
 444    * speed, or Nothing() if we don't record speed telemetry for this kind of
 445    * decoder.
 446    */
 447   virtual Maybe<Telemetry::HistogramID> SpeedHistogram() const { return Nothing(); }
 448
 449
 450   /*
 451    * Progress notifications.
 452    */
 453
 454   // Called by decoders when they determine the size of the image. Informs
 455   // the image of its size and sends notifications.
 456   void PostSize(int32_t aWidth,
 457                 int32_t aHeight,
 458                 Orientation aOrientation = Orientation());
 459
 460   // Called by decoders if they determine that the image has transparency.
 461   //
 462   // This should be fired as early as possible to allow observers to do things
 463   // that affect content, so it's necessarily pessimistic - if there's a
 464   // possibility that the image has transparency, for example because its header
 465   // specifies that it has an alpha channel, we fire PostHasTransparency
 466   // immediately. PostFrameStop's aFrameOpacity argument, on the other hand, is
 467   // only used internally to ImageLib. Because PostFrameStop isn't delivered
 468   // until the entire frame has been decoded, decoders may take into account the
 469   // actual contents of the frame and give a more accurate result.
 470   void PostHasTransparency();
 471
 472   // Called by decoders if they determine that the image is animated.
 473   //
 474   // @param aTimeout The time for which the first frame should be shown before
 475   //                 we advance to the next frame.
 476   void PostIsAnimated(FrameTimeout aFirstFrameTimeout);
 477
 478   // Called by decoders when they end a frame. Informs the image, sends
 479   // notifications, and does internal book-keeping.
 480   // Specify whether this frame is opaque as an optimization.
 481   // For animated images, specify the disposal, blend method and timeout for
 482   // this frame.
 483   void PostFrameStop(Opacity aFrameOpacity = Opacity::SOME_TRANSPARENCY);
 484
 485   /**
 486    * Called by the decoders when they have a region to invalidate. We may not
 487    * actually pass these invalidations on right away.
 488    *
 489    * @param aRect The invalidation rect in the coordinate system of the unscaled
 490    *              image (that is, the image at its intrinsic size).
 491    * @param aRectAtOutputSize If not Nothing(), the invalidation rect in the
 492    *                          coordinate system of the scaled image (that is,
 493    *                          the image at our output size). This must
 494    *                          be supplied if we're downscaling during decode.
 495    */
 496   void PostInvalidation(const gfx::IntRect& aRect,
 497                         const Maybe<gfx::IntRect>& aRectAtOutputSize = Nothing());
 498
 499   // Called by the decoders when they have successfully decoded the image. This
 500   // may occur as the result of the decoder getting to the appropriate point in
 501   // the stream, or by us calling FinishInternal().
 502   //
 503   // May not be called mid-frame.
 504   //
 505   // For animated images, specify the loop count. -1 means loop forever, 0
 506   // means a single iteration, stopping on the last frame.
 507   void PostDecodeDone(int32_t aLoopCount = 0);
 508
 509   /**
 510    * Allocates a new frame, making it our current frame if successful.
 511    *
 512    * If a non-paletted frame is desired, pass 0 for aPaletteDepth.
 513    */
 514   nsresult AllocateFrame(const gfx::IntSize& aOutputSize,
 515                          const gfx::IntRect& aFrameRect,
 516                          gfx::SurfaceFormat aFormat,
 517                          uint8_t aPaletteDepth = 0,
 518                          const Maybe<AnimationParams>& aAnimParams = Nothing());
 519
 520 private:
 521   /// Report that an error was encountered while decoding.
 522   void PostError();
 523
 524   /**
 525    * CompleteDecode() finishes up the decoding process after Decode() determines
 526    * that we're finished. It records final progress and does all the cleanup
 527    * that's possible off-main-thread.
 528    */
 529   void CompleteDecode();
 530
 531   /// @return the number of complete frames we have. Does not include the
 532   /// current frame if it's unfinished.
 533   uint32_t GetCompleteFrameCount()
 534   {
 535     if (mFrameCount == 0) {
 536       return 0;
 537     }
 538
 539     return mInFrame ? mFrameCount - 1 : mFrameCount;
 540   }
 541
 542   RawAccessFrameRef AllocateFrameInternal(const gfx::IntSize& aOutputSize,
 543                                           const gfx::IntRect& aFrameRect,
 544                                           gfx::SurfaceFormat aFormat,
 545                                           uint8_t aPaletteDepth,
 546                                           const Maybe<AnimationParams>& aAnimParams,
 547                                           imgFrame* aPreviousFrame);
 548
 549 protected:
 550   Maybe<Downscaler> mDownscaler;
 551
 552   uint8_t* mImageData;  // Pointer to image data in either Cairo or 8bit format
 553   uint32_t mImageDataLength;
 554   uint32_t* mColormap;  // Current colormap to be used in Cairo format
 555   uint32_t mColormapSize;
 556
 557 private:
 558   RefPtr<RasterImage> mImage;
 559   Maybe<SourceBufferIterator> mIterator;
 560   RawAccessFrameRef mCurrentFrame;
 561   ImageMetadata mImageMetadata;
 562   gfx::IntRect mInvalidRect; // Tracks an invalidation region in the current frame.
 563   Maybe<gfx::IntSize> mOutputSize;  // The size of our output surface.
 564   Maybe<gfx::IntSize> mExpectedSize; // The expected size of the image.
 565   Progress mProgress;
 566
 567   uint32_t mFrameCount; // Number of frames, including anything in-progress
 568   FrameTimeout mLoopLength;  // Length of a single loop of this image.
 569   gfx::IntRect mFirstFrameRefreshArea;  // The area of the image that needs to
 570                                         // be invalidated when the animation loops.
 571
 572   // Telemetry data for this decoder.
 573   TimeDuration mDecodeTime;
 574
 575   DecoderFlags mDecoderFlags;
 576   SurfaceFlags mSurfaceFlags;
 577
 578   bool mInitialized : 1;
 579   bool mMetadataDecode : 1;
 580   bool mHaveExplicitOutputSize : 1;
 581   bool mInFrame : 1;
 582   bool mFinishedNewFrame : 1;  // True if PostFrameStop() has been called since
 583                                // the last call to TakeCompleteFrameCount().
 584   // Has a new frame that AnimationSurfaceProvider can take. Unfortunately this
 585   // has to be separate from mFinishedNewFrame because the png decoder yields a
 586   // new frame before calling PostFrameStop().
 587   bool mHasFrameToTake : 1;
 588   bool mReachedTerminalState : 1;
 589   bool mDecodeDone : 1;
 590   bool mError : 1;
 591   bool mShouldReportError : 1;
 592   bool mFinalizeFrames : 1;
 593 };
 594
 595 } // namespace image
 596 } // namespace mozilla
 597
 598 #endif // mozilla_image_Decoder_h