You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
128 lines
3.8 KiB
128 lines
3.8 KiB
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 GL functions are used.
|
|
* GL 4.4 core and compatibility context support.
|
|
* GLES 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 GL 1.5+ implementations.
|
|
* EGL, GLX, and WGL support.
|
|
* Can be mixed with non-epoxy GL usage.
|
|
|
|
Building
|
|
--------
|
|
|
|
./autogen.sh
|
|
make
|
|
sudo make install
|
|
|
|
Dependencies for debian:
|
|
|
|
* automake
|
|
* libegl1-mesa-dev
|
|
* xutils-dev
|
|
|
|
Dependencies for OS X (macports):
|
|
|
|
* automake
|
|
* autoconf
|
|
* xorg-util-macros
|
|
* pkgconfig
|
|
* xorg-libX11
|
|
|
|
Other dependencies for OS X:
|
|
|
|
* [XQuartz](http://xquartz.macosforge.org/landing/)
|
|
|
|
The test suite has additional dependencies depending on the platform.
|
|
(X11, EGL, a running X Server).
|
|
|
|
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>
|
|
|
|
with:
|
|
|
|
#include <epoxy/gl.h>
|
|
#include <epoxy/glx.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 GL 3.2+ core contexts
|
|
* Doesn't support GLES.
|
|
* 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.
|
|
* User-visible multithreading support choice for win32.
|
|
|
|
The motivation for this project came out of previous use of libGLEW in
|
|
[piglit](http://piglit.freedesktop.org/). 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.
|
|
|
|
Caveats
|
|
-------
|
|
|
|
* libepoxy isn't intended to be dlopen()ed. On ifunc platforms,
|
|
RTLD_NOW would cause early resolution of all GL symbols, and the
|
|
following error from reentering the linker:
|
|
|
|
```
|
|
Inconsistency detected by ld.so: dl-open.c: 235: dl_open_worker:
|
|
Assertion `_dl_debug_initialize (0, args->nsid)->r_state ==
|
|
RT_CONSISTENT' failed!
|
|
```
|
|
|
|
* libepoxy isn't intended to be built statically. It usess ifuncs on
|
|
linux, since it can avoid its dispatch table entirely in that case.
|
|
Building statically disables ifuncs, dropping you to a
|
|
higher-overhead path!
|
|
|