-
-
Notifications
You must be signed in to change notification settings - Fork 184
/
Copy pathSurfaceCache.h
511 lines (458 loc) · 20.9 KB
/
SurfaceCache.h
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
/* -*- 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/HashFunctions.h" // for HashGeneric and AddToHash
#include "mozilla/Maybe.h" // for Maybe
#include "mozilla/MemoryReporting.h" // for MallocSizeOf
#include "mozilla/NotNull.h"
#include "mozilla/SVGImageContext.h" // for SVGImageContext
#include "mozilla/gfx/2D.h" // for SourceSurface
#include "mozilla/gfx/Point.h" // for mozilla::gfx::IntSize
#include "gfx2DGlue.h"
#include "gfxPoint.h" // for gfxSize
#include "nsCOMPtr.h" // for already_AddRefed
#include "ImageRegion.h"
#include "PlaybackType.h"
#include "SurfaceFlags.h"
namespace mozilla {
namespace image {
class ImageResource;
class ISurfaceProvider;
class LookupResult;
class SurfaceCacheImpl;
struct SurfaceMemoryCounter;
/*
* ImageKey contains the information we need to look up all SurfaceCache entries
* for a particular image.
*/
using ImageKey = ImageResource*;
/*
* 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.mRegion == mRegion &&
aOther.mSVGContext == mSVGContext && aOther.mPlayback == mPlayback &&
aOther.mFlags == mFlags;
}
PLDHashNumber Hash() const {
PLDHashNumber hash = HashGeneric(mSize.width, mSize.height);
hash = AddToHash(hash, mRegion.map(HashIIR).valueOr(0));
hash = AddToHash(hash, HashSIC(mSVGContext));
hash = AddToHash(hash, uint8_t(mPlayback), uint32_t(mFlags));
return hash;
}
SurfaceKey CloneWithSize(const IntSize& aSize) const {
return SurfaceKey(aSize, mRegion, mSVGContext, mPlayback, mFlags);
}
const IntSize& Size() const { return mSize; }
const Maybe<ImageIntRegion>& Region() const { return mRegion; }
const SVGImageContext& SVGContext() const { return mSVGContext; }
PlaybackType Playback() const { return mPlayback; }
SurfaceFlags Flags() const { return mFlags; }
private:
SurfaceKey(const IntSize& aSize, const Maybe<ImageIntRegion>& aRegion,
const SVGImageContext& aSVGContext, PlaybackType aPlayback,
SurfaceFlags aFlags)
: mSize(aSize),
mRegion(aRegion),
mSVGContext(aSVGContext),
mPlayback(aPlayback),
mFlags(aFlags) {}
static PLDHashNumber HashIIR(const ImageIntRegion& aIIR) {
return aIIR.Hash();
}
static PLDHashNumber HashSIC(const SVGImageContext& aSIC) {
return aSIC.Hash();
}
friend SurfaceKey RasterSurfaceKey(const IntSize&, SurfaceFlags,
PlaybackType);
friend SurfaceKey VectorSurfaceKey(const IntSize&, const SVGImageContext&);
friend SurfaceKey VectorSurfaceKey(const IntSize&,
const Maybe<ImageIntRegion>&,
const SVGImageContext&, SurfaceFlags,
PlaybackType);
IntSize mSize;
Maybe<ImageIntRegion> mRegion;
SVGImageContext mSVGContext;
PlaybackType mPlayback;
SurfaceFlags mFlags;
};
inline SurfaceKey RasterSurfaceKey(const gfx::IntSize& aSize,
SurfaceFlags aFlags,
PlaybackType aPlayback) {
return SurfaceKey(aSize, Nothing(), SVGImageContext(), aPlayback, aFlags);
}
inline SurfaceKey VectorSurfaceKey(const gfx::IntSize& aSize,
const Maybe<ImageIntRegion>& aRegion,
const SVGImageContext& aSVGContext,
SurfaceFlags aFlags,
PlaybackType aPlayback) {
return SurfaceKey(aSize, aRegion, aSVGContext, aPlayback, aFlags);
}
inline SurfaceKey VectorSurfaceKey(const gfx::IntSize& aSize,
const 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, Nothing(), 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().
*
* It also tracks whether or not there are "explicit" users of this surface
* which will not accept substitutes. This is used by SurfaceCache when pruning
* unnecessary surfaces from the cache.
*/
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; }
bool CannotSubstitute() const { return mCannotSubstitute; }
void SetCannotSubstitute() { mCannotSubstitute = true; }
private:
friend class SurfaceCacheImpl;
explicit AvailabilityState(bool aIsAvailable)
: mIsAvailable(aIsAvailable), mCannotSubstitute(false) {}
void SetAvailable() { mIsAvailable = true; }
bool mIsAvailable : 1;
bool mCannotSubstitute : 1;
};
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, bool aMarkUsed);
/**
* 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,
bool aMarkUsed);
/**
* 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);
/**
* Attempts to remove cache entries (including placeholders) associated with
* the given image from the cache, assuming there is an equivalent entry that
* it is able substitute that entry with. Note that this only applies if the
* image is in factor of 2 mode. If it is not, this operation does nothing.
*
* @param aImageKey The image whose cache which should be pruned.
*/
static void PruneImage(const ImageKey aImageKey);
/**
* Removes all rasterized cache entries (including placeholders) associated
* with the given image from the cache and marks their surface providers as
* dirty and should not be drawn again. Any blob recordings are left in th
* cache but marked as dirty and must be regenerated.
*
* @param aImageKey The image whose cache which should be regenerated.
*
* @returns true if any surface providers were present in the cache, else
* false.
*/
static bool InvalidateImage(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();
/**
* Calls Reset on the ISurfaceProvider (which is currently only implemented
* for AnimationSurfaceProvider). This is needed because we need to call Reset
* on AnimationSurfaceProvider while they are in placeholder status and there
* is no way to access a surface cache entry from outside of the surface cache
* when it's in placeholder status.
*/
static void ResetAnimation(const ImageKey aImageKey,
const SurfaceKey& aSurfaceKey);
/**
* 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();
/**
* @return true if the given size is valid.
*/
static bool IsLegalSize(const IntSize& aSize);
/**
* @return clamped size for the given vector image size to rasterize at.
*/
static IntSize ClampVectorSize(const IntSize& aSize);
/**
* @return clamped size for the given image and size to rasterize at.
*/
static IntSize ClampSize(const ImageKey aImageKey, const IntSize& aSize);
/**
* Release image on main thread.
* The function uses SurfaceCache to release pending releasing images quickly.
*/
static void ReleaseImageOnMainThread(already_AddRefed<image::Image> aImage,
bool aAlwaysProxy = false);
/**
* Clear all pending releasing images.
*/
static void ClearReleasingImages();
private:
virtual ~SurfaceCache() = 0; // Forbid instantiation.
};
} // namespace image
} // namespace mozilla
#endif // mozilla_image_SurfaceCache_h