summaryrefslogtreecommitdiffstats
path: root/image/Decoder.h
diff options
context:
space:
mode:
Diffstat (limited to 'image/Decoder.h')
-rw-r--r--image/Decoder.h562
1 files changed, 562 insertions, 0 deletions
diff --git a/image/Decoder.h b/image/Decoder.h
new file mode 100644
index 000000000..065a3c213
--- /dev/null
+++ b/image/Decoder.h
@@ -0,0 +1,562 @@
+/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+
+#ifndef mozilla_image_Decoder_h
+#define mozilla_image_Decoder_h
+
+#include "FrameAnimator.h"
+#include "RasterImage.h"
+#include "mozilla/Maybe.h"
+#include "mozilla/NotNull.h"
+#include "mozilla/RefPtr.h"
+#include "DecodePool.h"
+#include "DecoderFlags.h"
+#include "Downscaler.h"
+#include "ImageMetadata.h"
+#include "Orientation.h"
+#include "SourceBuffer.h"
+#include "StreamingLexer.h"
+#include "SurfaceFlags.h"
+
+namespace mozilla {
+
+namespace Telemetry {
+ enum ID : uint32_t;
+} // namespace Telemetry
+
+namespace image {
+
+struct DecoderFinalStatus final
+{
+ DecoderFinalStatus(bool aWasMetadataDecode,
+ bool aFinished,
+ bool aHadError,
+ bool aShouldReportError)
+ : mWasMetadataDecode(aWasMetadataDecode)
+ , mFinished(aFinished)
+ , mHadError(aHadError)
+ , mShouldReportError(aShouldReportError)
+ { }
+
+ /// True if this was a metadata decode.
+ const bool mWasMetadataDecode : 1;
+
+ /// True if this decoder finished, whether successfully or due to failure.
+ const bool mFinished : 1;
+
+ /// True if this decoder encountered an error.
+ const bool mHadError : 1;
+
+ /// True if this decoder encountered the kind of error that should be reported
+ /// to the console.
+ const bool mShouldReportError : 1;
+};
+
+struct DecoderTelemetry final
+{
+ DecoderTelemetry(Maybe<Telemetry::ID> aSpeedHistogram,
+ size_t aBytesDecoded,
+ uint32_t aChunkCount,
+ TimeDuration aDecodeTime)
+ : mSpeedHistogram(aSpeedHistogram)
+ , mBytesDecoded(aBytesDecoded)
+ , mChunkCount(aChunkCount)
+ , mDecodeTime(aDecodeTime)
+ { }
+
+ /// @return our decoder's speed, in KBps.
+ int32_t Speed() const
+ {
+ return mBytesDecoded / (1024 * mDecodeTime.ToSeconds());
+ }
+
+ /// @return our decoder's decode time, in microseconds.
+ int32_t DecodeTimeMicros() { return mDecodeTime.ToMicroseconds(); }
+
+ /// The per-image-format telemetry ID for recording our decoder's speed, or
+ /// Nothing() if we don't record speed telemetry for this kind of decoder.
+ const Maybe<Telemetry::ID> mSpeedHistogram;
+
+ /// The number of bytes of input our decoder processed.
+ const size_t mBytesDecoded;
+
+ /// The number of chunks our decoder's input was divided into.
+ const uint32_t mChunkCount;
+
+ /// The amount of time our decoder spent inside DoDecode().
+ const TimeDuration mDecodeTime;
+};
+
+class Decoder
+{
+public:
+ NS_INLINE_DECL_THREADSAFE_REFCOUNTING(Decoder)
+
+ explicit Decoder(RasterImage* aImage);
+
+ /**
+ * Initialize an image decoder. Decoders may not be re-initialized.
+ *
+ * @return NS_OK if the decoder could be initialized successfully.
+ */
+ nsresult Init();
+
+ /**
+ * Decodes, reading all data currently available in the SourceBuffer.
+ *
+ * If more data is needed and @aOnResume is non-null, Decode() will schedule
+ * @aOnResume to be called when more data is available.
+ *
+ * @return a LexerResult which may indicate:
+ * - the image has been successfully decoded (TerminalState::SUCCESS), or
+ * - the image has failed to decode (TerminalState::FAILURE), or
+ * - the decoder is yielding until it gets more data (Yield::NEED_MORE_DATA), or
+ * - the decoder is yielding to allow the caller to access intermediate
+ * output (Yield::OUTPUT_AVAILABLE).
+ */
+ LexerResult Decode(IResumable* aOnResume = nullptr);
+
+ /**
+ * Terminate this decoder in a failure state, just as if the decoder
+ * implementation had returned TerminalState::FAILURE from DoDecode().
+ *
+ * XXX(seth): This method should be removed ASAP; it exists only because
+ * RasterImage::FinalizeDecoder() requires an actual Decoder object as an
+ * argument, so we can't simply tell RasterImage a decode failed except via an
+ * intervening decoder. We'll fix this in bug 1291071.
+ */
+ LexerResult TerminateFailure();
+
+ /**
+ * Given a maximum number of bytes we're willing to decode, @aByteLimit,
+ * returns true if we should attempt to run this decoder synchronously.
+ */
+ bool ShouldSyncDecode(size_t aByteLimit);
+
+ /**
+ * Gets the invalidation region accumulated by the decoder so far, and clears
+ * the decoder's invalidation region. This means that each call to
+ * TakeInvalidRect() returns only the invalidation region accumulated since
+ * the last call to TakeInvalidRect().
+ */
+ nsIntRect TakeInvalidRect()
+ {
+ nsIntRect invalidRect = mInvalidRect;
+ mInvalidRect.SetEmpty();
+ return invalidRect;
+ }
+
+ /**
+ * Gets the progress changes accumulated by the decoder so far, and clears
+ * them. This means that each call to TakeProgress() returns only the changes
+ * accumulated since the last call to TakeProgress().
+ */
+ Progress TakeProgress()
+ {
+ Progress progress = mProgress;
+ mProgress = NoProgress;
+ return progress;
+ }
+
+ /**
+ * Returns true if there's any progress to report.
+ */
+ bool HasProgress() const
+ {
+ return mProgress != NoProgress || !mInvalidRect.IsEmpty() || mFinishedNewFrame;
+ }
+
+ /*
+ * State.
+ */
+
+ /**
+ * If we're doing a metadata decode, we only decode the image's headers, which
+ * is enough to determine the image's intrinsic size. A metadata decode is
+ * enabled by calling SetMetadataDecode() *before* calling Init().
+ */
+ void SetMetadataDecode(bool aMetadataDecode)
+ {
+ MOZ_ASSERT(!mInitialized, "Shouldn't be initialized yet");
+ mMetadataDecode = aMetadataDecode;
+ }
+ bool IsMetadataDecode() const { return mMetadataDecode; }
+
+ /**
+ * Sets the output size of this decoder. If this is smaller than the intrinsic
+ * size of the image, we'll downscale it while decoding. For memory usage
+ * reasons, upscaling is forbidden and will trigger assertions in debug
+ * builds.
+ *
+ * Not calling SetOutputSize() means that we should just decode at the
+ * intrinsic size, whatever it is.
+ *
+ * If SetOutputSize() was called, ExplicitOutputSize() can be used to
+ * determine the value that was passed to it.
+ *
+ * This must be called before Init() is called.
+ */
+ void SetOutputSize(const gfx::IntSize& aSize);
+
+ /**
+ * @return the output size of this decoder. If this is smaller than the
+ * intrinsic size, then the image will be downscaled during the decoding
+ * process.
+ *
+ * Illegal to call if HasSize() returns false.
+ */
+ gfx::IntSize OutputSize() const { MOZ_ASSERT(HasSize()); return *mOutputSize; }
+
+ /**
+ * @return either the size passed to SetOutputSize() or Nothing(), indicating
+ * that SetOutputSize() was not explicitly called.
+ */
+ Maybe<gfx::IntSize> ExplicitOutputSize() const;
+
+ /**
+ * Set the requested sample size for this decoder. Used to implement the
+ * -moz-sample-size media fragment.
+ *
+ * XXX(seth): Support for -moz-sample-size will be removed in bug 1120056.
+ */
+ virtual void SetSampleSize(int aSampleSize) { }
+
+ /**
+ * Set an iterator to the SourceBuffer which will feed data to this decoder.
+ * This must always be called before calling Init(). (And only before Init().)
+ *
+ * XXX(seth): We should eliminate this method and pass a SourceBufferIterator
+ * to the various decoder constructors instead.
+ */
+ void SetIterator(SourceBufferIterator&& aIterator)
+ {
+ MOZ_ASSERT(!mInitialized, "Shouldn't be initialized yet");
+ mIterator.emplace(Move(aIterator));
+ }
+
+ /**
+ * Should this decoder send partial invalidations?
+ */
+ bool ShouldSendPartialInvalidations() const
+ {
+ return !(mDecoderFlags & DecoderFlags::IS_REDECODE);
+ }
+
+ /**
+ * Should we stop decoding after the first frame?
+ */
+ bool IsFirstFrameDecode() const
+ {
+ return bool(mDecoderFlags & DecoderFlags::FIRST_FRAME_ONLY);
+ }
+
+ /**
+ * @return the number of complete animation frames which have been decoded so
+ * far, if it has changed since the last call to TakeCompleteFrameCount();
+ * otherwise, returns Nothing().
+ */
+ Maybe<uint32_t> TakeCompleteFrameCount();
+
+ // The number of frames we have, including anything in-progress. Thus, this
+ // is only 0 if we haven't begun any frames.
+ uint32_t GetFrameCount() { return mFrameCount; }
+
+ // Did we discover that the image we're decoding is animated?
+ bool HasAnimation() const { return mImageMetadata.HasAnimation(); }
+
+ // Error tracking
+ bool HasError() const { return mError; }
+ bool ShouldReportError() const { return mShouldReportError; }
+
+ /// Did we finish decoding enough that calling Decode() again would be useless?
+ bool GetDecodeDone() const
+ {
+ return mReachedTerminalState || mDecodeDone ||
+ (mMetadataDecode && HasSize()) || HasError();
+ }
+
+ /// Are we in the middle of a frame right now? Used for assertions only.
+ bool InFrame() const { return mInFrame; }
+
+ enum DecodeStyle {
+ PROGRESSIVE, // produce intermediate frames representing the partial
+ // state of the image
+ SEQUENTIAL // decode to final image immediately
+ };
+
+ /**
+ * Get or set the DecoderFlags that influence the behavior of this decoder.
+ */
+ void SetDecoderFlags(DecoderFlags aDecoderFlags)
+ {
+ MOZ_ASSERT(!mInitialized);
+ mDecoderFlags = aDecoderFlags;
+ }
+ DecoderFlags GetDecoderFlags() const { return mDecoderFlags; }
+
+ /**
+ * Get or set the SurfaceFlags that select the kind of output this decoder
+ * will produce.
+ */
+ void SetSurfaceFlags(SurfaceFlags aSurfaceFlags)
+ {
+ MOZ_ASSERT(!mInitialized);
+ mSurfaceFlags = aSurfaceFlags;
+ }
+ SurfaceFlags GetSurfaceFlags() const { return mSurfaceFlags; }
+
+ /// @return true if we know the intrinsic size of the image we're decoding.
+ bool HasSize() const { return mImageMetadata.HasSize(); }
+
+ /**
+ * @return the intrinsic size of the image we're decoding.
+ *
+ * Illegal to call if HasSize() returns false.
+ */
+ gfx::IntSize Size() const
+ {
+ MOZ_ASSERT(HasSize());
+ return mImageMetadata.GetSize();
+ }
+
+ /**
+ * @return an IntRect which covers the entire area of this image at its
+ * intrinsic size, appropriate for use as a frame rect when the image itself
+ * does not specify one.
+ *
+ * Illegal to call if HasSize() returns false.
+ */
+ gfx::IntRect FullFrame() const
+ {
+ return gfx::IntRect(gfx::IntPoint(), Size());
+ }
+
+ /**
+ * @return an IntRect which covers the entire area of this image at its size
+ * after scaling - that is, at its output size.
+ *
+ * XXX(seth): This is only used for decoders which are using the old
+ * Downscaler code instead of SurfacePipe, since the old AllocateFrame() and
+ * Downscaler APIs required that the frame rect be specified in output space.
+ * We should remove this once all decoders use SurfacePipe.
+ *
+ * Illegal to call if HasSize() returns false.
+ */
+ gfx::IntRect FullOutputFrame() const
+ {
+ return gfx::IntRect(gfx::IntPoint(), OutputSize());
+ }
+
+ /// @return final status information about this decoder. Should be called
+ /// after we decide we're not going to run the decoder anymore.
+ DecoderFinalStatus FinalStatus() const;
+
+ /// @return the metadata we collected about this image while decoding.
+ const ImageMetadata& GetImageMetadata() { return mImageMetadata; }
+
+ /// @return performance telemetry we collected while decoding.
+ DecoderTelemetry Telemetry() const;
+
+ /**
+ * @return a weak pointer to the image associated with this decoder. Illegal
+ * to call if this decoder is not associated with an image.
+ */
+ NotNull<RasterImage*> GetImage() const { return WrapNotNull(mImage.get()); }
+
+ /**
+ * @return a possibly-null weak pointer to the image associated with this
+ * decoder. May be called even if this decoder is not associated with an
+ * image.
+ */
+ RasterImage* GetImageMaybeNull() const { return mImage.get(); }
+
+ RawAccessFrameRef GetCurrentFrameRef()
+ {
+ return mCurrentFrame ? mCurrentFrame->RawAccessRef()
+ : RawAccessFrameRef();
+ }
+
+
+protected:
+ friend class AutoRecordDecoderTelemetry;
+ friend class nsICODecoder;
+ friend class PalettedSurfaceSink;
+ friend class SurfaceSink;
+
+ virtual ~Decoder();
+
+ /*
+ * Internal hooks. Decoder implementations may override these and
+ * only these methods.
+ *
+ * BeforeFinishInternal() can be used to detect if decoding is in an
+ * incomplete state, e.g. due to file truncation, in which case it should
+ * return a failing nsresult.
+ */
+ virtual nsresult InitInternal();
+ virtual LexerResult DoDecode(SourceBufferIterator& aIterator,
+ IResumable* aOnResume) = 0;
+ virtual nsresult BeforeFinishInternal();
+ virtual nsresult FinishInternal();
+ virtual nsresult FinishWithErrorInternal();
+
+ /**
+ * @return the per-image-format telemetry ID for recording this decoder's
+ * speed, or Nothing() if we don't record speed telemetry for this kind of
+ * decoder.
+ */
+ virtual Maybe<Telemetry::ID> SpeedHistogram() const { return Nothing(); }
+
+
+ /*
+ * Progress notifications.
+ */
+
+ // Called by decoders when they determine the size of the image. Informs
+ // the image of its size and sends notifications.
+ void PostSize(int32_t aWidth,
+ int32_t aHeight,
+ Orientation aOrientation = Orientation());
+
+ // Called by decoders if they determine that the image has transparency.
+ //
+ // This should be fired as early as possible to allow observers to do things
+ // that affect content, so it's necessarily pessimistic - if there's a
+ // possibility that the image has transparency, for example because its header
+ // specifies that it has an alpha channel, we fire PostHasTransparency
+ // immediately. PostFrameStop's aFrameOpacity argument, on the other hand, is
+ // only used internally to ImageLib. Because PostFrameStop isn't delivered
+ // until the entire frame has been decoded, decoders may take into account the
+ // actual contents of the frame and give a more accurate result.
+ void PostHasTransparency();
+
+ // Called by decoders if they determine that the image is animated.
+ //
+ // @param aTimeout The time for which the first frame should be shown before
+ // we advance to the next frame.
+ void PostIsAnimated(FrameTimeout aFirstFrameTimeout);
+
+ // Called by decoders when they end a frame. Informs the image, sends
+ // notifications, and does internal book-keeping.
+ // Specify whether this frame is opaque as an optimization.
+ // For animated images, specify the disposal, blend method and timeout for
+ // this frame.
+ void PostFrameStop(Opacity aFrameOpacity = Opacity::SOME_TRANSPARENCY,
+ DisposalMethod aDisposalMethod = DisposalMethod::KEEP,
+ FrameTimeout aTimeout = FrameTimeout::Forever(),
+ BlendMethod aBlendMethod = BlendMethod::OVER,
+ const Maybe<nsIntRect>& aBlendRect = Nothing());
+
+ /**
+ * Called by the decoders when they have a region to invalidate. We may not
+ * actually pass these invalidations on right away.
+ *
+ * @param aRect The invalidation rect in the coordinate system of the unscaled
+ * image (that is, the image at its intrinsic size).
+ * @param aRectAtOutputSize If not Nothing(), the invalidation rect in the
+ * coordinate system of the scaled image (that is,
+ * the image at our output size). This must
+ * be supplied if we're downscaling during decode.
+ */
+ void PostInvalidation(const gfx::IntRect& aRect,
+ const Maybe<gfx::IntRect>& aRectAtOutputSize = Nothing());
+
+ // Called by the decoders when they have successfully decoded the image. This
+ // may occur as the result of the decoder getting to the appropriate point in
+ // the stream, or by us calling FinishInternal().
+ //
+ // May not be called mid-frame.
+ //
+ // For animated images, specify the loop count. -1 means loop forever, 0
+ // means a single iteration, stopping on the last frame.
+ void PostDecodeDone(int32_t aLoopCount = 0);
+
+ /**
+ * Allocates a new frame, making it our current frame if successful.
+ *
+ * The @aFrameNum parameter only exists as a sanity check; it's illegal to
+ * create a new frame anywhere but immediately after the existing frames.
+ *
+ * If a non-paletted frame is desired, pass 0 for aPaletteDepth.
+ */
+ nsresult AllocateFrame(uint32_t aFrameNum,
+ const gfx::IntSize& aOutputSize,
+ const gfx::IntRect& aFrameRect,
+ gfx::SurfaceFormat aFormat,
+ uint8_t aPaletteDepth = 0);
+
+private:
+ /// Report that an error was encountered while decoding.
+ void PostError();
+
+ /**
+ * CompleteDecode() finishes up the decoding process after Decode() determines
+ * that we're finished. It records final progress and does all the cleanup
+ * that's possible off-main-thread.
+ */
+ void CompleteDecode();
+
+ /// @return the number of complete frames we have. Does not include the
+ /// current frame if it's unfinished.
+ uint32_t GetCompleteFrameCount()
+ {
+ if (mFrameCount == 0) {
+ return 0;
+ }
+
+ return mInFrame ? mFrameCount - 1 : mFrameCount;
+ }
+
+ RawAccessFrameRef AllocateFrameInternal(uint32_t aFrameNum,
+ const gfx::IntSize& aOutputSize,
+ const gfx::IntRect& aFrameRect,
+ gfx::SurfaceFormat aFormat,
+ uint8_t aPaletteDepth,
+ imgFrame* aPreviousFrame);
+
+protected:
+ Maybe<Downscaler> mDownscaler;
+
+ uint8_t* mImageData; // Pointer to image data in either Cairo or 8bit format
+ uint32_t mImageDataLength;
+ uint32_t* mColormap; // Current colormap to be used in Cairo format
+ uint32_t mColormapSize;
+
+private:
+ RefPtr<RasterImage> mImage;
+ Maybe<SourceBufferIterator> mIterator;
+ RawAccessFrameRef mCurrentFrame;
+ ImageMetadata mImageMetadata;
+ gfx::IntRect mInvalidRect; // Tracks an invalidation region in the current frame.
+ Maybe<gfx::IntSize> mOutputSize; // The size of our output surface.
+ Progress mProgress;
+
+ uint32_t mFrameCount; // Number of frames, including anything in-progress
+ FrameTimeout mLoopLength; // Length of a single loop of this image.
+ gfx::IntRect mFirstFrameRefreshArea; // The area of the image that needs to
+ // be invalidated when the animation loops.
+
+ // Telemetry data for this decoder.
+ TimeDuration mDecodeTime;
+
+ DecoderFlags mDecoderFlags;
+ SurfaceFlags mSurfaceFlags;
+
+ bool mInitialized : 1;
+ bool mMetadataDecode : 1;
+ bool mHaveExplicitOutputSize : 1;
+ bool mInFrame : 1;
+ bool mFinishedNewFrame : 1; // True if PostFrameStop() has been called since
+ // the last call to TakeCompleteFrameCount().
+ bool mReachedTerminalState : 1;
+ bool mDecodeDone : 1;
+ bool mError : 1;
+ bool mShouldReportError : 1;
+};
+
+} // namespace image
+} // namespace mozilla
+
+#endif // mozilla_image_Decoder_h