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