KonstantinSeurer
/
mesa
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

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>
This commit is contained in:
Eric Engestrom 2020-07-31 00:47:13 +02:00
parent 7897c315d4
commit ab2e59750f
2 changed files with 40 additions and 69 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

40
docs/egl.rst
View File

@ -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
-----------

69
src/egl/main/README.txt
View File

@ -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.