Epoxy is a library for handling OpenGL function pointer management for you.

It hides the complexity of dlopen(), dlsym(), glXGetProcAddress(), eglGetProcAddress(), etc. from the app developer, with very little knowledge needed on their part. They get to read GL specs and write code using undecorated function names like glCompileShader().

Don't forget to check for your extensions or versions being present before you use them, just like before! We'll tell you what you forgot to check for instead of just segfaulting, though.

Features

• Automatically initializes as new OpenGL functions are used.
• Desktop OpenGL 4.4 core and compatibility context support.
• OpenGL ES 1/2/3 context support.
• Knows about function aliases so (e.g.) glBufferData() can be used with GL_ARB_vertex_buffer_object implementations, along with desktop OpenGL 1.5+ implementations.
• GLX, and WGL support.
• EGL support. EGL headers are included, so they're not necessary to build Epoxy with EGL support.
• Can be mixed with non-epoxy OpenGL usage.

Building (CMake)

CMake is now the recommended way to build epoxy. It should be as cample as:

cd <my-build_dir>
cmake <my-source-dir>

And then build the project, depending on the type of your toolset, e.g. for Unix type "make", for MSVC open the solution in Visual studio and build the solution.

To rebuild the generated headers from the specs, add "-DEPOXY_REBUILD_FROM_SPECS=ON" to the "cmake" invocation.

Note that building with CMake currently doesn't support testing.

Building (Autotools)

On unix you can also use autotools to build:

./autogen.sh
make
make check [optional]
sudo make install

Dependencies for debian:

• automake
• libegl1-mesa-dev
• xutils-dev

Dependencies for OS X (macports):

• automake
• autoconf
• xorg-util-macros
• pkgconfig

The test suite has additional dependencies depending on the platform. (X11, EGL, a running X Server).

Building (NMAKE)

With MSVC you can also build directly with NMAKE:

1. Check src\Makefile.vc to ensure that PYTHONDIR is pointing to your Python installation, either a 32-bit or a 64-bit (x64) installation of Python 2 or 3 will do.
2. Copy "include\epoxy\config.h.guess" to "include\epoxy\config.h".
3. Open an MSVC Command prompt and run "nmake Makefile.vc CFG=release" or "nmake Makefile.vc CFG=debug" in src\ for a release or debug build.
4. Optionally, add src\ into your PATH and run the previous step in test. Run the tests by running the built .exe's.
5. Assuming you want to install in %INSTALL_DIR%, copy common.h, config.h, khrplatform.h, eglplatform.h, gl.h, gl_generated.h, wgl.h, wgl_generated.h, egl.h and egl_generated.h from include\epoxy\ to %INSTALL_DIR%\include\epoxy, copy src\epoxy.lib to %INSTALL_DIR%\lib\ and copy epoxy-vs12.dll and epoxy-vs12.pdb (if you've built a debug build) from src\ to %INSTALL_DIR%\bin. Create directories as needed.
6. To clean the project, repeat steps 2 and 3, adding " clean" to the commands.

Switching your code to using epoxy

It should be as easy as replacing:

#include <GL/gl.h>
#include <GL/glx.h>
#include <GL/glext.h>
#include <EGL/egl.h>
#include <EGL/eglext.h>
#include <Windows.h> // for WGL

with:

#include <epoxy/gl.h>
#include <epoxy/glx.h>
#include <epoxy/egl.h>
#include <epoxy/wgl.h>

As long as epoxy's headers appear first, you should be ready to go. Additionally, some new helpers become available, so you don't have to write them:

int epoxy_gl_version() returns the GL version:

• 12 for GL 1.2
• 20 for GL 2.0
• 44 for GL 4.4

bool epoxy_has_gl_extension() returns whether a GL extension is available (GL_ARB_texture_buffer_object, for example).

Note that this is not terribly fast, so keep it out of your hot paths, ok?

Why not use libGLEW?

GLEW has several issues:

• Doesn't know about aliases of functions (There are 5 providers of glPointParameterfv, for example, and you don't want to have to choose which one to call when they're all the same).
• Doesn't support Desktop OpenGL 3.2+ core contexts.
• Doesn't support OpenGL ES.
• Doesn't support EGL.
• Has a hard-to-maintain parser of extension specification text instead of using the old .spec file or the new .xml.
• Has significant startup time overhead when glewInit() autodetects the world.

The motivation for this project came out of previous use of libGLEW in piglit. Other GL dispatch code generation projects had similar failures. Ideally, piglit wants to be able to build a single binary for a test that can run on whatever context or window system it chooses, not based on link time choices.

We had to solve some of GLEW's problems for piglit and solving them meant replacing every single piece of GLEW, so we built piglit-dispatch from scratch. And since we wanted to reuse it in other GL-related projects, this is the result.

win32 issues

The automatic per-context symbol resolution for win32 requires that epoxy knows when wglMakeCurrent() is called, because wglGetProcAddress() return values depend on the context's device and pixel format. If wglMakeCurrent() is called from outside of epoxy (in a way that might change the device or pixel format), then epoxy needs to be notified of the change using the epoxy_handle_external_wglMakeCurrent() function.

The win32 wglMakeCurrent() variants are slower than they should be, because they should be caching the resolved dispatch tables instead of resetting an entire thread-local dispatch table every time.