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 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. 98 99``EGL_LOG_LEVEL`` 100 This changes the log level of the main library and the drivers. The 101 valid values are: ``debug``, ``info``, ``warning``, and ``fatal``. 102 103Packaging 104--------- 105 106The ABI between the main library and its drivers are not stable. Nor is 107there a plan to stabilize it at the moment. 108 109Developers 110---------- 111 112The sources of the main library and drivers can be found at 113``src/egl/``. 114 115The code basically consists of two things: 116 1171. An EGL API dispatcher. This directly routes all the ``eglFooBar()`` 118 API calls into driver-specific functions. 119 1202. Two EGL drivers (``dri2`` and ``haiku``), implementing the API 121 functions handling the platforms' specifics. 122 123Two of API functions are optional (``eglQuerySurface()`` and 124``eglSwapInterval()``); the former provides fallback for all the 125platform-agnostic attributes (i.e. everything except ``EGL_WIDTH`` 126& ``EGL_HEIGHT``), and the latter just silently pretends the API call 127succeeded (as per EGL spec). 128 129A driver _could_ implement all the other EGL API functions, but several of 130them are only needed for extensions, like ``eglSwapBuffersWithDamageEXT()``. 131See ``src/egl/main/egldriver.h`` to see which driver hooks are only 132required by extensions. 133 134Bootstrapping 135~~~~~~~~~~~~~ 136 137When the apps calls ``eglInitialize()``, the driver's ``Initialize()`` 138function is called. If the first driver initialization attempt fails, 139a second one is tried using only software components (this can be forced 140using the ``LIBGL_ALWAYS_SOFTWARE`` environment variable). Typically, 141this function takes care of setting up visual configs, creating EGL 142devices, etc. 143 144Teardown 145~~~~~~~~ 146 147When ``eglTerminate()`` is called, the ``driver->Terminate()`` function 148is called. The driver should clean up after itself. 149 150Subclassing 151~~~~~~~~~~~ 152 153The internal libEGL data structures such as ``_EGLDisplay``, 154``_EGLContext``, ``_EGLSurface``, etc. should be considered base classes 155from which drivers will derive subclasses. 156 157EGL Drivers 158----------- 159 160``egl_dri2`` 161 This driver supports several platforms: ``android``, ``device``, 162 ``drm``, ``surfaceless``, ``wayland`` and ``x11``. It functions as 163 a DRI driver loader. For ``x11`` support, it talks to the X server 164 directly using (XCB-)DRI3 protocol when available, and falls back to 165 DRI2 if necessary (can be forced with ``LIBGL_DRI3_DISABLE``). 166 167 This driver can share DRI drivers with ``libGL``. 168 169``haiku`` 170 This driver supports only the `Haiku <https://haiku-os.org>`__ 171 platform. It is also much less feature-complete than ``egl_dri2``, 172 supporting only part of EGL 1.4 and none of the extensions beyond it. 173 174Lifetime of Display Resources 175~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 176 177Contexts and surfaces are examples of display resources. They might live 178longer than the display that creates them. 179 180In EGL, when a display is terminated through ``eglTerminate``, all 181display resources should be destroyed. Similarly, when a thread is 182released through ``eglReleaseThread``, all current display resources 183should be released. Another way to destroy or release resources is 184through functions such as ``eglDestroySurface`` or ``eglMakeCurrent``. 185 186When a resource that is current to some thread is destroyed, the 187resource should not be destroyed immediately. EGL requires the resource 188to live until it is no longer current. A driver usually calls 189``eglIs<Resource>Bound`` to check if a resource is bound (current) to 190any thread in the destroy callbacks. If it is still bound, the resource 191is not destroyed. 192 193The main library will mark destroyed current resources as unlinked. In a 194driver's ``MakeCurrent`` callback, ``eglIs<Resource>Linked`` can then be 195called to check if a newly released resource is linked to a display. If 196it is not, the last reference to the resource is removed and the driver 197should destroy the resource. But it should be careful here because 198``MakeCurrent`` might be called with an uninitialized display. 199 200This is the only mechanism provided by the main library to help manage 201the resources. The drivers are responsible to the correct behavior as 202defined by EGL. 203 204``EGL_RENDER_BUFFER`` 205~~~~~~~~~~~~~~~~~~~~~ 206 207In EGL, the color buffer a context should try to render to is decided by 208the binding surface. It should try to render to the front buffer if the 209binding surface has ``EGL_RENDER_BUFFER`` set to ``EGL_SINGLE_BUFFER``; 210If the same context is later bound to a surface with 211``EGL_RENDER_BUFFER`` set to ``EGL_BACK_BUFFER``, the context should try 212to render to the back buffer. However, the context is allowed to make 213the final decision as to which color buffer it wants to or is able to 214render to. 215 216For pbuffer surfaces, the render buffer is always ``EGL_BACK_BUFFER``. 217And for pixmap surfaces, the render buffer is always 218``EGL_SINGLE_BUFFER``. Unlike window surfaces, EGL spec requires their 219``EGL_RENDER_BUFFER`` values to be honored. As a result, a driver should 220never set ``EGL_PIXMAP_BIT`` or ``EGL_PBUFFER_BIT`` bits of a config if 221the contexts created with the config won't be able to honor the 222``EGL_RENDER_BUFFER`` of pixmap or pbuffer surfaces. 223 224It should also be noted that pixmap and pbuffer surfaces are assumed to 225be single-buffered, in that ``eglSwapBuffers`` has no effect on them. It 226is desirable that a driver allocates a private color buffer for each 227pbuffer surface created. If the window system the driver supports has 228native pbuffers, or if the native pixmaps have more than one color 229buffers, the driver should carefully attach the native color buffers to 230the EGL surfaces, re-route them if required. 231 232There is no defined behavior as to, for example, how ``glDrawBuffer`` 233interacts with ``EGL_RENDER_BUFFER``. Right now, it is desired that the 234draw buffer in a client API be fixed for pixmap and pbuffer surfaces. 235Therefore, the driver is responsible to guarantee that the client API 236renders to the specified render buffer for pixmap and pbuffer surfaces. 237 238``EGLDisplay`` Mutex 239~~~~~~~~~~~~~~~~~~~~ 240 241The ``EGLDisplay`` will be locked before calling any of the dispatch 242functions (well, except for GetProcAddress which does not take an 243``EGLDisplay``). This guarantees that the same dispatch function will 244not be called with the same display at the same time. If a driver has 245access to an ``EGLDisplay`` without going through the EGL APIs, the 246driver should as well lock the display before using it. 247