File: SurfaceCache.h

package info (click to toggle)
icedove 1%3A45.8.0-3~deb8u1
  • links: PTS, VCS
  • area: main
  • in suites: jessie
  • size: 1,488,584 kB
  • ctags: 1,068,813
  • sloc: cpp: 4,801,496; ansic: 1,929,291; python: 379,296; java: 252,018; xml: 173,182; asm: 146,741; sh: 89,229; makefile: 23,462; perl: 16,380; objc: 4,088; yacc: 1,841; lex: 1,222; exp: 499; php: 437; lisp: 228; awk: 152; pascal: 116; sed: 51; ruby: 47; csh: 31; ada: 16
file content (423 lines) | stat: -rw-r--r-- 17,935 bytes parent folder | download
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
/* -*- 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/Maybe.h"           // for Maybe
#include "mozilla/MemoryReporting.h" // for MallocSizeOf
#include "mozilla/HashFunctions.h"   // for HashGeneric and AddToHash
#include "gfx2DGlue.h"
#include "gfxPoint.h"                // for gfxSize
#include "nsCOMPtr.h"                // for already_AddRefed
#include "mozilla/gfx/Point.h"       // for mozilla::gfx::IntSize
#include "mozilla/gfx/2D.h"          // for SourceSurface
#include "SurfaceFlags.h"
#include "SVGImageContext.h"         // for SVGImageContext

namespace mozilla {
namespace image {

class Image;
class imgFrame;
class LookupResult;
struct SurfaceMemoryCounter;

/*
 * ImageKey contains the information we need to look up all cached surfaces for
 * a particular image.
 */
typedef Image* ImageKey;

