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