OLD | NEW |
1 /* | 1 /* |
2 * Copyright 2013 Google Inc. | 2 * Copyright 2013 Google Inc. |
3 * | 3 * |
4 * Use of this source code is governed by a BSD-style license that can be | 4 * Use of this source code is governed by a BSD-style license that can be |
5 * found in the LICENSE file. | 5 * found in the LICENSE file. |
6 */ | 6 */ |
7 | 7 |
8 #ifndef SkImageCache_DEFINED | 8 #ifndef SkImageCache_DEFINED |
9 #define SkImageCache_DEFINED | 9 #define SkImageCache_DEFINED |
10 | 10 |
11 #include "SkRefCnt.h" | 11 #include "SkRefCnt.h" |
12 #include "SkTypes.h" | 12 #include "SkTypes.h" |
13 | 13 |
14 /** | 14 /** |
15 * Interface for a cache that manages pixel memory. | 15 * Interface for a cache that manages pixel memory. |
16 */ | 16 */ |
17 class SkImageCache : public SkRefCnt { | 17 class SkImageCache : public SkRefCnt { |
18 | 18 |
19 public: | 19 public: |
20 /** | 20 /** |
21 * Allocate memory whose lifetime is managed by the cache. On success, MUST
be balanced with a | 21 * Allocate memory whose lifetime is managed by the cache. On success, MUST
be balanced with a |
22 * call to releaseCache and a call to throwAwayCache. | 22 * call to releaseCache and a call to throwAwayCache. |
23 * @param bytes Number of bytes needed. | 23 * @param bytes Number of bytes needed. |
24 * @param ID Output parameter which must not be NULL. On success, ID will b
e set to a value | 24 * @param ID Output parameter which must not be NULL. On success, ID will b
e set to a value |
25 * associated with that memory which can be used as a parameter to t
he other functions | 25 * associated with that memory which can be used as a parameter to the
other functions |
26 * in SkImageCache. On failure, ID is unchanged. | 26 * in SkImageCache. On failure, ID is unchanged. |
27 * @return Pointer to the newly allocated memory, or NULL. This memory is s
afe to use until | 27 * @return Pointer to the newly allocated memory, or NULL. This memory is s
afe to use until |
28 * releaseCache is called with ID. | 28 * releaseCache is called with ID. |
29 */ | 29 */ |
30 virtual void* allocAndPinCache(size_t bytes, intptr_t* ID) = 0; | 30 virtual void* allocAndPinCache(size_t bytes, intptr_t* ID) = 0; |
31 | 31 |
32 /** | 32 /** |
33 * Re-request the memory associated with ID. | 33 * Output parameter for pinCache, stating whether the memory still contains
the data it held |
| 34 * when releaseCache was last called for the same ID. |
| 35 */ |
| 36 enum DataStatus { |
| 37 /** |
| 38 * The data has been purged, and therefore needs to be rewritten to the
returned memory. |
| 39 */ |
| 40 kUninitialized_DataStatus, |
| 41 |
| 42 /** |
| 43 * The memory still contains the data it held when releaseCache was las
t called with the |
| 44 * same ID. |
| 45 */ |
| 46 kRetained_DataStatus, |
| 47 }; |
| 48 |
| 49 /** |
| 50 * Re-request the memory associated with ID and pin it so that it will not
be reclaimed until |
| 51 * the next call to releaseCache with the same ID. |
34 * @param ID Unique ID for the memory block. | 52 * @param ID Unique ID for the memory block. |
| 53 * @param status Output parameter which must not be NULL. On success (i.e.
the return value is |
| 54 * not NULL), status will be set to one of two states representing the
cached memory. If |
| 55 * status is set to kRetained_DataStatus, the memory contains the same
data it did |
| 56 * before releaseCache was called with this ID. If status is set to |
| 57 * kUninitialized_DataStatus, the memory is still pinned, but the previ
ous data is no |
| 58 * longer available. If the return value is NULL, status is unchanged. |
35 * @return Pointer: If non-NULL, points to the previously allocated memory,
in which case | 59 * @return Pointer: If non-NULL, points to the previously allocated memory,
in which case |
36 * this call must be balanced with a call to releaseCache. If NULL,
the memory | 60 * this call must be balanced with a call to releaseCache. If NULL, the
memory |
37 * has been reclaimed, so allocAndPinCache must be called again wit
h a pointer to | 61 * has been reclaimed, and throwAwayCache MUST NOT be called. |
38 * the same ID. | |
39 */ | 62 */ |
40 virtual void* pinCache(intptr_t ID) = 0; | 63 virtual void* pinCache(intptr_t ID, DataStatus* status) = 0; |
41 | 64 |
42 /** | 65 /** |
43 * Inform the cache that it is safe to free the block of memory correspondi
ng to ID. After | 66 * Inform the cache that it is safe to free the block of memory correspondi
ng to ID. After |
44 * calling this function, the pointer returned by allocAndPinCache or pinCa
che must not be | 67 * calling this function, the pointer returned by allocAndPinCache or pinCa
che must not be |
45 * used again. In order to access the same memory after this, pinCache must
be called with | 68 * used again. In order to access the same memory after this, pinCache must
be called with |
46 * the same ID. | 69 * the same ID. |
47 * @param ID Unique ID for the memory block which is now safe to age out of
the cache. | 70 * @param ID Unique ID for the memory block which is now safe to age out of
the cache. |
48 */ | 71 */ |
49 virtual void releaseCache(intptr_t ID) = 0; | 72 virtual void releaseCache(intptr_t ID) = 0; |
50 | 73 |
51 /** | 74 /** |
52 * Inform the cache that the block of memory associated with ID will not be
asked for again. | 75 * Inform the cache that the block of memory associated with ID will not be
asked for again. |
53 * After this call, ID is no longer valid. Must not be called while the ass
ociated memory is | 76 * After this call, ID is no longer valid. Must not be called while the ass
ociated memory is |
54 * pinned. Must be called to balance a successful allocAndPinCache. | 77 * pinned. Must be called to balance a successful allocAndPinCache. |
55 */ | 78 */ |
56 virtual void throwAwayCache(intptr_t ID) = 0; | 79 virtual void throwAwayCache(intptr_t ID) = 0; |
57 | 80 |
58 /** | 81 /** |
59 * ID which does not correspond to any valid cache. | 82 * ID which does not correspond to any valid cache. |
60 */ | 83 */ |
61 static const intptr_t UNINITIALIZED_ID = 0; | 84 static const intptr_t UNINITIALIZED_ID = 0; |
62 | 85 |
63 #ifdef SK_DEBUG | 86 #ifdef SK_DEBUG |
64 enum CacheStatus { | 87 /** |
65 kPinned_CacheStatus, | 88 * Debug only status of a memory block. |
66 kUnpinned_CacheStatus, | 89 */ |
67 kThrownAway_CacheStatus, | 90 enum MemoryStatus { |
| 91 /** |
| 92 * It is safe to use the pointer returned by the most recent of allocAn
dPinCache(ID) or |
| 93 * pinCache(ID) with the same ID. |
| 94 */ |
| 95 kPinned_MemoryStatus, |
| 96 |
| 97 /** |
| 98 * The pointer returned by the most recent call to allocAndPinCache(ID)
or pinCache(ID) has |
| 99 * since been released by releaseCache(ID). In order to reuse it, pinCa
che(ID) must be |
| 100 * called again. Note that after calling releaseCache(ID), the status o
f that particular |
| 101 * ID may not be kUnpinned_MemoryStatus, depending on the implementatio
n, but it will not |
| 102 * be kPinned_MemoryStatus. |
| 103 */ |
| 104 kUnpinned_MemoryStatus, |
| 105 |
| 106 /** |
| 107 * The memory associated with ID has been thrown away. No calls should
be made using the |
| 108 * same ID. |
| 109 */ |
| 110 kFreed_MemoryStatus, |
68 }; | 111 }; |
69 | 112 |
70 /** | 113 /** |
71 * Debug only function to get the status of a particular block of memory. | 114 * Debug only function to get the status of a particular block of memory. S
afe to call after |
| 115 * throwAwayCache has been called with this ID. |
72 */ | 116 */ |
73 virtual CacheStatus getCacheStatus(intptr_t ID) const = 0; | 117 virtual MemoryStatus getMemoryStatus(intptr_t ID) const = 0; |
| 118 |
| 119 /** |
| 120 * Debug only function to clear all unpinned caches. |
| 121 */ |
| 122 virtual void purgeAllUnpinnedCaches() = 0; |
74 #endif | 123 #endif |
75 }; | 124 }; |
76 #endif // SkImageCache_DEFINED | 125 #endif // SkImageCache_DEFINED |
OLD | NEW |