]> git.sesse.net Git - movit/blob - resource_pool.h
In EffectChainTester, there is no point in making the FBO and texture persistent.
[movit] / resource_pool.h
1 #ifndef _MOVIT_RESOURCE_POOL_H
2 #define _MOVIT_RESOURCE_POOL_H 1
3
4 // A ResourcePool governs resources that are shared between multiple EffectChains;
5 // in particular, resources that might be expensive to acquire or hold. Thus,
6 // if you have many EffectChains, hooking them up to the same ResourcePool is
7 // probably a good idea.
8 //
9 // However, hooking an EffectChain to a ResourcePool extends the OpenGL context
10 // demands (see effect_chain.h) to that of the ResourcePool; all chains must then
11 // only be used in OpenGL contexts sharing resources with each other. This is
12 // the reason why there isn't just one global ResourcePool singleton (although
13 // most practical users will just want one).
14 //
15 // Thread-safety: All functions except the constructor and destructor can be
16 // safely called from multiple threads at the same time, provided they have
17 // separate (but sharing) OpenGL contexts.
18 //
19 // Memory management (only relevant if you use multiple contexts): Some objects,
20 // like FBOs, are not shareable across contexts, and can only be deleted from
21 // the context they were created in. Thus, you will need to tell the
22 // ResourcePool explicitly if you delete a context, or they will leak (and the
23 // ResourcePool destructor will assert-fail). See clean_context().
24
25 #include <epoxy/gl.h>
26 #include <pthread.h>
27 #include <stddef.h>
28 #include <list>
29 #include <map>
30 #include <string>
31 #include <utility>
32
33 namespace movit {
34
35 class ResourcePool {
36 public:
37         // program_freelist_max_length is how many compiled programs that are unused to keep
38         // around after they are no longer in use (in case another EffectChain
39         // wants that exact program later). Shaders are expensive to compile and do not
40         // need a lot of resources to keep around, so this should be a reasonable number.
41         //
42         // texture_freelist_max_bytes is how many bytes of unused textures to keep around
43         // after they are no longer in use (in case a new texture of the same dimensions
44         // and format is needed). Note that the size estimate is very coarse; it does not
45         // take into account padding, metadata, and most importantly mipmapping.
46         // This means you should be prepared for actual memory usage of the freelist being
47         // twice this estimate or more.
48         ResourcePool(size_t program_freelist_max_length = 100,
49                      size_t texture_freelist_max_bytes = 100 << 20,  // 100 MB.
50                      size_t fbo_freelist_max_length = 100);  // Per context.
51         ~ResourcePool();
52
53         // All remaining functions are intended for calls from EffectChain only.
54
55         // Compile the given vertex+fragment shader pair, or fetch an already
56         // compiled program from the cache if possible. Keeps ownership of the
57         // program; you must call release_glsl_program() instead of deleting it
58         // when you no longer want it.
59         GLuint compile_glsl_program(const std::string& vertex_shader, const std::string& fragment_shader);
60         void release_glsl_program(GLuint glsl_program_num);
61
62         // Allocate a 2D texture of the given internal format and dimensions,
63         // or fetch a previous used if possible. Unbinds GL_TEXTURE_2D afterwards.
64         // Keeps ownership of the texture; you must call release_2d_texture() instead
65         // of deleting it when you no longer want it.
66         GLuint create_2d_texture(GLint internal_format, GLsizei width, GLsizei height);
67         void release_2d_texture(GLuint texture_num);
68
69         // Allocate an FBO with the the given texture(s) bound as framebuffer attachment(s),
70         // or fetch a previous used if possible. Unbinds GL_FRAMEBUFFER afterwards.
71         // Keeps ownership of the FBO; you must call release_fbo() of deleting
72         // it when you no longer want it.
73         //
74         // NOTE: In principle, the FBO doesn't have a resolution or pixel format;
75         // you can bind almost whatever texture you want to it. However, changing
76         // textures can have an adverse effect on performance due to validation,
77         // in particular on NVidia cards. Also, keep in mind that FBOs are not
78         // shareable across contexts, so you must have the context that's supposed
79         // to own the FBO current when you create or release it.
80         GLuint create_fbo(GLuint texture0_num,
81                           GLuint texture1_num = 0,
82                           GLuint texture2_num = 0,
83                           GLuint texture3_num = 0);
84         void release_fbo(GLuint fbo_num);
85
86         // Informs the ResourcePool that the current context is going away soon,
87         // and that any resources held for it in the freelist should be deleted.
88         //
89         // You do not need to do this for the last context; the regular destructor
90         // will take care of that. This means that if you only ever use one
91         // thread/context, you never need to call this function.
92         void clean_context();
93
94 private:
95         // Delete the given program and both its shaders.
96         void delete_program(GLuint program_num);
97
98         // Deletes all FBOs for the given context that belong to deleted textures.
99         void cleanup_unlinked_fbos(void *context);
100
101         // Remove FBOs off the end of the freelist for <context>, until it
102         // is no more than <max_length> elements long.
103         void shrink_fbo_freelist(void *context, size_t max_length);
104
105         // Protects all the other elements in the class.
106         pthread_mutex_t lock;
107
108         size_t program_freelist_max_length, texture_freelist_max_bytes, fbo_freelist_max_length;
109                 
110         // A mapping from vertex/fragment shader source strings to compiled program number.
111         std::map<std::pair<std::string, std::string>, GLuint> programs;
112
113         // A mapping from compiled program number to number of current users.
114         // Once this reaches zero, the program is taken out of this map and instead
115         // put on the freelist (after which it may be deleted).
116         std::map<GLuint, int> program_refcount;
117
118         // A mapping from program number to vertex and fragment shaders.
119         std::map<GLuint, std::pair<GLuint, GLuint> > program_shaders;
120
121         // A list of programs that are no longer in use, most recently freed first.
122         // Once this reaches <program_freelist_max_length>, the last element
123         // will be deleted.
124         std::list<GLuint> program_freelist;
125
126         struct Texture2D {
127                 GLint internal_format;
128                 GLsizei width, height;
129         };
130
131         // A mapping from texture number to format details. This is filled if the
132         // texture is given out to a client or on the freelist, but not if it is
133         // deleted from the freelist.
134         std::map<GLuint, Texture2D> texture_formats;
135
136         // A list of all textures that are release but not freed (most recently freed
137         // first), and an estimate of their current memory usage. Once
138         // <texture_freelist_bytes> goes above <texture_freelist_max_bytes>,
139         // elements are deleted off the end of the list until we are under the limit
140         // again.
141         std::list<GLuint> texture_freelist;
142         size_t texture_freelist_bytes;
143
144         static const unsigned num_fbo_attachments = 4;
145         struct FBO {
146                 // GL_INVALID_INDEX means associated to a texture that has since been deleted.
147                 // 0 means the output isn't bound.
148                 GLuint texture_num[num_fbo_attachments];
149         };
150
151         // For each context, a mapping from FBO number to format details. This is
152         // filled if the FBO is given out to a client or on the freelist, but
153         // not if it is deleted from the freelist.
154         std::map<std::pair<void *, GLuint>, FBO> fbo_formats;
155
156         // For each context, a list of all FBOs that are released but not freed
157         // (most recently freed first). Once this reaches <fbo_freelist_max_length>,
158         // the last element will be deleted.
159         std::map<void *, std::list<GLuint> > fbo_freelist;
160
161         // See the caveats at the constructor.
162         static size_t estimate_texture_size(const Texture2D &texture_format);
163 };
164
165 }  // namespace movit
166
167 #endif  // !defined(_MOVIT_RESOURCE_POOL_H)