1 1.1 mrg <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> 2 1.1 mrg <html lang="en"> 3 1.1 mrg <head> 4 1.1 mrg <meta http-equiv="content-type" content="text/html; charset=utf-8"> 5 1.1 mrg <title>Mesa EGL</title> 6 1.1 mrg <link rel="stylesheet" type="text/css" href="mesa.css"> 7 1.1 mrg </head> 8 1.1 mrg <body> 9 1.1 mrg 10 1.1 mrg <div class="header"> 11 1.1 mrg <h1>The Mesa 3D Graphics Library</h1> 12 1.1 mrg </div> 13 1.1 mrg 14 1.1 mrg <iframe src="contents.html"></iframe> 15 1.1 mrg <div class="content"> 16 1.1 mrg 17 1.1 mrg <h1>Mesa EGL</h1> 18 1.1 mrg 19 1.1 mrg <p>The current version of EGL in Mesa implements EGL 1.4. More information 20 1.1 mrg about EGL can be found at 21 1.1.1.2 mrg <a href="https://www.khronos.org/egl/"> 22 1.1.1.2 mrg https://www.khronos.org/egl/</a>.</p> 23 1.1 mrg 24 1.1 mrg <p>The Mesa's implementation of EGL uses a driver architecture. The main 25 1.1 mrg library (<code>libEGL</code>) is window system neutral. It provides the EGL 26 1.1 mrg API entry points and helper functions for use by the drivers. Drivers are 27 1.1 mrg dynamically loaded by the main library and most of the EGL API calls are 28 1.1 mrg directly dispatched to the drivers.</p> 29 1.1 mrg 30 1.1 mrg <p>The driver in use decides the window system to support.</p> 31 1.1 mrg 32 1.1 mrg <h2>Build EGL</h2> 33 1.1 mrg 34 1.1 mrg <ol> 35 1.1 mrg <li> 36 1.1.1.2 mrg <p>Configure your build with the desired client APIs and enable 37 1.1.1.2 mrg the driver for your hardware. For example:</p> 38 1.1 mrg 39 1.1 mrg <pre> 40 1.1.1.2 mrg $ meson configure \ 41 1.1.1.2 mrg -D egl=true \ 42 1.1.1.2 mrg -D gles1=true \ 43 1.1.1.2 mrg -D gles2=true \ 44 1.1.1.2 mrg -D dri-drivers=... \ 45 1.1.1.2 mrg -D gallium-drivers=... 46 1.1 mrg </pre> 47 1.1 mrg 48 1.1 mrg <p>The main library and OpenGL is enabled by default. The first two options 49 1.1 mrg above enables <a href="opengles.html">OpenGL ES 1.x and 2.x</a>. The last two 50 1.1.1.2 mrg options enables the listed classic and Gallium drivers respectively.</p> 51 1.1 mrg 52 1.1 mrg </li> 53 1.1 mrg 54 1.1 mrg <li>Build and install Mesa as usual.</li> 55 1.1 mrg </ol> 56 1.1 mrg 57 1.1 mrg <p>In the given example, it will build and install <code>libEGL</code>, 58 1.1 mrg <code>libGL</code>, <code>libGLESv1_CM</code>, <code>libGLESv2</code>, and one 59 1.1 mrg or more EGL drivers.</p> 60 1.1 mrg 61 1.1 mrg <h3>Configure Options</h3> 62 1.1 mrg 63 1.1 mrg <p>There are several options that control the build of EGL at configuration 64 1.1 mrg time</p> 65 1.1 mrg 66 1.1 mrg <dl> 67 1.1.1.2 mrg <dt><code>-D egl=true</code></dt> 68 1.1 mrg <dd> 69 1.1 mrg 70 1.1 mrg <p>By default, EGL is enabled. When disabled, the main library and the drivers 71 1.1 mrg will not be built.</p> 72 1.1 mrg 73 1.1 mrg </dd> 74 1.1 mrg 75 1.1.1.2 mrg <dt><code>-D platforms=...</code></dt> 76 1.1 mrg <dd> 77 1.1 mrg 78 1.1 mrg <p>List the platforms (window systems) to support. Its argument is a comma 79 1.1.1.2 mrg separated string such as <code>-D platforms=x11,drm</code>. It decides 80 1.1 mrg the platforms a driver may support. The first listed platform is also used by 81 1.1.1.2 mrg the main library to decide the native platform.</p> 82 1.1 mrg 83 1.1 mrg <p>The available platforms are <code>x11</code>, <code>drm</code>, 84 1.1.1.2 mrg <code>wayland</code>, <code>surfaceless</code>, <code>android</code>, 85 1.1.1.2 mrg and <code>haiku</code>. 86 1.1.1.2 mrg The <code>android</code> platform can either be built as a system 87 1.1.1.2 mrg component, part of AOSP, using <code>Android.mk</code> files, or 88 1.1.1.2 mrg cross-compiled using appropriate options. 89 1.1.1.2 mrg The <code>haiku</code> platform can only be built with SCons or Meson. 90 1.1.1.2 mrg Unless for special needs, the build system should 91 1.1 mrg select the right platforms automatically.</p> 92 1.1 mrg 93 1.1 mrg </dd> 94 1.1 mrg 95 1.1.1.2 mrg <dt><code>-D gles1=true</code></dt> 96 1.1.1.2 mrg <dt><code>-D gles2=true</code></dt> 97 1.1 mrg <dd> 98 1.1 mrg 99 1.1 mrg <p>These options enable OpenGL ES support in OpenGL. The result is one big 100 1.1 mrg internal library that supports multiple APIs.</p> 101 1.1 mrg 102 1.1 mrg </dd> 103 1.1 mrg 104 1.1.1.2 mrg <dt><code>-D shared-glapi=true</code></dt> 105 1.1 mrg <dd> 106 1.1 mrg 107 1.1 mrg <p>By default, <code>libGL</code> has its own copy of <code>libglapi</code>. 108 1.1 mrg This options makes <code>libGL</code> use the shared <code>libglapi</code>. This 109 1.1 mrg is required if applications mix OpenGL and OpenGL ES.</p> 110 1.1 mrg 111 1.1 mrg </dd> 112 1.1 mrg 113 1.1 mrg </dl> 114 1.1 mrg 115 1.1 mrg <h2>Use EGL</h2> 116 1.1 mrg 117 1.1 mrg <h3>Demos</h3> 118 1.1 mrg 119 1.1 mrg <p>There are demos for the client APIs supported by EGL. They can be found in 120 1.1 mrg mesa/demos repository.</p> 121 1.1 mrg 122 1.1 mrg <h3>Environment Variables</h3> 123 1.1 mrg 124 1.1 mrg <p>There are several environment variables that control the behavior of EGL at 125 1.1 mrg runtime</p> 126 1.1 mrg 127 1.1 mrg <dl> 128 1.1 mrg <dt><code>EGL_PLATFORM</code></dt> 129 1.1 mrg <dd> 130 1.1 mrg 131 1.1 mrg <p>This variable specifies the native platform. The valid values are the same 132 1.1.1.2 mrg as those for <code>-D platforms=...</code>. When the variable is not set, 133 1.1 mrg the main library uses the first platform listed in 134 1.1.1.2 mrg <code>-D platforms=...</code> as the native platform.</p> 135 1.1 mrg 136 1.1 mrg <p>Extensions like <code>EGL_MESA_drm_display</code> define new functions to 137 1.1 mrg create displays for non-native platforms. These extensions are usually used by 138 1.1 mrg applications that support non-native platforms. Setting this variable is 139 1.1 mrg probably required only for some of the demos found in mesa/demo repository.</p> 140 1.1 mrg 141 1.1 mrg </dd> 142 1.1 mrg 143 1.1 mrg <dt><code>EGL_LOG_LEVEL</code></dt> 144 1.1 mrg <dd> 145 1.1 mrg 146 1.1 mrg <p>This changes the log level of the main library and the drivers. The valid 147 1.1 mrg values are: <code>debug</code>, <code>info</code>, <code>warning</code>, and 148 1.1 mrg <code>fatal</code>.</p> 149 1.1 mrg 150 1.1 mrg </dd> 151 1.1 mrg </dl> 152 1.1 mrg 153 1.1 mrg <h2>EGL Drivers</h2> 154 1.1 mrg 155 1.1 mrg <dl> 156 1.1 mrg <dt><code>egl_dri2</code></dt> 157 1.1 mrg <dd> 158 1.1 mrg 159 1.1 mrg <p>This driver supports both <code>x11</code> and <code>drm</code> platforms. 160 1.1 mrg It functions as a DRI driver loader. For <code>x11</code> support, it talks to 161 1.1 mrg the X server directly using (XCB-)DRI2 protocol.</p> 162 1.1 mrg 163 1.1 mrg <p>This driver can share DRI drivers with <code>libGL</code>.</p> 164 1.1 mrg 165 1.1 mrg </dd> 166 1.1.1.2 mrg </dl> 167 1.1 mrg 168 1.1 mrg <h2>Packaging</h2> 169 1.1 mrg 170 1.1 mrg <p>The ABI between the main library and its drivers are not stable. Nor is 171 1.1.1.2 mrg there a plan to stabilize it at the moment.</p> 172 1.1 mrg 173 1.1 mrg <h2>Developers</h2> 174 1.1 mrg 175 1.1.1.2 mrg <p>The sources of the main library and drivers can be found at 176 1.1.1.2 mrg <code>src/egl/</code>.</p> 177 1.1 mrg 178 1.1 mrg <h3>Lifetime of Display Resources</h3> 179 1.1 mrg 180 1.1 mrg <p>Contexts and surfaces are examples of display resources. They might live 181 1.1 mrg longer than the display that creates them.</p> 182 1.1 mrg 183 1.1 mrg <p>In EGL, when a display is terminated through <code>eglTerminate</code>, all 184 1.1 mrg display resources should be destroyed. Similarly, when a thread is released 185 1.1 mrg through <code>eglReleaseThread</code>, all current display resources should be 186 1.1 mrg released. Another way to destroy or release resources is through functions 187 1.1 mrg such as <code>eglDestroySurface</code> or <code>eglMakeCurrent</code>.</p> 188 1.1 mrg 189 1.1 mrg <p>When a resource that is current to some thread is destroyed, the resource 190 1.1 mrg should not be destroyed immediately. EGL requires the resource to live until 191 1.1 mrg it is no longer current. A driver usually calls 192 1.1 mrg <code>eglIs<Resource>Bound</code> to check if a resource is bound 193 1.1 mrg (current) to any thread in the destroy callbacks. If it is still bound, the 194 1.1 mrg resource is not destroyed.</p> 195 1.1 mrg 196 1.1 mrg <p>The main library will mark destroyed current resources as unlinked. In a 197 1.1 mrg driver's <code>MakeCurrent</code> callback, 198 1.1 mrg <code>eglIs<Resource>Linked</code> can then be called to check if a newly 199 1.1 mrg released resource is linked to a display. If it is not, the last reference to 200 1.1 mrg the resource is removed and the driver should destroy the resource. But it 201 1.1 mrg should be careful here because <code>MakeCurrent</code> might be called with an 202 1.1 mrg uninitialized display.</p> 203 1.1 mrg 204 1.1 mrg <p>This is the only mechanism provided by the main library to help manage the 205 1.1 mrg resources. The drivers are responsible to the correct behavior as defined by 206 1.1 mrg EGL.</p> 207 1.1 mrg 208 1.1 mrg <h3><code>EGL_RENDER_BUFFER</code></h3> 209 1.1 mrg 210 1.1 mrg <p>In EGL, the color buffer a context should try to render to is decided by the 211 1.1 mrg binding surface. It should try to render to the front buffer if the binding 212 1.1 mrg surface has <code>EGL_RENDER_BUFFER</code> set to 213 1.1 mrg <code>EGL_SINGLE_BUFFER</code>; If the same context is later bound to a 214 1.1 mrg surface with <code>EGL_RENDER_BUFFER</code> set to 215 1.1 mrg <code>EGL_BACK_BUFFER</code>, the context should try to render to the back 216 1.1 mrg buffer. However, the context is allowed to make the final decision as to which 217 1.1 mrg color buffer it wants to or is able to render to.</p> 218 1.1 mrg 219 1.1 mrg <p>For pbuffer surfaces, the render buffer is always 220 1.1 mrg <code>EGL_BACK_BUFFER</code>. And for pixmap surfaces, the render buffer is 221 1.1 mrg always <code>EGL_SINGLE_BUFFER</code>. Unlike window surfaces, EGL spec 222 1.1 mrg requires their <code>EGL_RENDER_BUFFER</code> values to be honored. As a 223 1.1 mrg result, a driver should never set <code>EGL_PIXMAP_BIT</code> or 224 1.1 mrg <code>EGL_PBUFFER_BIT</code> bits of a config if the contexts created with the 225 1.1 mrg config won't be able to honor the <code>EGL_RENDER_BUFFER</code> of pixmap or 226 1.1 mrg pbuffer surfaces.</p> 227 1.1 mrg 228 1.1 mrg <p>It should also be noted that pixmap and pbuffer surfaces are assumed to be 229 1.1 mrg single-buffered, in that <code>eglSwapBuffers</code> has no effect on them. It 230 1.1 mrg is desirable that a driver allocates a private color buffer for each pbuffer 231 1.1 mrg surface created. If the window system the driver supports has native pbuffers, 232 1.1 mrg or if the native pixmaps have more than one color buffers, the driver should 233 1.1 mrg carefully attach the native color buffers to the EGL surfaces, re-route them if 234 1.1 mrg required.</p> 235 1.1 mrg 236 1.1 mrg <p>There is no defined behavior as to, for example, how 237 1.1 mrg <code>glDrawBuffer</code> interacts with <code>EGL_RENDER_BUFFER</code>. Right 238 1.1 mrg now, it is desired that the draw buffer in a client API be fixed for pixmap and 239 1.1 mrg pbuffer surfaces. Therefore, the driver is responsible to guarantee that the 240 1.1 mrg client API renders to the specified render buffer for pixmap and pbuffer 241 1.1 mrg surfaces.</p> 242 1.1 mrg 243 1.1 mrg <h3><code>EGLDisplay</code> Mutex</h3> 244 1.1 mrg 245 1.1 mrg The <code>EGLDisplay</code> will be locked before calling any of the dispatch 246 1.1 mrg functions (well, except for GetProcAddress which does not take an 247 1.1 mrg <code>EGLDisplay</code>). This guarantees that the same dispatch function will 248 1.1 mrg not be called with the sample display at the same time. If a driver has access 249 1.1 mrg to an <code>EGLDisplay</code> without going through the EGL APIs, the driver 250 1.1 mrg should as well lock the display before using it. 251 1.1 mrg 252 1.1 mrg </div> 253 1.1 mrg </body> 254 1.1 mrg </html> 255
Indexes created Wed Apr 22 00:22:44 UTC 2026