summaryrefslogtreecommitdiff
path: root/dist/libepoxy/README.md
diff options
context:
space:
mode:
authorMatthieu Herrb <matthieu@cvs.openbsd.org>2018-05-25 06:25:01 +0000
committerMatthieu Herrb <matthieu@cvs.openbsd.org>2018-05-25 06:25:01 +0000
commit220887c311639cef803ccd488763c95df7257e6c (patch)
tree531774d0c2b7b00be6a8ea5a47c6e734538fc198 /dist/libepoxy/README.md
parent16ed5aea860709587587c30a24f18039f2074831 (diff)
Update to libepoxy 1.5.2. ok aja@
Diffstat (limited to 'dist/libepoxy/README.md')
-rw-r--r--dist/libepoxy/README.md122
1 files changed, 60 insertions, 62 deletions
diff --git a/dist/libepoxy/README.md b/dist/libepoxy/README.md
index 5d1053981..56b6a65e3 100644
--- a/dist/libepoxy/README.md
+++ b/dist/libepoxy/README.md
@@ -1,11 +1,13 @@
+[![Build Status](https://travis-ci.org/anholt/libepoxy.svg?branch=master)](https://travis-ci.org/anholt/libepoxy)
+[![Build status](https://ci.appveyor.com/api/projects/status/xv6y5jurt5v5ngjx/branch/master?svg=true)](https://ci.appveyor.com/project/ebassi/libepoxy/branch/master)
+
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()```.
+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
@@ -14,39 +16,34 @@ 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.
+ * Automatically initializes as new GL functions are used.
+ * GL 4.6 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:
+```sh
+mkdir _build && cd _build
+meson
+ninja
+sudo ninja install
+```
-* automake
-* libegl1-mesa-dev
-* xutils-dev
+Dependencies for Debian:
-Dependencies for OS X (macports):
+ * meson
+ * libegl1-mesa-dev
-* automake
-* autoconf
-* xorg-util-macros
-* pkgconfig
-* xorg-libX11
+Dependencies for macOS (using MacPorts):
-Other dependencies for OS X:
-
-* [XQuartz](http://xquartz.macosforge.org/landing/)
+ * pkgconfig
+ * meson
The test suite has additional dependencies depending on the platform.
(X11, EGL, a running X Server).
@@ -56,27 +53,31 @@ 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>
+```cpp
+#include <GL/gl.h>
+#include <GL/glx.h>
+#include <GL/glext.h>
+```
with:
- #include <epoxy/gl.h>
- #include <epoxy/glx.h>
+```cpp
+#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:
+`int epoxy_gl_version()` returns the GL version:
-* 12 for GL 1.2
-* 20 for GL 2.0
-* 44 for GL 4.4
+ * 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).
+`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?
@@ -86,17 +87,15 @@ 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.
+ * 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 OpenGL ES.
+ * 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
@@ -109,17 +108,16 @@ 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
-------------
+Known issues when running on Windows
+------------------------------------
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,
+epoxy knows when `wglMakeCurrent()` is called, because `wglGetProcAddress()`
+returns 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.