README.md revision f71742df
1[](https://travis-ci.org/anholt/libepoxy) 2[](https://ci.appveyor.com/project/ebassi/libepoxy/branch/master) 3 4Epoxy is a library for handling OpenGL function pointer management for 5you. 6 7It hides the complexity of `dlopen()`, `dlsym()`, `glXGetProcAddress()`, 8`eglGetProcAddress()`, etc. from the app developer, with very little 9knowledge needed on their part. They get to read GL specs and write 10code using undecorated function names like `glCompileShader()`. 11 12Don't forget to check for your extensions or versions being present 13before you use them, just like before! We'll tell you what you forgot 14to check for instead of just segfaulting, though. 15 16Features 17-------- 18 19 * Automatically initializes as new GL functions are used. 20 * GL 4.5 core and compatibility context support. 21 * GLES 1/2/3 context support. 22 * Knows about function aliases so (e.g.) `glBufferData()` can be 23 used with `GL_ARB_vertex_buffer_object` implementations, along 24 with GL 1.5+ implementations. 25 * EGL, GLX, and WGL support. 26 * Can be mixed with non-epoxy GL usage. 27 28Building 29-------- 30 31```sh 32mkdir _build && cd _build 33meson 34ninja 35sudo ninja install 36``` 37 38Dependencies for Debian: 39 40 * meson 41 * libegl1-mesa-dev 42 43Dependencies for macOS (using MacPorts): 44 45 * pkgconfig 46 * meson 47 48The test suite has additional dependencies depending on the platform. 49(X11, EGL, a running X Server). 50 51Switching your code to using epoxy 52---------------------------------- 53 54It should be as easy as replacing: 55 56```cpp 57#include <GL/gl.h> 58#include <GL/glx.h> 59#include <GL/glext.h> 60``` 61 62with: 63 64```cpp 65#include <epoxy/gl.h> 66#include <epoxy/glx.h> 67``` 68 69As long as epoxy's headers appear first, you should be ready to go. 70Additionally, some new helpers become available, so you don't have to 71write them: 72 73`int epoxy_gl_version()` returns the GL version: 74 75 * 12 for GL 1.2 76 * 20 for GL 2.0 77 * 44 for GL 4.4 78 79`bool epoxy_has_gl_extension()` returns whether a GL extension is 80available (`GL_ARB_texture_buffer_object`, for example). 81 82Note that this is not terribly fast, so keep it out of your hot paths, 83ok? 84 85Why not use libGLEW? 86-------------------- 87 88GLEW has several issues: 89 90 * Doesn't know about aliases of functions (There are 5 providers of 91 `glPointParameterfv()`, for example, and you don't want to have to 92 choose which one to call when they're all the same). 93 * Doesn't support OpenGL ES. 94 * Doesn't support EGL. 95 * Has a hard-to-maintain parser of extension specification text 96 instead of using the old .spec file or the new .xml. 97 * Has significant startup time overhead when `glewInit()` 98 autodetects the world. 99 * User-visible multithreading support choice for win32. 100 101The motivation for this project came out of previous use of libGLEW in 102[piglit](http://piglit.freedesktop.org/). Other GL dispatch code 103generation projects had similar failures. Ideally, piglit wants to be 104able to build a single binary for a test that can run on whatever 105context or window system it chooses, not based on link time choices. 106 107We had to solve some of GLEW's problems for piglit and solving them 108meant replacing every single piece of GLEW, so we built 109piglit-dispatch from scratch. And since we wanted to reuse it in 110other GL-related projects, this is the result. 111 112Known issues when running on Windows 113------------------------------------ 114 115The automatic per-context symbol resolution for win32 requires that 116epoxy knows when `wglMakeCurrent()` is called, because `wglGetProcAddress()` 117returns values depend on the context's device and pixel format. If 118`wglMakeCurrent()` is called from outside of epoxy (in a way that might 119change the device or pixel format), then epoxy needs to be notified of 120the change using the `epoxy_handle_external_wglMakeCurrent()` function. 121 122The win32 `wglMakeCurrent()` variants are slower than they should be, 123because they should be caching the resolved dispatch tables instead of 124resetting an entire thread-local dispatch table every time. 125
