docs/egl.rst

   1 EGL
   2 ===
   3
   4 The current version of EGL in Mesa implements EGL 1.4. More information
   5 about EGL can be found at https://www.khronos.org/egl/.
   6
   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.
  12
  13 The driver in use decides the window system to support.
  14
  15 Build 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=true \
  25               -D gles1=true \
  26               -D gles2=true \
  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
  37 In the given example, it will build and install ``libEGL``, ``libGL``,
  38 ``libGLESv1_CM``, ``libGLESv2``, and one or more EGL drivers.
  39
  40 Configure Options
  41 ~~~~~~~~~~~~~~~~~
  42
  43 There are several options that control the build of EGL at configuration
  44 time
  45
  46 ``-D egl=true``
  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=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.
  66
  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.
  71
  72 Use EGL
  73 -------
  74
  75 Demos
  76 ~~~~~
  77
  78 There are demos for the client APIs supported by EGL. They can be found
  79 in mesa/demos repository.
  80
  81 Environment Variables
  82 ~~~~~~~~~~~~~~~~~~~~~
  83
  84 There are several environment variables that control the behavior of EGL
  85 at 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
 103 Packaging
 104 ---------
 105
 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.
 108
 109 Developers
 110 ----------
 111
 112 The sources of the main library and drivers can be found at
 113 ``src/egl/``.
 114
 115 The code basically consists of two things:
 116
 117 1. An EGL API dispatcher. This directly routes all the ``eglFooBar()``
 118    API calls into driver-specific functions.
 119
 120 2. Two EGL drivers (``dri2`` and ``haiku``), implementing the API
 121    functions handling the platforms' specifics.
 122
 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).
 128
 129 A driver _could_ implement all the other EGL API functions, but several of
 130 them are only needed for extensions, like ``eglSwapBuffersWithDamageEXT()``.
 131
 132 Bootstrapping
 133 ~~~~~~~~~~~~~
 134
 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.
 141
 142 Teardown
 143 ~~~~~~~~
 144
 145 When ``eglTerminate()`` is called, the ``driver->Terminate()`` function
 146 is called. The driver should clean up after itself.
 147
 148 Subclassing
 149 ~~~~~~~~~~~
 150
 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.
 154
 155 EGL Drivers
 156 -----------
 157
 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-)DRI3 protocol when available, and falls back to
 163    DRI2 if necessary (can be forced with ``LIBGL_DRI3_DISABLE``).
 164
 165    This driver can share DRI drivers with ``libGL``.
 166
 167 ``haiku``
 168    This driver supports only the `Haiku <https://haiku-os.org>`__
 169    platform. It is also much less feature-complete than ``egl_dri2``,
 170    supporting only part of EGL 1.4 and none of the extensions beyond it.
 171
 172 Lifetime of Display Resources
 173 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 174
 175 Contexts and surfaces are examples of display resources. They might live
 176 longer than the display that creates them.
 177
 178 In EGL, when a display is terminated through ``eglTerminate``, all
 179 display resources should be destroyed. Similarly, when a thread is
 180 released through ``eglReleaseThread``, all current display resources
 181 should be released. Another way to destroy or release resources is
 182 through functions such as ``eglDestroySurface`` or ``eglMakeCurrent``.
 183
 184 When a resource that is current to some thread is destroyed, the
 185 resource should not be destroyed immediately. EGL requires the resource
 186 to live until it is no longer current. A driver usually calls
 187 ``eglIs<Resource>Bound`` to check if a resource is bound (current) to
 188 any thread in the destroy callbacks. If it is still bound, the resource
 189 is not destroyed.
 190
 191 The main library will mark destroyed current resources as unlinked. In a
 192 driver's ``MakeCurrent`` callback, ``eglIs<Resource>Linked`` can then be
 193 called to check if a newly released resource is linked to a display. If
 194 it is not, the last reference to the resource is removed and the driver
 195 should destroy the resource. But it should be careful here because
 196 ``MakeCurrent`` might be called with an uninitialized display.
 197
 198 This is the only mechanism provided by the main library to help manage
 199 the resources. The drivers are responsible to the correct behavior as
 200 defined by EGL.
 201
 202 ``EGL_RENDER_BUFFER``
 203 ~~~~~~~~~~~~~~~~~~~~~
 204
 205 In EGL, the color buffer a context should try to render to is decided by
 206 the binding surface. It should try to render to the front buffer if the
 207 binding surface has ``EGL_RENDER_BUFFER`` set to ``EGL_SINGLE_BUFFER``;
 208 If the same context is later bound to a surface with
 209 ``EGL_RENDER_BUFFER`` set to ``EGL_BACK_BUFFER``, the context should try
 210 to render to the back buffer. However, the context is allowed to make
 211 the final decision as to which color buffer it wants to or is able to
 212 render to.
 213
 214 For pbuffer surfaces, the render buffer is always ``EGL_BACK_BUFFER``.
 215 And for pixmap surfaces, the render buffer is always
 216 ``EGL_SINGLE_BUFFER``. Unlike window surfaces, EGL spec requires their
 217 ``EGL_RENDER_BUFFER`` values to be honored. As a result, a driver should
 218 never set ``EGL_PIXMAP_BIT`` or ``EGL_PBUFFER_BIT`` bits of a config if
 219 the contexts created with the config won't be able to honor the
 220 ``EGL_RENDER_BUFFER`` of pixmap or pbuffer surfaces.
 221
 222 It should also be noted that pixmap and pbuffer surfaces are assumed to
 223 be single-buffered, in that ``eglSwapBuffers`` has no effect on them. It
 224 is desirable that a driver allocates a private color buffer for each
 225 pbuffer surface created. If the window system the driver supports has
 226 native pbuffers, or if the native pixmaps have more than one color
 227 buffers, the driver should carefully attach the native color buffers to
 228 the EGL surfaces, re-route them if required.
 229
 230 There is no defined behavior as to, for example, how ``glDrawBuffer``
 231 interacts with ``EGL_RENDER_BUFFER``. Right now, it is desired that the
 232 draw buffer in a client API be fixed for pixmap and pbuffer surfaces.
 233 Therefore, the driver is responsible to guarantee that the client API
 234 renders to the specified render buffer for pixmap and pbuffer surfaces.
 235
 236 ``EGLDisplay`` Mutex
 237 ~~~~~~~~~~~~~~~~~~~~
 238
 239 The ``EGLDisplay`` will be locked before calling any of the dispatch
 240 functions (well, except for GetProcAddress which does not take an
 241 ``EGLDisplay``). This guarantees that the same dispatch function will
 242 not be called with the same display at the same time. If a driver has
 243 access to an ``EGLDisplay`` without going through the EGL APIs, the
 244 driver should as well lock the display before using it.