image/RasterImage.h

   1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*-
   2  *
   3  * This Source Code Form is subject to the terms of the Mozilla Public
   4  * License, v. 2.0. If a copy of the MPL was not distributed with this
   5  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   6
   7 /** @file
   8  * This file declares the RasterImage class, which
   9  * handles static and animated rasterized images.
  10  *
  11  * @author  Stuart Parmenter <pavlov@netscape.com>
  12  * @author  Chris Saari <saari@netscape.com>
  13  * @author  Arron Mogge <paper@animecity.nu>
  14  * @author  Andrew Smith <asmith15@learn.senecac.on.ca>
  15  */
  16
  17 #ifndef mozilla_image_RasterImage_h
  18 #define mozilla_image_RasterImage_h
  19
  20 #include "Image.h"
  21 #include "nsCOMPtr.h"
  22 #include "imgIContainer.h"
  23 #include "nsIProperties.h"
  24 #include "nsTArray.h"
  25 #include "LookupResult.h"
  26 #include "nsThreadUtils.h"
  27 #include "DecoderFactory.h"
  28 #include "FrameAnimator.h"
  29 #include "ImageMetadata.h"
  30 #include "ISurfaceProvider.h"
  31 #include "Orientation.h"
  32 #include "nsIObserver.h"
  33 #include "mozilla/Attributes.h"
  34 #include "mozilla/Maybe.h"
  35 #include "mozilla/MemoryReporting.h"
  36 #include "mozilla/NotNull.h"
  37 #include "mozilla/TimeStamp.h"
  38 #include "mozilla/WeakPtr.h"
  39 #include "mozilla/UniquePtr.h"
  40 #include "ImageContainer.h"
  41 #include "PlaybackType.h"
  42 #ifdef DEBUG
  43 #  include "imgIContainerDebug.h"
  44 #endif
  45
  46 class nsIInputStream;
  47 class nsIRequest;
  48
  49 #define NS_RASTERIMAGE_CID                           \
  50   { /* 376ff2c1-9bf6-418a-b143-3340c00112f7 */       \
  51     0x376ff2c1, 0x9bf6, 0x418a, {                    \
  52       0xb1, 0x43, 0x33, 0x40, 0xc0, 0x01, 0x12, 0xf7 \
  53     }                                                \
  54   }
  55
  56 /**
  57  * Handles static and animated image containers.
  58  *
  59  *
  60  * @par A Quick Walk Through
  61  * The decoder initializes this class and calls AppendFrame() to add a frame.
  62  * Once RasterImage detects more than one frame, it starts the animation
  63  * with StartAnimation(). Note that the invalidation events for RasterImage are
  64  * generated automatically using nsRefreshDriver.
  65  *
  66  * @par
  67  * StartAnimation() initializes the animation helper object and sets the time
  68  * the first frame was displayed to the current clock time.
  69  *
  70  * @par
  71  * When the refresh driver corresponding to the imgIContainer that this image is
  72  * a part of notifies the RasterImage that it's time to invalidate,
  73  * RequestRefresh() is called with a given TimeStamp to advance to. As long as
  74  * the timeout of the given frame (the frame's "delay") plus the time that frame
  75  * was first displayed is less than or equal to the TimeStamp given,
  76  * RequestRefresh() calls AdvanceFrame().
  77  *
  78  * @par
  79  * AdvanceFrame() is responsible for advancing a single frame of the animation.
  80  * It can return true, meaning that the frame advanced, or false, meaning that
  81  * the frame failed to advance (usually because the next frame hasn't been
  82  * decoded yet). It is also responsible for performing the final animation stop
  83  * procedure if the final frame of a non-looping animation is reached.
  84  *
  85  * @par
  86  * Each frame can have a different method of removing itself. These are
  87  * listed as imgIContainer::cDispose... constants.  Notify() calls
  88  * DoComposite() to handle any special frame destruction.
  89  *
  90  * @par
  91  * The basic path through DoComposite() is:
  92  * 1) Calculate Area that needs updating, which is at least the area of
  93  *    aNextFrame.
  94  * 2) Dispose of previous frame.
  95  * 3) Draw new image onto compositingFrame.
  96  * See comments in DoComposite() for more information and optimizations.
  97  *
  98  * @par
  99  * The rest of the RasterImage specific functions are used by DoComposite to
 100  * destroy the old frame and build the new one.
 101  *
 102  * @note
 103  * <li> "Mask", "Alpha", and "Alpha Level" are interchangeable phrases in
 104  * respects to RasterImage.
 105  *
 106  * @par
 107  * <li> GIFs never have more than a 1 bit alpha.
 108  * <li> APNGs may have a full alpha channel.
 109  *
 110  * @par
 111  * <li> Background color specified in GIF is ignored by web browsers.
 112  *
 113  * @par
 114  * <li> If Frame 3 wants to dispose by restoring previous, what it wants is to
 115  * restore the composition up to and including Frame 2, as well as Frame 2s
 116  * disposal.  So, in the middle of DoComposite when composing Frame 3, right
 117  * after destroying Frame 2's area, we copy compositingFrame to
 118  * prevCompositingFrame.  When DoComposite gets called to do Frame 4, we
 119  * copy prevCompositingFrame back, and then draw Frame 4 on top.
 120  *
 121  * @par
 122  * The mAnim structure has members only needed for animated images, so
 123  * it's not allocated until the second frame is added.
 124  */
 125
 126 namespace mozilla {
 127
 128 namespace layers {
 129 class ImageContainer;
 130 class Image;
 131 class LayersManager;
 132 }  // namespace layers
 133
 134 namespace image {
 135
 136 class Decoder;
 137 struct DecoderFinalStatus;
 138 struct DecoderTelemetry;
 139 class ImageMetadata;
 140 class SourceBuffer;
 141
 142 class RasterImage final : public ImageResource,
 143                           public nsIProperties,
 144                           public SupportsWeakPtr<RasterImage>
 145 #ifdef DEBUG
 146     ,
 147                           public imgIContainerDebug
 148 #endif
 149 {
 150   // (no public constructor - use ImageFactory)
 151   virtual ~RasterImage();
 152
 153  public:
 154   MOZ_DECLARE_WEAKREFERENCE_TYPENAME(RasterImage)
 155   NS_DECL_THREADSAFE_ISUPPORTS
 156   NS_DECL_NSIPROPERTIES
 157   NS_DECL_IMGICONTAINER
 158 #ifdef DEBUG
 159   NS_DECL_IMGICONTAINERDEBUG
 160 #endif
 161
 162   nsresult GetNativeSizes(nsTArray<gfx::IntSize>& aNativeSizes) const override;
 163   size_t GetNativeSizesLength() const override;
 164   virtual nsresult StartAnimation() override;
 165   virtual nsresult StopAnimation() override;
 166
 167   // Methods inherited from Image
 168   virtual void OnSurfaceDiscarded(const SurfaceKey& aSurfaceKey) override;
 169
 170   virtual size_t SizeOfSourceWithComputedFallback(
 171       SizeOfState& aState) const override;
 172   virtual void CollectSizeOfSurfaces(nsTArray<SurfaceMemoryCounter>& aCounters,
 173                                      MallocSizeOf aMallocSizeOf) const override;
 174
 175   /* Triggers discarding. */
 176   void Discard();
 177
 178   //////////////////////////////////////////////////////////////////////////////
 179   // Decoder callbacks.
 180   //////////////////////////////////////////////////////////////////////////////
 181
 182   /**
 183    * Sends the provided progress notifications to ProgressTracker.
 184    *
 185    * Main-thread only.
 186    *
 187    * @param aProgress    The progress notifications to send.
 188    * @param aInvalidRect An invalidation rect to send.
 189    * @param aFrameCount  If Some(), an updated count of the number of frames of
 190    *                     animation the decoder has finished decoding so far.
 191    *                     This is a lower bound for the total number of
 192    *                     animation frames this image has.
 193    * @param aDecoderFlags The decoder flags used by the decoder that generated
 194    *                      these notifications, or DefaultDecoderFlags() if the
 195    *                      notifications don't come from a decoder.
 196    * @param aSurfaceFlags The surface flags used by the decoder that generated
 197    *                      these notifications, or DefaultSurfaceFlags() if the
 198    *                      notifications don't come from a decoder.
 199    */
 200   void NotifyProgress(Progress aProgress,
 201                       const gfx::IntRect& aInvalidRect = nsIntRect(),
 202                       const Maybe<uint32_t>& aFrameCount = Nothing(),
 203                       DecoderFlags aDecoderFlags = DefaultDecoderFlags(),
 204                       SurfaceFlags aSurfaceFlags = DefaultSurfaceFlags());
 205
 206   /**
 207    * Records decoding results, sends out any final notifications, updates the
 208    * state of this image, and records telemetry.
 209    *
 210    * Main-thread only.
 211    *
 212    * @param aStatus       Final status information about the decoder. (Whether
 213    * it encountered an error, etc.)
 214    * @param aMetadata     Metadata about this image that the decoder gathered.
 215    * @param aTelemetry    Telemetry data about the decoder.
 216    * @param aProgress     Any final progress notifications to send.
 217    * @param aInvalidRect  Any final invalidation rect to send.
 218    * @param aFrameCount   If Some(), a final updated count of the number of
 219    * frames of animation the decoder has finished decoding so far. This is a
 220    * lower bound for the total number of animation frames this image has.
 221    * @param aDecoderFlags The decoder flags used by the decoder.
 222    * @param aSurfaceFlags The surface flags used by the decoder.
 223    */
 224   void NotifyDecodeComplete(
 225       const DecoderFinalStatus& aStatus, const ImageMetadata& aMetadata,
 226       const DecoderTelemetry& aTelemetry, Progress aProgress,
 227       const gfx::IntRect& aInvalidRect, const Maybe<uint32_t>& aFrameCount,
 228       DecoderFlags aDecoderFlags, SurfaceFlags aSurfaceFlags);
 229
 230   // Helper method for NotifyDecodeComplete.
 231   void ReportDecoderError();
 232
 233   //////////////////////////////////////////////////////////////////////////////
 234   // Network callbacks.
 235   //////////////////////////////////////////////////////////////////////////////
 236
 237   virtual nsresult OnImageDataAvailable(nsIRequest* aRequest,
 238                                         nsISupports* aContext,
 239                                         nsIInputStream* aInStr,
 240                                         uint64_t aSourceOffset,
 241                                         uint32_t aCount) override;
 242   virtual nsresult OnImageDataComplete(nsIRequest* aRequest,
 243                                        nsISupports* aContext, nsresult aStatus,
 244                                        bool aLastPart) override;
 245
 246   void NotifyForLoadEvent(Progress aProgress);
 247
 248   /**
 249    * A hint of the number of bytes of source data that the image contains. If
 250    * called early on, this can help reduce copying and reallocations by
 251    * appropriately preallocating the source data buffer.
 252    *
 253    * We take this approach rather than having the source data management code do
 254    * something more complicated (like chunklisting) because HTTP is by far the
 255    * dominant source of images, and the Content-Length header is quite reliable.
 256    * Thus, pre-allocation simplifies code and reduces the total number of
 257    * allocations.
 258    */
 259   nsresult SetSourceSizeHint(uint32_t aSizeHint);
 260
 261   nsCString GetURIString() {
 262     nsCString spec;
 263     if (GetURI()) {
 264       GetURI()->GetSpec(spec);
 265     }
 266     return spec;
 267   }
 268
 269  private:
 270   nsresult Init(const char* aMimeType, uint32_t aFlags);
 271
 272   /**
 273    * Tries to retrieve a surface for this image with size @aSize, surface flags
 274    * matching @aFlags, and a playback type of @aPlaybackType.
 275    *
 276    * If @aFlags specifies FLAG_SYNC_DECODE and we already have all the image
 277    * data, we'll attempt a sync decode if no matching surface is found. If
 278    * FLAG_SYNC_DECODE was not specified and no matching surface was found, we'll
 279    * kick off an async decode so that the surface is (hopefully) available next
 280    * time it's requested. aMarkUsed determines if we mark the surface used in
 281    * the surface cache or not.
 282    *
 283    * @return a drawable surface, which may be empty if the requested surface
 284    *         could not be found.
 285    */
 286   LookupResult LookupFrame(const gfx::IntSize& aSize, uint32_t aFlags,
 287                            PlaybackType aPlaybackType, bool aMarkUsed);
 288
 289   /// Helper method for LookupFrame().
 290   LookupResult LookupFrameInternal(const gfx::IntSize& aSize, uint32_t aFlags,
 291                                    PlaybackType aPlaybackType, bool aMarkUsed);
 292
 293   ImgDrawResult DrawInternal(DrawableSurface&& aFrameRef, gfxContext* aContext,
 294                              const nsIntSize& aSize, const ImageRegion& aRegion,
 295                              gfx::SamplingFilter aSamplingFilter,
 296                              uint32_t aFlags, float aOpacity);
 297
 298   Tuple<ImgDrawResult, gfx::IntSize, RefPtr<gfx::SourceSurface>>
 299   GetFrameInternal(const gfx::IntSize& aSize,
 300                    const Maybe<SVGImageContext>& aSVGContext,
 301                    uint32_t aWhichFrame, uint32_t aFlags) override;
 302
 303   Tuple<ImgDrawResult, gfx::IntSize> GetImageContainerSize(
 304       layers::LayerManager* aManager, const gfx::IntSize& aSize,
 305       uint32_t aFlags) override;
 306
 307   //////////////////////////////////////////////////////////////////////////////
 308   // Decoding.
 309   //////////////////////////////////////////////////////////////////////////////
 310
 311   /**
 312    * Creates and runs a decoder, either synchronously or asynchronously
 313    * according to @aFlags. Decodes at the provided target size @aSize, using
 314    * decode flags @aFlags. Performs a single-frame decode of this image unless
 315    * we know the image is animated *and* @aPlaybackType is
 316    * PlaybackType::eAnimated.
 317    *
 318    * It's an error to call Decode() before this image's intrinsic size is
 319    * available. A metadata decode must successfully complete first.
 320    *
 321    * Returns true of the decode was run synchronously.
 322    */
 323   bool Decode(const gfx::IntSize& aSize, uint32_t aFlags,
 324               PlaybackType aPlaybackType);
 325
 326   /**
 327    * Creates and runs a metadata decoder, either synchronously or
 328    * asynchronously according to @aFlags.
 329    */
 330   NS_IMETHOD DecodeMetadata(uint32_t aFlags);
 331
 332   /**
 333    * Sets the size, inherent orientation, animation metadata, and other
 334    * information about the image gathered during decoding.
 335    *
 336    * This function may be called multiple times, but will throw an error if
 337    * subsequent calls do not match the first.
 338    *
 339    * @param aMetadata The metadata to set on this image.
 340    * @param aFromMetadataDecode True if this metadata came from a metadata
 341    *                            decode; false if it came from a full decode.
 342    * @return |true| unless a catastrophic failure was discovered. If |false| is
 343    * returned, it indicates that the image is corrupt in a way that requires all
 344    * surfaces to be discarded to recover.
 345    */
 346   bool SetMetadata(const ImageMetadata& aMetadata, bool aFromMetadataDecode);
 347
 348   /**
 349    * In catastrophic circumstances like a GPU driver crash, the contents of our
 350    * frames may become invalid.  If the information we gathered during the
 351    * metadata decode proves to be wrong due to image corruption, the frames we
 352    * have may violate this class's invariants. Either way, we need to
 353    * immediately discard the invalid frames and redecode so that callers don't
 354    * perceive that we've entered an invalid state.
 355    *
 356    * RecoverFromInvalidFrames discards all existing frames and redecodes using
 357    * the provided @aSize and @aFlags.
 358    */
 359   void RecoverFromInvalidFrames(const nsIntSize& aSize, uint32_t aFlags);
 360
 361   void OnSurfaceDiscardedInternal(bool aAnimatedFramesDiscarded);
 362
 363  private:  // data
 364   nsIntSize mSize;
 365   nsTArray<nsIntSize> mNativeSizes;
 366   Orientation mOrientation;
 367
 368   /// If this has a value, we're waiting for SetSize() to send the load event.
 369   Maybe<Progress> mLoadProgress;
 370
 371   nsCOMPtr<nsIProperties> mProperties;
 372
 373   /// If this image is animated, a FrameAnimator which manages its animation.
 374   UniquePtr<FrameAnimator> mFrameAnimator;
 375
 376   /// Animation timeline and other state for animation images.
 377   Maybe<AnimationState> mAnimationState;
 378
 379   // Image locking.
 380   uint32_t mLockCount;
 381
 382   // The type of decoder this image needs. Computed from the MIME type in
 383   // Init().
 384   DecoderType mDecoderType;
 385
 386   // How many times we've decoded this image.
 387   // This is currently only used for statistics
 388   int32_t mDecodeCount;
 389
 390 #ifdef DEBUG
 391   uint32_t mFramesNotified;
 392 #endif
 393
 394   // The source data for this image.
 395   NotNull<RefPtr<SourceBuffer>> mSourceBuffer;
 396
 397   // Boolean flags (clustered together to conserve space):
 398   bool mHasSize : 1;         // Has SetSize() been called?
 399   bool mTransient : 1;       // Is the image short-lived?
 400   bool mSyncLoad : 1;        // Are we loading synchronously?
 401   bool mDiscardable : 1;     // Is container discardable?
 402   bool mSomeSourceData : 1;  // Do we have some source data?
 403   bool mAllSourceData : 1;   // Do we have all the source data?
 404   bool mHasBeenDecoded : 1;  // Decoded at least once?
 405
 406   // Whether we're waiting to start animation. If we get a StartAnimation() call
 407   // but we don't yet have more than one frame, mPendingAnimation is set so that
 408   // we know to start animation later if/when we have more frames.
 409   bool mPendingAnimation : 1;
 410
 411   // Whether the animation can stop, due to running out
 412   // of frames, or no more owning request
 413   bool mAnimationFinished : 1;
 414
 415   // Whether, once we are done doing a metadata decode, we should immediately
 416   // kick off a full decode.
 417   bool mWantFullDecode : 1;
 418
 419   TimeStamp mDrawStartTime;
 420
 421   //////////////////////////////////////////////////////////////////////////////
 422   // Scaling.
 423   //////////////////////////////////////////////////////////////////////////////
 424
 425   // Determines whether we can downscale during decode with the given
 426   // parameters.
 427   bool CanDownscaleDuringDecode(const nsIntSize& aSize, uint32_t aFlags);
 428
 429   // Error handling.
 430   void DoError();
 431
 432   class HandleErrorWorker : public Runnable {
 433    public:
 434     /**
 435      * Called from decoder threads when DoError() is called, since errors can't
 436      * be handled safely off-main-thread. Dispatches an event which reinvokes
 437      * DoError on the main thread if there isn't one already pending.
 438      */
 439     static void DispatchIfNeeded(RasterImage* aImage);
 440
 441     NS_IMETHOD Run() override;
 442
 443    private:
 444     explicit HandleErrorWorker(RasterImage* aImage);
 445
 446     RefPtr<RasterImage> mImage;
 447   };
 448
 449   // Helpers
 450   bool CanDiscard();
 451
 452   bool IsOpaque();
 453
 454   DrawableSurface RequestDecodeForSizeInternal(const gfx::IntSize& aSize,
 455                                                uint32_t aFlags,
 456                                                uint32_t aWhichFrame);
 457
 458  protected:
 459   explicit RasterImage(nsIURI* aURI = nullptr);
 460
 461   bool ShouldAnimate() override;
 462
 463   friend class ImageFactory;
 464 };
 465
 466 inline NS_IMETHODIMP RasterImage::GetAnimationMode(uint16_t* aAnimationMode) {
 467   return GetAnimationModeInternal(aAnimationMode);
 468 }
 469
 470 }  // namespace image
 471 }  // namespace mozilla
 472
 473 /**
 474  * Casting RasterImage to nsISupports is ambiguous. This method handles that.
 475  */
 476 inline nsISupports* ToSupports(mozilla::image::RasterImage* p) {
 477   return NS_ISUPPORTS_CAST(mozilla::image::ImageResource*, p);
 478 }
 479
 480 #endif /* mozilla_image_RasterImage_h */