1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
|
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.
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 dispatch layer is currently slower than it should be in the
single-context (or multi-context, but same device and pixel format)
case. We need to switch to using the linux-like function pointer
stubs, and detect when transitioning to multi-device/format and hook
in the per-thread dispatch table at that point.
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.
|
