Bug 1812499 [wpt PR 38184] - Simplify handling of name-to-subdir mapping in canvas...
[gecko.git] / dom / base / nsImageLoadingContent.h
blob0437380323b6ddf71a6a8c6a6bccf06ec68ba62d
1 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
2 /* vim: set ts=8 sts=2 et sw=2 tw=80: */
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/. */
7 /*
8 * A base class which implements nsIImageLoadingContent and can be
9 * subclassed by various content nodes that want to provide image
10 * loading functionality (eg <img>, <object>, etc).
13 #ifndef nsImageLoadingContent_h__
14 #define nsImageLoadingContent_h__
16 #include "imgINotificationObserver.h"
17 #include "mozilla/CORSMode.h"
18 #include "mozilla/TimeStamp.h"
19 #include "nsCOMPtr.h"
20 #include "nsIContentPolicy.h"
21 #include "nsIImageLoadingContent.h"
22 #include "nsIRequest.h"
23 #include "mozilla/dom/BindingDeclarations.h"
24 #include "mozilla/dom/Promise.h"
25 #include "mozilla/dom/RustTypes.h"
26 #include "nsAttrValue.h"
27 #include "Units.h"
29 class nsINode;
30 class nsIURI;
31 class nsPresContext;
32 class nsIContent;
33 class imgRequestProxy;
35 namespace mozilla {
36 class AsyncEventDispatcher;
37 class ErrorResult;
39 namespace dom {
40 struct BindContext;
41 class Document;
42 class Element;
43 } // namespace dom
44 } // namespace mozilla
46 #ifdef LoadImage
47 // Undefine LoadImage to prevent naming conflict with Windows.
48 # undef LoadImage
49 #endif
51 class nsImageLoadingContent : public nsIImageLoadingContent {
52 protected:
53 template <typename T>
54 using Maybe = mozilla::Maybe<T>;
55 using Nothing = mozilla::Nothing;
56 using OnNonvisible = mozilla::OnNonvisible;
57 using Visibility = mozilla::Visibility;
59 /* METHODS */
60 public:
61 nsImageLoadingContent();
62 virtual ~nsImageLoadingContent();
64 NS_DECL_IMGINOTIFICATIONOBSERVER
65 NS_DECL_NSIIMAGELOADINGCONTENT
67 // Web IDL binding methods.
68 // Note that the XPCOM SetLoadingEnabled, ForceImageState methods are OK for
69 // Web IDL bindings to use as well, since none of them throw when called via
70 // the Web IDL bindings.
72 bool LoadingEnabled() const { return mLoadingEnabled; }
73 void AddObserver(imgINotificationObserver* aObserver);
74 void RemoveObserver(imgINotificationObserver* aObserver);
75 already_AddRefed<imgIRequest> GetRequest(int32_t aRequestType,
76 mozilla::ErrorResult& aError);
77 int32_t GetRequestType(imgIRequest* aRequest, mozilla::ErrorResult& aError);
78 already_AddRefed<nsIURI> GetCurrentURI();
79 already_AddRefed<nsIURI> GetCurrentRequestFinalURI();
80 void ForceReload(bool aNotify, mozilla::ErrorResult& aError);
82 mozilla::dom::Element* FindImageMap();
84 /**
85 * Toggle whether or not to synchronously decode an image on draw.
87 void SetSyncDecodingHint(bool aHint);
89 /**
90 * Notify us that the document state has changed. Called by nsDocument so that
91 * we may reject any promises which require the document to be active.
93 void NotifyOwnerDocumentActivityChanged();
95 /**
96 * Enables/disables image state forcing. When |aForce| is true, we force
97 * nsImageLoadingContent::ImageState() to return |aState|. Call again with
98 * |aForce| as false to revert ImageState() to its original behaviour.
100 void ForceImageState(bool aForce,
101 mozilla::dom::ElementState::InternalType aState);
103 // Trigger text recognition for the current image request.
104 already_AddRefed<mozilla::dom::Promise> RecognizeCurrentImageText(
105 mozilla::ErrorResult&);
107 protected:
108 enum ImageLoadType {
109 // Most normal image loads
110 eImageLoadType_Normal,
111 // From a <img srcset> or <picture> context. Affects type given to content
112 // policy.
113 eImageLoadType_Imageset
117 * LoadImage is called by subclasses when the appropriate
118 * attributes (eg 'src' for <img> tags) change. The string passed
119 * in is the new uri string; this consolidates the code for getting
120 * the charset, constructing URI objects, and any other incidentals
121 * into this superclass.
123 * @param aNewURI the URI spec to be loaded (may be a relative URI)
124 * @param aForce If true, make sure to load the URI. If false, only
125 * load if the URI is different from the currently loaded URI.
126 * @param aNotify If true, nsIDocumentObserver state change notifications
127 * will be sent as needed.
128 * @param aImageLoadType The ImageLoadType for this request
129 * @param aTriggeringPrincipal Optional parameter specifying the triggering
130 * principal to use for the image load
132 nsresult LoadImage(const nsAString& aNewURI, bool aForce, bool aNotify,
133 ImageLoadType aImageLoadType,
134 nsIPrincipal* aTriggeringPrincipal = nullptr);
137 * ImageState is called by subclasses that are computing their content state.
138 * The return value will have the ElementState::BROKEN bit set as needed.
140 * Note that this state assumes that this node is "trying" to be an
141 * image (so for example complete lack of attempt to load an image will lead
142 * to ElementState::BROKEN being set). Subclasses that are not "trying" to
143 * be an image (eg an HTML <input> of type other than "image") should just
144 * not call this method when computing their intrinsic state.
146 mozilla::dom::ElementState ImageState() const;
149 * LoadImage is called by subclasses when the appropriate
150 * attributes (eg 'src' for <img> tags) change. If callers have an
151 * URI object already available, they should use this method.
153 * @param aNewURI the URI to be loaded
154 * @param aForce If true, make sure to load the URI. If false, only
155 * load if the URI is different from the currently loaded URI.
156 * @param aNotify If true, nsIDocumentObserver state change notifications
157 * will be sent as needed.
158 * @param aImageLoadType The ImageLoadType for this request
159 * @param aDocument Optional parameter giving the document this node is in.
160 * This is purely a performance optimization.
161 * @param aLoadFlags Optional parameter specifying load flags to use for
162 * the image load
163 * @param aTriggeringPrincipal Optional parameter specifying the triggering
164 * principal to use for the image load
166 nsresult LoadImage(nsIURI* aNewURI, bool aForce, bool aNotify,
167 ImageLoadType aImageLoadType, nsLoadFlags aLoadFlags,
168 mozilla::dom::Document* aDocument = nullptr,
169 nsIPrincipal* aTriggeringPrincipal = nullptr);
171 nsresult LoadImage(nsIURI* aNewURI, bool aForce, bool aNotify,
172 ImageLoadType aImageLoadType,
173 nsIPrincipal* aTriggeringPrincipal) {
174 return LoadImage(aNewURI, aForce, aNotify, aImageLoadType, LoadFlags(),
175 nullptr, aTriggeringPrincipal);
179 * helpers to get the document for this content (from the nodeinfo
180 * and such). Not named GetOwnerDoc/GetCurrentDoc to prevent ambiguous
181 * method names in subclasses
183 * @return the document we belong to
185 mozilla::dom::Document* GetOurOwnerDoc();
186 mozilla::dom::Document* GetOurCurrentDoc();
189 * Helper function to get the frame associated with this content. Not named
190 * GetPrimaryFrame to prevent ambiguous method names in subclasses.
192 * @return The frame we own, or nullptr if it doesn't exist, or isn't
193 * associated with any of our requests.
195 nsIFrame* GetOurPrimaryImageFrame();
198 * Helper function to get the PresContext associated with this content's
199 * frame. Not named GetPresContext to prevent ambiguous method names in
200 * subclasses.
202 * @return The nsPresContext associated with our frame, or nullptr if either
203 * the frame doesn't exist, or the frame's prescontext doesn't exist.
205 nsPresContext* GetFramePresContext();
208 * CancelImageRequests is called by subclasses when they want to
209 * cancel all image requests (for example when the subclass is
210 * somehow not an image anymore).
212 void CancelImageRequests(bool aNotify);
215 * Derived classes of nsImageLoadingContent MUST call Destroy from their
216 * destructor, or earlier. It does things that cannot be done in
217 * ~nsImageLoadingContent because they rely on being able to QueryInterface to
218 * other derived classes, which cannot happen once the derived class
219 * destructor has started calling the base class destructors.
221 void Destroy();
224 * Returns the CORS mode that will be used for all future image loads. The
225 * default implementation returns CORS_NONE unconditionally.
227 virtual mozilla::CORSMode GetCORSMode();
229 // Subclasses are *required* to call BindToTree/UnbindFromTree.
230 void BindToTree(mozilla::dom::BindContext&, nsINode& aParent);
231 void UnbindFromTree(bool aNullParent);
233 void OnLoadComplete(imgIRequest* aRequest, nsresult aStatus);
234 void OnUnlockedDraw();
235 void OnImageIsAnimated(imgIRequest* aRequest);
237 // The nsContentPolicyType we would use for this ImageLoadType
238 static nsContentPolicyType PolicyTypeForLoad(ImageLoadType aImageLoadType);
240 void AsyncEventRunning(mozilla::AsyncEventDispatcher* aEvent);
242 // Get ourselves as an nsIContent*. Not const because some of the callers
243 // want a non-const nsIContent.
244 virtual nsIContent* AsContent() = 0;
247 * Get width and height of the current request, using given image request if
248 * attributes are unset.
250 MOZ_CAN_RUN_SCRIPT mozilla::CSSIntSize GetWidthHeightForImage();
253 * Create a promise and queue a microtask which will ensure the current
254 * request (after any pending loads are applied) has requested a full decode.
255 * The promise is fulfilled once the request has a fully decoded surface that
256 * is available for drawing, or an error condition occurrs (e.g. broken image,
257 * current request is updated, etc).
259 * https://html.spec.whatwg.org/multipage/embedded-content.html#dom-img-decode
261 already_AddRefed<mozilla::dom::Promise> QueueDecodeAsync(
262 mozilla::ErrorResult& aRv);
264 enum class ImageDecodingType : uint8_t {
265 Auto,
266 Async,
267 Sync,
270 static const nsAttrValue::EnumTable kDecodingTable[];
271 static const nsAttrValue::EnumTable* kDecodingTableDefault;
273 private:
275 * Enqueue and/or fulfill a promise created by QueueDecodeAsync.
277 void DecodeAsync(RefPtr<mozilla::dom::Promise>&& aPromise,
278 uint32_t aRequestGeneration);
281 * Attempt to resolve all queued promises based on the state of the current
282 * request. If the current request does not yet have all of the encoded data,
283 * or the decoding has not yet completed, it will return without changing the
284 * promise states.
286 void MaybeResolveDecodePromises();
289 * Reject all queued promises with the given status.
291 void RejectDecodePromises(nsresult aStatus);
294 * Age the generation counter if we have a new current request with a
295 * different URI. If the generation counter is aged, then all queued promises
296 * will also be rejected.
298 void MaybeAgeRequestGeneration(nsIURI* aNewURI);
301 * Deregister as an observer for the owner document's activity notifications
302 * if we have no outstanding decode promises.
304 void MaybeDeregisterActivityObserver();
307 * Struct used to manage the native image observers.
309 struct ImageObserver {
310 explicit ImageObserver(imgINotificationObserver* aObserver);
311 ~ImageObserver();
313 nsCOMPtr<imgINotificationObserver> mObserver;
314 ImageObserver* mNext;
318 * Struct used to manage the scripted/XPCOM image observers.
320 class ScriptedImageObserver final {
321 public:
322 NS_INLINE_DECL_REFCOUNTING(ScriptedImageObserver)
324 ScriptedImageObserver(imgINotificationObserver* aObserver,
325 RefPtr<imgRequestProxy>&& aCurrentRequest,
326 RefPtr<imgRequestProxy>&& aPendingRequest);
327 bool CancelRequests();
329 nsCOMPtr<imgINotificationObserver> mObserver;
330 RefPtr<imgRequestProxy> mCurrentRequest;
331 RefPtr<imgRequestProxy> mPendingRequest;
333 private:
334 ~ScriptedImageObserver();
338 * Struct to report state changes
340 struct AutoStateChanger {
341 AutoStateChanger(nsImageLoadingContent* aImageContent, bool aNotify)
342 : mImageContent(aImageContent), mNotify(aNotify) {
343 mImageContent->mStateChangerDepth++;
345 ~AutoStateChanger() {
346 mImageContent->mStateChangerDepth--;
347 mImageContent->UpdateImageState(mNotify);
350 nsImageLoadingContent* mImageContent;
351 bool mNotify;
354 friend struct AutoStateChanger;
357 * Method to fire an event once we know what's going on with the image load.
359 * @param aEventType "load", or "error" depending on how things went
360 * @param aIsCancelable true if event is cancelable.
362 nsresult FireEvent(const nsAString& aEventType, bool aIsCancelable = false);
365 * Method to cancel and null-out pending event if they exist.
367 void CancelPendingEvent();
369 RefPtr<mozilla::AsyncEventDispatcher> mPendingEvent;
371 protected:
373 * UpdateImageState recomputes the current state of this image loading
374 * content and updates what ImageState() returns accordingly. It will also
375 * fire a ContentStatesChanged() notification as needed if aNotify is true.
377 void UpdateImageState(bool aNotify);
380 * Method to create an nsIURI object from the given string (will
381 * handle getting the right charset, base, etc). You MUST pass in a
382 * non-null document to this function.
384 * @param aSpec the string spec (from an HTML attribute, eg)
385 * @param aDocument the document we belong to
386 * @return the URI we want to be loading
388 nsresult StringToURI(const nsAString& aSpec,
389 mozilla::dom::Document* aDocument, nsIURI** aURI);
392 * Prepare and returns a reference to the "next request". If there's already
393 * a _usable_ current request (one with SIZE_AVAILABLE), this request is
394 * "pending" until it becomes usable. Otherwise, this becomes the current
395 * request.
397 * @param aImageLoadType The ImageLoadType for this request
399 RefPtr<imgRequestProxy>& PrepareNextRequest(ImageLoadType aImageLoadType);
402 * Returns a COMPtr reference to the current/pending image requests, cleaning
403 * up and canceling anything that was there before. Note that if you just want
404 * to get rid of one of the requests, you should call
405 * Clear*Request(NS_BINDING_ABORTED) instead.
407 * @param aImageLoadType The ImageLoadType for this request
409 RefPtr<imgRequestProxy>& PrepareCurrentRequest(ImageLoadType aImageLoadType);
410 RefPtr<imgRequestProxy>& PreparePendingRequest(ImageLoadType aImageLoadType);
413 * Switch our pending request to be our current request.
414 * mPendingRequest must be non-null!
416 void MakePendingRequestCurrent();
419 * Cancels and nulls-out the "current" and "pending" requests if they exist.
421 * @param aNonvisibleAction An action to take if the image is no longer
422 * visible as a result; see |UntrackImage|.
424 void ClearCurrentRequest(
425 nsresult aReason,
426 const Maybe<OnNonvisible>& aNonvisibleAction = Nothing());
427 void ClearPendingRequest(
428 nsresult aReason,
429 const Maybe<OnNonvisible>& aNonvisibleAction = Nothing());
432 * Reset animation of the current request if
433 * |mNewRequestsWillNeedAnimationReset| was true when the request was
434 * prepared.
436 void ResetAnimationIfNeeded();
439 * Static helper method to tell us if we have the size of a request. The
440 * image may be null.
442 static bool HaveSize(imgIRequest* aImage);
445 * Adds/Removes a given imgIRequest from our document's tracker.
447 * No-op if aImage is null.
449 * @param aFrame If called from FrameCreated the frame passed to FrameCreated.
450 * This is our frame, but at the time of the FrameCreated call
451 * our primary frame pointer hasn't been set yet, so this is
452 * only way to get our frame.
454 * @param aNonvisibleAction A requested action if the frame has become
455 * nonvisible. If Nothing(), no action is
456 * requested. If DISCARD_IMAGES is specified, the
457 * frame is requested to ask any images it's
458 * associated with to discard their surfaces if
459 * possible.
461 void TrackImage(imgIRequest* aImage, nsIFrame* aFrame = nullptr);
462 void UntrackImage(imgIRequest* aImage,
463 const Maybe<OnNonvisible>& aNonvisibleAction = Nothing());
465 nsLoadFlags LoadFlags();
467 /* MEMBERS */
468 RefPtr<imgRequestProxy> mCurrentRequest;
469 RefPtr<imgRequestProxy> mPendingRequest;
470 uint8_t mCurrentRequestFlags = 0;
471 uint8_t mPendingRequestFlags = 0;
473 enum {
474 // Set if the request needs ResetAnimation called on it.
475 REQUEST_NEEDS_ANIMATION_RESET = 1 << 0,
476 // Set if the request is currently tracked with the document.
477 REQUEST_IS_TRACKED = 1 << 1,
478 // Set if this is an imageset request, such as from <img srcset> or
479 // <picture>
480 REQUEST_IS_IMAGESET = 1 << 2,
483 // If the image was blocked or if there was an error loading, it's nice to
484 // still keep track of what the URI was despite not having an imgIRequest.
485 // We only maintain this in those situations (in the common case, this is
486 // always null).
487 nsCOMPtr<nsIURI> mCurrentURI;
489 private:
491 * Clones the given "current" or "pending" request for each scripted observer.
493 void CloneScriptedRequests(imgRequestProxy* aRequest);
496 * Cancels and nulls-out the "current" or "pending" requests if they exist
497 * for each scripted observer.
499 void ClearScriptedRequests(int32_t aRequestType, nsresult aReason);
502 * Moves the "pending" request into the "current" request for each scripted
503 * observer. If there is an existing "current" request, it will cancel it
504 * first.
506 void MakePendingScriptedRequestsCurrent();
509 * Depending on the configured decoding hint, and/or how recently we updated
510 * the image request, force or stop the frame from decoding the image
511 * synchronously when it is drawn.
512 * @param aPrepareNextRequest True if this is when updating the image request.
513 * @param aFrame If called from FrameCreated the frame passed to FrameCreated.
514 * This is our frame, but at the time of the FrameCreated call
515 * our primary frame pointer hasn't been set yet, so this is
516 * only way to get our frame.
518 void MaybeForceSyncDecoding(bool aPrepareNextRequest,
519 nsIFrame* aFrame = nullptr);
522 * Typically we will have only one observer (our frame in the screen
523 * prescontext), so we want to only make space for one and to
524 * heap-allocate anything past that (saves memory and malloc churn
525 * in the common case). The storage is a linked list, we just
526 * happen to actually hold the first observer instead of a pointer
527 * to it.
529 ImageObserver mObserverList;
532 * Typically we will have no scripted observers, as this is only used by
533 * chrome, legacy extensions, and some mochitests. An empty array reserves
534 * minimal memory.
536 nsTArray<RefPtr<ScriptedImageObserver>> mScriptedObservers;
539 * Promises created by QueueDecodeAsync that are still waiting to be
540 * fulfilled by the image being fully decoded.
542 nsTArray<RefPtr<mozilla::dom::Promise>> mDecodePromises;
545 * When mIsImageStateForced is true, this holds the ImageState that we'll
546 * return in ImageState().
548 mozilla::dom::ElementState mForcedImageState;
550 mozilla::TimeStamp mMostRecentRequestChange;
553 * Total number of outstanding decode promises, including those stored in
554 * mDecodePromises and those embedded in runnables waiting to be enqueued.
555 * This is used to determine whether we need to register as an observer for
556 * document activity notifications.
558 size_t mOutstandingDecodePromises;
561 * An incrementing counter representing the current request generation;
562 * Each time mCurrentRequest is modified with a different URI, this will
563 * be incremented. Each QueueDecodeAsync call will cache the generation
564 * of the current request so that when it is processed, it knows if it
565 * should have rejected because the request changed.
567 uint32_t mRequestGeneration;
569 bool mLoadingEnabled : 1;
572 * When true, we return mForcedImageState from ImageState().
574 bool mIsImageStateForced : 1;
577 * The state we had the last time we checked whether we needed to notify the
578 * document of a state change. These are maintained by UpdateImageState.
580 bool mLoading : 1;
581 bool mBroken : 1;
583 protected:
585 * A hack to get animations to reset, see bug 594771. On requests
586 * that originate from setting .src, we mark them for needing their animation
587 * reset when they are ready. mNewRequestsWillNeedAnimationReset is set to
588 * true while preparing such requests (as a hack around needing to change an
589 * interface), and the other two booleans store which of the current
590 * and pending requests are of the sort that need their animation restarted.
592 bool mNewRequestsWillNeedAnimationReset : 1;
595 * Flag to indicate whether the channel should be mark as urgent-start.
596 * It should be set in *Element and passed to nsContentUtils::LoadImage.
597 * True if we want to set nsIClassOfService::UrgentStart to the channel to
598 * get the response ASAP for better user responsiveness.
600 bool mUseUrgentStartForChannel : 1;
602 // Represents the image is deferred loading until this element gets visible.
603 bool mLazyLoading : 1;
605 private:
606 /* The number of nested AutoStateChangers currently tracking our state. */
607 uint8_t mStateChangerDepth;
609 // Flags to indicate whether each of the current and pending requests are
610 // registered with the refresh driver.
611 bool mCurrentRequestRegistered;
612 bool mPendingRequestRegistered;
614 // TODO:
615 // Bug 1353685: Should ServiceWorker call SetBlockedRequest?
617 // This member is used in SetBlockedRequest, if it's true, then this call is
618 // triggered from LoadImage.
619 // If this is false, it means this call is from other places like
620 // ServiceWorker, then we will ignore call to SetBlockedRequest for now.
622 // Also we use this variable to check if some evil code is reentering
623 // LoadImage.
624 bool mIsStartingImageLoad;
626 // If true, force frames to synchronously decode images on draw.
627 bool mSyncDecodingHint;
630 #endif // nsImageLoadingContent_h__