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/. */
7 * SurfaceCache is a service for caching temporary surfaces and decoded image
11 #ifndef mozilla_image_SurfaceCache_h
12 #define mozilla_image_SurfaceCache_h
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"
32 class ISurfaceProvider
;
34 class SurfaceCacheImpl
;
35 struct SurfaceMemoryCounter
;
38 * ImageKey contains the information we need to look up all SurfaceCache entries
39 * for a particular image.
41 using ImageKey
= ImageResource
*;
44 * SurfaceKey contains the information we need to look up a specific
45 * SurfaceCache entry. Together with an ImageKey, this uniquely identifies the
48 * Callers should construct a SurfaceKey using the appropriate helper function
49 * for their image type - either RasterSurfaceKey or VectorSurfaceKey.
52 typedef gfx::IntSize IntSize
;
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
;
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
, mSVGContext
.map(HashSIC
).valueOr(0));
65 hash
= AddToHash(hash
, uint8_t(mPlayback
), uint32_t(mFlags
));
69 SurfaceKey
CloneWithSize(const IntSize
& aSize
) const {
70 return SurfaceKey(aSize
, mRegion
, mSVGContext
, mPlayback
, mFlags
);
73 const IntSize
& Size() const { return mSize
; }
74 const Maybe
<ImageIntRegion
>& Region() const { return mRegion
; }
75 const Maybe
<SVGImageContext
>& SVGContext() const { return mSVGContext
; }
76 PlaybackType
Playback() const { return mPlayback
; }
77 SurfaceFlags
Flags() const { return mFlags
; }
80 SurfaceKey(const IntSize
& aSize
, const Maybe
<ImageIntRegion
>& aRegion
,
81 const Maybe
<SVGImageContext
>& aSVGContext
, PlaybackType aPlayback
,
85 mSVGContext(aSVGContext
),
89 static PLDHashNumber
HashIIR(const ImageIntRegion
& aIIR
) {
93 static PLDHashNumber
HashSIC(const SVGImageContext
& aSIC
) {
97 friend SurfaceKey
RasterSurfaceKey(const IntSize
&, SurfaceFlags
,
99 friend SurfaceKey
VectorSurfaceKey(const IntSize
&,
100 const Maybe
<SVGImageContext
>&);
101 friend SurfaceKey
VectorSurfaceKey(const IntSize
&,
102 const Maybe
<ImageIntRegion
>&,
103 const Maybe
<SVGImageContext
>&,
104 SurfaceFlags
, PlaybackType
);
107 Maybe
<ImageIntRegion
> mRegion
;
108 Maybe
<SVGImageContext
> mSVGContext
;
109 PlaybackType mPlayback
;
113 inline SurfaceKey
RasterSurfaceKey(const gfx::IntSize
& aSize
,
115 PlaybackType aPlayback
) {
116 return SurfaceKey(aSize
, Nothing(), Nothing(), aPlayback
, aFlags
);
119 inline SurfaceKey
VectorSurfaceKey(const gfx::IntSize
& aSize
,
120 const Maybe
<ImageIntRegion
>& aRegion
,
121 const Maybe
<SVGImageContext
>& aSVGContext
,
123 PlaybackType aPlayback
) {
124 return SurfaceKey(aSize
, aRegion
, aSVGContext
, aPlayback
, aFlags
);
127 inline SurfaceKey
VectorSurfaceKey(const gfx::IntSize
& aSize
,
128 const Maybe
<SVGImageContext
>& aSVGContext
) {
129 // We don't care about aFlags for VectorImage because none of the flags we
130 // have right now influence VectorImage's rendering. If we add a new flag that
131 // *does* affect how a VectorImage renders, we'll have to change this.
132 // Similarly, we don't accept a PlaybackType parameter because we don't
133 // currently cache frames of animated SVG images.
134 return SurfaceKey(aSize
, Nothing(), aSVGContext
, PlaybackType::eStatic
,
135 DefaultSurfaceFlags());
139 * AvailabilityState is used to track whether an ISurfaceProvider has a surface
140 * available or is just a placeholder.
142 * To ensure that availability changes are atomic (and especially that internal
143 * SurfaceCache code doesn't have to deal with asynchronous availability
144 * changes), an ISurfaceProvider which starts as a placeholder can only reveal
145 * the fact that it now has a surface available via a call to
146 * SurfaceCache::SurfaceAvailable().
148 * It also tracks whether or not there are "explicit" users of this surface
149 * which will not accept substitutes. This is used by SurfaceCache when pruning
150 * unnecessary surfaces from the cache.
152 class AvailabilityState
{
154 static AvailabilityState
StartAvailable() { return AvailabilityState(true); }
155 static AvailabilityState
StartAsPlaceholder() {
156 return AvailabilityState(false);
159 bool IsAvailable() const { return mIsAvailable
; }
160 bool IsPlaceholder() const { return !mIsAvailable
; }
161 bool CannotSubstitute() const { return mCannotSubstitute
; }
163 void SetCannotSubstitute() { mCannotSubstitute
= true; }
166 friend class SurfaceCacheImpl
;
168 explicit AvailabilityState(bool aIsAvailable
)
169 : mIsAvailable(aIsAvailable
), mCannotSubstitute(false) {}
171 void SetAvailable() { mIsAvailable
= true; }
173 bool mIsAvailable
: 1;
174 bool mCannotSubstitute
: 1;
177 enum class InsertOutcome
: uint8_t {
178 SUCCESS
, // Success (but see Insert documentation).
179 FAILURE
, // Couldn't insert (e.g., for capacity reasons).
180 FAILURE_ALREADY_PRESENT
// A surface with the same key is already present.
184 * SurfaceCache is an ImageLib-global service that allows caching of decoded
185 * image surfaces, temporary surfaces (e.g. for caching rotated or clipped
186 * versions of images), or dynamically generated surfaces (e.g. for animations).
187 * SurfaceCache entries normally expire from the cache automatically if they go
188 * too long without being accessed.
190 * Because SurfaceCache must support both normal surfaces and dynamically
191 * generated surfaces, it does not actually hold surfaces directly. Instead, it
192 * holds ISurfaceProvider objects which can provide access to a surface when
193 * requested; SurfaceCache doesn't care about the details of how this is
196 * Sometime it's useful to temporarily prevent entries from expiring from the
197 * cache. This is most often because losing the data could harm the user
198 * experience (for example, we often don't want to allow surfaces that are
199 * currently visible to expire) or because it's not possible to rematerialize
200 * the surface. SurfaceCache supports this through the use of image locking; see
201 * the comments for Insert() and LockImage() for more details.
203 * Any image which stores surfaces in the SurfaceCache *must* ensure that it
204 * calls RemoveImage() before it is destroyed. See the comments for
205 * RemoveImage() for more details.
207 struct SurfaceCache
{
208 typedef gfx::IntSize IntSize
;
211 * Initialize static data. Called during imagelib module initialization.
213 static void Initialize();
216 * Release static data. Called during imagelib module shutdown.
218 static void Shutdown();
221 * Looks up the requested cache entry and returns a drawable reference to its
222 * associated surface.
224 * If the image associated with the cache entry is locked, then the entry will
225 * be locked before it is returned.
227 * If a matching ISurfaceProvider was found in the cache, but SurfaceCache
228 * couldn't obtain a surface from it (e.g. because it had stored its surface
229 * in a volatile buffer which was discarded by the OS) then it is
230 * automatically removed from the cache and an empty LookupResult is returned.
231 * Note that this will never happen to ISurfaceProviders associated with a
232 * locked image; SurfaceCache tells such ISurfaceProviders to keep a strong
233 * references to their data internally.
235 * @param aImageKey Key data identifying which image the cache entry
237 * @param aSurfaceKey Key data which uniquely identifies the requested
239 * @return a LookupResult which will contain a DrawableSurface
240 * if the cache entry was found.
242 static LookupResult
Lookup(const ImageKey aImageKey
,
243 const SurfaceKey
& aSurfaceKey
, bool aMarkUsed
);
246 * Looks up the best matching cache entry and returns a drawable reference to
247 * its associated surface.
249 * The result may vary from the requested cache entry only in terms of size.
251 * @param aImageKey Key data identifying which image the cache entry
253 * @param aSurfaceKey Key data which uniquely identifies the requested
255 * @return a LookupResult which will contain a DrawableSurface
256 * if a cache entry similar to the one the caller
257 * requested could be found. Callers can use
258 * LookupResult::IsExactMatch() to check whether the
259 * returned surface exactly matches @aSurfaceKey.
261 static LookupResult
LookupBestMatch(const ImageKey aImageKey
,
262 const SurfaceKey
& aSurfaceKey
,
266 * Insert an ISurfaceProvider into the cache. If an entry with the same
267 * ImageKey and SurfaceKey is already in the cache, Insert returns
268 * FAILURE_ALREADY_PRESENT. If a matching placeholder is already present, it
271 * Cache entries will never expire as long as they remain locked, but if they
272 * become unlocked, they can expire either because the SurfaceCache runs out
273 * of capacity or because they've gone too long without being used. When it
274 * is first inserted, a cache entry is locked if its associated image is
275 * locked. When that image is later unlocked, the cache entry becomes
276 * unlocked too. To become locked again at that point, two things must happen:
277 * the image must become locked again (via LockImage()), and the cache entry
278 * must be touched again (via one of the Lookup() functions).
280 * All of this means that a very particular procedure has to be followed for
281 * cache entries which cannot be rematerialized. First, they must be inserted
282 * *after* the image is locked with LockImage(); if you use the other order,
283 * the cache entry might expire before LockImage() gets called or before the
284 * entry is touched again by Lookup(). Second, the image they are associated
285 * with must never be unlocked.
287 * If a cache entry cannot be rematerialized, it may be important to know
288 * whether it was inserted into the cache successfully. Insert() returns
289 * FAILURE if it failed to insert the cache entry, which could happen because
290 * of capacity reasons, or because it was already freed by the OS. If the
291 * cache entry isn't associated with a locked image, checking for SUCCESS or
292 * FAILURE is useless: the entry might expire immediately after being
293 * inserted, even though Insert() returned SUCCESS. Thus, many callers do not
294 * need to check the result of Insert() at all.
296 * @param aProvider The new cache entry to insert into the cache.
297 * @return SUCCESS if the cache entry was inserted successfully. (But see
298 * above for more information about when you should check this.)
299 * FAILURE if the cache entry could not be inserted, e.g. for capacity
300 * reasons. (But see above for more information about when you
301 * should check this.)
302 * FAILURE_ALREADY_PRESENT if an entry with the same ImageKey and
303 * SurfaceKey already exists in the cache.
305 static InsertOutcome
Insert(NotNull
<ISurfaceProvider
*> aProvider
);
308 * Mark the cache entry @aProvider as having an available surface. This turns
309 * a placeholder cache entry into a normal cache entry. The cache entry
310 * becomes locked if the associated image is locked; otherwise, it starts in
311 * the unlocked state.
313 * If the cache entry containing @aProvider has already been evicted from the
314 * surface cache, this function has no effect.
316 * It's illegal to call this function if @aProvider is not a placeholder; by
317 * definition, non-placeholder ISurfaceProviders should have a surface
320 * @param aProvider The cache entry that now has a surface available.
322 static void SurfaceAvailable(NotNull
<ISurfaceProvider
*> aProvider
);
325 * Checks if a surface of a given size could possibly be stored in the cache.
326 * If CanHold() returns false, Insert() will always fail to insert the
327 * surface, but the inverse is not true: Insert() may take more information
328 * into account than just image size when deciding whether to cache the
329 * surface, so Insert() may still fail even if CanHold() returns true.
331 * Use CanHold() to avoid the need to create a temporary surface when we know
332 * for sure the cache can't hold it.
334 * @param aSize The dimensions of a surface in pixels.
335 * @param aBytesPerPixel How many bytes each pixel of the surface requires.
336 * Defaults to 4, which is appropriate for RGBA or RGBX
339 * @return false if the surface cache can't hold a surface of that size.
341 static bool CanHold(const IntSize
& aSize
, uint32_t aBytesPerPixel
= 4);
342 static bool CanHold(size_t aSize
);
345 * Locks an image. Any of the image's cache entries which are either inserted
346 * or accessed while the image is locked will not expire.
348 * Locking an image does not automatically lock that image's existing cache
349 * entries. A call to LockImage() guarantees that entries which are inserted
350 * afterward will not expire before the next call to UnlockImage() or
351 * UnlockSurfaces() for that image. Cache entries that are accessed via
352 * Lookup() or LookupBestMatch() after a LockImage() call will also not expire
353 * until the next UnlockImage() or UnlockSurfaces() call for that image. Any
354 * other cache entries owned by the image may expire at any time.
356 * All of an image's cache entries are removed by RemoveImage(), whether the
357 * image is locked or not.
359 * It's safe to call LockImage() on an image that's already locked; this has
362 * You must always unlock any image you lock. You may do this explicitly by
363 * calling UnlockImage(), or implicitly by calling RemoveImage(). Since you're
364 * required to call RemoveImage() when you destroy an image, this doesn't
365 * impose any additional requirements, but it's preferable to call
366 * UnlockImage() earlier if it's possible.
368 * @param aImageKey The image to lock.
370 static void LockImage(const ImageKey aImageKey
);
373 * Unlocks an image, allowing any of its cache entries to expire at any time.
375 * It's OK to call UnlockImage() on an image that's already unlocked; this has
378 * @param aImageKey The image to unlock.
380 static void UnlockImage(const ImageKey aImageKey
);
383 * Unlocks the existing cache entries of an image, allowing them to expire at
386 * This does not unlock the image itself, so accessing the cache entries via
387 * Lookup() or LookupBestMatch() will lock them again, and prevent them from
390 * This is intended to be used in situations where it's no longer clear that
391 * all of the cache entries owned by an image are needed. Calling
392 * UnlockSurfaces() and then taking some action that will cause Lookup() to
393 * touch any cache entries that are still useful will permit the remaining
394 * entries to expire from the cache.
396 * If the image is unlocked, this has no effect.
398 * @param aImageKey The image which should have its existing cache entries
401 static void UnlockEntries(const ImageKey aImageKey
);
404 * Removes all cache entries (including placeholders) associated with the
405 * given image from the cache. If the image is locked, it is automatically
408 * This MUST be called, at a minimum, when an Image which could be storing
409 * entries in the surface cache is destroyed. If another image were allocated
410 * at the same address it could result in subtle, difficult-to-reproduce bugs.
412 * @param aImageKey The image which should be removed from the cache.
414 static void RemoveImage(const ImageKey aImageKey
);
417 * Attempts to remove cache entries (including placeholders) associated with
418 * the given image from the cache, assuming there is an equivalent entry that
419 * it is able substitute that entry with. Note that this only applies if the
420 * image is in factor of 2 mode. If it is not, this operation does nothing.
422 * @param aImageKey The image whose cache which should be pruned.
424 static void PruneImage(const ImageKey aImageKey
);
427 * Removes all rasterized cache entries (including placeholders) associated
428 * with the given image from the cache. Any blob recordings are marked as
429 * dirty and must be regenerated.
431 * @param aImageKey The image whose cache which should be regenerated.
433 * @returns true if any recordings were invalidated, else false.
435 static bool InvalidateImage(const ImageKey aImageKey
);
438 * Evicts all evictable entries from the cache.
440 * All entries are evictable except for entries associated with locked images.
441 * Non-evictable entries can only be removed by RemoveImage().
443 static void DiscardAll();
446 * Collects an accounting of the surfaces contained in the SurfaceCache for
447 * the given image, along with their size and various other metadata.
449 * This is intended for use with memory reporting.
451 * @param aImageKey The image to report memory usage for.
452 * @param aCounters An array into which the report for each surface will
454 * @param aMallocSizeOf A fallback malloc memory reporting function.
456 static void CollectSizeOfSurfaces(const ImageKey aImageKey
,
457 nsTArray
<SurfaceMemoryCounter
>& aCounters
,
458 MallocSizeOf aMallocSizeOf
);
461 * @return maximum capacity of the SurfaceCache in bytes. This is only exposed
462 * for use by tests; normal code should use CanHold() instead.
464 static size_t MaximumCapacity();
467 * @return true if the given size is valid.
469 static bool IsLegalSize(const IntSize
& aSize
);
472 * @return clamped size for the given vector image size to rasterize at.
474 static IntSize
ClampVectorSize(const IntSize
& aSize
);
477 * @return clamped size for the given image and size to rasterize at.
479 static IntSize
ClampSize(const ImageKey aImageKey
, const IntSize
& aSize
);
482 * Release image on main thread.
483 * The function uses SurfaceCache to release pending releasing images quickly.
485 static void ReleaseImageOnMainThread(already_AddRefed
<image::Image
> aImage
,
486 bool aAlwaysProxy
= false);
489 * Clear all pending releasing images.
491 static void ClearReleasingImages();
494 virtual ~SurfaceCache() = 0; // Forbid instantiation.
498 } // namespace mozilla
500 #endif // mozilla_image_SurfaceCache_h