/* -*- 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/. */
/** @file
* This file declares the RasterImage class, which
* handles static and animated rasterized images.
*
* @author Stuart Parmenter <pavlov@netscape.com>
* @author Chris Saari <saari@netscape.com>
* @author Arron Mogge <paper@animecity.nu>
* @author Andrew Smith <asmith15@learn.senecac.on.ca>
*/
#ifndef mozilla_image_RasterImage_h
#define mozilla_image_RasterImage_h
#include "Image.h"
#include "nsCOMPtr.h"
#include "imgIContainer.h"
#include "nsIProperties.h"
#include "nsTArray.h"
#include "LookupResult.h"
#include "nsThreadUtils.h"
#include "DecoderFactory.h"
#include "FrameAnimator.h"
#include "ImageMetadata.h"
#include "ISurfaceProvider.h"
#include "Orientation.h"
#include "nsIObserver.h"
#include "mozilla/Attributes.h"
#include "mozilla/Maybe.h"
#include "mozilla/MemoryReporting.h"
#include "mozilla/NotNull.h"
#include "mozilla/TimeStamp.h"
#include "mozilla/WeakPtr.h"
#include "mozilla/UniquePtr.h"
#include "ImageContainer.h"
#include "PlaybackType.h"
#ifdef DEBUG
#include "imgIContainerDebug.h"
#endif
class nsIInputStream;
class nsIRequest;
#define NS_RASTERIMAGE_CID \
{ /* 376ff2c1-9bf6-418a-b143-3340c00112f7 */ \
0x376ff2c1, 0x9bf6, 0x418a, { \
0xb1, 0x43, 0x33, 0x40, 0xc0, 0x01, 0x12, 0xf7 \
} \
}
/**
* Handles static and animated image containers.
*
*
* @par A Quick Walk Through
* The decoder initializes this class and calls AppendFrame() to add a frame.
* Once RasterImage detects more than one frame, it starts the animation
* with StartAnimation(). Note that the invalidation events for RasterImage are
* generated automatically using nsRefreshDriver.
*
* @par
* StartAnimation() initializes the animation helper object and sets the time
* the first frame was displayed to the current clock time.
*
* @par
* When the refresh driver corresponding to the imgIContainer that this image is
* a part of notifies the RasterImage that it's time to invalidate,
* RequestRefresh() is called with a given TimeStamp to advance to. As long as
* the timeout of the given frame (the frame's "delay") plus the time that frame
* was first displayed is less than or equal to the TimeStamp given,
* RequestRefresh() calls AdvanceFrame().
*
* @par
* AdvanceFrame() is responsible for advancing a single frame of the animation.
* It can return true, meaning that the frame advanced, or false, meaning that
* the frame failed to advance (usually because the next frame hasn't been
* decoded yet). It is also responsible for performing the final animation stop
* procedure if the final frame of a non-looping animation is reached.
*
* @par
* Each frame can have a different method of removing itself. These are
* listed as imgIContainer::cDispose... constants. Notify() calls
* DoComposite() to handle any special frame destruction.
*
* @par
* The basic path through DoComposite() is:
* 1) Calculate Area that needs updating, which is at least the area of
* aNextFrame.
* 2) Dispose of previous frame.
* 3) Draw new image onto compositingFrame.
* See comments in DoComposite() for more information and optimizations.
*
* @par
* The rest of the RasterImage specific functions are used by DoComposite to
* destroy the old frame and build the new one.
*
* @note
* <li> "Mask", "Alpha", and "Alpha Level" are interchangeable phrases in
* respects to RasterImage.
*
* @par
* <li> GIFs never have more than a 1 bit alpha.
* <li> APNGs may have a full alpha channel.
*
* @par
* <li> Background color specified in GIF is ignored by web browsers.
*
* @par
* <li> If Frame 3 wants to dispose by restoring previous, what it wants is to
* restore the composition up to and including Frame 2, as well as Frame 2s
* disposal. So, in the middle of DoComposite when composing Frame 3, right
* after destroying Frame 2's area, we copy compositingFrame to
* prevCompositingFrame. When DoComposite gets called to do Frame 4, we
* copy prevCompositingFrame back, and then draw Frame 4 on top.
*
* @par
* The mAnim structure has members only needed for animated images, so
* it's not allocated until the second frame is added.
*/
namespace mozilla {
namespace layers {
class ImageContainer;
class Image;
class LayersManager;
} // namespace layers
namespace image {
class Decoder;
struct DecoderFinalStatus;
struct DecoderTelemetry;
class ImageMetadata;
class SourceBuffer;
class RasterImage final : public ImageResource,
public nsIProperties,
public SupportsWeakPtr<RasterImage>
#ifdef DEBUG
,
public imgIContainerDebug
#endif
{
// (no public constructor - use ImageFactory)
virtual ~RasterImage();
public:
MOZ_DECLARE_WEAKREFERENCE_TYPENAME(RasterImage)
NS_DECL_THREADSAFE_ISUPPORTS
NS_DECL_NSIPROPERTIES
NS_DECL_IMGICONTAINER
#ifdef DEBUG
NS_DECL_IMGICONTAINERDEBUG
#endif
nsresult GetNativeSizes(nsTArray<gfx::IntSize>& aNativeSizes) const override;
size_t GetNativeSizesLength() const override;
virtual nsresult StartAnimation() override;
virtual nsresult StopAnimation() override;
// Methods inherited from Image
virtual void OnSurfaceDiscarded(const SurfaceKey& aSurfaceKey) override;
virtual size_t SizeOfSourceWithComputedFallback(
SizeOfState& aState) const override;
virtual void CollectSizeOfSurfaces(nsTArray<SurfaceMemoryCounter>& aCounters,
MallocSizeOf aMallocSizeOf) const override;
/* Triggers discarding. */
void Discard();
//////////////////////////////////////////////////////////////////////////////
// Decoder callbacks.
//////////////////////////////////////////////////////////////////////////////
/**
* Sends the provided progress notifications to ProgressTracker.
*
* Main-thread only.
*
* @param aProgress The progress notifications to send.
* @param aInvalidRect An invalidation rect to send.
* @param aFrameCount If Some(), an updated count of the number of frames of
* animation the decoder has finished decoding so far.
* This is a lower bound for the total number of
* animation frames this image has.
* @param aDecoderFlags The decoder flags used by the decoder that generated
* these notifications, or DefaultDecoderFlags() if the
* notifications don't come from a decoder.
* @param aSurfaceFlags The surface flags used by the decoder that generated
* these notifications, or DefaultSurfaceFlags() if the
* notifications don't come from a decoder.
*/
void NotifyProgress(Progress aProgress,
const gfx::IntRect& aInvalidRect = nsIntRect(),
const Maybe<uint32_t>& aFrameCount = Nothing(),
DecoderFlags aDecoderFlags = DefaultDecoderFlags(),
SurfaceFlags aSurfaceFlags = DefaultSurfaceFlags());
/**
* Records decoding results, sends out any final notifications, updates the
* state of this image, and records telemetry.
*
* Main-thread only.
*
* @param aStatus Final status information about the decoder. (Whether
* it encountered an error, etc.)
* @param aMetadata Metadata about this image that the decoder gathered.
* @param aTelemetry Telemetry data about the decoder.
* @param aProgress Any final progress notifications to send.
* @param aInvalidRect Any final invalidation rect to send.
* @param aFrameCount If Some(), a final updated count of the number of
* frames of animation the decoder has finished decoding so far. This is a
* lower bound for the total number of animation frames
* this image has.
* @param aDecoderFlags The decoder flags used by the decoder.
* @param aSurfaceFlags The surface flags used by the decoder.
*/
void NotifyDecodeComplete(
const DecoderFinalStatus& aStatus, const ImageMetadata& aMetadata,
const DecoderTelemetry& aTelemetry, Progress aProgress,
const gfx::IntRect& aInvalidRect, const Maybe<uint32_t>& aFrameCount,
DecoderFlags aDecoderFlags, SurfaceFlags aSurfaceFlags);
// Helper method for NotifyDecodeComplete.
void ReportDecoderError();
//////////////////////////////////////////////////////////////////////////////
// Network callbacks.
//////////////////////////////////////////////////////////////////////////////
virtual nsresult OnImageDataAvailable(nsIRequest* aRequest,
nsISupports* aContext,
nsIInputStream* aInStr,
uint64_t aSourceOffset,
uint32_t aCount) override;
virtual nsresult OnImageDataComplete(nsIRequest* aRequest,
nsISupports* aContext, nsresult aStatus,
bool aLastPart) override;
void NotifyForLoadEvent(Progress aProgress);
/**
* A hint of the number of bytes of source data that the image contains. If
* called early on, this can help reduce copying and reallocations by
* appropriately preallocating the source data buffer.
*
* We take this approach rather than having the source data management code do
* something more complicated (like chunklisting) because HTTP is by far the
* dominant source of images, and the Content-Length header is quite reliable.
* Thus, pre-allocation simplifies code and reduces the total number of
* allocations.
*/
nsresult SetSourceSizeHint(uint32_t aSizeHint);
nsCString GetURIString() {
nsCString spec;
if (GetURI()) {
GetURI()->GetSpec(spec);
}
return spec;
}
private:
nsresult Init(const char* aMimeType, uint32_t aFlags);
/**
* Tries to retrieve a surface for this image with size @aSize, surface flags
* matching @aFlags, and a playback type of @aPlaybackType.
*
* If @aFlags specifies FLAG_SYNC_DECODE and we already have all the image
* data, we'll attempt a sync decode if no matching surface is found. If
* FLAG_SYNC_DECODE was not specified and no matching surface was found, we'll
* kick off an async decode so that the surface is (hopefully) available next
* time it's requested.
*
* @return a drawable surface, which may be empty if the requested surface
* could not be found.
*/
LookupResult LookupFrame(const gfx::IntSize& aSize, uint32_t aFlags,
PlaybackType aPlaybackType);
/// Helper method for LookupFrame().
LookupResult LookupFrameInternal(const gfx::IntSize& aSize, uint32_t aFlags,
PlaybackType aPlaybackType);
ImgDrawResult DrawInternal(DrawableSurface&& aFrameRef, gfxContext* aContext,
const nsIntSize& aSize, const ImageRegion& aRegion,
gfx::SamplingFilter aSamplingFilter,
uint32_t aFlags, float aOpacity);
Tuple<ImgDrawResult, gfx::IntSize, RefPtr<gfx::SourceSurface>>
GetFrameInternal(const gfx::IntSize& aSize,
const Maybe<SVGImageContext>& aSVGContext,
uint32_t aWhichFrame, uint32_t aFlags) override;
gfx::IntSize GetImageContainerSize(layers::LayerManager* aManager,
const gfx::IntSize& aSize,
uint32_t aFlags) override;
//////////////////////////////////////////////////////////////////////////////
// Decoding.
//////////////////////////////////////////////////////////////////////////////
/**
* Creates and runs a decoder, either synchronously or asynchronously
* according to @aFlags. Decodes at the provided target size @aSize, using
* decode flags @aFlags. Performs a single-frame decode of this image unless
* we know the image is animated *and* @aPlaybackType is
* PlaybackType::eAnimated.
*
* It's an error to call Decode() before this image's intrinsic size is
* available. A metadata decode must successfully complete first.
*
* Returns true of the decode was run synchronously.
*/
bool Decode(const gfx::IntSize& aSize, uint32_t aFlags,
PlaybackType aPlaybackType);
/**
* Creates and runs a metadata decoder, either synchronously or
* asynchronously according to @aFlags.
*/
NS_IMETHOD DecodeMetadata(uint32_t aFlags);
/**
* Sets the size, inherent orientation, animation metadata, and other
* information about the image gathered during decoding.
*
* This function may be called multiple times, but will throw an error if
* subsequent calls do not match the first.
*
* @param aMetadata The metadata to set on this image.
* @param aFromMetadataDecode True if this metadata came from a metadata
* decode; false if it came from a full decode.
* @return |true| unless a catastrophic failure was discovered. If |false| is
* returned, it indicates that the image is corrupt in a way that requires all
* surfaces to be discarded to recover.
*/
bool SetMetadata(const ImageMetadata& aMetadata, bool aFromMetadataDecode);
/**
* In catastrophic circumstances like a GPU driver crash, the contents of our
* frames may become invalid. If the information we gathered during the
* metadata decode proves to be wrong due to image corruption, the frames we
* have may violate this class's invariants. Either way, we need to
* immediately discard the invalid frames and redecode so that callers don't
* perceive that we've entered an invalid state.
*
* RecoverFromInvalidFrames discards all existing frames and redecodes using
* the provided @aSize and @aFlags.
*/
void RecoverFromInvalidFrames(const nsIntSize& aSize, uint32_t aFlags);
void OnSurfaceDiscardedInternal(bool aAnimatedFramesDiscarded);
private: // data
nsIntSize mSize;
nsTArray<nsIntSize> mNativeSizes;
Orientation mOrientation;
/// If this has a value, we're waiting for SetSize() to send the load event.
Maybe<Progress> mLoadProgress;
nsCOMPtr<nsIProperties> mProperties;
/// If this image is animated, a FrameAnimator which manages its animation.
UniquePtr<FrameAnimator> mFrameAnimator;
/// Animation timeline and other state for animation images.
Maybe<AnimationState> mAnimationState;
// Image locking.
uint32_t mLockCount;
// The type of decoder this image needs. Computed from the MIME type in
// Init().
DecoderType mDecoderType;
// How many times we've decoded this image.
// This is currently only used for statistics
int32_t mDecodeCount;
#ifdef DEBUG
uint32_t mFramesNotified;
#endif
// The source data for this image.
NotNull<RefPtr<SourceBuffer>> mSourceBuffer;
// Boolean flags (clustered together to conserve space):
bool mHasSize : 1; // Has SetSize() been called?
bool mTransient : 1; // Is the image short-lived?
bool mSyncLoad : 1; // Are we loading synchronously?
bool mDiscardable : 1; // Is container discardable?
bool mSomeSourceData : 1; // Do we have some source data?
bool mAllSourceData : 1; // Do we have all the source data?
bool mHasBeenDecoded : 1; // Decoded at least once?
// Whether we're waiting to start animation. If we get a StartAnimation() call
// but we don't yet have more than one frame, mPendingAnimation is set so that
// we know to start animation later if/when we have more frames.
bool mPendingAnimation : 1;
// Whether the animation can stop, due to running out
// of frames, or no more owning request
bool mAnimationFinished : 1;
// Whether, once we are done doing a metadata decode, we should immediately
// kick off a full decode.
bool mWantFullDecode : 1;
TimeStamp mDrawStartTime;
//////////////////////////////////////////////////////////////////////////////
// Scaling.
//////////////////////////////////////////////////////////////////////////////
// Determines whether we can downscale during decode with the given
// parameters.
bool CanDownscaleDuringDecode(const nsIntSize& aSize, uint32_t aFlags);
// Error handling.
void DoError();
class HandleErrorWorker : public Runnable {
public:
/**
* Called from decoder threads when DoError() is called, since errors can't
* be handled safely off-main-thread. Dispatches an event which reinvokes
* DoError on the main thread if there isn't one already pending.
*/
static void DispatchIfNeeded(RasterImage* aImage);
NS_IMETHOD Run() override;
private:
explicit HandleErrorWorker(RasterImage* aImage);
RefPtr<RasterImage> mImage;
};
// Helpers
bool CanDiscard();
bool IsOpaque();
DrawableSurface RequestDecodeForSizeInternal(const gfx::IntSize& aSize,
uint32_t aFlags);
protected:
explicit RasterImage(ImageURL* aURI = nullptr);
bool ShouldAnimate() override;
friend class ImageFactory;
};
inline NS_IMETHODIMP RasterImage::GetAnimationMode(uint16_t* aAnimationMode) {
return GetAnimationModeInternal(aAnimationMode);
}
} // namespace image
} // namespace mozilla
/**
* Casting RasterImage to nsISupports is ambiguous. This method handles that.
*/
inline nsISupports* ToSupports(mozilla::image::RasterImage* p) {
return NS_ISUPPORTS_CAST(mozilla::image::ImageResource*, p);
}
#endif /* mozilla_image_RasterImage_h */