From ab2e59750f28b5e861f9a2a114ea28f5bc3f9975 Mon Sep 17 00:00:00 2001 From: Eric Engestrom Date: Fri, 31 Jul 2020 00:47:13 +0200 Subject: [PATCH] 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 Reviewed-by: Frank Binns Reviewed-by: Emil Velikov Part-of: --- docs/egl.rst | 40 ++++++++++++++++++++++++ src/egl/main/README.txt | 69 ----------------------------------------- 2 files changed, 40 insertions(+), 69 deletions(-) delete mode 100644 src/egl/main/README.txt 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 ----------- diff --git a/src/egl/main/README.txt b/src/egl/main/README.txt deleted file mode 100644 index 3e236500215..00000000000 --- a/src/egl/main/README.txt +++ /dev/null @@ -1,69 +0,0 @@ - - -Notes about the EGL library: - - -The EGL code here basically consists of two things: - -1. An EGL API dispatcher. This directly routes all the eglFooBar() API - calls into driver-specific functions. - -2. Fallbacks for EGL API functions. A driver _could_ implement all the - EGL API calls from scratch. But in many cases, the fallbacks provided - in libEGL (such as eglChooseConfig()) will do the job. - - - -Bootstrapping: - -When the apps calls eglInitialize() a device driver is selected and loaded -(look for _eglAddDrivers() and _eglLoadModule() in egldriver.c). - -The built-in driver's entry point function is then called and given -a freshly allocated and initialised _EGLDriver, with default fallback -entrypoints set. - -As part of initialization, the dispatch table in _EGLDriver->API must be -populated with all the EGL entrypoints. Some functions like -driver->Initialize and driver->Terminate _must_ be implemented -with driver-specific code (no default/fallback function is possible). - - -Shortly after, the driver->Initialize() function is executed. Any additional -driver initialization that wasn't done in the driver entry point should be -done at this point. Typically, this will involve setting up visual configs, etc. - - - -Special Functions: - -Certain EGL functions _must_ be implemented by the driver. This includes: - -eglCreateContext -eglCreateWindowSurface -eglCreatePixmapSurface -eglCreatePBufferSurface -eglMakeCurrent -eglSwapBuffers - -Most of the EGLConfig-related functions can be implemented with the -defaults/fallbacks. Same thing for the eglGet/Query functions. - - - - -Teardown: - -When eglTerminate() is called, the driver->Terminate() function is -called. The driver should clean up after itself. eglTerminate() will -then close/unload the driver (shared library). - - - - -Subclassing: - -The internal libEGL data structures such as _EGLDisplay, _EGLContext, -_EGLSurface, etc should be considered base classes from which drivers -will derive subclasses. - -- 2.30.2