third_party/libepoxy/libepoxy/README.md

   1 ![Ubuntu](https://github.com/anholt/libepoxy/workflows/Ubuntu/badge.svg)
   2 ![macOS](https://github.com/anholt/libepoxy/workflows/macOS/badge.svg)
   3 ![MSVC Build](https://github.com/anholt/libepoxy/workflows/MSVC%20Build/badge.svg)
   4 ![MSYS2 Build](https://github.com/anholt/libepoxy/workflows/MSYS2%20Build/badge.svg)
   5 [![License: MIT](https://img.shields.io/badge/license-MIT-brightgreen.svg)](https://opensource.org/licenses/MIT)
   6
   7 Epoxy is a library for handling OpenGL function pointer management for
   8 you.
   9
  10 It hides the complexity of `dlopen()`, `dlsym()`, `glXGetProcAddress()`,
  11 `eglGetProcAddress()`, etc. from the app developer, with very little
  12 knowledge needed on their part.  They get to read GL specs and write
  13 code using undecorated function names like `glCompileShader()`.
  14
  15 Don't forget to check for your extensions or versions being present
  16 before you use them, just like before!  We'll tell you what you forgot
  17 to check for instead of just segfaulting, though.
  18
  19 Features
  20 --------
  21
  22   * Automatically initializes as new GL functions are used.
  23   * GL 4.6 core and compatibility context support.
  24   * GLES 1/2/3 context support.
  25   * Knows about function aliases so (e.g.) `glBufferData()` can be
  26     used with `GL_ARB_vertex_buffer_object` implementations, along
  27     with GL 1.5+ implementations.
  28   * EGL, GLX, and WGL support.
  29   * Can be mixed with non-epoxy GL usage.
  30
  31 Building
  32 --------
  33
  34 ```sh
  35 mkdir _build && cd _build
  36 meson
  37 ninja
  38 sudo ninja install
  39 ```
  40
  41 Dependencies for Debian:
  42
  43   * meson
  44   * libegl1-mesa-dev
  45
  46 Dependencies for macOS (using MacPorts):
  47
  48   * pkgconfig
  49   * meson
  50
  51 The test suite has additional dependencies depending on the platform.
  52 (X11, EGL, a running X Server).
  53
  54 Switching your code to using epoxy
  55 ----------------------------------
  56
  57 It should be as easy as replacing:
  58
  59 ```cpp
  60 #include <GL/gl.h>
  61 #include <GL/glx.h>
  62 #include <GL/glext.h>
  63 ```
  64
  65 with:
  66
  67 ```cpp
  68 #include <epoxy/gl.h>
  69 #include <epoxy/glx.h>
  70 ```
  71
  72 As long as epoxy's headers appear first, you should be ready to go.
  73 Additionally, some new helpers become available, so you don't have to
  74 write them:
  75
  76 `int epoxy_gl_version()` returns the GL version:
  77
  78   * 12 for GL 1.2
  79   * 20 for GL 2.0
  80   * 44 for GL 4.4
  81
  82 `bool epoxy_has_gl_extension()` returns whether a GL extension is
  83 available (`GL_ARB_texture_buffer_object`, for example).
  84
  85 Note that this is not terribly fast, so keep it out of your hot paths,
  86 ok?
  87
  88 Why not use libGLEW?
  89 --------------------
  90
  91 GLEW has several issues:
  92
  93   * Doesn't know about aliases of functions (There are 5 providers of
  94     `glPointParameterfv()`, for example, and you don't want to have to
  95     choose which one to call when they're all the same).
  96   * Doesn't support OpenGL ES.
  97   * Has a hard-to-maintain parser of extension specification text
  98     instead of using the old .spec file or the new .xml.
  99   * Has significant startup time overhead when `glewInit()`
 100     autodetects the world.
 101   * User-visible multithreading support choice for win32.
 102
 103 The motivation for this project came out of previous use of libGLEW in
 104 [piglit](http://piglit.freedesktop.org/).  Other GL dispatch code
 105 generation projects had similar failures.  Ideally, piglit wants to be
 106 able to build a single binary for a test that can run on whatever
 107 context or window system it chooses, not based on link time choices.
 108
 109 We had to solve some of GLEW's problems for piglit and solving them
 110 meant replacing every single piece of GLEW, so we built
 111 piglit-dispatch from scratch.  And since we wanted to reuse it in
 112 other GL-related projects, this is the result.
 113
 114 Known issues when running on Windows
 115 ------------------------------------
 116
 117 The automatic per-context symbol resolution for win32 requires that
 118 epoxy knows when `wglMakeCurrent()` is called, because `wglGetProcAddress()`
 119 returns values depend on the context's device and pixel format.  If
 120 `wglMakeCurrent()` is called from outside of epoxy (in a way that might
 121 change the device or pixel format), then epoxy needs to be notified of
 122 the change using the `epoxy_handle_external_wglMakeCurrent()` function.
 123
 124 The win32 `wglMakeCurrent()` variants are slower than they should be,
 125 because they should be caching the resolved dispatch tables instead of
 126 resetting an entire thread-local dispatch table every time.