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/. */
6 #ifndef mozilla_image_Decoder_h
7 #define mozilla_image_Decoder_h
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"
26 enum HistogramID
: uint32_t;
27 } // namespace Telemetry
33 struct DecoderFinalStatus final
{
34 DecoderFinalStatus(bool aWasMetadataDecode
, bool aFinished
, bool aHadError
,
35 bool aShouldReportError
)
36 : mWasMetadataDecode(aWasMetadataDecode
),
39 mShouldReportError(aShouldReportError
) {}
41 /// True if this was a metadata decode.
42 const bool mWasMetadataDecode
: 1;
44 /// True if this decoder finished, whether successfully or due to failure.
45 const bool mFinished
: 1;
47 /// True if this decoder encountered an error.
48 const bool mHadError
: 1;
50 /// True if this decoder encountered the kind of error that should be reported
52 const bool mShouldReportError
: 1;
55 struct DecoderTelemetry final
{
56 DecoderTelemetry(const Maybe
<Telemetry::HistogramID
>& aSpeedHistogram
,
57 size_t aBytesDecoded
, uint32_t aChunkCount
,
58 TimeDuration aDecodeTime
)
59 : mSpeedHistogram(aSpeedHistogram
),
60 mBytesDecoded(aBytesDecoded
),
61 mChunkCount(aChunkCount
),
62 mDecodeTime(aDecodeTime
) {}
64 /// @return our decoder's speed, in KBps.
65 int32_t Speed() const {
66 return mBytesDecoded
/ (1024 * mDecodeTime
.ToSeconds());
69 /// @return our decoder's decode time, in microseconds.
70 int32_t DecodeTimeMicros() { return mDecodeTime
.ToMicroseconds(); }
72 /// The per-image-format telemetry ID for recording our decoder's speed, or
73 /// Nothing() if we don't record speed telemetry for this kind of decoder.
74 const Maybe
<Telemetry::HistogramID
> mSpeedHistogram
;
76 /// The number of bytes of input our decoder processed.
77 const size_t mBytesDecoded
;
79 /// The number of chunks our decoder's input was divided into.
80 const uint32_t mChunkCount
;
82 /// The amount of time our decoder spent inside DoDecode().
83 const TimeDuration mDecodeTime
;
87 * Interface which owners of an animated Decoder object must implement in order
88 * to use recycling. It allows the decoder to get a handle to the recycled
91 class IDecoderFrameRecycler
{
94 * Request the next available recycled imgFrame from the recycler.
96 * @param aRecycleRect If a frame is returned, this must be set to the
97 * accumulated dirty rect between the frame being
98 * recycled, and the frame being generated.
100 * @returns The recycled frame, if any is available.
102 virtual RawAccessFrameRef
RecycleFrame(gfx::IntRect
& aRecycleRect
) = 0;
107 NS_INLINE_DECL_THREADSAFE_REFCOUNTING_RECORDED(Decoder
)
109 explicit Decoder(RasterImage
* aImage
);
112 * Initialize an image decoder. Decoders may not be re-initialized.
114 * @return NS_OK if the decoder could be initialized successfully.
119 * Decodes, reading all data currently available in the SourceBuffer.
121 * If more data is needed and @aOnResume is non-null, Decode() will schedule
122 * @aOnResume to be called when more data is available.
124 * @return a LexerResult which may indicate:
125 * - the image has been successfully decoded (TerminalState::SUCCESS), or
126 * - the image has failed to decode (TerminalState::FAILURE), or
127 * - the decoder is yielding until it gets more data
128 * (Yield::NEED_MORE_DATA), or
129 * - the decoder is yielding to allow the caller to access intermediate
130 * output (Yield::OUTPUT_AVAILABLE).
132 LexerResult
Decode(IResumable
* aOnResume
= nullptr);
135 * Terminate this decoder in a failure state, just as if the decoder
136 * implementation had returned TerminalState::FAILURE from DoDecode().
138 * XXX(seth): This method should be removed ASAP; it exists only because
139 * RasterImage::FinalizeDecoder() requires an actual Decoder object as an
140 * argument, so we can't simply tell RasterImage a decode failed except via an
141 * intervening decoder. We'll fix this in bug 1291071.
143 LexerResult
TerminateFailure();
146 * Given a maximum number of bytes we're willing to decode, @aByteLimit,
147 * returns true if we should attempt to run this decoder synchronously.
149 bool ShouldSyncDecode(size_t aByteLimit
);
152 * Gets the invalidation region accumulated by the decoder so far, and clears
153 * the decoder's invalidation region. This means that each call to
154 * TakeInvalidRect() returns only the invalidation region accumulated since
155 * the last call to TakeInvalidRect().
157 nsIntRect
TakeInvalidRect() {
158 nsIntRect invalidRect
= mInvalidRect
;
159 mInvalidRect
.SetEmpty();
164 * Gets the progress changes accumulated by the decoder so far, and clears
165 * them. This means that each call to TakeProgress() returns only the changes
166 * accumulated since the last call to TakeProgress().
168 Progress
TakeProgress() {
169 Progress progress
= mProgress
;
170 mProgress
= NoProgress
;
175 * Returns true if there's any progress to report.
177 bool HasProgress() const {
178 return mProgress
!= NoProgress
|| !mInvalidRect
.IsEmpty() ||
187 * If we're doing a metadata decode, we only decode the image's headers, which
188 * is enough to determine the image's intrinsic size. A metadata decode is
189 * enabled by calling SetMetadataDecode() *before* calling Init().
191 void SetMetadataDecode(bool aMetadataDecode
) {
192 MOZ_ASSERT(!mInitialized
, "Shouldn't be initialized yet");
193 mMetadataDecode
= aMetadataDecode
;
195 bool IsMetadataDecode() const { return mMetadataDecode
; }
198 * Sets the output size of this decoder. If this is smaller than the intrinsic
199 * size of the image, we'll downscale it while decoding. For memory usage
200 * reasons, upscaling is forbidden and will trigger assertions in debug
203 * Not calling SetOutputSize() means that we should just decode at the
204 * intrinsic size, whatever it is.
206 * If SetOutputSize() was called, ExplicitOutputSize() can be used to
207 * determine the value that was passed to it.
209 * This must be called before Init() is called.
211 void SetOutputSize(const gfx::IntSize
& aSize
);
214 * @return the output size of this decoder. If this is smaller than the
215 * intrinsic size, then the image will be downscaled during the decoding
218 * Illegal to call if HasSize() returns false.
220 gfx::IntSize
OutputSize() const {
221 MOZ_ASSERT(HasSize());
226 * @return either the size passed to SetOutputSize() or Nothing(), indicating
227 * that SetOutputSize() was not explicitly called.
229 Maybe
<gfx::IntSize
> ExplicitOutputSize() const;
232 * Sets the expected image size of this decoder. Decoding will fail if this
235 void SetExpectedSize(const gfx::IntSize
& aSize
) {
236 mExpectedSize
.emplace(aSize
);
240 * Is the image size what was expected, if specified?
242 bool IsExpectedSize() const {
243 return mExpectedSize
.isNothing() || *mExpectedSize
== Size();
247 * Set an iterator to the SourceBuffer which will feed data to this decoder.
248 * This must always be called before calling Init(). (And only before Init().)
250 * XXX(seth): We should eliminate this method and pass a SourceBufferIterator
251 * to the various decoder constructors instead.
253 void SetIterator(SourceBufferIterator
&& aIterator
) {
254 MOZ_ASSERT(!mInitialized
, "Shouldn't be initialized yet");
255 mIterator
.emplace(std::move(aIterator
));
258 SourceBuffer
* GetSourceBuffer() const { return mIterator
->Owner(); }
261 * Should this decoder send partial invalidations?
263 bool ShouldSendPartialInvalidations() const {
264 return !(mDecoderFlags
& DecoderFlags::IS_REDECODE
);
268 * Should we stop decoding after the first frame?
270 bool IsFirstFrameDecode() const {
271 return bool(mDecoderFlags
& DecoderFlags::FIRST_FRAME_ONLY
);
275 * Should blend the current frame with the previous frames to produce a
276 * complete frame instead of a partial frame for animated images.
278 bool ShouldBlendAnimation() const {
279 return bool(mDecoderFlags
& DecoderFlags::BLEND_ANIMATION
);
283 * @return the number of complete animation frames which have been decoded so
284 * far, if it has changed since the last call to TakeCompleteFrameCount();
285 * otherwise, returns Nothing().
287 Maybe
<uint32_t> TakeCompleteFrameCount();
289 // The number of frames we have, including anything in-progress. Thus, this
290 // is only 0 if we haven't begun any frames.
291 uint32_t GetFrameCount() { return mFrameCount
; }
293 // Did we discover that the image we're decoding is animated?
294 bool HasAnimation() const { return mImageMetadata
.HasAnimation(); }
297 bool HasError() const { return mError
; }
298 bool ShouldReportError() const { return mShouldReportError
; }
301 void SetFinalizeFrames(bool aFinalize
) { mFinalizeFrames
= aFinalize
; }
302 bool GetFinalizeFrames() const { return mFinalizeFrames
; }
304 /// Did we finish decoding enough that calling Decode() again would be
306 bool GetDecodeDone() const {
307 return mReachedTerminalState
|| mDecodeDone
||
308 (mMetadataDecode
&& HasSize()) || HasError();
311 /// Are we in the middle of a frame right now? Used for assertions only.
312 bool InFrame() const { return mInFrame
; }
314 /// Is the image valid if embedded inside an ICO.
315 virtual bool IsValidICOResource() const { return false; }
318 virtual DecoderType
GetType() const { return DecoderType::UNKNOWN
; }
321 PROGRESSIVE
, // produce intermediate frames representing the partial
322 // state of the image
323 SEQUENTIAL
// decode to final image immediately
327 * Get or set the DecoderFlags that influence the behavior of this decoder.
329 void SetDecoderFlags(DecoderFlags aDecoderFlags
) {
330 MOZ_ASSERT(!mInitialized
);
331 mDecoderFlags
= aDecoderFlags
;
333 DecoderFlags
GetDecoderFlags() const { return mDecoderFlags
; }
336 * Get or set the SurfaceFlags that select the kind of output this decoder
339 void SetSurfaceFlags(SurfaceFlags aSurfaceFlags
) {
340 MOZ_ASSERT(!mInitialized
);
341 mSurfaceFlags
= aSurfaceFlags
;
343 SurfaceFlags
GetSurfaceFlags() const { return mSurfaceFlags
; }
345 /// @return true if we know the intrinsic size of the image we're decoding.
346 bool HasSize() const { return mImageMetadata
.HasSize(); }
349 * @return the intrinsic size of the image we're decoding.
351 * Illegal to call if HasSize() returns false.
353 gfx::IntSize
Size() const {
354 MOZ_ASSERT(HasSize());
355 return mImageMetadata
.GetSize();
359 * @return an IntRect which covers the entire area of this image at its
360 * intrinsic size, appropriate for use as a frame rect when the image itself
361 * does not specify one.
363 * Illegal to call if HasSize() returns false.
365 gfx::IntRect
FullFrame() const {
366 return gfx::IntRect(gfx::IntPoint(), Size());
370 * @return an IntRect which covers the entire area of this image at its size
371 * after scaling - that is, at its output size.
373 * XXX(seth): This is only used for decoders which are using the old
374 * Downscaler code instead of SurfacePipe, since the old AllocateFrame() and
375 * Downscaler APIs required that the frame rect be specified in output space.
376 * We should remove this once all decoders use SurfacePipe.
378 * Illegal to call if HasSize() returns false.
380 gfx::IntRect
FullOutputFrame() const {
381 return gfx::IntRect(gfx::IntPoint(), OutputSize());
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;
388 /// @return the metadata we collected about this image while decoding.
389 const ImageMetadata
& GetImageMetadata() { return mImageMetadata
; }
391 /// @return performance telemetry we collected while decoding.
392 DecoderTelemetry
Telemetry() const;
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.
398 NotNull
<RasterImage
*> GetImage() const { return WrapNotNull(mImage
.get()); }
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
405 RasterImage
* GetImageMaybeNull() const { return mImage
.get(); }
407 RawAccessFrameRef
GetCurrentFrameRef() {
408 return mCurrentFrame
? mCurrentFrame
->RawAccessRef() : RawAccessFrameRef();
412 * For use during decoding only. Allows the BlendAnimationFilter to get the
413 * current frame we are producing for its animation parameters.
415 imgFrame
* GetCurrentFrame() { return mCurrentFrame
.get(); }
418 * For use during decoding only. Allows the BlendAnimationFilter to get the
419 * frame it should be pulling the previous frame data from.
421 const RawAccessFrameRef
& GetRestoreFrameRef() const {
422 MOZ_ASSERT(ShouldBlendAnimation());
423 return mRestoreFrame
;
426 const gfx::IntRect
& GetRestoreDirtyRect() const {
427 MOZ_ASSERT(ShouldBlendAnimation());
428 return mRestoreDirtyRect
;
431 const gfx::IntRect
& GetRecycleRect() const {
432 MOZ_ASSERT(ShouldBlendAnimation());
436 const gfx::IntRect
& GetFirstFrameRefreshArea() const {
437 return mFirstFrameRefreshArea
;
440 bool HasFrameToTake() const { return mHasFrameToTake
; }
441 void ClearHasFrameToTake() {
442 MOZ_ASSERT(mHasFrameToTake
);
443 mHasFrameToTake
= false;
446 IDecoderFrameRecycler
* GetFrameRecycler() const { return mFrameRecycler
; }
447 void SetFrameRecycler(IDecoderFrameRecycler
* aFrameRecycler
) {
448 mFrameRecycler
= aFrameRecycler
;
452 friend class AutoRecordDecoderTelemetry
;
453 friend class DecoderTestHelper
;
454 friend class nsICODecoder
;
455 friend class PalettedSurfaceSink
;
456 friend class SurfaceSink
;
461 * Internal hooks. Decoder implementations may override these and
462 * only these methods.
464 * BeforeFinishInternal() can be used to detect if decoding is in an
465 * incomplete state, e.g. due to file truncation, in which case it should
466 * return a failing nsresult.
468 virtual nsresult
InitInternal();
469 virtual LexerResult
DoDecode(SourceBufferIterator
& aIterator
,
470 IResumable
* aOnResume
) = 0;
471 virtual nsresult
BeforeFinishInternal();
472 virtual nsresult
FinishInternal();
473 virtual nsresult
FinishWithErrorInternal();
476 * @return the per-image-format telemetry ID for recording this decoder's
477 * speed, or Nothing() if we don't record speed telemetry for this kind of
480 virtual Maybe
<Telemetry::HistogramID
> SpeedHistogram() const {
485 * Progress notifications.
488 // Called by decoders when they determine the size of the image. Informs
489 // the image of its size and sends notifications.
490 void PostSize(int32_t aWidth
, int32_t aHeight
,
491 Orientation aOrientation
= Orientation());
493 // Called by decoders if they determine that the image has transparency.
495 // This should be fired as early as possible to allow observers to do things
496 // that affect content, so it's necessarily pessimistic - if there's a
497 // possibility that the image has transparency, for example because its header
498 // specifies that it has an alpha channel, we fire PostHasTransparency
499 // immediately. PostFrameStop's aFrameOpacity argument, on the other hand, is
500 // only used internally to ImageLib. Because PostFrameStop isn't delivered
501 // until the entire frame has been decoded, decoders may take into account the
502 // actual contents of the frame and give a more accurate result.
503 void PostHasTransparency();
505 // Called by decoders if they determine that the image is animated.
507 // @param aTimeout The time for which the first frame should be shown before
508 // we advance to the next frame.
509 void PostIsAnimated(FrameTimeout aFirstFrameTimeout
);
511 // Called by decoders when they end a frame. Informs the image, sends
512 // notifications, and does internal book-keeping.
513 // Specify whether this frame is opaque as an optimization.
514 // For animated images, specify the disposal, blend method and timeout for
516 void PostFrameStop(Opacity aFrameOpacity
= Opacity::SOME_TRANSPARENCY
);
519 * Called by the decoders when they have a region to invalidate. We may not
520 * actually pass these invalidations on right away.
522 * @param aRect The invalidation rect in the coordinate system of the unscaled
523 * image (that is, the image at its intrinsic size).
524 * @param aRectAtOutputSize If not Nothing(), the invalidation rect in the
525 * coordinate system of the scaled image (that is,
526 * the image at our output size). This must
527 * be supplied if we're downscaling during decode.
529 void PostInvalidation(
530 const gfx::IntRect
& aRect
,
531 const Maybe
<gfx::IntRect
>& aRectAtOutputSize
= Nothing());
533 // Called by the decoders when they have successfully decoded the image. This
534 // may occur as the result of the decoder getting to the appropriate point in
535 // the stream, or by us calling FinishInternal().
537 // May not be called mid-frame.
539 // For animated images, specify the loop count. -1 means loop forever, 0
540 // means a single iteration, stopping on the last frame.
541 void PostDecodeDone(int32_t aLoopCount
= 0);
544 * Allocates a new frame, making it our current frame if successful.
546 * If a non-paletted frame is desired, pass 0 for aPaletteDepth.
548 nsresult
AllocateFrame(const gfx::IntSize
& aOutputSize
,
549 const gfx::IntRect
& aFrameRect
,
550 gfx::SurfaceFormat aFormat
, uint8_t aPaletteDepth
= 0,
551 const Maybe
<AnimationParams
>& aAnimParams
= Nothing());
554 /// Report that an error was encountered while decoding.
558 * CompleteDecode() finishes up the decoding process after Decode() determines
559 * that we're finished. It records final progress and does all the cleanup
560 * that's possible off-main-thread.
562 void CompleteDecode();
564 /// @return the number of complete frames we have. Does not include the
565 /// current frame if it's unfinished.
566 uint32_t GetCompleteFrameCount() {
567 if (mFrameCount
== 0) {
571 return mInFrame
? mFrameCount
- 1 : mFrameCount
;
574 RawAccessFrameRef
AllocateFrameInternal(
575 const gfx::IntSize
& aOutputSize
, const gfx::IntRect
& aFrameRect
,
576 gfx::SurfaceFormat aFormat
, uint8_t aPaletteDepth
,
577 const Maybe
<AnimationParams
>& aAnimParams
,
578 RawAccessFrameRef
&& aPreviousFrame
);
581 Maybe
<Downscaler
> mDownscaler
;
583 uint8_t* mImageData
; // Pointer to image data in either Cairo or 8bit format
584 uint32_t mImageDataLength
;
585 uint32_t* mColormap
; // Current colormap to be used in Cairo format
586 uint32_t mColormapSize
;
589 RefPtr
<RasterImage
> mImage
;
590 Maybe
<SourceBufferIterator
> mIterator
;
591 IDecoderFrameRecycler
* mFrameRecycler
;
593 // The current frame the decoder is producing.
594 RawAccessFrameRef mCurrentFrame
;
596 // The complete frame to combine with the current partial frame to produce
597 // a complete current frame.
598 RawAccessFrameRef mRestoreFrame
;
600 ImageMetadata mImageMetadata
;
603 mInvalidRect
; // Tracks new rows as the current frame is decoded.
604 gfx::IntRect mRestoreDirtyRect
; // Tracks an invalidation region between the
605 // restore frame and the previous frame.
606 gfx::IntRect mRecycleRect
; // Tracks an invalidation region between the
607 // recycled frame and the current frame.
608 Maybe
<gfx::IntSize
> mOutputSize
; // The size of our output surface.
609 Maybe
<gfx::IntSize
> mExpectedSize
; // The expected size of the image.
612 uint32_t mFrameCount
; // Number of frames, including anything in-progress
613 FrameTimeout mLoopLength
; // Length of a single loop of this image.
615 mFirstFrameRefreshArea
; // The area of the image that needs to
616 // be invalidated when the animation loops.
618 // Telemetry data for this decoder.
619 TimeDuration mDecodeTime
;
621 DecoderFlags mDecoderFlags
;
622 SurfaceFlags mSurfaceFlags
;
624 bool mInitialized
: 1;
625 bool mMetadataDecode
: 1;
626 bool mHaveExplicitOutputSize
: 1;
628 bool mFinishedNewFrame
: 1; // True if PostFrameStop() has been called since
629 // the last call to TakeCompleteFrameCount().
630 // Has a new frame that AnimationSurfaceProvider can take. Unfortunately this
631 // has to be separate from mFinishedNewFrame because the png decoder yields a
632 // new frame before calling PostFrameStop().
633 bool mHasFrameToTake
: 1;
634 bool mReachedTerminalState
: 1;
635 bool mDecodeDone
: 1;
637 bool mShouldReportError
: 1;
638 bool mFinalizeFrames
: 1;
642 } // namespace mozilla
644 #endif // mozilla_image_Decoder_h