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