tor-browser

SurfaceCache.h (21359B)

---

/* -*- 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/. */

/**
* SurfaceCache is a service for caching temporary surfaces and decoded image
* data in imagelib.
*/

#ifndef mozilla_image_SurfaceCache_h
#define mozilla_image_SurfaceCache_h

#include "mozilla/HashFunctions.h"    // for HashGeneric and AddToHash
#include "mozilla/Maybe.h"            // for Maybe
#include "mozilla/MemoryReporting.h"  // for MallocSizeOf
#include "mozilla/NotNull.h"
#include "mozilla/SVGImageContext.h"  // for SVGImageContext
#include "mozilla/gfx/2D.h"           // for SourceSurface
#include "mozilla/gfx/Point.h"        // for mozilla::gfx::IntSize
#include "gfx2DGlue.h"
#include "gfxPoint.h"  // for gfxSize
#include "nsCOMPtr.h"  // for already_AddRefed
#include "ImageRegion.h"
#include "PlaybackType.h"
#include "SurfaceFlags.h"

namespace mozilla {
namespace image {

class ImageResource;
class ISurfaceProvider;
class LookupResult;
class SurfaceCacheImpl;
struct SurfaceMemoryCounter;

/*
* ImageKey contains the information we need to look up all SurfaceCache entries
* for a particular image.
*/
using ImageKey = ImageResource*;

/*
* SurfaceKey contains the information we need to look up a specific
* SurfaceCache entry. Together with an ImageKey, this uniquely identifies the
* surface.
*
* Callers should construct a SurfaceKey using the appropriate helper function
* for their image type - either RasterSurfaceKey or VectorSurfaceKey.
*/
class SurfaceKey {
 typedef gfx::IntSize IntSize;

public:
 bool operator==(const SurfaceKey& aOther) const {
   return aOther.mSize == mSize && aOther.mRegion == mRegion &&
          aOther.mSVGContext == mSVGContext && aOther.mPlayback == mPlayback &&
          aOther.mFlags == mFlags;
 }

 PLDHashNumber Hash() const {
   PLDHashNumber hash = HashGeneric(mSize.width, mSize.height);
   hash = AddToHash(hash, mRegion.map(HashIIR).valueOr(0));
   hash = AddToHash(hash, HashSIC(mSVGContext));
   hash = AddToHash(hash, uint8_t(mPlayback), uint32_t(mFlags));
   return hash;
 }

 SurfaceKey CloneWithSize(const IntSize& aSize) const {
   return SurfaceKey(aSize, mRegion, mSVGContext, mPlayback, mFlags);
 }

 const IntSize& Size() const { return mSize; }
 const Maybe<ImageIntRegion>& Region() const { return mRegion; }
 const SVGImageContext& SVGContext() const { return mSVGContext; }
 PlaybackType Playback() const { return mPlayback; }
 SurfaceFlags Flags() const { return mFlags; }

private:
 SurfaceKey(const IntSize& aSize, const Maybe<ImageIntRegion>& aRegion,
            const SVGImageContext& aSVGContext, PlaybackType aPlayback,
            SurfaceFlags aFlags)
     : mSize(aSize),
       mRegion(aRegion),
       mSVGContext(aSVGContext),
       mPlayback(aPlayback),
       mFlags(aFlags) {}

 static PLDHashNumber HashIIR(const ImageIntRegion& aIIR) {
   return aIIR.Hash();
 }

 static PLDHashNumber HashSIC(const SVGImageContext& aSIC) {
   return aSIC.Hash();
 }

 friend SurfaceKey RasterSurfaceKey(const IntSize&, SurfaceFlags,
                                    PlaybackType);
 friend SurfaceKey VectorSurfaceKey(const IntSize&, const SVGImageContext&);
 friend SurfaceKey VectorSurfaceKey(const IntSize&,
                                    const Maybe<ImageIntRegion>&,
                                    const SVGImageContext&, SurfaceFlags,
                                    PlaybackType);

