Mesa (master): docs/egl: add some more documentation

[GitLab Mirror]

Module: Mesa
Branch: master
Commit: ab2e59750f28b5e861f9a2a114ea28f5bc3f9975
URL:    http://cgit.freedesktop.org/mesa/mesa/commit/?id=ab2e59750f28b5e861f9a2a114ea28f5bc3f9975

Author: Eric Engestrom <eric at engestrom.ch>
Date:   Fri Jul 31 00:47:13 2020 +0200

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 at engestrom.ch>
Reviewed-by: Frank Binns <frank.binns at imgtec.com>
Reviewed-by: Emil Velikov <emil.velikov at collabora.com>
Part-of: <https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/6130>

---

 docs/egl.rst            | 40 ++++++++++++++++++++++++++++
 src/egl/main/README.txt | 69 -------------------------------------------------
 2 files changed, 40 insertions(+), 69 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
 -----------
 
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.
-