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