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