no bug - Bumping Firefox l10n changesets r=release a=l10n-bump DONTBUILD CLOSED TREE
[gecko.git] / image / SurfaceCache.h
blob864a6ffbc4759781b52232e336b56b9fbf9d698f
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/. */
6 /**
7 * SurfaceCache is a service for caching temporary surfaces and decoded image
8 * data in imagelib.
9 */
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"
28 namespace mozilla {
29 namespace image {
31 class ImageResource;
32 class ISurfaceProvider;
33 class LookupResult;
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
46 * surface.
48 * Callers should construct a SurfaceKey using the appropriate helper function
49 * for their image type - either RasterSurfaceKey or VectorSurfaceKey.
51 class SurfaceKey {
52 typedef gfx::IntSize IntSize;
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;
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;
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 SVGImageContext& SVGContext() const { return mSVGContext; }
76 PlaybackType Playback() const { return mPlayback; }
77 SurfaceFlags Flags() const { return mFlags; }
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) {}
89 static PLDHashNumber HashIIR(const ImageIntRegion& aIIR) {
90 return aIIR.Hash();
93 static PLDHashNumber HashSIC(const SVGImageContext& aSIC) {
94 return aSIC.Hash();
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);
105 IntSize mSize;
106 Maybe<ImageIntRegion> mRegion;
107 SVGImageContext mSVGContext;
108 PlaybackType mPlayback;
109 SurfaceFlags mFlags;
112 inline SurfaceKey RasterSurfaceKey(const gfx::IntSize& aSize,
113 SurfaceFlags aFlags,
114 PlaybackType aPlayback) {
115 return SurfaceKey(aSize, Nothing(), SVGImageContext(), aPlayback, aFlags);
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);
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());
138 * AvailabilityState is used to track whether an ISurfaceProvider has a surface
139 * available or is just a placeholder.
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().
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.
151 class AvailabilityState {
152 public:
153 static AvailabilityState StartAvailable() { return AvailabilityState(true); }
154 static AvailabilityState StartAsPlaceholder() {
155 return AvailabilityState(false);
158 bool IsAvailable() const { return mIsAvailable; }
159 bool IsPlaceholder() const { return !mIsAvailable; }
160 bool CannotSubstitute() const { return mCannotSubstitute; }
162 void SetCannotSubstitute() { mCannotSubstitute = true; }
164 private:
165 friend class SurfaceCacheImpl;
167 explicit AvailabilityState(bool aIsAvailable)
168 : mIsAvailable(aIsAvailable), mCannotSubstitute(false) {}
170 void SetAvailable() { mIsAvailable = true; }
172 bool mIsAvailable : 1;
173 bool mCannotSubstitute : 1;
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.
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.
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.
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.
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.
206 struct SurfaceCache {
207 typedef gfx::IntSize IntSize;
210 * Initialize static data. Called during imagelib module initialization.
212 static void Initialize();
215 * Release static data. Called during imagelib module shutdown.
217 static void Shutdown();
220 * Looks up the requested cache entry and returns a drawable reference to its
221 * associated surface.
223 * If the image associated with the cache entry is locked, then the entry will
224 * be locked before it is returned.
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.
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.
241 static LookupResult Lookup(const ImageKey aImageKey,
242 const SurfaceKey& aSurfaceKey, bool aMarkUsed);
245 * Looks up the best matching cache entry and returns a drawable reference to
246 * its associated surface.
248 * The result may vary from the requested cache entry only in terms of size.
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.
260 static LookupResult LookupBestMatch(const ImageKey aImageKey,
261 const SurfaceKey& aSurfaceKey,
262 bool aMarkUsed);
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.
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).
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.
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.
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.
304 static InsertOutcome Insert(NotNull<ISurfaceProvider*> aProvider);
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.
312 * If the cache entry containing @aProvider has already been evicted from the
313 * surface cache, this function has no effect.
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.
319 * @param aProvider The cache entry that now has a surface available.
321 static void SurfaceAvailable(NotNull<ISurfaceProvider*> aProvider);
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.
330 * Use CanHold() to avoid the need to create a temporary surface when we know
331 * for sure the cache can't hold it.
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.
338 * @return false if the surface cache can't hold a surface of that size.
340 static bool CanHold(const IntSize& aSize, uint32_t aBytesPerPixel = 4);
341 static bool CanHold(size_t aSize);
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.
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.
355 * All of an image's cache entries are removed by RemoveImage(), whether the
356 * image is locked or not.
358 * It's safe to call LockImage() on an image that's already locked; this has
359 * no effect.
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.
367 * @param aImageKey The image to lock.
369 static void LockImage(const ImageKey aImageKey);
372 * Unlocks an image, allowing any of its cache entries to expire at any time.
374 * It's OK to call UnlockImage() on an image that's already unlocked; this has
375 * no effect.
377 * @param aImageKey The image to unlock.
379 static void UnlockImage(const ImageKey aImageKey);
382 * Unlocks the existing cache entries of an image, allowing them to expire at
383 * any time.
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.
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.
395 * If the image is unlocked, this has no effect.
397 * @param aImageKey The image which should have its existing cache entries
398 * unlocked.
400 static void UnlockEntries(const ImageKey aImageKey);
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.
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.
411 * @param aImageKey The image which should be removed from the cache.
413 static void RemoveImage(const ImageKey aImageKey);
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.
421 * @param aImageKey The image whose cache which should be pruned.
423 static void PruneImage(const ImageKey aImageKey);
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.
430 * @param aImageKey The image whose cache which should be regenerated.
432 * @returns true if any recordings were invalidated, else false.
434 static bool InvalidateImage(const ImageKey aImageKey);
437 * Evicts all evictable entries from the cache.
439 * All entries are evictable except for entries associated with locked images.
440 * Non-evictable entries can only be removed by RemoveImage().
442 static void DiscardAll();
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.
451 static void ResetAnimation(const ImageKey aImageKey,
452 const SurfaceKey& aSurfaceKey);
455 * Collects an accounting of the surfaces contained in the SurfaceCache for
456 * the given image, along with their size and various other metadata.
458 * This is intended for use with memory reporting.
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.
465 static void CollectSizeOfSurfaces(const ImageKey aImageKey,
466 nsTArray<SurfaceMemoryCounter>& aCounters,
467 MallocSizeOf aMallocSizeOf);
470 * @return maximum capacity of the SurfaceCache in bytes. This is only exposed
471 * for use by tests; normal code should use CanHold() instead.
473 static size_t MaximumCapacity();
476 * @return true if the given size is valid.
478 static bool IsLegalSize(const IntSize& aSize);
481 * @return clamped size for the given vector image size to rasterize at.
483 static IntSize ClampVectorSize(const IntSize& aSize);
486 * @return clamped size for the given image and size to rasterize at.
488 static IntSize ClampSize(const ImageKey aImageKey, const IntSize& aSize);
491 * Release image on main thread.
492 * The function uses SurfaceCache to release pending releasing images quickly.
494 static void ReleaseImageOnMainThread(already_AddRefed<image::Image> aImage,
495 bool aAlwaysProxy = false);
498 * Clear all pending releasing images.
500 static void ClearReleasingImages();
502 private:
503 virtual ~SurfaceCache() = 0; // Forbid instantiation.
506 } // namespace image
507 } // namespace mozilla
509 #endif // mozilla_image_SurfaceCache_h