diff options
| -rw-r--r-- | include/epoxy/egl.h | 2 | ||||
| -rw-r--r-- | include/epoxy/gl.h | 2 | ||||
| -rw-r--r-- | include/epoxy/glx.h | 2 | ||||
| -rw-r--r-- | src/dispatch_common.c | 118 | ||||
| -rw-r--r-- | src/dispatch_egl.c | 30 | ||||
| -rw-r--r-- | src/dispatch_glx.c | 33 |
6 files changed, 175 insertions, 12 deletions
diff --git a/include/epoxy/egl.h b/include/epoxy/egl.h index 67b22ce..2550acc 100644 --- a/include/epoxy/egl.h +++ b/include/epoxy/egl.h @@ -25,6 +25,8 @@ * * Provides an implementation of an EGL dispatch layer using global * function pointers + * + * You should include `<epoxy/egl.h>` instead of `<EGL/egl.h>`. */ #ifndef EPOXY_EGL_H diff --git a/include/epoxy/gl.h b/include/epoxy/gl.h index c3a7437..078ecee 100644 --- a/include/epoxy/gl.h +++ b/include/epoxy/gl.h @@ -25,6 +25,8 @@ * * Provides an implementation of a GL dispatch layer using either * global function pointers or a hidden vtable. + * + * You should include `<epoxy/gl.h>` instead of `<GL/gl.h>` and `<GL/glext.h>`. */ #ifndef EPOXY_GL_H diff --git a/include/epoxy/glx.h b/include/epoxy/glx.h index f5214f1..c911b7c 100644 --- a/include/epoxy/glx.h +++ b/include/epoxy/glx.h @@ -25,6 +25,8 @@ * * Provides an implementation of a GLX dispatch layer using global * function pointers. + * + * You should include `<epoxy/glx.h>` instead of `<GL/glx.h>`. */ #ifndef EPOXY_GLX_H diff --git a/src/dispatch_common.c b/src/dispatch_common.c index 374f6d5..17d0c5e 100644 --- a/src/dispatch_common.c +++ b/src/dispatch_common.c @@ -22,9 +22,80 @@ */ /** + * \mainpage Epoxy + * + * \section intro_sec Introduction + * + * 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. + * + * \section features_sec 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. + * + * \section using_sec Using Epoxy + * + * Using Epoxy should be as easy as replacing: + * + * ```cpp + * #include <GL/gl.h> + * #include <GL/glx.h> + * #include <GL/glext.h> + * ``` + * + * with: + * + * ```cpp + * #include <epoxy/gl.h> + * #include <epoxy/glx.h> + * ``` + * + * \subsection using_include_sec Headers + * + * Epoxy comes with the following public headers: + * + * - `epoxy/gl.h` - For GL API + * - `epoxy/egl.h` - For EGL API + * - `epoxy/glx.h` - For GLX API + * - `epoxy/wgl.h` - For WGL API + * + * \section links_sec Additional links + * + * The latest version of the Epoxy code is available on [GitHub](https://github.com/anholt/libepoxy). + * + * For bug reports and enhancements, please use the [Issues](https://github.com/anholt/libepoxy/issues) + * link. + * + * The scope of this API reference does not include the documentation for + * OpenGL and OpenGL ES. For more information on those programming interfaces + * please visit: + * + * - [Khronos](https://www.khronos.org/) + * - [OpenGL page on Khronos.org](https://www.khronos.org/opengl/) + * - [OpenGL ES page on Khronos.org](https://www.khronos.org/opengles/) + * - [docs.GL](http://docs.gl/) + */ + +/** * @file dispatch_common.c * - * Implements common code shared by the generated GL/EGL/GLX dispatch code. + * @brief Implements common code shared by the generated GL/EGL/GLX dispatch code. * * A collection of some important specs on getting GL function pointers. * @@ -146,32 +217,32 @@ struct api { #ifndef _WIN32 - /** + /* * Locking for making sure we don't double-dlopen(). */ pthread_mutex_t mutex; #endif - /** dlopen() return value for libGL.so.1. */ + /* dlopen() return value for libGL.so.1. */ void *glx_handle; - /** + /* * dlopen() return value for OS X's GL library. * * On linux, glx_handle is used instead. */ void *gl_handle; - /** dlopen() return value for libEGL.so.1 */ + /* dlopen() return value for libEGL.so.1 */ void *egl_handle; - /** dlopen() return value for libGLESv1_CM.so.1 */ + /* dlopen() return value for libGLESv1_CM.so.1 */ void *gles1_handle; - /** dlopen() return value for libGLESv2.so.2 */ + /* dlopen() return value for libGLESv2.so.2 */ void *gles2_handle; - /** + /* * This value gets incremented when any thread is in * glBegin()/glEnd() called through epoxy. * @@ -269,6 +340,11 @@ do_dlsym(void **handle, const char *lib_name, const char *name, return result; } +/** + * @brief Checks whether we're using OpenGL or OpenGL ES + * + * @return `true` if we're using OpenGL + */ bool epoxy_is_desktop_gl(void) { @@ -333,6 +409,21 @@ epoxy_internal_gl_version(int error_version) return 10 * major + minor; } +/** + * @brief Returns the version of OpenGL we are using + * + * The version is encoded as: + * + * ``` + * + * version = major * 10 + minor + * + * ``` + * + * So it can be easily used for version comparisons. + * + * @return The encoded version of OpenGL we are using + */ int epoxy_gl_version(void) { @@ -452,12 +543,15 @@ epoxy_current_context_is_glx(void) } /** - * Returns true if the given GL extension is supported in the current context. + * @brief Returns true if the given GL extension is supported in the current context. + * + * @param ext The name of the GL extension + * @return `true` if the extension is available * - * Note that this function can't be called from within glBegin()/glEnd(). + * @note that this function can't be called from within `glBegin()` and `glEnd()`. * - * \sa epoxy_has_egl_extension() - * \sa epoxy_has_glx_extension() + * @see epoxy_has_egl_extension() + * @see epoxy_has_glx_extension() */ bool epoxy_has_gl_extension(const char *ext) diff --git a/src/dispatch_egl.c b/src/dispatch_egl.c index d1dc53c..7f970d9 100644 --- a/src/dispatch_egl.c +++ b/src/dispatch_egl.c @@ -38,6 +38,25 @@ epoxy_conservative_egl_version(void) return epoxy_egl_version(dpy); } +/** + * @brief Returns the version of OpenGL we are using + * + * The version is encoded as: + * + * ``` + * + * version = major * 10 + minor + * + * ``` + * + * So it can be easily used for version comparisons. + * + * @param The EGL display + * + * @return The encoded version of EGL we are using + * + * @see epoxy_gl_version() + */ int epoxy_egl_version(EGLDisplay dpy) { @@ -57,6 +76,17 @@ epoxy_conservative_has_egl_extension(const char *ext) return epoxy_has_egl_extension(eglGetCurrentDisplay(), ext); } +/** + * @brief Returns true if the given EGL extension is supported in the current context. + * + * @param dpy The EGL display + * @param extension The name of the EGL extension + * + * @return `true` if the extension is available + * + * @see epoxy_has_gl_extension() + * @see epoxy_has_glx_extension() + */ bool epoxy_has_egl_extension(EGLDisplay dpy, const char *ext) { diff --git a/src/dispatch_glx.c b/src/dispatch_glx.c index 9396f1c..a74725e 100644 --- a/src/dispatch_glx.c +++ b/src/dispatch_glx.c @@ -47,6 +47,27 @@ epoxy_conservative_glx_version(void) return epoxy_glx_version(dpy, screen); } + +/** + * @brief Returns the version of GLX we are using + * + * The version is encoded as: + * + * ``` + * + * version = major * 10 + minor + * + * ``` + * + * So it can be easily used for version comparisons. + * + * @param dpy The X11 display + * @param screen The X11 screen + * + * @return The encoded version of GLX we are using + * + * @see epoxy_gl_version() + */ int epoxy_glx_version(Display *dpy, int screen) { @@ -98,6 +119,18 @@ epoxy_conservative_has_glx_extension(const char *ext) return epoxy_has_glx_extension(dpy, screen, ext); } +/** + * @brief Returns true if the given GLX extension is supported in the current context. + * + * @param dpy The X11 display + * @param screen The X11 screen + * @param extension The name of the GLX extension + * + * @return `true` if the extension is available + * + * @see epoxy_has_gl_extension() + * @see epoxy_has_egl_extension() + */ bool epoxy_has_glx_extension(Display *dpy, int screen, const char *ext) { |