summaryrefslogtreecommitdiffstats
path: root/image/SurfaceCache.h
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-19 00:47:55 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-19 00:47:55 +0000
commit26a029d407be480d791972afb5975cf62c9360a6 (patch)
treef435a8308119effd964b339f76abb83a57c29483 /image/SurfaceCache.h
parentInitial commit. (diff)
downloadfirefox-26a029d407be480d791972afb5975cf62c9360a6.tar.xz
firefox-26a029d407be480d791972afb5975cf62c9360a6.zip
Adding upstream version 124.0.1.upstream/124.0.1
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'image/SurfaceCache.h')
-rw-r--r--image/SurfaceCache.h509
1 files changed, 509 insertions, 0 deletions
diff --git a/image/SurfaceCache.h b/image/SurfaceCache.h
new file mode 100644
index 0000000000..864a6ffbc4
--- /dev/null
+++ b/image/SurfaceCache.h
@@ -0,0 +1,509 @@
+/* -*- 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. Any blob recordings are marked as
+ * dirty and must be regenerated.
+ *
+ * @param aImageKey The image whose cache which should be regenerated.
+ *
+ * @returns true if any recordings were invalidated, 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