 IntSize mSize;
 Maybe<ImageIntRegion> mRegion;
 SVGImageContext mSVGContext;
 PlaybackType mPlayback;
 SurfaceFlags mFlags;
};

inline SurfaceKey RasterSurfaceKey(const gfx::IntSize& aSize,
                                  SurfaceFlags aFlags,
                                  PlaybackType aPlayback) {
 return SurfaceKey(aSize, Nothing(), SVGImageContext(), aPlayback, aFlags);
}

inline SurfaceKey VectorSurfaceKey(const gfx::IntSize& aSize,
                                  const Maybe<ImageIntRegion>& aRegion,
                                  const SVGImageContext& aSVGContext,
                                  SurfaceFlags aFlags,
                                  PlaybackType aPlayback) {
 return SurfaceKey(aSize, aRegion, aSVGContext, aPlayback, aFlags);
}

inline SurfaceKey VectorSurfaceKey(const gfx::IntSize& aSize,
                                  const SVGImageContext& aSVGContext) {
 // We don't care about aFlags for VectorImage because none of the flags we
 // have right now influence VectorImage's rendering. If we add a new flag that
 // *does* affect how a VectorImage renders, we'll have to change this.
 // Similarly, we don't accept a PlaybackType parameter because we don't
 // currently cache frames of animated SVG images.
 return SurfaceKey(aSize, Nothing(), aSVGContext, PlaybackType::eStatic,
                   DefaultSurfaceFlags());
}

/**
* AvailabilityState is used to track whether an ISurfaceProvider has a surface
* available or is just a placeholder.
*
* To ensure that availability changes are atomic (and especially that internal
* SurfaceCache code doesn't have to deal with asynchronous availability
* changes), an ISurfaceProvider which starts as a placeholder can only reveal
* the fact that it now has a surface available via a call to
* SurfaceCache::SurfaceAvailable().
*
* It also tracks whether or not there are "explicit" users of this surface
* which will not accept substitutes. This is used by SurfaceCache when pruning
* unnecessary surfaces from the cache.
*/
class AvailabilityState {
public:
 static AvailabilityState StartAvailable() { return AvailabilityState(true); }
 static AvailabilityState StartAsPlaceholder() {
   return AvailabilityState(false);
 }

 bool IsAvailable() const { return mIsAvailable; }
 bool IsPlaceholder() const { return !mIsAvailable; }
 bool CannotSubstitute() const { return mCannotSubstitute; }

 void SetCannotSubstitute() { mCannotSubstitute = true; }

private:
 friend class SurfaceCacheImpl;

 explicit AvailabilityState(bool aIsAvailable)
     : mIsAvailable(aIsAvailable), mCannotSubstitute(false) {}

 void SetAvailable() { mIsAvailable = true; }

 bool mIsAvailable : 1;
 bool mCannotSubstitute : 1;
};

enum class InsertOutcome : uint8_t {
 SUCCESS,                 // Success (but see Insert documentation).
 FAILURE,                 // Couldn't insert (e.g., for capacity reasons).
 FAILURE_ALREADY_PRESENT  // A surface with the same key is already present.
};

/**
* SurfaceCache is an ImageLib-global service that allows caching of decoded
* image surfaces, temporary surfaces (e.g. for caching rotated or clipped
* versions of images), or dynamically generated surfaces (e.g. for animations).
* SurfaceCache entries normally expire from the cache automatically if they go
* too long without being accessed.
*
* Because SurfaceCache must support both normal surfaces and dynamically
* generated surfaces, it does not actually hold surfaces directly. Instead, it
* holds ISurfaceProvider objects which can provide access to a surface when
* requested; SurfaceCache doesn't care about the details of how this is
* accomplished.
*
* Sometime it's useful to temporarily prevent entries from expiring from the
* cache. This is most often because losing the data could harm the user
* experience (for example, we often don't want to allow surfaces that are
* currently visible to expire) or because it's not possible to rematerialize
* the surface. SurfaceCache supports this through the use of image locking; see
* the comments for Insert() and LockImage() for more details.
*
* Any image which stores surfaces in the SurfaceCache *must* ensure that it
* calls RemoveImage() before it is destroyed. See the comments for
* RemoveImage() for more details.
*/
struct SurfaceCache {
 typedef gfx::IntSize IntSize;

