xref: /aosp_15_r20/external/mesa3d/docs/egl.rst (revision 6104692788411f58d303aa86923a9ff6ecaded22)
1EGL
2===
3
4The current version of EGL in Mesa implements EGL 1.5. More information
5about EGL can be found at https://www.khronos.org/egl/.
6
7The Mesa's implementation of EGL uses a driver architecture. The main
8library (``libEGL``) is window system neutral. It provides the EGL API
9entry points and helper functions for use by the drivers. Drivers are
10dynamically loaded by the main library and most of the EGL API calls are
11directly dispatched to the drivers.
12
13The driver in use decides the window system to support.
14
15Build EGL
16---------
17
18#. Configure your build with the desired client APIs and enable the
19   driver for your hardware. For example:
20
21   .. code-block:: sh
22
23      $ meson configure \
24              -D egl=enabled \
25              -D gles1=enabled \
26              -D gles2=enabled \
27              -D gallium-drivers=...
28
29   The main EGL library and OpenGL are enabled by default. The two
30   ``gles*`` options after enable :doc:`OpenGL ES 1.x and 2.x+
31   <opengles>`. The last option enables the listed Gallium drivers.
32
33#. Build and install Mesa as usual.
34
35In the given example, it will build and install ``libEGL``, ``libGL``,
36``libGLESv1_CM``, ``libGLESv2``, and one or more EGL drivers.
37
38Configure Options
39~~~~~~~~~~~~~~~~~
40
41There are several options that control the build of EGL at configuration
42time
43
44``-D egl=enabled``
45   By default, EGL is enabled. When disabled, the main library and the
46   drivers will not be built.
47
48``-D platforms=...``
49   List the platforms (window systems) to support. Its argument is a
50   comma separated string such as ``-D platforms=x11,wayland``. It decides
51   the platforms a driver may support. The first listed platform is also
52   used by the main library to decide the native platform.
53
54   The available platforms are ``x11``, ``wayland``,
55   ``android``, and ``haiku``. The ``android`` platform
56   can either be built as a system component, part of AOSP, using
57   ``Android.mk`` files, or cross-compiled using appropriate options.
58   Unless for special needs, the build system should select the right
59   platforms automatically.
60
61``-D gles1=enabled`` and ``-D gles2=enabled``
62   These options enable OpenGL ES support in OpenGL. The result is one
63   big internal library that supports multiple APIs.
64
65``-D shared-glapi=enabled``
66   By default, ``libGL`` has its own copy of ``libglapi``. This options
67   makes ``libGL`` use the shared ``libglapi``. This is required if
68   applications mix OpenGL and OpenGL ES.
69
70Use EGL
71-------
72
73Demos
74~~~~~
75
76There are demos for the client APIs supported by EGL. They can be found
77in mesa/demos repository.
78
79Environment Variables
80~~~~~~~~~~~~~~~~~~~~~
81
82There are several environment variables that control the behavior of EGL
83at runtime
84
85``EGL_PLATFORM``
86   This variable specifies the native platform. The valid values are the
87   same as those for ``-D platforms=...``. When the variable is not set,
88   the main library uses the first platform listed in
89   ``-D platforms=...`` as the native platform.
90
91``EGL_LOG_LEVEL``
92   This changes the log level of the main library and the drivers. The
93   valid values are: ``debug``, ``info``, ``warning``, and ``fatal``.
94
95Packaging
96---------
97
98The ABI between the main library and its drivers are not stable. Nor is
99there a plan to stabilize it at the moment.
100
101Developers
102----------
103
104The sources of the main library and drivers can be found at
105``src/egl/``.
106
107The code basically consists of two things:
108
1091. An EGL API dispatcher. This directly routes all the ``eglFooBar()``
110   API calls into driver-specific functions.
111
1122. Two EGL drivers (``dri2`` and ``haiku``), implementing the API
113   functions handling the platforms' specifics.
114
115Two of API functions are optional (``eglQuerySurface()`` and
116``eglSwapInterval()``); the former provides fallback for all the
117platform-agnostic attributes (i.e. everything except ``EGL_WIDTH``
118& ``EGL_HEIGHT``), and the latter just silently pretends the API call
119succeeded (as per EGL spec).
120
121A driver _could_ implement all the other EGL API functions, but several of
122them are only needed for extensions, like ``eglSwapBuffersWithDamageEXT()``.
123See ``src/egl/main/egldriver.h`` to see which driver hooks are only
124required by extensions.
125
126Bootstrapping
127~~~~~~~~~~~~~
128
129When the apps calls ``eglInitialize()``, the driver's ``Initialize()``
130function is called. If the first driver initialization attempt fails,
131a second one is tried using only software components (this can be forced
132using the ``LIBGL_ALWAYS_SOFTWARE`` environment variable). Typically,
133this function takes care of setting up visual configs, creating EGL
134devices, etc.
135
136Teardown
137~~~~~~~~
138
139When ``eglTerminate()`` is called, the ``driver->Terminate()`` function
140is called. The driver should clean up after itself.
141
142Subclassing
143~~~~~~~~~~~
144
145The internal libEGL data structures such as ``_EGLDisplay``,
146``_EGLContext``, ``_EGLSurface``, etc. should be considered base classes
147from which drivers will derive subclasses.
148
149EGL Drivers
150-----------
151
152``egl_dri2``
153   This driver supports several platforms: ``android``, ``device``,
154   ``drm``, ``surfaceless``, ``wayland`` and ``x11``. It functions as
155   a DRI driver loader. For ``x11`` support, it talks to the X server
156   directly using (XCB-)DRI3 protocol when available, and falls back to
157   DRI2 if necessary (can be forced with ``LIBGL_DRI3_DISABLE``).
158
159   This driver can share DRI drivers with ``libGL``.
160
161``haiku``
162   This driver supports only the `Haiku <https://www.haiku-os.org/>`__
163   platform. It is also much less feature-complete than ``egl_dri2``,
164   supporting only part of EGL 1.4 and none of the extensions beyond it.
165
166Lifetime of Display Resources
167~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
168
169Contexts and surfaces are examples of display resources. They might live
170longer than the display that creates them.
171
172In EGL, when a display is terminated through ``eglTerminate``, all
173display resources should be destroyed. Similarly, when a thread is
174released through ``eglReleaseThread``, all current display resources
175should be released. Another way to destroy or release resources is
176through functions such as ``eglDestroySurface`` or ``eglMakeCurrent``.
177
178When a resource that is current to some thread is destroyed, the
179resource should not be destroyed immediately. EGL requires the resource
180to live until it is no longer current. A driver usually calls
181``eglIs<Resource>Bound`` to check if a resource is bound (current) to
182any thread in the destroy callbacks. If it is still bound, the resource
183is not destroyed.
184
185The main library will mark destroyed current resources as unlinked. In a
186driver's ``MakeCurrent`` callback, ``eglIs<Resource>Linked`` can then be
187called to check if a newly released resource is linked to a display. If
188it is not, the last reference to the resource is removed and the driver
189should destroy the resource. But it should be careful here because
190``MakeCurrent`` might be called with an uninitialized display.
191
192This is the only mechanism provided by the main library to help manage
193the resources. The drivers are responsible to the correct behavior as
194defined by EGL.
195
196``EGL_RENDER_BUFFER``
197~~~~~~~~~~~~~~~~~~~~~
198
199In EGL, the color buffer a context should try to render to is decided by
200the binding surface. It should try to render to the front buffer if the
201binding surface has ``EGL_RENDER_BUFFER`` set to ``EGL_SINGLE_BUFFER``;
202If the same context is later bound to a surface with
203``EGL_RENDER_BUFFER`` set to ``EGL_BACK_BUFFER``, the context should try
204to render to the back buffer. However, the context is allowed to make
205the final decision as to which color buffer it wants to or is able to
206render to.
207
208For pbuffer surfaces, the render buffer is always ``EGL_BACK_BUFFER``.
209And for pixmap surfaces, the render buffer is always
210``EGL_SINGLE_BUFFER``. Unlike window surfaces, EGL spec requires their
211``EGL_RENDER_BUFFER`` values to be honored. As a result, a driver should
212never set ``EGL_PIXMAP_BIT`` or ``EGL_PBUFFER_BIT`` bits of a config if
213the contexts created with the config won't be able to honor the
214``EGL_RENDER_BUFFER`` of pixmap or pbuffer surfaces.
215
216It should also be noted that pixmap and pbuffer surfaces are assumed to
217be single-buffered, in that ``eglSwapBuffers`` has no effect on them. It
218is desirable that a driver allocates a private color buffer for each
219pbuffer surface created. If the window system the driver supports has
220native pbuffers, or if the native pixmaps have more than one color
221buffers, the driver should carefully attach the native color buffers to
222the EGL surfaces, re-route them if required.
223
224There is no defined behavior as to, for example, how ``glDrawBuffer``
225interacts with ``EGL_RENDER_BUFFER``. Right now, it is desired that the
226draw buffer in a client API be fixed for pixmap and pbuffer surfaces.
227Therefore, the driver is responsible to guarantee that the client API
228renders to the specified render buffer for pixmap and pbuffer surfaces.
229
230``EGLDisplay`` Mutex
231~~~~~~~~~~~~~~~~~~~~
232
233The ``EGLDisplay`` will be locked before calling any of the dispatch
234functions (well, except for GetProcAddress which does not take an
235``EGLDisplay``). This guarantees that the same dispatch function will
236not be called with the same display at the same time. If a driver has
237access to an ``EGLDisplay`` without going through the EGL APIs, the
238driver should as well lock the display before using it.
239