Add support for compute shaders.
[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 <set>
31 #include <stack>
32 #include <string>
33 #include <utility>
34 #include <vector>
35
36 namespace movit {
37
38 class ResourcePool {
39 public:
40         // program_freelist_max_length is how many compiled programs that are unused to keep
41         // around after they are no longer in use (in case another EffectChain
42         // wants that exact program later). Shaders are expensive to compile and do not
43         // need a lot of resources to keep around, so this should be a reasonable number.
44         //
45         // texture_freelist_max_bytes is how many bytes of unused textures to keep around
46         // after they are no longer in use (in case a new texture of the same dimensions
47         // and format is needed). Note that the size estimate is very coarse; it does not
48         // take into account padding, metadata, and most importantly mipmapping.
49         // This means you should be prepared for actual memory usage of the freelist being
50         // twice this estimate or more.
51         ResourcePool(size_t program_freelist_max_length = 100,
52                      size_t texture_freelist_max_bytes = 100 << 20,  // 100 MB.
53                      size_t fbo_freelist_max_length = 100,  // Per context.
54                      size_t vao_freelist_max_length = 100);  // Per context.
55         ~ResourcePool();
56
57         // All remaining functions are intended for calls from EffectChain only.
58
59         // Compile the given vertex+fragment shader pair, or fetch an already
60         // compiled program from the cache if possible. Keeps ownership of the
61         // program; you must call release_glsl_program() instead of deleting it
62         // when you no longer want it.
63         //
64         // If <fragment_shader_outputs> contains more than one value, the given
65         // outputs will be bound to fragment shader output colors in the order
66         // they appear in the vector. Otherwise, output order is undefined and
67         // determined by the OpenGL driver.
68         GLuint compile_glsl_program(const std::string& vertex_shader,
69                                     const std::string& fragment_shader,
70                                     const std::vector<std::string>& frag_shader_outputs);
71         void release_glsl_program(GLuint glsl_program_num);
72
73         // Same as the previous, but for compile shaders instead. There is currently
74         // no support for binding multiple outputs.
75         GLuint compile_glsl_compute_program(const std::string& compile_shader);
76         void release_glsl_compute_program(GLuint glsl_program_num);
77
78         // Since uniforms belong to the program and not to the context,
79         // a given GLSL program number can't be used by more than one thread
80         // at a time. Thus, if two threads want to use the same program
81         // (usually because two EffectChains share them via caching),
82         // we will need to make a clone. use_glsl_program() makes such
83         // a clone if needed, calls glUseProgram(), and returns the real
84         // program number that was used; this must be given to
85         // unuse_glsl_program() to release it. unuse_glsl_program() does not
86         // actually change any OpenGL state, though.
87         GLuint use_glsl_program(GLuint glsl_program_num);
88         void unuse_glsl_program(GLuint instance_program_num);
89
90         // Allocate a 2D texture of the given internal format and dimensions,
91         // or fetch a previous used if possible. Unbinds GL_TEXTURE_2D afterwards.
92         // Keeps ownership of the texture; you must call release_2d_texture() instead
93         // of deleting it when you no longer want it.
94         GLuint create_2d_texture(GLint internal_format, GLsizei width, GLsizei height);
95         void release_2d_texture(GLuint texture_num);
96
97         // Allocate an FBO with the the given texture(s) bound as framebuffer attachment(s),
98         // or fetch a previous used if possible. Unbinds GL_FRAMEBUFFER afterwards.
99         // Keeps ownership of the FBO; you must call release_fbo() of deleting
100         // it when you no longer want it.
101         //
102         // NOTE: In principle, the FBO doesn't have a resolution or pixel format;
103         // you can bind almost whatever texture you want to it. However, changing
104         // textures can have an adverse effect on performance due to validation,
105         // in particular on NVidia cards. Also, keep in mind that FBOs are not
106         // shareable across contexts, so you must have the context that's supposed
107         // to own the FBO current when you create or release it.
108         GLuint create_fbo(GLuint texture0_num,
109                           GLuint texture1_num = 0,
110                           GLuint texture2_num = 0,
111                           GLuint texture3_num = 0);
112         void release_fbo(GLuint fbo_num);
113
114         // Create a VAO of a very specific form: All the given attribute indices
115         // are bound to start of the  given VBO and contain two-component floats.
116         // Keeps ownership of the VAO; you must call release_vec2_vao() of deleting
117         // it when you no longer want it. VAOs are not sharable across contexts.
118         //
119         // These are not cached primarily for performance, but rather to work
120         // around an NVIDIA driver bug where glVertexAttribPointer() is thread-hostile
121         // (ie., simultaneous GL work in unrelated contexts can cause the driver
122         // to free() memory that was never malloc()-ed).
123         GLuint create_vec2_vao(const std::set<GLint> &attribute_indices,
124                                GLuint vbo_num);
125         void release_vec2_vao(const GLuint vao_num);
126
127         // Informs the ResourcePool that the current context is going away soon,
128         // and that any resources held for it in the freelist should be deleted.
129         //
130         // You do not need to do this for the last context; the regular destructor
131         // will take care of that. This means that if you only ever use one
132         // thread/context, you never need to call this function.
133         void clean_context();
134
135 private:
136         // Delete the given program and both its shaders.
137         void delete_program(GLuint program_num);
138
139         // Deletes all FBOs for the given context that belong to deleted textures.
140         void cleanup_unlinked_fbos(void *context);
141
142         // Remove FBOs off the end of the freelist for <context>, until it
143         // is no more than <max_length> elements long.
144         void shrink_fbo_freelist(void *context, size_t max_length);
145
146         // Same, for VAOs.
147         void shrink_vao_freelist(void *context, size_t max_length);
148
149         // Increment the refcount, or take it off the freelist if it's zero.
150         void increment_program_refcount(GLuint program_num);
151
152         // If debugging is on, output shader to a temporary file, for easier debugging.
153         void output_debug_shader(const std::string &shader_src, const std::string &suffix);
154
155         // For a new program that's not a clone of anything, insert it into the right
156         // structures: Give it a refcount, and set up the program_masters / program_instances lists.
157         void add_master_program(GLuint program_num);
158
159         // Link the given vertex and fragment shaders into a full GLSL program.
160         // See compile_glsl_program() for explanation of <fragment_shader_outputs>.
161         static GLuint link_program(GLuint vs_obj,
162                                    GLuint fs_obj,
163                                    const std::vector<std::string>& fragment_shader_outputs);
164
165         static GLuint link_compute_program(GLuint cs_obj);
166
167         // Protects all the other elements in the class.
168         pthread_mutex_t lock;
169
170         size_t program_freelist_max_length, texture_freelist_max_bytes, fbo_freelist_max_length, vao_freelist_max_length;
171                 
172         // A mapping from vertex/fragment shader source strings to compiled program number.
173         std::map<std::pair<std::string, std::string>, GLuint> programs;
174
175         // A mapping from compute shader source string to compiled program number.
176         std::map<std::string, GLuint> compute_programs;
177
178         // A mapping from compiled program number to number of current users.
179         // Once this reaches zero, the program is taken out of this map and instead
180         // put on the freelist (after which it may be deleted).
181         std::map<GLuint, int> program_refcount;
182
183         // A mapping from program number to vertex and fragment shaders.
184         // Contains everything needed to re-link the program.
185         struct ShaderSpec {
186                 GLuint vs_obj, fs_obj;
187                 std::vector<std::string> fragment_shader_outputs;
188         };
189         std::map<GLuint, ShaderSpec> program_shaders;
190
191         struct ComputeShaderSpec {
192                 GLuint cs_obj;
193         };
194         std::map<GLuint, ComputeShaderSpec> compute_program_shaders;
195
196         // For each program, a list of other programs that are exactly like it.
197         // By default, will only contain the program itself, but due to cloning
198         // (see use_glsl_program()), may grow. Programs are taken off this list
199         // while they are in use (by use_glsl_program()).
200         std::map<GLuint, std::stack<GLuint> > program_instances;
201
202         // For each program, the master program that created it
203         // (inverse of program_instances).
204         std::map<GLuint, GLuint> program_masters;
205
206         // A list of programs that are no longer in use, most recently freed first.
207         // Once this reaches <program_freelist_max_length>, the last element
208         // will be deleted.
209         std::list<GLuint> program_freelist;
210
211         struct Texture2D {
212                 GLint internal_format;
213                 GLsizei width, height;
214         };
215
216         // A mapping from texture number to format details. This is filled if the
217         // texture is given out to a client or on the freelist, but not if it is
218         // deleted from the freelist.
219         std::map<GLuint, Texture2D> texture_formats;
220
221         // A list of all textures that are release but not freed (most recently freed
222         // first), and an estimate of their current memory usage. Once
223         // <texture_freelist_bytes> goes above <texture_freelist_max_bytes>,
224         // elements are deleted off the end of the list until we are under the limit
225         // again.
226         std::list<GLuint> texture_freelist;
227         size_t texture_freelist_bytes;
228
229         static const unsigned num_fbo_attachments = 4;
230         struct FBO {
231                 GLuint fbo_num;
232                 // GL_INVALID_INDEX means associated to a texture that has since been deleted.
233                 // 0 means the output isn't bound.
234                 GLuint texture_num[num_fbo_attachments];
235         };
236
237         // For each context, a mapping from FBO number to format details. This is
238         // filled if the FBO is given out to a client or on the freelist, but
239         // not if it is deleted from the freelist.
240         std::map<std::pair<void *, GLuint>, FBO> fbo_formats;
241         typedef std::map<std::pair<void *, GLuint>, FBO>::iterator FBOFormatIterator;
242
243         // For each context, a list of all FBOs that are released but not freed
244         // (most recently freed first). Once this reaches <fbo_freelist_max_length>,
245         // the last element will be deleted.
246         //
247         // We store iterators directly into <fbo_format> for efficiency.
248         std::map<void *, std::list<FBOFormatIterator> > fbo_freelist;
249
250         // Very similar, for VAOs.
251         struct VAO {
252                 GLuint vao_num;
253                 std::set<GLint> attribute_indices;
254                 GLuint vbo_num;
255         };
256         std::map<std::pair<void *, GLuint>, VAO> vao_formats;
257         typedef std::map<std::pair<void *, GLuint>, VAO>::iterator VAOFormatIterator;
258         std::map<void *, std::list<VAOFormatIterator> > vao_freelist;
259
260         // See the caveats at the constructor.
261         static size_t estimate_texture_size(const Texture2D &texture_format);
262 };
263
264 }  // namespace movit
265
266 #endif  // !defined(_MOVIT_RESOURCE_POOL_H)