diff options
author | Eric Engestrom <eric@engestrom.ch> | 2020-07-31 00:47:13 +0200 |
---|---|---|
committer | Eric Engestrom <eric@engestrom.ch> | 2020-08-27 23:06:28 +0200 |
commit | ab2e59750f28b5e861f9a2a114ea28f5bc3f9975 (patch) | |
tree | 0483dc092bc095fee049f7438c380aea5c6afe54 /docs | |
parent | 7897c315d4f4978257a59271ce156d07ed678566 (diff) |
docs/egl: add some more documentation
Inspired by `src/egl/main/README.txt`, which was severely outdated, but
still contained valid information.
Signed-off-by: Eric Engestrom <eric@engestrom.ch>
Reviewed-by: Frank Binns <frank.binns@imgtec.com>
Reviewed-by: Emil Velikov <emil.velikov@collabora.com>
Part-of: <https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/6130>
Diffstat (limited to 'docs')
-rw-r--r-- | docs/egl.rst | 40 |
1 files changed, 40 insertions, 0 deletions
diff --git a/docs/egl.rst b/docs/egl.rst index 2959dede86f..2268098fb5f 100644 --- a/docs/egl.rst +++ b/docs/egl.rst @@ -112,6 +112,46 @@ Developers The sources of the main library and drivers can be found at ``src/egl/``. +The code basically consists of two things: + +1. An EGL API dispatcher. This directly routes all the ``eglFooBar()`` + API calls into driver-specific functions. + +2. Two EGL drivers (``dri2`` and ``haiku``), implementing the API + functions handling the platforms' specifics. + +Two of API functions are optional (``eglQuerySurface()`` and +``eglSwapInterval()``); the former provides fallback for all the +platform-agnostic attributes (ie. everything except ``EGL_WIDTH`` +& ``EGL_HEIGHT``), and the latter just silently pretends the API call +succeeded (as per EGL spec). + +A driver _could_ implement all the other EGL API functions, but several of +them are only needed for extensions, like ``eglSwapBuffersWithDamageEXT()``. + +Bootstrapping +~~~~~~~~~~~~~ + +When the apps calls ``eglInitialize()``, the driver's ``Initialize()`` +function is called. If the first driver initialisation attempt fails, +a second one is tried using only software components (this can be forced +using the ``LIBGL_ALWAYS_SOFTWARE`` environment variable). Typically, +this function takes care of setting up visual configs, creating EGL +devices, etc. + +Teardown +~~~~~~~~ + +When ``eglTerminate()`` is called, the ``driver->Terminate()`` function +is called. The driver should clean up after itself. + +Subclassing +~~~~~~~~~~~ + +The internal libEGL data structures such as ``_EGLDisplay``, +``_EGLContext``, ``_EGLSurface``, etc. should be considered base classes +from which drivers will derive subclasses. + EGL Drivers ----------- |