/*
 * SurfaceKey contains the information we need to look up a specific cached
 * surface. 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.mSVGContext == mSVGContext &&
           aOther.mAnimationTime == mAnimationTime &&
           aOther.mFlags == mFlags;
  }

  uint32_t Hash() const
  {
    uint32_t hash = HashGeneric(mSize.width, mSize.height);
    hash = AddToHash(hash, mSVGContext.map(HashSIC).valueOr(0));
    hash = AddToHash(hash, mAnimationTime, uint32_t(mFlags));
    return hash;
  }

  IntSize Size() const { return mSize; }
  Maybe<SVGImageContext> SVGContext() const { return mSVGContext; }
  float AnimationTime() const { return mAnimationTime; }
  SurfaceFlags Flags() const { return mFlags; }

private:
  SurfaceKey(const IntSize& aSize,
             const Maybe<SVGImageContext>& aSVGContext,
             const float aAnimationTime,
             const SurfaceFlags aFlags)
    : mSize(aSize)
    , mSVGContext(aSVGContext)
    , mAnimationTime(aAnimationTime)
    , mFlags(aFlags)
  { }

  static uint32_t HashSIC(const SVGImageContext& aSIC) {
    return aSIC.Hash();
  }

  friend SurfaceKey RasterSurfaceKey(const IntSize&,
                                     SurfaceFlags,
                                     uint32_t);
  friend SurfaceKey VectorSurfaceKey(const IntSize&,
                                     const Maybe<SVGImageContext>&,
                                     float);

  IntSize                mSize;
  Maybe<SVGImageContext> mSVGContext;
  float                  mAnimationTime;
  SurfaceFlags           mFlags;
};

inline SurfaceKey
RasterSurfaceKey(const gfx::IntSize& aSize,
                 SurfaceFlags aFlags,
                 uint32_t aFrameNum)
{
  return SurfaceKey(aSize, Nothing(), float(aFrameNum), aFlags);
}

inline SurfaceKey
VectorSurfaceKey(const gfx::IntSize& aSize,
                 const Maybe<SVGImageContext>& aSVGContext,
                 float aAnimationTime)
{
  // 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.
  return SurfaceKey(aSize, aSVGContext, aAnimationTime, DefaultSurfaceFlags());
}

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 temporary
 * surfaces. Surfaces normally expire from the cache automatically if they go
 * too long without being accessed.
 *
 * SurfaceCache does not hold surfaces directly; instead, it holds imgFrame
 * objects, which hold surfaces but also layer on additional features specific
 * to imagelib's needs like animation, padding support, and transparent support
 * for volatile buffers.
 *
 * Sometime it's useful to temporarily prevent surfaces 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();

  /**
   * Look up the imgFrame containing a surface in the cache and returns a
   * drawable reference to that imgFrame.
   *
   * If the image associated with the surface is locked, then the surface will
   * be locked before it is returned.
   *
   * If the imgFrame was found in the cache, but 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 surfaces associated with a locked image; the
   * cache keeps a strong reference to such surfaces internally.
   *
   * @param aImageKey       Key data identifying which image the surface belongs
   *                        to.
   *
   * @param aSurfaceKey     Key data which uniquely identifies the requested
   *                        surface.
   *
   * @return                a LookupResult, which will either contain a
   *                        DrawableFrameRef to the requested surface, or an
   *                        empty DrawableFrameRef if the surface was not found.
   */
  static LookupResult Lookup(const ImageKey    aImageKey,
                             const SurfaceKey& aSurfaceKey);

  /**
   * Looks up the best matching surface in the cache and returns a drawable
   * reference to the imgFrame containing it.
   *
   * Returned surfaces may vary from the requested surface only in terms of
   * size.
   *
   * @param aImageKey    Key data identifying which image the surface belongs
   *                     to.
   *
   * @param aSurfaceKey  Key data which identifies the ideal surface to return.
   *
   * @return                a LookupResult, which will either contain a
   *                        DrawableFrameRef to a surface similar to the
   *                        requested surface, or an empty DrawableFrameRef if
   *                        the surface was not found. Callers can use
   *                        LookupResult::IsExactMatch() to check whether the
   *                        returned surface exactly matches @aSurfaceKey.
   */
  static LookupResult LookupBestMatch(const ImageKey    aImageKey,
                                      const SurfaceKey& aSurfaceKey);

  /**
   * Insert a surface into the cache. If a surface with the same ImageKey and
   * SurfaceKey is already in the cache, Insert returns FAILURE_ALREADY_PRESENT.
   * If a matching placeholder is already present, the placeholder is removed.
   *
   * Surfaces 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 surface is locked if its associated image is locked.
   * When that image is later unlocked, the surface becomes unlocked too. To
   * become locked again at that point, two things must happen: the image must
   * become locked again (via LockImage()), and the surface must be touched
   * again (via one of the Lookup() functions).
   *
   * All of this means that a very particular procedure has to be followed for
   * surfaces which cannot be rematerialized. First, they must be inserted
   * *after* the image is locked with LockImage(); if you use the other order,
   * the surfaces might expire before LockImage() gets called or before the
   * surface is touched again by Lookup(). Second, the image they are associated
   * with must never be unlocked.
   *
   * If a surface 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 surface, which could happen because of capacity
   * reasons, or because it was already freed by the OS. If the surface isn't
   * associated with a locked image, checking for SUCCESS or FAILURE is useless:
   * the surface 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 aTarget      The new surface (wrapped in an imgFrame) to insert into
   *                     the cache.
   * @param aImageKey    Key data identifying which image the surface belongs
   *                     to.
   * @param aSurfaceKey  Key data which uniquely identifies the requested
   *                     surface.
   * @return SUCCESS if the surface was inserted successfully. (But see above
   *           for more information about when you should check this.)
   *         FAILURE if the surface 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 a surface with the same ImageKey and
   *           SurfaceKey already exists in the cache.
   */
  static InsertOutcome Insert(imgFrame*         aSurface,
                              const ImageKey    aImageKey,
                              const SurfaceKey& aSurfaceKey);

  /**
   * Insert a placeholder for a surface into the cache. If a surface with the
   * same ImageKey and SurfaceKey is already in the cache, InsertPlaceholder()
   * returns FAILURE_ALREADY_PRESENT.
   *
   * Placeholders exist to allow lazy allocation of surfaces. The Lookup*()
   * methods will report whether a placeholder for an exactly matching surface
   * existed by returning a MatchType of PENDING or SUBSTITUTE_BECAUSE_PENDING,
   * but they will never return a placeholder directly. (They couldn't, since
   * placeholders don't have an associated surface.)
   *
   * Once inserted, placeholders can be removed using RemoveSurface() or
   * RemoveImage(), just like a surface.  They're automatically removed when a
   * real surface that matches the placeholder is inserted with Insert().
   *
   * @param aImageKey    Key data identifying which image the placeholder
   *                     belongs to.
   * @param aSurfaceKey  Key data which uniquely identifies the surface the
   *                     placeholder stands in for.
   * @return SUCCESS if the placeholder was inserted successfully.
   *         FAILURE if the placeholder could not be inserted for some reason.
   *         FAILURE_ALREADY_PRESENT if a surface with the same ImageKey and
   *           SurfaceKey already exists in the cache.
   */
  static InsertOutcome InsertPlaceholder(const ImageKey    aImageKey,
                                         const SurfaceKey& aSurfaceKey);

  /**
   * 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 surfaces 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
   * surfaces. A call to LockImage() guarantees that surfaces which are inserted
   * afterward will not expire before the next call to UnlockImage() or
   * UnlockSurfaces() for that image. Surfaces 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
   * surfaces owned by the image may expire at any time.
   *
   * Regardless of locking, any of an image's surfaces may be removed using
   * RemoveSurface(), and all of an image's surfaces 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 surfaces 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 surfaces of an image, allowing them to expire at any
   * time.
   *
   * This does not unlock the image itself, so accessing the surfaces 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 surfaces owned by an image are needed. Calling UnlockSurfaces()
   * and then taking some action that will cause Lookup() to touch any surfaces
   * that are still useful will permit the remaining surfaces to expire from the
   * cache.
   *
   * If the image is unlocked, this has no effect.
   *
   * @param aImageKey    The image which should have its existing surfaces
   *                     unlocked.
   */
  static void UnlockSurfaces(const ImageKey aImageKey);

  /**
   * Removes a surface or placeholder from the cache, if it's present. If it's
   * not present, RemoveSurface() has no effect.
   *
   * Use this function to remove individual surfaces that have become invalid.
   * Prefer RemoveImage() or DiscardAll() when they're applicable, as they have
   * much better performance than calling this function repeatedly.
   *
   * @param aImageKey    Key data identifying which image the surface belongs
                         to.
   * @param aSurfaceKey  Key data which uniquely identifies the requested
                         surface.
   */
  static void RemoveSurface(const ImageKey    aImageKey,
                            const SurfaceKey& aSurfaceKey);

  /**
   * Removes all cached surfaces and 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
   * surfaces 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);

  /**
   * Evicts all evictable surfaces from the cache.
   *
   * All surfaces are evictable except for surfaces associated with locked
   * images. Non-evictable surfaces can only be removed by RemoveSurface() or
   * RemoveImage().
   */
  static void DiscardAll();

  /**
   * 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);

private:
  virtual ~SurfaceCache() = 0;  // Forbid instantiation.
};

} // namespace image
} // namespace mozilla

#endif // mozilla_image_SurfaceCache_h