diff options
Diffstat (limited to 'image/SurfaceCache.h')
| -rw-r--r-- | image/SurfaceCache.h | 427 |
1 files changed, 427 insertions, 0 deletions
diff --git a/image/SurfaceCache.h b/image/SurfaceCache.h new file mode 100644 index 000000000..e0c22c999 --- /dev/null +++ b/image/SurfaceCache.h @@ -0,0 +1,427 @@ +/* -*- 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/Maybe.h" // for Maybe +#include "mozilla/NotNull.h" +#include "mozilla/MemoryReporting.h" // for MallocSizeOf +#include "mozilla/HashFunctions.h" // for HashGeneric and AddToHash +#include "gfx2DGlue.h" +#include "gfxPoint.h" // for gfxSize +#include "nsCOMPtr.h" // for already_AddRefed +#include "mozilla/gfx/Point.h" // for mozilla::gfx::IntSize +#include "mozilla/gfx/2D.h" // for SourceSurface +#include "PlaybackType.h" +#include "SurfaceFlags.h" +#include "SVGImageContext.h" // for SVGImageContext + +namespace mozilla { +namespace image { + +class Image; +class ISurfaceProvider; +class LookupResult; +class SurfaceCacheImpl; +struct SurfaceMemoryCounter; + +/* + * ImageKey contains the information we need to look up all SurfaceCache entries + * for a particular image. + */ +typedef Image* ImageKey; + +/* + * 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.mSVGContext == mSVGContext && + aOther.mPlayback == mPlayback && + aOther.mFlags == mFlags; + } + + uint32_t Hash() const + { + uint32_t hash = HashGeneric(mSize.width, mSize.height); + hash = AddToHash(hash, mSVGContext.map(HashSIC).valueOr(0)); + hash = AddToHash(hash, uint8_t(mPlayback), uint32_t(mFlags)); + return hash; + } + + const IntSize& Size() const { return mSize; } + Maybe<SVGImageContext> SVGContext() const { return mSVGContext; } + PlaybackType Playback() const { return mPlayback; } + SurfaceFlags Flags() const { return mFlags; } + +private: + SurfaceKey(const IntSize& aSize, + const Maybe<SVGImageContext>& aSVGContext, + PlaybackType aPlayback, + SurfaceFlags aFlags) + : mSize(aSize) + , mSVGContext(aSVGContext) + , mPlayback(aPlayback) + , mFlags(aFlags) + { } + + static uint32_t HashSIC(const SVGImageContext& aSIC) { + return aSIC.Hash(); + } + + friend SurfaceKey RasterSurfaceKey(const IntSize&, SurfaceFlags, PlaybackType); + friend SurfaceKey VectorSurfaceKey(const IntSize&, + const Maybe<SVGImageContext>&); + + IntSize mSize; + Maybe<SVGImageContext> mSVGContext; + PlaybackType mPlayback; + SurfaceFlags mFlags; +}; + +inline SurfaceKey +RasterSurfaceKey(const gfx::IntSize& aSize, + SurfaceFlags aFlags, + PlaybackType aPlayback) +{ + return SurfaceKey(aSize, Nothing(), aPlayback, aFlags); +} + +inline SurfaceKey +VectorSurfaceKey(const gfx::IntSize& aSize, + const Maybe<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, 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(). + */ +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; } + +private: + friend class SurfaceCacheImpl; + + explicit AvailabilityState(bool aIsAvailable) : mIsAvailable(aIsAvailable) { } + + void SetAvailable() { mIsAvailable = true; } + + bool mIsAvailable; +}; + +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); + + /** + * 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); + + /** + * 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); + + /** + * 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(); + + /** + * 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(); + +private: + virtual ~SurfaceCache() = 0; // Forbid instantiation. +}; + +} // namespace image +} // namespace mozilla + +#endif // mozilla_image_SurfaceCache_h |