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 "nsTArray.h"
24 #include "LookupResult.h"
25 #include "nsThreadUtils.h"
26 #include "DecoderFactory.h"
27 #include "FrameAnimator.h"
28 #include "ImageMetadata.h"
29 #include "ISurfaceProvider.h"
30 #include "Orientation.h"
31 #include "mozilla/AtomicBitfields.h"
32 #include "mozilla/Attributes.h"
33 #include "mozilla/Maybe.h"
34 #include "mozilla/MemoryReporting.h"
35 #include "mozilla/NotNull.h"
36 #include "mozilla/StaticPrefs_image.h"
37 #include "mozilla/TimeStamp.h"
38 #include "mozilla/WeakPtr.h"
39 #include "mozilla/UniquePtr.h"
40 #include "mozilla/image/Resolution.h"
41 #include "ImageContainer.h"
42 #include "PlaybackType.h"
43 #ifdef DEBUG
44 # include "imgIContainerDebug.h"
45 #endif
46
47 class nsIInputStream;
48 class nsIRequest;
49
50 #define NS_RASTERIMAGE_CID \
51 { /* 376ff2c1-9bf6-418a-b143-3340c00112f7 */ \
52 0x376ff2c1, 0x9bf6, 0x418a, { \
53 0xb1, 0x43, 0x33, 0x40, 0xc0, 0x01, 0x12, 0xf7 \
54 } \
55 }
56
57 /**
58 * Handles static and animated image containers.
59 *
60 *
61 * @par A Quick Walk Through
62 * The decoder initializes this class and calls AppendFrame() to add a frame.
63 * Once RasterImage detects more than one frame, it starts the animation
64 * with StartAnimation(). Note that the invalidation events for RasterImage are
65 * generated automatically using nsRefreshDriver.
66 *
67 * @par
68 * StartAnimation() initializes the animation helper object and sets the time
69 * the first frame was displayed to the current clock time.
70 *
71 * @par
72 * When the refresh driver corresponding to the imgIContainer that this image is
73 * a part of notifies the RasterImage that it's time to invalidate,
74 * RequestRefresh() is called with a given TimeStamp to advance to. As long as
75 * the timeout of the given frame (the frame's "delay") plus the time that frame
76 * was first displayed is less than or equal to the TimeStamp given,
77 * RequestRefresh() calls AdvanceFrame().
78 *
79 * @par
80 * AdvanceFrame() is responsible for advancing a single frame of the animation.
81 * It can return true, meaning that the frame advanced, or false, meaning that
82 * the frame failed to advance (usually because the next frame hasn't been
83 * decoded yet). It is also responsible for performing the final animation stop
84 * procedure if the final frame of a non-looping animation is reached.
85 *
86 * @par
87 * Each frame can have a different method of removing itself. These are
88 * listed as imgIContainer::cDispose... constants. Notify() calls
89 * DoComposite() to handle any special frame destruction.
90 *
91 * @par
92 * The basic path through DoComposite() is:
93 * 1) Calculate Area that needs updating, which is at least the area of
94 * aNextFrame.
95 * 2) Dispose of previous frame.
96 * 3) Draw new image onto compositingFrame.
97 * See comments in DoComposite() for more information and optimizations.
98 *
99 * @par
100 * The rest of the RasterImage specific functions are used by DoComposite to
101 * destroy the old frame and build the new one.
102 *
103 * @note
104 * <li> "Mask", "Alpha", and "Alpha Level" are interchangeable phrases in
105 * respects to RasterImage.
106 *
107 * @par
108 * <li> GIFs never have more than a 1 bit alpha.
109 * <li> APNGs may have a full alpha channel.
110 *
111 * @par
112 * <li> Background color specified in GIF is ignored by web browsers.
113 *
114 * @par
115 * <li> If Frame 3 wants to dispose by restoring previous, what it wants is to
116 * restore the composition up to and including Frame 2, as well as Frame 2s
117 * disposal. So, in the middle of DoComposite when composing Frame 3, right
118 * after destroying Frame 2's area, we copy compositingFrame to
119 * prevCompositingFrame. When DoComposite gets called to do Frame 4, we
120 * copy prevCompositingFrame back, and then draw Frame 4 on top.
121 *
122 * @par
123 * The mAnim structure has members only needed for animated images, so
124 * it's not allocated until the second frame is added.
125 */
126
127 namespace mozilla {
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 SupportsWeakPtr
144 #ifdef DEBUG
145 ,
146 public imgIContainerDebug
147 #endif
148 {
149 // (no public constructor - use ImageFactory)
150 virtual ~RasterImage();
151
152 public:
153 NS_DECL_THREADSAFE_ISUPPORTS
154 NS_DECL_IMGICONTAINER
155 #ifdef DEBUG
156 NS_DECL_IMGICONTAINERDEBUG
157 #endif
158
159 nsresult GetNativeSizes(nsTArray<gfx::IntSize>& aNativeSizes) const override;
160 size_t GetNativeSizesLength() const override;
161 virtual nsresult StartAnimation() override;
162 virtual nsresult StopAnimation() override;
163
164 // Methods inherited from Image
165 virtual void OnSurfaceDiscarded(const SurfaceKey& aSurfaceKey) override;
166
167 virtual size_t SizeOfSourceWithComputedFallback(
168 SizeOfState& aState) const override;
169
170 /* Triggers discarding. */
171 void Discard();
172
173 //////////////////////////////////////////////////////////////////////////////
174 // Decoder callbacks.
175 //////////////////////////////////////////////////////////////////////////////
176
177 /**
178 * Sends the provided progress notifications to ProgressTracker.
179 *
180 * Main-thread only.
181 *
182 * @param aProgress The progress notifications to send.
183 * @param aInvalidRect An invalidation rect to send.
184 * @param aFrameCount If Some(), an updated count of the number of frames of
185 * animation the decoder has finished decoding so far.
186 * This is a lower bound for the total number of
187 * animation frames this image has.
188 * @param aDecoderFlags The decoder flags used by the decoder that generated
189 * these notifications, or DefaultDecoderFlags() if the
190 * notifications don't come from a decoder.
191 * @param aSurfaceFlags The surface flags used by the decoder that generated
192 * these notifications, or DefaultSurfaceFlags() if the
193 * notifications don't come from a decoder.
194 */
195 void NotifyProgress(Progress aProgress,
196 const OrientedIntRect& aInvalidRect = OrientedIntRect(),
197 const Maybe<uint32_t>& aFrameCount = Nothing(),
198 DecoderFlags aDecoderFlags = DefaultDecoderFlags(),
199 SurfaceFlags aSurfaceFlags = DefaultSurfaceFlags());
200
201 /**
202 * Records decoding results, sends out any final notifications, updates the
203 * state of this image, and records telemetry.
204 *
205 * Main-thread only.
206 *
207 * @param aStatus Final status information about the decoder. (Whether
208 * it encountered an error, etc.)
209 * @param aMetadata Metadata about this image that the decoder gathered.
210 * @param aTelemetry Telemetry data about the decoder.
211 * @param aProgress Any final progress notifications to send.
212 * @param aInvalidRect Any final invalidation rect to send.
213 * @param aFrameCount If Some(), a final updated count of the number of
214 * frames of animation the decoder has finished decoding so far. This is a
215 * lower bound for the total number of animation frames this image has.
216 * @param aDecoderFlags The decoder flags used by the decoder.
217 * @param aSurfaceFlags The surface flags used by the decoder.
218 */
219 void NotifyDecodeComplete(
220 const DecoderFinalStatus& aStatus, const ImageMetadata& aMetadata,
221 const DecoderTelemetry& aTelemetry, Progress aProgress,
222 const OrientedIntRect& aInvalidRect, const Maybe<uint32_t>& aFrameCount,
223 DecoderFlags aDecoderFlags, SurfaceFlags aSurfaceFlags);
224
225 // Helper method for NotifyDecodeComplete.
226 void ReportDecoderError();
227
228 //////////////////////////////////////////////////////////////////////////////
229 // Network callbacks.
230 //////////////////////////////////////////////////////////////////////////////
231
232 virtual nsresult OnImageDataAvailable(nsIRequest* aRequest,
233 nsIInputStream* aInStr,
234 uint64_t aSourceOffset,
235 uint32_t aCount) override;
236 virtual nsresult OnImageDataComplete(nsIRequest* aRequest, nsresult aStatus,
237 bool aLastPart) override;
238
239 void NotifyForLoadEvent(Progress aProgress);
240
241 /**
242 * A hint of the number of bytes of source data that the image contains. If
243 * called early on, this can help reduce copying and reallocations by
244 * appropriately preallocating the source data buffer.
245 *
246 * We take this approach rather than having the source data management code do
247 * something more complicated (like chunklisting) because HTTP is by far the
248 * dominant source of images, and the Content-Length header is quite reliable.
249 * Thus, pre-allocation simplifies code and reduces the total number of
250 * allocations.
251 */
252 nsresult SetSourceSizeHint(uint32_t aSizeHint);
253
GetURIString()254 nsCString GetURIString() {
255 nsCString spec;
256 if (GetURI()) {
257 GetURI()->GetSpec(spec);
258 }
259 return spec;
260 }
261
262 private:
263 nsresult Init(const char* aMimeType, uint32_t aFlags);
264
265 /**
266 * Tries to retrieve a surface for this image with size @aSize, surface flags
267 * matching @aFlags, and a playback type of @aPlaybackType.
268 *
269 * If @aFlags specifies FLAG_SYNC_DECODE and we already have all the image
270 * data, we'll attempt a sync decode if no matching surface is found. If
271 * FLAG_SYNC_DECODE was not specified and no matching surface was found, we'll
272 * kick off an async decode so that the surface is (hopefully) available next
273 * time it's requested. aMarkUsed determines if we mark the surface used in
274 * the surface cache or not.
275 *
276 * @return a drawable surface, which may be empty if the requested surface
277 * could not be found.
278 */
279 LookupResult LookupFrame(const OrientedIntSize& aSize, uint32_t aFlags,
280 PlaybackType aPlaybackType, bool aMarkUsed);
281
282 /// Helper method for LookupFrame().
283 LookupResult LookupFrameInternal(const OrientedIntSize& aSize,
284 uint32_t aFlags, PlaybackType aPlaybackType,
285 bool aMarkUsed);
286
287 ImgDrawResult DrawInternal(DrawableSurface&& aFrameRef, gfxContext* aContext,
288 const OrientedIntSize& aSize,
289 const ImageRegion& aRegion,
290 gfx::SamplingFilter aSamplingFilter,
291 uint32_t aFlags, float aOpacity);
292
293 //////////////////////////////////////////////////////////////////////////////
294 // Decoding.
295 //////////////////////////////////////////////////////////////////////////////
296
297 /**
298 * Creates and runs a decoder, either synchronously or asynchronously
299 * according to @aFlags. Decodes at the provided target size @aSize, using
300 * decode flags @aFlags. Performs a single-frame decode of this image unless
301 * we know the image is animated *and* @aPlaybackType is
302 * PlaybackType::eAnimated.
303 *
304 * It's an error to call Decode() before this image's intrinsic size is
305 * available. A metadata decode must successfully complete first.
306 *
307 * aOutRanSync is set to true if the decode was run synchronously.
308 * aOutFailed is set to true if failed to start a decode.
309 */
310 void Decode(const OrientedIntSize& aSize, uint32_t aFlags,
311 PlaybackType aPlaybackType, bool& aOutRanSync, bool& aOutFailed);
312
313 /**
314 * Creates and runs a metadata decoder, either synchronously or
315 * asynchronously according to @aFlags.
316 */
317 NS_IMETHOD DecodeMetadata(uint32_t aFlags);
318
319 /**
320 * Sets the size, inherent orientation, animation metadata, and other
321 * information about the image gathered during decoding.
322 *
323 * This function may be called multiple times, but will throw an error if
324 * subsequent calls do not match the first.
325 *
326 * @param aMetadata The metadata to set on this image.
327 * @param aFromMetadataDecode True if this metadata came from a metadata
328 * decode; false if it came from a full decode.
329 * @return |true| unless a catastrophic failure was discovered. If |false| is
330 * returned, it indicates that the image is corrupt in a way that requires all
331 * surfaces to be discarded to recover.
332 */
333 bool SetMetadata(const ImageMetadata& aMetadata, bool aFromMetadataDecode);
334
335 /**
336 * In catastrophic circumstances like a GPU driver crash, the contents of our
337 * frames may become invalid. If the information we gathered during the
338 * metadata decode proves to be wrong due to image corruption, the frames we
339 * have may violate this class's invariants. Either way, we need to
340 * immediately discard the invalid frames and redecode so that callers don't
341 * perceive that we've entered an invalid state.
342 *
343 * RecoverFromInvalidFrames discards all existing frames and redecodes using
344 * the provided @aSize and @aFlags.
345 */
346 void RecoverFromInvalidFrames(const OrientedIntSize& aSize, uint32_t aFlags);
347
348 void OnSurfaceDiscardedInternal(bool aAnimatedFramesDiscarded);
349
350 private: // data
351 OrientedIntSize mSize;
352 nsTArray<OrientedIntSize> mNativeSizes;
353
354 // The orientation required to correctly orient the image, from the image's
355 // metadata. RasterImage will handle and apply this orientation itself.
356 Orientation mOrientation;
357
358 // The resolution as specified in the image metadata, in dppx.
359 Resolution mResolution;
360
361 /// If this has a value, we're waiting for SetSize() to send the load event.
362 Maybe<Progress> mLoadProgress;
363
364 // Hotspot of this image, or (0, 0) if there is no hotspot data.
365 //
366 // We assume (and assert) that no image has both orientation metadata and a
367 // hotspot, so we store this as an untyped point.
368 gfx::IntPoint mHotspot;
369
370 /// If this image is animated, a FrameAnimator which manages its animation.
371 UniquePtr<FrameAnimator> mFrameAnimator;
372
373 /// Animation timeline and other state for animation images.
374 Maybe<AnimationState> mAnimationState;
375
376 // Image locking.
377 uint32_t mLockCount;
378
379 // The type of decoder this image needs. Computed from the MIME type in
380 // Init().
381 DecoderType mDecoderType;
382
383 // How many times we've decoded this image.
384 // This is currently only used for statistics
385 int32_t mDecodeCount;
386
387 #ifdef DEBUG
388 uint32_t mFramesNotified;
389 #endif
390
391 // The source data for this image.
392 NotNull<RefPtr<SourceBuffer>> mSourceBuffer;
393
394 // Boolean flags (clustered together to conserve space):
395 MOZ_ATOMIC_BITFIELDS(
396 mAtomicBitfields, 16,
397 ((bool, HasSize, 1), // Has SetSize() been called?
398 (bool, Transient, 1), // Is the image short-lived?
399 (bool, SyncLoad, 1), // Are we loading synchronously?
400 (bool, Discardable, 1), // Is container discardable?
401 (bool, SomeSourceData, 1), // Do we have some source data?
402 (bool, AllSourceData, 1), // Do we have all the source data?
403 (bool, HasBeenDecoded, 1), // Decoded at least once?
404
405 // Whether we're waiting to start animation. If we get a StartAnimation()
406 // call but we don't yet have more than one frame, mPendingAnimation is
407 // set so that we know to start animation later if/when we have more
408 // frames.
409 (bool, PendingAnimation, 1),
410
411 // Whether the animation can stop, due to running out
412 // of frames, or no more owning request
413 (bool, AnimationFinished, 1),
414
415 // Whether, once we are done doing a metadata decode, we should
416 // immediately kick off a full decode.
417 (bool, WantFullDecode, 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 OrientedIntSize& 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 LookupResult RequestDecodeForSizeInternal(const OrientedIntSize& 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
GetAnimationMode(uint16_t * aAnimationMode)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 */
ToSupports(mozilla::image::RasterImage * p)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 */
481