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=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
  36 In the given example, it will build and install ``libEGL``, ``libGL``,
  37 ``libGLESv1_CM``, ``libGLESv2``, and one or more EGL drivers.
  38
  39 Configure Options
  40 ~~~~~~~~~~~~~~~~~
  41
  42 There are several options that control the build of EGL at configuration
  43 time
  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
  71 Use EGL
  72 -------
  73
  74 Demos
  75 ~~~~~
  76
  77 There are demos for the client APIs supported by EGL. They can be found
  78 in mesa/demos repository.
  79
  80 Environment Variables
  81 ~~~~~~~~~~~~~~~~~~~~~
  82
  83 There are several environment variables that control the behavior of EGL
  84 at 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
  96 Packaging
  97 ---------
  98
  99 The ABI between the main library and its drivers are not stable. Nor is
 100 there a plan to stabilize it at the moment.
 101
 102 Developers
 103 ----------
 104
 105 The sources of the main library and drivers can be found at
 106 ``src/egl/``.
 107
 108 The code basically consists of two things:
 109
 110 1. An EGL API dispatcher. This directly routes all the ``eglFooBar()``
 111    API calls into driver-specific functions.
 112
 113 2. Two EGL drivers (``dri2`` and ``haiku``), implementing the API
 114    functions handling the platforms' specifics.
 115
 116 Two of API functions are optional (``eglQuerySurface()`` and
 117 ``eglSwapInterval()``); the former provides fallback for all the
 118 platform-agnostic attributes (i.e. everything except ``EGL_WIDTH``
 119 & ``EGL_HEIGHT``), and the latter just silently pretends the API call
 120 succeeded (as per EGL spec).
 121
 122 A driver _could_ implement all the other EGL API functions, but several of
 123 them are only needed for extensions, like ``eglSwapBuffersWithDamageEXT()``.
 124 See ``src/egl/main/egldriver.h`` to see which driver hooks are only
 125 required by extensions.
 126
 127 Bootstrapping
 128 ~~~~~~~~~~~~~
 129
 130 When the apps calls ``eglInitialize()``, the driver's ``Initialize()``
 131 function is called. If the first driver initialization attempt fails,
 132 a second one is tried using only software components (this can be forced
 133 using the ``LIBGL_ALWAYS_SOFTWARE`` environment variable). Typically,
 134 this function takes care of setting up visual configs, creating EGL
 135 devices, etc.
 136
 137 Teardown
 138 ~~~~~~~~
 139
 140 When ``eglTerminate()`` is called, the ``driver->Terminate()`` function
 141 is called. The driver should clean up after itself.
 142
 143 Subclassing
 144 ~~~~~~~~~~~
 145
 146 The internal libEGL data structures such as ``_EGLDisplay``,
 147 ``_EGLContext``, ``_EGLSurface``, etc. should be considered base classes
 148 from which drivers will derive subclasses.
 149
 150 EGL 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://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
 167 Lifetime of Display Resources
 168 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 169
 170 Contexts and surfaces are examples of display resources. They might live
 171 longer than the display that creates them.
 172
 173 In EGL, when a display is terminated through ``eglTerminate``, all
 174 display resources should be destroyed. Similarly, when a thread is
 175 released through ``eglReleaseThread``, all current display resources
 176 should be released. Another way to destroy or release resources is
 177 through functions such as ``eglDestroySurface`` or ``eglMakeCurrent``.
 178
 179 When a resource that is current to some thread is destroyed, the
 180 resource should not be destroyed immediately. EGL requires the resource
 181 to live until it is no longer current. A driver usually calls
 182 ``eglIs<Resource>Bound`` to check if a resource is bound (current) to
 183 any thread in the destroy callbacks. If it is still bound, the resource
 184 is not destroyed.
 185
 186 The main library will mark destroyed current resources as unlinked. In a
 187 driver's ``MakeCurrent`` callback, ``eglIs<Resource>Linked`` can then be
 188 called to check if a newly released resource is linked to a display. If
 189 it is not, the last reference to the resource is removed and the driver
 190 should destroy the resource. But it should be careful here because
 191 ``MakeCurrent`` might be called with an uninitialized display.
 192
 193 This is the only mechanism provided by the main library to help manage
 194 the resources. The drivers are responsible to the correct behavior as
 195 defined by EGL.
 196
 197 ``EGL_RENDER_BUFFER``
 198 ~~~~~~~~~~~~~~~~~~~~~
 199
 200 In EGL, the color buffer a context should try to render to is decided by
 201 the binding surface. It should try to render to the front buffer if the
 202 binding surface has ``EGL_RENDER_BUFFER`` set to ``EGL_SINGLE_BUFFER``;
 203 If the same context is later bound to a surface with
 204 ``EGL_RENDER_BUFFER`` set to ``EGL_BACK_BUFFER``, the context should try
 205 to render to the back buffer. However, the context is allowed to make
 206 the final decision as to which color buffer it wants to or is able to
 207 render to.
 208
 209 For pbuffer surfaces, the render buffer is always ``EGL_BACK_BUFFER``.
 210 And 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
 213 never set ``EGL_PIXMAP_BIT`` or ``EGL_PBUFFER_BIT`` bits of a config if
 214 the contexts created with the config won't be able to honor the
 215 ``EGL_RENDER_BUFFER`` of pixmap or pbuffer surfaces.
 216
 217 It should also be noted that pixmap and pbuffer surfaces are assumed to
 218 be single-buffered, in that ``eglSwapBuffers`` has no effect on them. It
 219 is desirable that a driver allocates a private color buffer for each
 220 pbuffer surface created. If the window system the driver supports has
 221 native pbuffers, or if the native pixmaps have more than one color
 222 buffers, the driver should carefully attach the native color buffers to
 223 the EGL surfaces, re-route them if required.
 224
 225 There is no defined behavior as to, for example, how ``glDrawBuffer``
 226 interacts with ``EGL_RENDER_BUFFER``. Right now, it is desired that the
 227 draw buffer in a client API be fixed for pixmap and pbuffer surfaces.
 228 Therefore, the driver is responsible to guarantee that the client API
 229 renders to the specified render buffer for pixmap and pbuffer surfaces.
 230
 231 ``EGLDisplay`` Mutex
 232 ~~~~~~~~~~~~~~~~~~~~
 233
 234 The ``EGLDisplay`` will be locked before calling any of the dispatch
 235 functions (well, except for GetProcAddress which does not take an
 236 ``EGLDisplay``). This guarantees that the same dispatch function will
 237 not be called with the same display at the same time. If a driver has
 238 access to an ``EGLDisplay`` without going through the EGL APIs, the
 239 driver should as well lock the display before using it.