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