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