 /**
  * Initialize static data. Called during imagelib module initialization.
  */
 static void Initialize();

 /**
  * Release static data. Called during imagelib module shutdown.
  */
 static void Shutdown();

 /**
  * Looks up the requested cache entry and returns a drawable reference to its
  * associated surface.
  *
  * If the image associated with the cache entry is locked, then the entry will
  * be locked before it is returned.
  *
  * If a matching ISurfaceProvider was found in the cache, but SurfaceCache
  * couldn't obtain a surface from it (e.g. because it had stored its surface
  * in a volatile buffer which was discarded by the OS) then it is
  * automatically removed from the cache and an empty LookupResult is returned.
  * Note that this will never happen to ISurfaceProviders associated with a
  * locked image; SurfaceCache tells such ISurfaceProviders to keep a strong
  * references to their data internally.
  *
  * @param aImageKey       Key data identifying which image the cache entry
  *                        belongs to.
  * @param aSurfaceKey     Key data which uniquely identifies the requested
  *                        cache entry.
  * @return                a LookupResult which will contain a DrawableSurface
  *                        if the cache entry was found.
  */
 static LookupResult Lookup(const ImageKey aImageKey,
                            const SurfaceKey& aSurfaceKey, bool aMarkUsed);

 /**
  * Looks up the best matching cache entry and returns a drawable reference to
  * its associated surface.
  *
  * The result may vary from the requested cache entry only in terms of size.
  *
  * @param aImageKey       Key data identifying which image the cache entry
  *                        belongs to.
  * @param aSurfaceKey     Key data which uniquely identifies the requested
  *                        cache entry.
  * @return                a LookupResult which will contain a DrawableSurface
  *                        if a cache entry similar to the one the caller
  *                        requested could be found. Callers can use
  *                        LookupResult::IsExactMatch() to check whether the
  *                        returned surface exactly matches @aSurfaceKey.
  */
 static LookupResult LookupBestMatch(const ImageKey aImageKey,
                                     const SurfaceKey& aSurfaceKey,
                                     bool aMarkUsed);

 /**
  * Insert an ISurfaceProvider into the cache. If an entry with the same
  * ImageKey and SurfaceKey is already in the cache, Insert returns
  * FAILURE_ALREADY_PRESENT. If a matching placeholder is already present, it
  * is replaced.
  *
  * Cache entries will never expire as long as they remain locked, but if they
  * become unlocked, they can expire either because the SurfaceCache runs out
  * of capacity or because they've gone too long without being used.  When it
  * is first inserted, a cache entry is locked if its associated image is
  * locked.  When that image is later unlocked, the cache entry becomes
  * unlocked too. To become locked again at that point, two things must happen:
  * the image must become locked again (via LockImage()), and the cache entry
  * must be touched again (via one of the Lookup() functions).
  *
  * All of this means that a very particular procedure has to be followed for
  * cache entries which cannot be rematerialized. First, they must be inserted
  * *after* the image is locked with LockImage(); if you use the other order,
  * the cache entry might expire before LockImage() gets called or before the
  * entry is touched again by Lookup(). Second, the image they are associated
  * with must never be unlocked.
  *
  * If a cache entry cannot be rematerialized, it may be important to know
  * whether it was inserted into the cache successfully. Insert() returns
  * FAILURE if it failed to insert the cache entry, which could happen because
  * of capacity reasons, or because it was already freed by the OS. If the
  * cache entry isn't associated with a locked image, checking for SUCCESS or
  * FAILURE is useless: the entry might expire immediately after being
  * inserted, even though Insert() returned SUCCESS. Thus, many callers do not
  * need to check the result of Insert() at all.
  *
  * @param aProvider    The new cache entry to insert into the cache.
  * @return SUCCESS if the cache entry was inserted successfully. (But see
  *           above for more information about when you should check this.)
  *         FAILURE if the cache entry could not be inserted, e.g. for capacity
  *           reasons. (But see above for more information about when you
  *           should check this.)
  *         FAILURE_ALREADY_PRESENT if an entry with the same ImageKey and
  *           SurfaceKey already exists in the cache.
  */
 static InsertOutcome Insert(NotNull<ISurfaceProvider*> aProvider);

