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/. */
5
6 /**
7 * SurfaceCache is a service for caching temporary surfaces and decoded image
8 * data in imagelib.
9 */
10
11 #ifndef mozilla_image_SurfaceCache_h
12 #define mozilla_image_SurfaceCache_h
13
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 "PlaybackType.h"
25 #include "SurfaceFlags.h"
26
27 namespace mozilla {
28 namespace image {
29
30 class Image;
31 class ISurfaceProvider;
32 class LookupResult;
33 class SurfaceCacheImpl;
34 struct SurfaceMemoryCounter;
35
36 /*
37 * ImageKey contains the information we need to look up all SurfaceCache entries
38 * for a particular image.
39 */
40 typedef Image* ImageKey;
41
42 /*
43 * SurfaceKey contains the information we need to look up a specific
44 * SurfaceCache entry. Together with an ImageKey, this uniquely identifies the
45 * surface.
46 *
47 * Callers should construct a SurfaceKey using the appropriate helper function
48 * for their image type - either RasterSurfaceKey or VectorSurfaceKey.
49 */
50 class SurfaceKey {
51 typedef gfx::IntSize IntSize;
52
53 public:
54 bool operator==(const SurfaceKey& aOther) const {
55 return aOther.mSize == mSize && aOther.mSVGContext == mSVGContext &&
56 aOther.mPlayback == mPlayback && aOther.mFlags == mFlags;
57 }
58
Hash()59 PLDHashNumber Hash() const {
60 PLDHashNumber hash = HashGeneric(mSize.width, mSize.height);
61 hash = AddToHash(hash, mSVGContext.map(HashSIC).valueOr(0));
62 hash = AddToHash(hash, uint8_t(mPlayback), uint32_t(mFlags));
63 return hash;
64 }
65
CloneWithSize(const IntSize & aSize)66 SurfaceKey CloneWithSize(const IntSize& aSize) const {
67 return SurfaceKey(aSize, mSVGContext, mPlayback, mFlags);
68 }
69
Size()70 const IntSize& Size() const { return mSize; }
SVGContext()71 const Maybe<SVGImageContext>& SVGContext() const { return mSVGContext; }
Playback()72 PlaybackType Playback() const { return mPlayback; }
Flags()73 SurfaceFlags Flags() const { return mFlags; }
74
75 private:
SurfaceKey(const IntSize & aSize,const Maybe<SVGImageContext> & aSVGContext,PlaybackType aPlayback,SurfaceFlags aFlags)76 SurfaceKey(const IntSize& aSize, const Maybe<SVGImageContext>& aSVGContext,
77 PlaybackType aPlayback, SurfaceFlags aFlags)
78 : mSize(aSize),
79 mSVGContext(aSVGContext),
80 mPlayback(aPlayback),
81 mFlags(aFlags) {}
82
HashSIC(const SVGImageContext & aSIC)83 static PLDHashNumber HashSIC(const SVGImageContext& aSIC) {
84 return aSIC.Hash();
85 }
86
87 friend SurfaceKey RasterSurfaceKey(const IntSize&, SurfaceFlags,
88 PlaybackType);
89 friend SurfaceKey VectorSurfaceKey(const IntSize&,
90 const Maybe<SVGImageContext>&);
91 friend SurfaceKey ContainerSurfaceKey(
92 const gfx::IntSize& aSize, const Maybe<SVGImageContext>& aSVGContext,
93 SurfaceFlags aFlags);
94
95 IntSize mSize;
96 Maybe<SVGImageContext> mSVGContext;
97 PlaybackType mPlayback;
98 SurfaceFlags mFlags;
99 };
100
RasterSurfaceKey(const gfx::IntSize & aSize,SurfaceFlags aFlags,PlaybackType aPlayback)101 inline SurfaceKey RasterSurfaceKey(const gfx::IntSize& aSize,
102 SurfaceFlags aFlags,
103 PlaybackType aPlayback) {
104 return SurfaceKey(aSize, Nothing(), aPlayback, aFlags);
105 }
106
VectorSurfaceKey(const gfx::IntSize & aSize,const Maybe<SVGImageContext> & aSVGContext)107 inline SurfaceKey VectorSurfaceKey(const gfx::IntSize& aSize,
108 const Maybe<SVGImageContext>& aSVGContext) {
109 // We don't care about aFlags for VectorImage because none of the flags we
110 // have right now influence VectorImage's rendering. If we add a new flag that
111 // *does* affect how a VectorImage renders, we'll have to change this.
112 // Similarly, we don't accept a PlaybackType parameter because we don't
113 // currently cache frames of animated SVG images.
114 return SurfaceKey(aSize, aSVGContext, PlaybackType::eStatic,
115 DefaultSurfaceFlags());
116 }
117
ContainerSurfaceKey(const gfx::IntSize & aSize,const Maybe<SVGImageContext> & aSVGContext,SurfaceFlags aFlags)118 inline SurfaceKey ContainerSurfaceKey(const gfx::IntSize& aSize,
119 const Maybe<SVGImageContext>& aSVGContext,
120 SurfaceFlags aFlags) {
121 return SurfaceKey(aSize, aSVGContext, PlaybackType::eStatic, aFlags);
122 }
123
124 /**
125 * AvailabilityState is used to track whether an ISurfaceProvider has a surface
126 * available or is just a placeholder.
127 *
128 * To ensure that availability changes are atomic (and especially that internal
129 * SurfaceCache code doesn't have to deal with asynchronous availability
130 * changes), an ISurfaceProvider which starts as a placeholder can only reveal
131 * the fact that it now has a surface available via a call to
132 * SurfaceCache::SurfaceAvailable().
133 *
134 * It also tracks whether or not there are "explicit" users of this surface
135 * which will not accept substitutes. This is used by SurfaceCache when pruning
136 * unnecessary surfaces from the cache.
137 */
138 class AvailabilityState {
139 public:
StartAvailable()140 static AvailabilityState StartAvailable() { return AvailabilityState(true); }
StartAsPlaceholder()141 static AvailabilityState StartAsPlaceholder() {
142 return AvailabilityState(false);
143 }
144
IsAvailable()145 bool IsAvailable() const { return mIsAvailable; }
IsPlaceholder()146 bool IsPlaceholder() const { return !mIsAvailable; }
CannotSubstitute()147 bool CannotSubstitute() const { return mCannotSubstitute; }
148
SetCannotSubstitute()149 void SetCannotSubstitute() { mCannotSubstitute = true; }
150
151 private:
152 friend class SurfaceCacheImpl;
153
AvailabilityState(bool aIsAvailable)154 explicit AvailabilityState(bool aIsAvailable)
155 : mIsAvailable(aIsAvailable), mCannotSubstitute(false) {}
156
SetAvailable()157 void SetAvailable() { mIsAvailable = true; }
158
159 bool mIsAvailable : 1;
160 bool mCannotSubstitute : 1;
161 };
162
163 enum class InsertOutcome : uint8_t {
164 SUCCESS, // Success (but see Insert documentation).
165 FAILURE, // Couldn't insert (e.g., for capacity reasons).
166 FAILURE_ALREADY_PRESENT // A surface with the same key is already present.
167 };
168
169 /**
170 * SurfaceCache is an ImageLib-global service that allows caching of decoded
171 * image surfaces, temporary surfaces (e.g. for caching rotated or clipped
172 * versions of images), or dynamically generated surfaces (e.g. for animations).
173 * SurfaceCache entries normally expire from the cache automatically if they go
174 * too long without being accessed.
175 *
176 * Because SurfaceCache must support both normal surfaces and dynamically
177 * generated surfaces, it does not actually hold surfaces directly. Instead, it
178 * holds ISurfaceProvider objects which can provide access to a surface when
179 * requested; SurfaceCache doesn't care about the details of how this is
180 * accomplished.
181 *
182 * Sometime it's useful to temporarily prevent entries from expiring from the
183 * cache. This is most often because losing the data could harm the user
184 * experience (for example, we often don't want to allow surfaces that are
185 * currently visible to expire) or because it's not possible to rematerialize
186 * the surface. SurfaceCache supports this through the use of image locking; see
187 * the comments for Insert() and LockImage() for more details.
188 *
189 * Any image which stores surfaces in the SurfaceCache *must* ensure that it
190 * calls RemoveImage() before it is destroyed. See the comments for
191 * RemoveImage() for more details.
192 */
193 struct SurfaceCache {
194 typedef gfx::IntSize IntSize;
195
196 /**
197 * Initialize static data. Called during imagelib module initialization.
198 */
199 static void Initialize();
200
201 /**
202 * Release static data. Called during imagelib module shutdown.
203 */
204 static void Shutdown();
205
206 /**
207 * Looks up the requested cache entry and returns a drawable reference to its
208 * associated surface.
209 *
210 * If the image associated with the cache entry is locked, then the entry will
211 * be locked before it is returned.
212 *
213 * If a matching ISurfaceProvider was found in the cache, but SurfaceCache
214 * couldn't obtain a surface from it (e.g. because it had stored its surface
215 * in a volatile buffer which was discarded by the OS) then it is
216 * automatically removed from the cache and an empty LookupResult is returned.
217 * Note that this will never happen to ISurfaceProviders associated with a
218 * locked image; SurfaceCache tells such ISurfaceProviders to keep a strong
219 * references to their data internally.
220 *
221 * @param aImageKey Key data identifying which image the cache entry
222 * belongs to.
223 * @param aSurfaceKey Key data which uniquely identifies the requested
224 * cache entry.
225 * @return a LookupResult which will contain a DrawableSurface
226 * if the cache entry was found.
227 */
228 static LookupResult Lookup(const ImageKey aImageKey,
229 const SurfaceKey& aSurfaceKey, bool aMarkUsed);
230
231 /**
232 * Looks up the best matching cache entry and returns a drawable reference to
233 * its associated surface.
234 *
235 * The result may vary from the requested cache entry only in terms of size.
236 *
237 * @param aImageKey Key data identifying which image the cache entry
238 * belongs to.
239 * @param aSurfaceKey Key data which uniquely identifies the requested
240 * cache entry.
241 * @return a LookupResult which will contain a DrawableSurface
242 * if a cache entry similar to the one the caller
243 * requested could be found. Callers can use
244 * LookupResult::IsExactMatch() to check whether the
245 * returned surface exactly matches @aSurfaceKey.
246 */
247 static LookupResult LookupBestMatch(const ImageKey aImageKey,
248 const SurfaceKey& aSurfaceKey,
249 bool aMarkUsed);
250
251 /**
252 * Insert an ISurfaceProvider into the cache. If an entry with the same
253 * ImageKey and SurfaceKey is already in the cache, Insert returns
254 * FAILURE_ALREADY_PRESENT. If a matching placeholder is already present, it
255 * is replaced.
256 *
257 * Cache entries will never expire as long as they remain locked, but if they
258 * become unlocked, they can expire either because the SurfaceCache runs out
259 * of capacity or because they've gone too long without being used. When it
260 * is first inserted, a cache entry is locked if its associated image is
261 * locked. When that image is later unlocked, the cache entry becomes
262 * unlocked too. To become locked again at that point, two things must happen:
263 * the image must become locked again (via LockImage()), and the cache entry
264 * must be touched again (via one of the Lookup() functions).
265 *
266 * All of this means that a very particular procedure has to be followed for
267 * cache entries which cannot be rematerialized. First, they must be inserted
268 * *after* the image is locked with LockImage(); if you use the other order,
269 * the cache entry might expire before LockImage() gets called or before the
270 * entry is touched again by Lookup(). Second, the image they are associated
271 * with must never be unlocked.
272 *
273 * If a cache entry cannot be rematerialized, it may be important to know
274 * whether it was inserted into the cache successfully. Insert() returns
275 * FAILURE if it failed to insert the cache entry, which could happen because
276 * of capacity reasons, or because it was already freed by the OS. If the
277 * cache entry isn't associated with a locked image, checking for SUCCESS or
278 * FAILURE is useless: the entry might expire immediately after being
279 * inserted, even though Insert() returned SUCCESS. Thus, many callers do not
280 * need to check the result of Insert() at all.
281 *
282 * @param aProvider The new cache entry to insert into the cache.
283 * @return SUCCESS if the cache entry was inserted successfully. (But see
284 * above for more information about when you should check this.)
285 * FAILURE if the cache entry could not be inserted, e.g. for capacity
286 * reasons. (But see above for more information about when you
287 * should check this.)
288 * FAILURE_ALREADY_PRESENT if an entry with the same ImageKey and
289 * SurfaceKey already exists in the cache.
290 */
291 static InsertOutcome Insert(NotNull<ISurfaceProvider*> aProvider);
292
293 /**
294 * Mark the cache entry @aProvider as having an available surface. This turns
295 * a placeholder cache entry into a normal cache entry. The cache entry
296 * becomes locked if the associated image is locked; otherwise, it starts in
297 * the unlocked state.
298 *
299 * If the cache entry containing @aProvider has already been evicted from the
300 * surface cache, this function has no effect.
301 *
302 * It's illegal to call this function if @aProvider is not a placeholder; by
303 * definition, non-placeholder ISurfaceProviders should have a surface
304 * available already.
305 *
306 * @param aProvider The cache entry that now has a surface available.
307 */
308 static void SurfaceAvailable(NotNull<ISurfaceProvider*> aProvider);
309
310 /**
311 * Checks if a surface of a given size could possibly be stored in the cache.
312 * If CanHold() returns false, Insert() will always fail to insert the
313 * surface, but the inverse is not true: Insert() may take more information
314 * into account than just image size when deciding whether to cache the
315 * surface, so Insert() may still fail even if CanHold() returns true.
316 *
317 * Use CanHold() to avoid the need to create a temporary surface when we know
318 * for sure the cache can't hold it.
319 *
320 * @param aSize The dimensions of a surface in pixels.
321 * @param aBytesPerPixel How many bytes each pixel of the surface requires.
322 * Defaults to 4, which is appropriate for RGBA or RGBX
323 * images.
324 *
325 * @return false if the surface cache can't hold a surface of that size.
326 */
327 static bool CanHold(const IntSize& aSize, uint32_t aBytesPerPixel = 4);
328 static bool CanHold(size_t aSize);
329
330 /**
331 * Locks an image. Any of the image's cache entries which are either inserted
332 * or accessed while the image is locked will not expire.
333 *
334 * Locking an image does not automatically lock that image's existing cache
335 * entries. A call to LockImage() guarantees that entries which are inserted
336 * afterward will not expire before the next call to UnlockImage() or
337 * UnlockSurfaces() for that image. Cache entries that are accessed via
338 * Lookup() or LookupBestMatch() after a LockImage() call will also not expire
339 * until the next UnlockImage() or UnlockSurfaces() call for that image. Any
340 * other cache entries owned by the image may expire at any time.
341 *
342 * All of an image's cache entries are removed by RemoveImage(), whether the
343 * image is locked or not.
344 *
345 * It's safe to call LockImage() on an image that's already locked; this has
346 * no effect.
347 *
348 * You must always unlock any image you lock. You may do this explicitly by
349 * calling UnlockImage(), or implicitly by calling RemoveImage(). Since you're
350 * required to call RemoveImage() when you destroy an image, this doesn't
351 * impose any additional requirements, but it's preferable to call
352 * UnlockImage() earlier if it's possible.
353 *
354 * @param aImageKey The image to lock.
355 */
356 static void LockImage(const ImageKey aImageKey);
357
358 /**
359 * Unlocks an image, allowing any of its cache entries to expire at any time.
360 *
361 * It's OK to call UnlockImage() on an image that's already unlocked; this has
362 * no effect.
363 *
364 * @param aImageKey The image to unlock.
365 */
366 static void UnlockImage(const ImageKey aImageKey);
367
368 /**
369 * Unlocks the existing cache entries of an image, allowing them to expire at
370 * any time.
371 *
372 * This does not unlock the image itself, so accessing the cache entries via
373 * Lookup() or LookupBestMatch() will lock them again, and prevent them from
374 * expiring.
375 *
376 * This is intended to be used in situations where it's no longer clear that
377 * all of the cache entries owned by an image are needed. Calling
378 * UnlockSurfaces() and then taking some action that will cause Lookup() to
379 * touch any cache entries that are still useful will permit the remaining
380 * entries to expire from the cache.
381 *
382 * If the image is unlocked, this has no effect.
383 *
384 * @param aImageKey The image which should have its existing cache entries
385 * unlocked.
386 */
387 static void UnlockEntries(const ImageKey aImageKey);
388
389 /**
390 * Removes all cache entries (including placeholders) associated with the
391 * given image from the cache. If the image is locked, it is automatically
392 * unlocked.
393 *
394 * This MUST be called, at a minimum, when an Image which could be storing
395 * entries in the surface cache is destroyed. If another image were allocated
396 * at the same address it could result in subtle, difficult-to-reproduce bugs.
397 *
398 * @param aImageKey The image which should be removed from the cache.
399 */
400 static void RemoveImage(const ImageKey aImageKey);
401
402 /**
403 * Attempts to remove cache entries (including placeholders) associated with
404 * the given image from the cache, assuming there is an equivalent entry that
405 * it is able substitute that entry with. Note that this only applies if the
406 * image is in factor of 2 mode. If it is not, this operation does nothing.
407 *
408 * @param aImageKey The image whose cache which should be pruned.
409 */
410 static void PruneImage(const ImageKey aImageKey);
411
412 /**
413 * Evicts all evictable entries from the cache.
414 *
415 * All entries are evictable except for entries associated with locked images.
416 * Non-evictable entries can only be removed by RemoveImage().
417 */
418 static void DiscardAll();
419
420 /**
421 * Collects an accounting of the surfaces contained in the SurfaceCache for
422 * the given image, along with their size and various other metadata.
423 *
424 * This is intended for use with memory reporting.
425 *
426 * @param aImageKey The image to report memory usage for.
427 * @param aCounters An array into which the report for each surface will
428 * be written.
429 * @param aMallocSizeOf A fallback malloc memory reporting function.
430 */
431 static void CollectSizeOfSurfaces(const ImageKey aImageKey,
432 nsTArray<SurfaceMemoryCounter>& aCounters,
433 MallocSizeOf aMallocSizeOf);
434
435 /**
436 * @return maximum capacity of the SurfaceCache in bytes. This is only exposed
437 * for use by tests; normal code should use CanHold() instead.
438 */
439 static size_t MaximumCapacity();
440
441 /**
442 * @return true if the given size is valid.
443 */
444 static bool IsLegalSize(const IntSize& aSize);
445
446 /**
447 * @return clamped size for the given vector image size to rasterize at.
448 */
449 static IntSize ClampVectorSize(const IntSize& aSize);
450
451 /**
452 * @return clamped size for the given image and size to rasterize at.
453 */
454 static IntSize ClampSize(const ImageKey aImageKey, const IntSize& aSize);
455
456 /**
457 * Release image on main thread.
458 * The function uses SurfaceCache to release pending releasing images quickly.
459 */
460 static void ReleaseImageOnMainThread(already_AddRefed<image::Image> aImage,
461 bool aAlwaysProxy = false);
462
463 /**
464 * Clear all pending releasing images.
465 */
466 static void ClearReleasingImages();
467
468 private:
469 virtual ~SurfaceCache() = 0; // Forbid instantiation.
470 };
471
472 } // namespace image
473 } // namespace mozilla
474
475 #endif // mozilla_image_SurfaceCache_h
476