/* -*- 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>
*/
/** * 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 SupportsWeakPtr #ifdef DEBUG
, public imgIContainerDebug #endif
{ // (no public constructor - use ImageFactory) virtual ~RasterImage();
/** * 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 OrientedIntRect& aInvalidRect = OrientedIntRect(), 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 OrientedIntRect& aInvalidRect, const Maybe<uint32_t>& aFrameCount,
DecoderFlags aDecoderFlags, SurfaceFlags aSurfaceFlags);
// Helper method for NotifyDecodeComplete. void ReportDecoderError();
/** * 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);
/** * 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. aMarkUsed determines if we mark the surface used in * the surface cache or not. * * @return a drawable surface, which may be empty if the requested surface * could not be found.
*/
LookupResult LookupFrame(const OrientedIntSize& aSize, uint32_t aFlags,
PlaybackType aPlaybackType, bool aMarkUsed);
/** * 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. * * aOutRanSync is set to true if the decode was run synchronously. * aOutFailed is set to true if failed to start a decode.
*/ void Decode(const OrientedIntSize& aSize, uint32_t aFlags,
PlaybackType aPlaybackType, bool& aOutRanSync, bool& aOutFailed);
/** * 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 OrientedIntSize& aSize, uint32_t aFlags);
private: // data
OrientedIntSize mSize;
nsTArray<OrientedIntSize> mNativeSizes;
// The orientation required to correctly orient the image, from the image's // metadata. RasterImage will handle and apply this orientation itself.
Orientation mOrientation;
// The resolution as specified in the image metadata, in dppx.
Resolution mResolution;
/// If this has a value, we're waiting for SetSize() to send the load event.
Maybe<Progress> mLoadProgress;
// Hotspot of this image, or (0, 0) if there is no hotspot data. // // We assume (and assert) that no image has both orientation metadata and a // hotspot, so we store this as an untyped point.
gfx::IntPoint mHotspot;
/// 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):
MOZ_ATOMIC_BITFIELDS(
mAtomicBitfields, 16,
((bool, HasSize, 1), // Has SetSize() been called?
(bool, Transient, 1), // Is the image short-lived?
(bool, SyncLoad, 1), // Are we loading synchronously?
(bool, Discardable, 1), // Is container discardable?
(bool, SomeSourceData, 1), // Do we have some source data?
(bool, AllSourceData, 1), // Do we have all the source data?
(bool, HasBeenDecoded, 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, PendingAnimation, 1),
// Whether the animation can stop, due to running out // of frames, or no more owning request
(bool, AnimationFinished, 1),
// Whether, once we are done doing a metadata decode, we should // immediately kick off a full decode.
(bool, WantFullDecode, 1)))
TimeStamp mDrawStartTime;
// This field is set according to the DecoderType of this image once when // initialized so that a decoder's flags can be set according to any // preferences that affect its behavior in a way that would otherwise cause // errors, such as enabling or disabling animation.
DecoderFlags mDefaultDecoderFlags = DefaultDecoderFlags();
// Determines whether we can downscale during decode with the given // parameters. bool CanDownscaleDuringDecode(const OrientedIntSize& 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.
*/ staticvoid DispatchIfNeeded(RasterImage* aImage);
Die Informationen auf dieser Webseite wurden
nach bestem Wissen sorgfältig zusammengestellt. Es wird jedoch weder Vollständigkeit, noch Richtigkeit,
noch Qualität der bereit gestellten Informationen zugesichert.
Bemerkung:
Die farbliche Syntaxdarstellung ist noch experimentell.