 /**
  * Mark the cache entry @aProvider as having an available surface. This turns
  * a placeholder cache entry into a normal cache entry. The cache entry
  * becomes locked if the associated image is locked; otherwise, it starts in
  * the unlocked state.
  *
  * If the cache entry containing @aProvider has already been evicted from the
  * surface cache, this function has no effect.
  *
  * It's illegal to call this function if @aProvider is not a placeholder; by
  * definition, non-placeholder ISurfaceProviders should have a surface
  * available already.
  *
  * @param aProvider       The cache entry that now has a surface available.
  */
 static void SurfaceAvailable(NotNull<ISurfaceProvider*> aProvider);

 /**
  * Checks if a surface of a given size could possibly be stored in the cache.
  * If CanHold() returns false, Insert() will always fail to insert the
  * surface, but the inverse is not true: Insert() may take more information
  * into account than just image size when deciding whether to cache the
  * surface, so Insert() may still fail even if CanHold() returns true.
  *
  * Use CanHold() to avoid the need to create a temporary surface when we know
  * for sure the cache can't hold it.
  *
  * @param aSize  The dimensions of a surface in pixels.
  * @param aBytesPerPixel  How many bytes each pixel of the surface requires.
  *                        Defaults to 4, which is appropriate for RGBA or RGBX
  *                        images.
  *
  * @return false if the surface cache can't hold a surface of that size.
  */
 static bool CanHold(const IntSize& aSize, uint32_t aBytesPerPixel = 4);
 static bool CanHold(size_t aSize);

 /**
  * Locks an image. Any of the image's cache entries which are either inserted
  * or accessed while the image is locked will not expire.
  *
  * Locking an image does not automatically lock that image's existing cache
  * entries. A call to LockImage() guarantees that entries which are inserted
  * afterward will not expire before the next call to UnlockImage() or
  * UnlockSurfaces() for that image. Cache entries that are accessed via
  * Lookup() or LookupBestMatch() after a LockImage() call will also not expire
  * until the next UnlockImage() or UnlockSurfaces() call for that image. Any
  * other cache entries owned by the image may expire at any time.
  *
  * All of an image's cache entries are removed by RemoveImage(), whether the
  * image is locked or not.
  *
  * It's safe to call LockImage() on an image that's already locked; this has
  * no effect.
  *
  * You must always unlock any image you lock. You may do this explicitly by
  * calling UnlockImage(), or implicitly by calling RemoveImage(). Since you're
  * required to call RemoveImage() when you destroy an image, this doesn't
  * impose any additional requirements, but it's preferable to call
  * UnlockImage() earlier if it's possible.
  *
  * @param aImageKey    The image to lock.
  */
 static void LockImage(const ImageKey aImageKey);

 /**
  * Unlocks an image, allowing any of its cache entries to expire at any time.
  *
  * It's OK to call UnlockImage() on an image that's already unlocked; this has
  * no effect.
  *
  * @param aImageKey    The image to unlock.
  */
 static void UnlockImage(const ImageKey aImageKey);

 /**
  * Unlocks the existing cache entries of an image, allowing them to expire at
  * any time.
  *
  * This does not unlock the image itself, so accessing the cache entries via
  * Lookup() or LookupBestMatch() will lock them again, and prevent them from
  * expiring.
  *
  * This is intended to be used in situations where it's no longer clear that
  * all of the cache entries owned by an image are needed. Calling
  * UnlockSurfaces() and then taking some action that will cause Lookup() to
  * touch any cache entries that are still useful will permit the remaining
  * entries to expire from the cache.
  *
  * If the image is unlocked, this has no effect.
  *
  * @param aImageKey    The image which should have its existing cache entries
  *                     unlocked.
  */
 static void UnlockEntries(const ImageKey aImageKey);

