egl_cache.h revision 99c3d700d2d0886fe27fa961c89dae7c6c3b8195 
1/*
2 ** Copyright 2011, The Android Open Source Project
3 **
4 ** Licensed under the Apache License, Version 2.0 (the "License");
5 ** you may not use this file except in compliance with the License.
6 ** You may obtain a copy of the License at
7 **
8 **     http://www.apache.org/licenses/LICENSE-2.0
9 **
10 ** Unless required by applicable law or agreed to in writing, software
11 ** distributed under the License is distributed on an "AS IS" BASIS,
12 ** WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 ** See the License for the specific language governing permissions and
14 ** limitations under the License.
15 */
16
17#ifndef ANDROID_EGL_CACHE_H
18#define ANDROID_EGL_CACHE_H
19
20#include <EGL/egl.h>
21#include <EGL/eglext.h>
22
23#include <utils/BlobCache.h>
24#include <utils/String8.h>
25#include <utils/StrongPointer.h>
26
27// ----------------------------------------------------------------------------
28namespace android {
29// ----------------------------------------------------------------------------
30
31class egl_display_t;
32
33class EGLAPI egl_cache_t {
34public:
35
36    // get returns a pointer to the singleton egl_cache_t object.  This
37    // singleton object will never be destroyed.
38    static egl_cache_t* get();
39
40    // initialize puts the egl_cache_t into an initialized state, such that it
41    // is able to insert and retrieve entries from the cache.  This should be
42    // called when EGL is initialized.  When not in the initialized state the
43    // getBlob and setBlob methods will return without performing any cache
44    // operations.
45    void initialize(egl_display_t* display);
46
47    // terminate puts the egl_cache_t back into the uninitialized state.  When
48    // in this state the getBlob and setBlob methods will return without
49    // performing any cache operations.
50    void terminate();
51
52    // setBlob attempts to insert a new key/value blob pair into the cache.
53    // This will be called by the hardware vendor's EGL implementation via the
54    // EGL_ANDROID_blob_cache extension.
55    void setBlob(const void* key, EGLsizei keySize, const void* value,
56        EGLsizei valueSize);
57
58    // getBlob attempts to retrieve the value blob associated with a given key
59    // blob from cache.  This will be called by the hardware vendor's EGL
60    // implementation via the EGL_ANDROID_blob_cache extension.
61    EGLsizei getBlob(const void* key, EGLsizei keySize, void* value,
62        EGLsizei valueSize);
63
64    // setCacheFilename sets the name of the file that should be used to store
65    // cache contents from one program invocation to another.
66    void setCacheFilename(const char* filename);
67
68private:
69    // Creation and (the lack of) destruction is handled internally.
70    egl_cache_t();
71    ~egl_cache_t();
72
73    // Copying is disallowed.
74    egl_cache_t(const egl_cache_t&); // not implemented
75    void operator=(const egl_cache_t&); // not implemented
76
77    // getBlobCacheLocked returns the BlobCache object being used to store the
78    // key/value blob pairs.  If the BlobCache object has not yet been created,
79    // this will do so, loading the serialized cache contents from disk if
80    // possible.
81    sp<BlobCache> getBlobCacheLocked();
82
83    // saveBlobCache attempts to save the current contents of mBlobCache to
84    // disk.
85    void saveBlobCacheLocked();
86
87    // loadBlobCache attempts to load the saved cache contents from disk into
88    // mBlobCache.
89    void loadBlobCacheLocked();
90
91    // mInitialized indicates whether the egl_cache_t is in the initialized
92    // state.  It is initialized to false at construction time, and gets set to
93    // true when initialize is called.  It is set back to false when terminate
94    // is called.  When in this state, the cache behaves as normal.  When not,
95    // the getBlob and setBlob methods will return without performing any cache
96    // operations.
97    bool mInitialized;
98
99    // mBlobCache is the cache in which the key/value blob pairs are stored.  It
100    // is initially NULL, and will be initialized by getBlobCacheLocked the
101    // first time it's needed.
102    sp<BlobCache> mBlobCache;
103
104    // mFilename is the name of the file for storing cache contents in between
105    // program invocations.  It is initialized to an empty string at
106    // construction time, and can be set with the setCacheFilename method.  An
107    // empty string indicates that the cache should not be saved to or restored
108    // from disk.
109    String8 mFilename;
110
111    // mSavePending indicates whether or not a deferred save operation is
112    // pending.  Each time a key/value pair is inserted into the cache via
113    // setBlob, a deferred save is initiated if one is not already pending.
114    // This will wait some amount of time and then trigger a save of the cache
115    // contents to disk.
116    bool mSavePending;
117
118    // mMutex is the mutex used to prevent concurrent access to the member
119    // variables. It must be locked whenever the member variables are accessed.
120    mutable Mutex mMutex;
121
122    // sCache is the singleton egl_cache_t object.
123    static egl_cache_t sCache;
124};
125
126// ----------------------------------------------------------------------------
127}; // namespace android
128// ----------------------------------------------------------------------------
129
130#endif // ANDROID_EGL_CACHE_H
131