Erik Faye-Lund | 4d06683 | 2020-06-12 20:09:42 +0200 | [diff] [blame] | 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 | |
Erik Faye-Lund | d6be994 | 2019-06-04 14:14:13 +0200 | [diff] [blame] | 21 | .. code-block:: console |
Erik Faye-Lund | 4d06683 | 2020-06-12 20:09:42 +0200 | [diff] [blame] | 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 |
Erik Faye-Lund | 9be0e2d | 2020-06-15 12:31:36 +0200 | [diff] [blame] | 31 | options above enables :doc:`OpenGL ES 1.x and 2.x <opengles>`. The |
Erik Faye-Lund | 4d06683 | 2020-06-12 20:09:42 +0200 | [diff] [blame] | 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 |
Eric Engestrom | e00adef | 2019-06-25 15:44:16 +0100 | [diff] [blame] | 52 | comma separated string such as ``-D platforms=x11,wayland``. It decides |
Erik Faye-Lund | 4d06683 | 2020-06-12 20:09:42 +0200 | [diff] [blame] | 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 | |
Eric Engestrom | e00adef | 2019-06-25 15:44:16 +0100 | [diff] [blame] | 56 | The available platforms are ``x11``, ``wayland``, |
Eric Engestrom | a38e21d | 2019-06-25 13:47:04 +0100 | [diff] [blame] | 57 | ``android``, and ``haiku``. The ``android`` platform |
Erik Faye-Lund | 4d06683 | 2020-06-12 20:09:42 +0200 | [diff] [blame] | 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 | EGL Drivers |
| 104 | ----------- |
| 105 | |
| 106 | ``egl_dri2`` |
| 107 | This driver supports both ``x11`` and ``drm`` platforms. It functions |
| 108 | as a DRI driver loader. For ``x11`` support, it talks to the X server |
| 109 | directly using (XCB-)DRI2 protocol. |
| 110 | |
| 111 | This driver can share DRI drivers with ``libGL``. |
| 112 | |
| 113 | Packaging |
| 114 | --------- |
| 115 | |
| 116 | The ABI between the main library and its drivers are not stable. Nor is |
| 117 | there a plan to stabilize it at the moment. |
| 118 | |
| 119 | Developers |
| 120 | ---------- |
| 121 | |
| 122 | The sources of the main library and drivers can be found at |
| 123 | ``src/egl/``. |
| 124 | |
| 125 | Lifetime of Display Resources |
| 126 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 127 | |
| 128 | Contexts and surfaces are examples of display resources. They might live |
| 129 | longer than the display that creates them. |
| 130 | |
| 131 | In EGL, when a display is terminated through ``eglTerminate``, all |
| 132 | display resources should be destroyed. Similarly, when a thread is |
| 133 | released through ``eglReleaseThread``, all current display resources |
| 134 | should be released. Another way to destroy or release resources is |
| 135 | through functions such as ``eglDestroySurface`` or ``eglMakeCurrent``. |
| 136 | |
| 137 | When a resource that is current to some thread is destroyed, the |
| 138 | resource should not be destroyed immediately. EGL requires the resource |
| 139 | to live until it is no longer current. A driver usually calls |
| 140 | ``eglIs<Resource>Bound`` to check if a resource is bound (current) to |
| 141 | any thread in the destroy callbacks. If it is still bound, the resource |
| 142 | is not destroyed. |
| 143 | |
| 144 | The main library will mark destroyed current resources as unlinked. In a |
| 145 | driver's ``MakeCurrent`` callback, ``eglIs<Resource>Linked`` can then be |
| 146 | called to check if a newly released resource is linked to a display. If |
| 147 | it is not, the last reference to the resource is removed and the driver |
| 148 | should destroy the resource. But it should be careful here because |
| 149 | ``MakeCurrent`` might be called with an uninitialized display. |
| 150 | |
| 151 | This is the only mechanism provided by the main library to help manage |
| 152 | the resources. The drivers are responsible to the correct behavior as |
| 153 | defined by EGL. |
| 154 | |
| 155 | ``EGL_RENDER_BUFFER`` |
| 156 | ~~~~~~~~~~~~~~~~~~~~~ |
| 157 | |
| 158 | In EGL, the color buffer a context should try to render to is decided by |
| 159 | the binding surface. It should try to render to the front buffer if the |
| 160 | binding surface has ``EGL_RENDER_BUFFER`` set to ``EGL_SINGLE_BUFFER``; |
| 161 | If the same context is later bound to a surface with |
| 162 | ``EGL_RENDER_BUFFER`` set to ``EGL_BACK_BUFFER``, the context should try |
| 163 | to render to the back buffer. However, the context is allowed to make |
| 164 | the final decision as to which color buffer it wants to or is able to |
| 165 | render to. |
| 166 | |
| 167 | For pbuffer surfaces, the render buffer is always ``EGL_BACK_BUFFER``. |
| 168 | And for pixmap surfaces, the render buffer is always |
| 169 | ``EGL_SINGLE_BUFFER``. Unlike window surfaces, EGL spec requires their |
| 170 | ``EGL_RENDER_BUFFER`` values to be honored. As a result, a driver should |
| 171 | never set ``EGL_PIXMAP_BIT`` or ``EGL_PBUFFER_BIT`` bits of a config if |
| 172 | the contexts created with the config won't be able to honor the |
| 173 | ``EGL_RENDER_BUFFER`` of pixmap or pbuffer surfaces. |
| 174 | |
| 175 | It should also be noted that pixmap and pbuffer surfaces are assumed to |
| 176 | be single-buffered, in that ``eglSwapBuffers`` has no effect on them. It |
| 177 | is desirable that a driver allocates a private color buffer for each |
| 178 | pbuffer surface created. If the window system the driver supports has |
| 179 | native pbuffers, or if the native pixmaps have more than one color |
| 180 | buffers, the driver should carefully attach the native color buffers to |
| 181 | the EGL surfaces, re-route them if required. |
| 182 | |
| 183 | There is no defined behavior as to, for example, how ``glDrawBuffer`` |
| 184 | interacts with ``EGL_RENDER_BUFFER``. Right now, it is desired that the |
| 185 | draw buffer in a client API be fixed for pixmap and pbuffer surfaces. |
| 186 | Therefore, the driver is responsible to guarantee that the client API |
| 187 | renders to the specified render buffer for pixmap and pbuffer surfaces. |
| 188 | |
| 189 | ``EGLDisplay`` Mutex |
| 190 | ~~~~~~~~~~~~~~~~~~~~ |
| 191 | |
| 192 | The ``EGLDisplay`` will be locked before calling any of the dispatch |
| 193 | functions (well, except for GetProcAddress which does not take an |
| 194 | ``EGLDisplay``). This guarantees that the same dispatch function will |
| 195 | not be called with the sample display at the same time. If a driver has |
| 196 | access to an ``EGLDisplay`` without going through the EGL APIs, the |
| 197 | driver should as well lock the display before using it. |