 /**
  * Removes all cache entries (including placeholders) associated with the
  * given image from the cache.  If the image is locked, it is automatically
  * unlocked.
  *
  * This MUST be called, at a minimum, when an Image which could be storing
  * entries in the surface cache is destroyed. If another image were allocated
  * at the same address it could result in subtle, difficult-to-reproduce bugs.
  *
  * @param aImageKey  The image which should be removed from the cache.
  */
 static void RemoveImage(const ImageKey aImageKey);

 /**
  * Attempts to remove cache entries (including placeholders) associated with
  * the given image from the cache, assuming there is an equivalent entry that
  * it is able substitute that entry with. Note that this only applies if the
  * image is in factor of 2 mode. If it is not, this operation does nothing.
  *
  * @param aImageKey  The image whose cache which should be pruned.
  */
 static void PruneImage(const ImageKey aImageKey);

 /**
  * Removes all rasterized cache entries (including placeholders) associated
  * with the given image from the cache and marks their surface providers as
  * dirty and should not be drawn again. Any blob recordings are left in th
  * cache but marked as dirty and must be regenerated.
  *
  * @param aImageKey  The image whose cache which should be regenerated.
  *
  * @returns true if any surface providers were present in the cache, else
  * false.
  */
 static bool InvalidateImage(const ImageKey aImageKey);

 /**
  * Evicts all evictable entries from the cache.
  *
  * All entries are evictable except for entries associated with locked images.
  * Non-evictable entries can only be removed by RemoveImage().
  */
 static void DiscardAll();

 /**
  * Calls Reset on the ISurfaceProvider (which is currently only implemented
  * for AnimationSurfaceProvider). This is needed because we need to call Reset
  * on AnimationSurfaceProvider while they are in placeholder status and there
  * is no way to access a surface cache entry from outside of the surface cache
  * when it's in placeholder status.
  */
 static void ResetAnimation(const ImageKey aImageKey,
                            const SurfaceKey& aSurfaceKey);

 /**
  * Collects an accounting of the surfaces contained in the SurfaceCache for
  * the given image, along with their size and various other metadata.
  *
  * This is intended for use with memory reporting.
  *
  * @param aImageKey     The image to report memory usage for.
  * @param aCounters     An array into which the report for each surface will
  *                      be written.
  * @param aMallocSizeOf A fallback malloc memory reporting function.
  */
 static void CollectSizeOfSurfaces(const ImageKey aImageKey,
                                   nsTArray<SurfaceMemoryCounter>& aCounters,
                                   MallocSizeOf aMallocSizeOf);

 /**
  * @return maximum capacity of the SurfaceCache in bytes. This is only exposed
  * for use by tests; normal code should use CanHold() instead.
  */
 static size_t MaximumCapacity();

 /**
  * @return true if the given size is valid.
  */
 static bool IsLegalSize(const IntSize& aSize);

 /**
  * @return clamped size for the given vector image size to rasterize at.
  */
 static IntSize ClampVectorSize(const IntSize& aSize);

 /**
  * @return clamped size for the given image and size to rasterize at.
  */
 static IntSize ClampSize(const ImageKey aImageKey, const IntSize& aSize);

 /**
  * Release image on main thread.
  * The function uses SurfaceCache to release pending releasing images quickly.
  */
 static void ReleaseImageOnMainThread(already_AddRefed<image::Image> aImage,
                                      bool aAlwaysProxy = false);

 /**
  * Clear all pending releasing images.
  */
 static void ClearReleasingImages();

private:
 virtual ~SurfaceCache() = 0;  // Forbid instantiation.
};

}  // namespace image
}  // namespace mozilla

#endif  // mozilla_image_SurfaceCache_h