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.
154 lines
5.6 KiB
154 lines
5.6 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 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](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 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.
|
|
|