1 /* 2 * This file is part of libplacebo. 3 * 4 * libplacebo is free software; you can redistribute it and/or 5 * modify it under the terms of the GNU Lesser General Public 6 * License as published by the Free Software Foundation; either 7 * version 2.1 of the License, or (at your option) any later version. 8 * 9 * libplacebo is distributed in the hope that it will be useful, 10 * but WITHOUT ANY WARRANTY; without even the implied warranty of 11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 12 * GNU Lesser General Public License for more details. 13 * 14 * You should have received a copy of the GNU Lesser General Public 15 * License along with libplacebo. If not, see <http://www.gnu.org/licenses/>. 16 */ 17 18 #ifndef LIBPLACEBO_OPENGL_H_ 19 #define LIBPLACEBO_OPENGL_H_ 20 21 #include <libplacebo/gpu.h> 22 #include <libplacebo/swapchain.h> 23 24 PL_API_BEGIN 25 26 // Note on thread safety: The thread safety of `pl_opengl` and any associated 27 // GPU objects follows the same thread safety rules as the underlying OpenGL 28 // context. In other words, they must only be called from the thread the OpenGL 29 // context is current on. 30 31 typedef const PL_STRUCT(pl_opengl) { 32 pl_gpu gpu; 33 } *pl_opengl; 34 35 struct pl_opengl_params { 36 // Enable OpenGL debug report callbacks. May have little effect depending 37 // on whether or not the GL context was initialized with appropriate 38 // debugging enabled. 39 bool debug; 40 41 // Allow the use of (suspected) software rasterizers and renderers. These 42 // can be useful for debugging purposes, but normally, their use is 43 // undesirable when GPU-accelerated processing is expected. 44 bool allow_software; 45 46 // Restrict the maximum allowed GLSL version. (Mainly for testing) 47 int max_glsl_version; 48 49 // Optional. Required when importing/exporting dmabufs as textures. 50 void *egl_display; 51 void *egl_context; 52 53 // Optional callbacks to bind/release the OpenGL context on the current 54 // thread. If these are specified, then the resulting `pl_gpu` will have 55 // `pl_gpu_limits.thread_safe` enabled, and may therefore be used from any 56 // thread without first needing to bind the OpenGL context. 57 // 58 // If the user is re-using the same OpenGL context in non-libplacebo code, 59 // then these callbacks should include whatever synchronization is 60 // necessary to prevent simultaneous use between libplacebo and the user. 61 bool (*make_current)(void *priv); 62 void (*release_current)(void *priv); 63 void *priv; 64 }; 65 66 // Default/recommended parameters 67 extern const struct pl_opengl_params pl_opengl_default_params; 68 69 // Creates a new OpenGL renderer based on the given parameters. This will 70 // internally use whatever platform-defined mechanism (WGL, X11, EGL) is 71 // appropriate for loading the OpenGL function calls, so the user doesn't need 72 // to pass in a `getProcAddress` callback. If `params` is left as NULL, it 73 // defaults to `&pl_opengl_default_params`. The context must be active when 74 // calling this function, and must remain active whenever calling any 75 // libplacebo function on the resulting `pl_opengl` or `pl_gpu`. 76 // 77 // Note that creating multiple `pl_opengl` instances from the same OpenGL 78 // context is undefined behavior. 79 pl_opengl pl_opengl_create(pl_log log, const struct pl_opengl_params *params); 80 81 // All resources allocated from the `pl_gpu` contained by this `pl_opengl` must 82 // be explicitly destroyed by the user before calling `pl_opengl_destroy`. 83 void pl_opengl_destroy(pl_opengl *gl); 84 85 struct pl_opengl_framebuffer { 86 // ID of the framebuffer, or 0 to use the context's default framebuffer. 87 int id; 88 89 // If true, then the framebuffer is assumed to be "flipped" relative to 90 // normal GL semantics, i.e. set this to `true` if the first pixel is the 91 // top left corner. 92 bool flipped; 93 }; 94 95 struct pl_opengl_swapchain_params { 96 // Set this to the platform-specific function to swap buffers, e.g. 97 // glXSwapBuffers, eglSwapBuffers etc. This will be called internally by 98 // `pl_swapchain_swap_buffers`. Required, unless you never call that 99 // function. 100 void (*swap_buffers)(void *priv); 101 102 // Initial framebuffer description. This can be changed later on using 103 // `pl_opengl_swapchain_update_fb`. 104 struct pl_opengl_framebuffer framebuffer; 105 106 // Attempt forcing a specific latency. If this is nonzero, then 107 // `pl_swapchain_swap_buffers` will wait until fewer than N frames are "in 108 // flight" before returning. Setting this to a high number generally 109 // accomplished nothing, because the OpenGL driver typically limits the 110 // number of buffers on its own. But setting it to a low number like 2 or 111 // even 1 can reduce latency (at the cost of throughput). 112 int max_swapchain_depth; 113 114 // Arbitrary user pointer that gets passed to `swap_buffers` etc. 115 void *priv; 116 }; 117 118 // Creates an instance of `pl_swapchain` tied to the active context. 119 // Note: Due to OpenGL semantics, users *must* call `pl_swapchain_resize` 120 // before attempting to use this swapchain, otherwise calls to 121 // `pl_swapchain_start_frame` will fail. 122 pl_swapchain pl_opengl_create_swapchain(pl_opengl gl, 123 const struct pl_opengl_swapchain_params *params); 124 125 // Update the framebuffer description. After calling this function, users 126 // *must* call `pl_swapchain_resize` before attempting to use the swapchain 127 // again, otherwise calls to `pl_swapchain_start_frame` will fail. 128 void pl_opengl_swapchain_update_fb(pl_swapchain sw, 129 const struct pl_opengl_framebuffer *fb); 130 131 struct pl_opengl_wrap_params { 132 // The GLuint texture object itself. Optional. If no texture is provided, 133 // then only the opaque framebuffer `fbo` will be wrapped, leaving the 134 // resulting `pl_tex` object with some operations (such as sampling) being 135 // unsupported. 136 unsigned int texture; 137 138 // The GLuint associated framebuffer. Optional. If this is not specified, 139 // then libplacebo will attempt creating a framebuffer from the provided 140 // texture object (if possible). 141 // 142 // Note: As a special case, if neither a texture nor an FBO are provided, 143 // this is equivalent to wrapping the OpenGL default framebuffer (id 0). 144 unsigned int framebuffer; 145 146 // The image's dimensions (unused dimensions must be 0) 147 int width; 148 int height; 149 int depth; 150 151 // Texture-specific fields: 152 // 153 // Note: These are only relevant if `texture` is provided. 154 155 // The GLenum for the texture target to use, e.g. GL_TEXTURE_2D. Optional. 156 // If this is left as 0, the target is inferred from the number of 157 // dimensions. Users may want to set this to something specific like 158 // GL_TEXTURE_EXTERNAL_OES depending on the nature of the texture. 159 unsigned int target; 160 161 // The texture's GLint sized internal format (e.g. GL_RGBA16F). Required. 162 int iformat; 163 164 // Deprecated fields. These are now ignored completely. 165 int filter PL_DEPRECATED; 166 int address_mode PL_DEPRECATED; 167 }; 168 169 // Wraps an external OpenGL object into a `pl_tex` abstraction. Due to the 170 // internally synchronized nature of OpenGL, no explicit synchronization 171 // is needed between libplacebo `pl_tex_` operations, and host accesses to 172 // the texture. Wrapping the same OpenGL texture multiple times is permitted. 173 // Note that this function transfers no ownership. 174 // 175 // This wrapper can be destroyed by simply calling `pl_tex_destroy` on it, 176 // which will *not* destroy the user-provided OpenGL texture or framebuffer. 177 // 178 // This function may fail, in which case it returns NULL. 179 pl_tex pl_opengl_wrap(pl_gpu gpu, const struct pl_opengl_wrap_params *params); 180 181 // Analogous to `pl_opengl_wrap`, this function takes any `pl_tex` (including 182 // ones created by `pl_tex_create`) and unwraps it to expose the underlying 183 // OpenGL texture to the user. Note that this function transfers no ownership, 184 // i.e. the texture object and framebuffer shall not be destroyed by the user. 185 // 186 // Returns the OpenGL texture. `out_target` and `out_iformat` will be updated 187 // to hold the target type and internal format, respectively. (Optional) 188 // 189 // For renderable/blittable textures, `out_fbo` will be updated to the ID of 190 // the framebuffer attached to this texture, or 0 if there is none. (Optional) 191 unsigned int pl_opengl_unwrap(pl_gpu gpu, pl_tex tex, unsigned int *out_target, 192 int *out_iformat, unsigned int *out_fbo); 193 194 PL_API_END 195 196 #endif // LIBPLACEBO_OPENGL_H_ 197