image/SurfaceCache.h

   1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* This Source Code Form is subject to the terms of the Mozilla Public
   3  * License, v. 2.0. If a copy of the MPL was not distributed with this
   4  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   5
   6 /**
   7  * SurfaceCache is a service for caching temporary surfaces and decoded image
   8  * data in imagelib.
   9  */
  10
  11 #ifndef mozilla_image_SurfaceCache_h
  12 #define mozilla_image_SurfaceCache_h
  13
  14 #include "mozilla/HashFunctions.h"    // for HashGeneric and AddToHash
  15 #include "mozilla/Maybe.h"            // for Maybe
  16 #include "mozilla/MemoryReporting.h"  // for MallocSizeOf
  17 #include "mozilla/NotNull.h"
  18 #include "mozilla/SVGImageContext.h"  // for SVGImageContext
  19 #include "mozilla/gfx/2D.h"           // for SourceSurface
  20 #include "mozilla/gfx/Point.h"        // for mozilla::gfx::IntSize
  21 #include "gfx2DGlue.h"
  22 #include "gfxPoint.h"  // for gfxSize
  23 #include "nsCOMPtr.h"  // for already_AddRefed
  24 #include "ImageRegion.h"
  25 #include "PlaybackType.h"
  26 #include "SurfaceFlags.h"
  27
  28 namespace mozilla {
  29 namespace image {
  30
  31 class ImageResource;
  32 class ISurfaceProvider;
  33 class LookupResult;
  34 class SurfaceCacheImpl;
  35 struct SurfaceMemoryCounter;
  36
  37 /*
  38  * ImageKey contains the information we need to look up all SurfaceCache entries
  39  * for a particular image.
  40  */
  41 using ImageKey = ImageResource*;
  42
  43 /*
  44  * SurfaceKey contains the information we need to look up a specific
  45  * SurfaceCache entry. Together with an ImageKey, this uniquely identifies the
  46  * surface.
  47  *
  48  * Callers should construct a SurfaceKey using the appropriate helper function
  49  * for their image type - either RasterSurfaceKey or VectorSurfaceKey.
  50  */
  51 class SurfaceKey {
  52   typedef gfx::IntSize IntSize;
  53
  54  public:
  55   bool operator==(const SurfaceKey& aOther) const {
  56     return aOther.mSize == mSize && aOther.mRegion == mRegion &&
  57            aOther.mSVGContext == mSVGContext && aOther.mPlayback == mPlayback &&
  58            aOther.mFlags == mFlags;
  59   }
  60
  61   PLDHashNumber Hash() const {
  62     PLDHashNumber hash = HashGeneric(mSize.width, mSize.height);
  63     hash = AddToHash(hash, mRegion.map(HashIIR).valueOr(0));
  64     hash = AddToHash(hash, HashSIC(mSVGContext));
  65     hash = AddToHash(hash, uint8_t(mPlayback), uint32_t(mFlags));
  66     return hash;
  67   }
  68
  69   SurfaceKey CloneWithSize(const IntSize& aSize) const {
  70     return SurfaceKey(aSize, mRegion, mSVGContext, mPlayback, mFlags);
  71   }
  72
  73   const IntSize& Size() const { return mSize; }
  74   const Maybe<ImageIntRegion>& Region() const { return mRegion; }
  75   const SVGImageContext& SVGContext() const { return mSVGContext; }
  76   PlaybackType Playback() const { return mPlayback; }
  77   SurfaceFlags Flags() const { return mFlags; }
  78
  79  private:
  80   SurfaceKey(const IntSize& aSize, const Maybe<ImageIntRegion>& aRegion,
  81              const SVGImageContext& aSVGContext, PlaybackType aPlayback,
  82              SurfaceFlags aFlags)
  83       : mSize(aSize),
  84         mRegion(aRegion),
  85         mSVGContext(aSVGContext),
  86         mPlayback(aPlayback),
  87         mFlags(aFlags) {}
  88
  89   static PLDHashNumber HashIIR(const ImageIntRegion& aIIR) {
  90     return aIIR.Hash();
  91   }
  92
  93   static PLDHashNumber HashSIC(const SVGImageContext& aSIC) {
  94     return aSIC.Hash();
  95   }
  96
  97   friend SurfaceKey RasterSurfaceKey(const IntSize&, SurfaceFlags,
  98                                      PlaybackType);
  99   friend SurfaceKey VectorSurfaceKey(const IntSize&, const SVGImageContext&);
 100   friend SurfaceKey VectorSurfaceKey(const IntSize&,
 101                                      const Maybe<ImageIntRegion>&,
 102                                      const SVGImageContext&, SurfaceFlags,
 103                                      PlaybackType);
 104
 105   IntSize mSize;
 106   Maybe<ImageIntRegion> mRegion;
 107   SVGImageContext mSVGContext;
 108   PlaybackType mPlayback;
 109   SurfaceFlags mFlags;
 110 };
 111
 112 inline SurfaceKey RasterSurfaceKey(const gfx::IntSize& aSize,
 113                                    SurfaceFlags aFlags,
 114                                    PlaybackType aPlayback) {
 115   return SurfaceKey(aSize, Nothing(), SVGImageContext(), aPlayback, aFlags);
 116 }
 117
 118 inline SurfaceKey VectorSurfaceKey(const gfx::IntSize& aSize,
 119                                    const Maybe<ImageIntRegion>& aRegion,
 120                                    const SVGImageContext& aSVGContext,
 121                                    SurfaceFlags aFlags,
 122                                    PlaybackType aPlayback) {
 123   return SurfaceKey(aSize, aRegion, aSVGContext, aPlayback, aFlags);
 124 }
 125
 126 inline SurfaceKey VectorSurfaceKey(const gfx::IntSize& aSize,
 127                                    const SVGImageContext& aSVGContext) {
 128   // We don't care about aFlags for VectorImage because none of the flags we
 129   // have right now influence VectorImage's rendering. If we add a new flag that
 130   // *does* affect how a VectorImage renders, we'll have to change this.
 131   // Similarly, we don't accept a PlaybackType parameter because we don't
 132   // currently cache frames of animated SVG images.
 133   return SurfaceKey(aSize, Nothing(), aSVGContext, PlaybackType::eStatic,
 134                     DefaultSurfaceFlags());
 135 }
 136
 137 /**
 138  * AvailabilityState is used to track whether an ISurfaceProvider has a surface
 139  * available or is just a placeholder.
 140  *
 141  * To ensure that availability changes are atomic (and especially that internal
 142  * SurfaceCache code doesn't have to deal with asynchronous availability
 143  * changes), an ISurfaceProvider which starts as a placeholder can only reveal
 144  * the fact that it now has a surface available via a call to
 145  * SurfaceCache::SurfaceAvailable().
 146  *
 147  * It also tracks whether or not there are "explicit" users of this surface
 148  * which will not accept substitutes. This is used by SurfaceCache when pruning
 149  * unnecessary surfaces from the cache.
 150  */
 151 class AvailabilityState {
 152  public:
 153   static AvailabilityState StartAvailable() { return AvailabilityState(true); }
 154   static AvailabilityState StartAsPlaceholder() {
 155     return AvailabilityState(false);
 156   }
 157
 158   bool IsAvailable() const { return mIsAvailable; }
 159   bool IsPlaceholder() const { return !mIsAvailable; }
 160   bool CannotSubstitute() const { return mCannotSubstitute; }
 161
 162   void SetCannotSubstitute() { mCannotSubstitute = true; }
 163
 164  private:
 165   friend class SurfaceCacheImpl;
 166
 167   explicit AvailabilityState(bool aIsAvailable)
 168       : mIsAvailable(aIsAvailable), mCannotSubstitute(false) {}
 169
 170   void SetAvailable() { mIsAvailable = true; }
 171
 172   bool mIsAvailable : 1;
 173   bool mCannotSubstitute : 1;
 174 };
 175
 176 enum class InsertOutcome : uint8_t {
 177   SUCCESS,                 // Success (but see Insert documentation).
 178   FAILURE,                 // Couldn't insert (e.g., for capacity reasons).
 179   FAILURE_ALREADY_PRESENT  // A surface with the same key is already present.
 180 };
 181
 182 /**
 183  * SurfaceCache is an ImageLib-global service that allows caching of decoded
 184  * image surfaces, temporary surfaces (e.g. for caching rotated or clipped
 185  * versions of images), or dynamically generated surfaces (e.g. for animations).
 186  * SurfaceCache entries normally expire from the cache automatically if they go
 187  * too long without being accessed.
 188  *
 189  * Because SurfaceCache must support both normal surfaces and dynamically
 190  * generated surfaces, it does not actually hold surfaces directly. Instead, it
 191  * holds ISurfaceProvider objects which can provide access to a surface when
 192  * requested; SurfaceCache doesn't care about the details of how this is
 193  * accomplished.
 194  *
 195  * Sometime it's useful to temporarily prevent entries from expiring from the
 196  * cache. This is most often because losing the data could harm the user
 197  * experience (for example, we often don't want to allow surfaces that are
 198  * currently visible to expire) or because it's not possible to rematerialize
 199  * the surface. SurfaceCache supports this through the use of image locking; see
 200  * the comments for Insert() and LockImage() for more details.
 201  *
 202  * Any image which stores surfaces in the SurfaceCache *must* ensure that it
 203  * calls RemoveImage() before it is destroyed. See the comments for
 204  * RemoveImage() for more details.
 205  */
 206 struct SurfaceCache {
 207   typedef gfx::IntSize IntSize;
 208
 209   /**
 210    * Initialize static data. Called during imagelib module initialization.
 211    */
 212   static void Initialize();
 213
 214   /**
 215    * Release static data. Called during imagelib module shutdown.
 216    */
 217   static void Shutdown();
 218
 219   /**
 220    * Looks up the requested cache entry and returns a drawable reference to its
 221    * associated surface.
 222    *
 223    * If the image associated with the cache entry is locked, then the entry will
 224    * be locked before it is returned.
 225    *
 226    * If a matching ISurfaceProvider was found in the cache, but SurfaceCache
 227    * couldn't obtain a surface from it (e.g. because it had stored its surface
 228    * in a volatile buffer which was discarded by the OS) then it is
 229    * automatically removed from the cache and an empty LookupResult is returned.
 230    * Note that this will never happen to ISurfaceProviders associated with a
 231    * locked image; SurfaceCache tells such ISurfaceProviders to keep a strong
 232    * references to their data internally.
 233    *
 234    * @param aImageKey       Key data identifying which image the cache entry
 235    *                        belongs to.
 236    * @param aSurfaceKey     Key data which uniquely identifies the requested
 237    *                        cache entry.
 238    * @return                a LookupResult which will contain a DrawableSurface
 239    *                        if the cache entry was found.
 240    */
 241   static LookupResult Lookup(const ImageKey aImageKey,
 242                              const SurfaceKey& aSurfaceKey, bool aMarkUsed);
 243
 244   /**
 245    * Looks up the best matching cache entry and returns a drawable reference to
 246    * its associated surface.
 247    *
 248    * The result may vary from the requested cache entry only in terms of size.
 249    *
 250    * @param aImageKey       Key data identifying which image the cache entry
 251    *                        belongs to.
 252    * @param aSurfaceKey     Key data which uniquely identifies the requested
 253    *                        cache entry.
 254    * @return                a LookupResult which will contain a DrawableSurface
 255    *                        if a cache entry similar to the one the caller
 256    *                        requested could be found. Callers can use
 257    *                        LookupResult::IsExactMatch() to check whether the
 258    *                        returned surface exactly matches @aSurfaceKey.
 259    */
 260   static LookupResult LookupBestMatch(const ImageKey aImageKey,
 261                                       const SurfaceKey& aSurfaceKey,
 262                                       bool aMarkUsed);
 263
 264   /**
 265    * Insert an ISurfaceProvider into the cache. If an entry with the same
 266    * ImageKey and SurfaceKey is already in the cache, Insert returns
 267    * FAILURE_ALREADY_PRESENT. If a matching placeholder is already present, it
 268    * is replaced.
 269    *
 270    * Cache entries will never expire as long as they remain locked, but if they
 271    * become unlocked, they can expire either because the SurfaceCache runs out
 272    * of capacity or because they've gone too long without being used.  When it
 273    * is first inserted, a cache entry is locked if its associated image is
 274    * locked.  When that image is later unlocked, the cache entry becomes
 275    * unlocked too. To become locked again at that point, two things must happen:
 276    * the image must become locked again (via LockImage()), and the cache entry
 277    * must be touched again (via one of the Lookup() functions).
 278    *
 279    * All of this means that a very particular procedure has to be followed for
 280    * cache entries which cannot be rematerialized. First, they must be inserted
 281    * *after* the image is locked with LockImage(); if you use the other order,
 282    * the cache entry might expire before LockImage() gets called or before the
 283    * entry is touched again by Lookup(). Second, the image they are associated
 284    * with must never be unlocked.
 285    *
 286    * If a cache entry cannot be rematerialized, it may be important to know
 287    * whether it was inserted into the cache successfully. Insert() returns
 288    * FAILURE if it failed to insert the cache entry, which could happen because
 289    * of capacity reasons, or because it was already freed by the OS. If the
 290    * cache entry isn't associated with a locked image, checking for SUCCESS or
 291    * FAILURE is useless: the entry might expire immediately after being
 292    * inserted, even though Insert() returned SUCCESS. Thus, many callers do not
 293    * need to check the result of Insert() at all.
 294    *
 295    * @param aProvider    The new cache entry to insert into the cache.
 296    * @return SUCCESS if the cache entry was inserted successfully. (But see
 297    *           above for more information about when you should check this.)
 298    *         FAILURE if the cache entry could not be inserted, e.g. for capacity
 299    *           reasons. (But see above for more information about when you
 300    *           should check this.)
 301    *         FAILURE_ALREADY_PRESENT if an entry with the same ImageKey and
 302    *           SurfaceKey already exists in the cache.
 303    */
 304   static InsertOutcome Insert(NotNull<ISurfaceProvider*> aProvider);
 305
 306   /**
 307    * Mark the cache entry @aProvider as having an available surface. This turns
 308    * a placeholder cache entry into a normal cache entry. The cache entry
 309    * becomes locked if the associated image is locked; otherwise, it starts in
 310    * the unlocked state.
 311    *
 312    * If the cache entry containing @aProvider has already been evicted from the
 313    * surface cache, this function has no effect.
 314    *
 315    * It's illegal to call this function if @aProvider is not a placeholder; by
 316    * definition, non-placeholder ISurfaceProviders should have a surface
 317    * available already.
 318    *
 319    * @param aProvider       The cache entry that now has a surface available.
 320    */
 321   static void SurfaceAvailable(NotNull<ISurfaceProvider*> aProvider);
 322
 323   /**
 324    * Checks if a surface of a given size could possibly be stored in the cache.
 325    * If CanHold() returns false, Insert() will always fail to insert the
 326    * surface, but the inverse is not true: Insert() may take more information
 327    * into account than just image size when deciding whether to cache the
 328    * surface, so Insert() may still fail even if CanHold() returns true.
 329    *
 330    * Use CanHold() to avoid the need to create a temporary surface when we know
 331    * for sure the cache can't hold it.
 332    *
 333    * @param aSize  The dimensions of a surface in pixels.
 334    * @param aBytesPerPixel  How many bytes each pixel of the surface requires.
 335    *                        Defaults to 4, which is appropriate for RGBA or RGBX
 336    *                        images.
 337    *
 338    * @return false if the surface cache can't hold a surface of that size.
 339    */
 340   static bool CanHold(const IntSize& aSize, uint32_t aBytesPerPixel = 4);
 341   static bool CanHold(size_t aSize);
 342
 343   /**
 344    * Locks an image. Any of the image's cache entries which are either inserted
 345    * or accessed while the image is locked will not expire.
 346    *
 347    * Locking an image does not automatically lock that image's existing cache
 348    * entries. A call to LockImage() guarantees that entries which are inserted
 349    * afterward will not expire before the next call to UnlockImage() or
 350    * UnlockSurfaces() for that image. Cache entries that are accessed via
 351    * Lookup() or LookupBestMatch() after a LockImage() call will also not expire
 352    * until the next UnlockImage() or UnlockSurfaces() call for that image. Any
 353    * other cache entries owned by the image may expire at any time.
 354    *
 355    * All of an image's cache entries are removed by RemoveImage(), whether the
 356    * image is locked or not.
 357    *
 358    * It's safe to call LockImage() on an image that's already locked; this has
 359    * no effect.
 360    *
 361    * You must always unlock any image you lock. You may do this explicitly by
 362    * calling UnlockImage(), or implicitly by calling RemoveImage(). Since you're
 363    * required to call RemoveImage() when you destroy an image, this doesn't
 364    * impose any additional requirements, but it's preferable to call
 365    * UnlockImage() earlier if it's possible.
 366    *
 367    * @param aImageKey    The image to lock.
 368    */
 369   static void LockImage(const ImageKey aImageKey);
 370
 371   /**
 372    * Unlocks an image, allowing any of its cache entries to expire at any time.
 373    *
 374    * It's OK to call UnlockImage() on an image that's already unlocked; this has
 375    * no effect.
 376    *
 377    * @param aImageKey    The image to unlock.
 378    */
 379   static void UnlockImage(const ImageKey aImageKey);
 380
 381   /**
 382    * Unlocks the existing cache entries of an image, allowing them to expire at
 383    * any time.
 384    *
 385    * This does not unlock the image itself, so accessing the cache entries via
 386    * Lookup() or LookupBestMatch() will lock them again, and prevent them from
 387    * expiring.
 388    *
 389    * This is intended to be used in situations where it's no longer clear that
 390    * all of the cache entries owned by an image are needed. Calling
 391    * UnlockSurfaces() and then taking some action that will cause Lookup() to
 392    * touch any cache entries that are still useful will permit the remaining
 393    * entries to expire from the cache.
 394    *
 395    * If the image is unlocked, this has no effect.
 396    *
 397    * @param aImageKey    The image which should have its existing cache entries
 398    *                     unlocked.
 399    */
 400   static void UnlockEntries(const ImageKey aImageKey);
 401
 402   /**
 403    * Removes all cache entries (including placeholders) associated with the
 404    * given image from the cache.  If the image is locked, it is automatically
 405    * unlocked.
 406    *
 407    * This MUST be called, at a minimum, when an Image which could be storing
 408    * entries in the surface cache is destroyed. If another image were allocated
 409    * at the same address it could result in subtle, difficult-to-reproduce bugs.
 410    *
 411    * @param aImageKey  The image which should be removed from the cache.
 412    */
 413   static void RemoveImage(const ImageKey aImageKey);
 414
 415   /**
 416    * Attempts to remove cache entries (including placeholders) associated with
 417    * the given image from the cache, assuming there is an equivalent entry that
 418    * it is able substitute that entry with. Note that this only applies if the
 419    * image is in factor of 2 mode. If it is not, this operation does nothing.
 420    *
 421    * @param aImageKey  The image whose cache which should be pruned.
 422    */
 423   static void PruneImage(const ImageKey aImageKey);
 424
 425   /**
 426    * Removes all rasterized cache entries (including placeholders) associated
 427    * with the given image from the cache. Any blob recordings are marked as
 428    * dirty and must be regenerated.
 429    *
 430    * @param aImageKey  The image whose cache which should be regenerated.
 431    *
 432    * @returns true if any recordings were invalidated, else false.
 433    */
 434   static bool InvalidateImage(const ImageKey aImageKey);
 435
 436   /**
 437    * Evicts all evictable entries from the cache.
 438    *
 439    * All entries are evictable except for entries associated with locked images.
 440    * Non-evictable entries can only be removed by RemoveImage().
 441    */
 442   static void DiscardAll();
 443
 444   /**
 445    * Calls Reset on the ISurfaceProvider (which is currently only implemented
 446    * for AnimationSurfaceProvider). This is needed because we need to call Reset
 447    * on AnimationSurfaceProvider while they are in placeholder status and there
 448    * is no way to access a surface cache entry from outside of the surface cache
 449    * when it's in placeholder status.
 450    */
 451   static void ResetAnimation(const ImageKey aImageKey,
 452                              const SurfaceKey& aSurfaceKey);
 453
 454   /**
 455    * Collects an accounting of the surfaces contained in the SurfaceCache for
 456    * the given image, along with their size and various other metadata.
 457    *
 458    * This is intended for use with memory reporting.
 459    *
 460    * @param aImageKey     The image to report memory usage for.
 461    * @param aCounters     An array into which the report for each surface will
 462    *                      be written.
 463    * @param aMallocSizeOf A fallback malloc memory reporting function.
 464    */
 465   static void CollectSizeOfSurfaces(const ImageKey aImageKey,
 466                                     nsTArray<SurfaceMemoryCounter>& aCounters,
 467                                     MallocSizeOf aMallocSizeOf);
 468
 469   /**
 470    * @return maximum capacity of the SurfaceCache in bytes. This is only exposed
 471    * for use by tests; normal code should use CanHold() instead.
 472    */
 473   static size_t MaximumCapacity();
 474
 475   /**
 476    * @return true if the given size is valid.
 477    */
 478   static bool IsLegalSize(const IntSize& aSize);
 479
 480   /**
 481    * @return clamped size for the given vector image size to rasterize at.
 482    */
 483   static IntSize ClampVectorSize(const IntSize& aSize);
 484
 485   /**
 486    * @return clamped size for the given image and size to rasterize at.
 487    */
 488   static IntSize ClampSize(const ImageKey aImageKey, const IntSize& aSize);
 489
 490   /**
 491    * Release image on main thread.
 492    * The function uses SurfaceCache to release pending releasing images quickly.
 493    */
 494   static void ReleaseImageOnMainThread(already_AddRefed<image::Image> aImage,
 495                                        bool aAlwaysProxy = false);
 496
 497   /**
 498    * Clear all pending releasing images.
 499    */
 500   static void ClearReleasingImages();
 501
 502  private:
 503   virtual ~SurfaceCache() = 0;  // Forbid instantiation.
 504 };
 505
 506 }  // namespace image
 507 }  // namespace mozilla
 508
 509 #endif  // mozilla_image_SurfaceCache_h