egl.html revision 1.1
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 mrg <a href="http://www.khronos.org/egl/"> 22 1.1 mrg http://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 mrg <p>Run <code>configure</code> with the desired client APIs and enable 37 1.1 mrg the driver for your hardware. For example</p> 38 1.1 mrg 39 1.1 mrg <pre> 40 1.1 mrg $ ./configure --enable-gles1 --enable-gles2 \ 41 1.1 mrg --with-dri-drivers=... \ 42 1.1 mrg --with-gallium-drivers=... 43 1.1 mrg </pre> 44 1.1 mrg 45 1.1 mrg <p>The main library and OpenGL is enabled by default. The first two options 46 1.1 mrg above enables <a href="opengles.html">OpenGL ES 1.x and 2.x</a>. The last two 47 1.1 mrg options enables the listed classic and and Gallium drivers respectively.</p> 48 1.1 mrg 49 1.1 mrg </li> 50 1.1 mrg 51 1.1 mrg <li>Build and install Mesa as usual.</li> 52 1.1 mrg </ol> 53 1.1 mrg 54 1.1 mrg <p>In the given example, it will build and install <code>libEGL</code>, 55 1.1 mrg <code>libGL</code>, <code>libGLESv1_CM</code>, <code>libGLESv2</code>, and one 56 1.1 mrg or more EGL drivers.</p> 57 1.1 mrg 58 1.1 mrg <h3>Configure Options</h3> 59 1.1 mrg 60 1.1 mrg <p>There are several options that control the build of EGL at configuration 61 1.1 mrg time</p> 62 1.1 mrg 63 1.1 mrg <dl> 64 1.1 mrg <dt><code>--enable-egl</code></dt> 65 1.1 mrg <dd> 66 1.1 mrg 67 1.1 mrg <p>By default, EGL is enabled. When disabled, the main library and the drivers 68 1.1 mrg will not be built.</p> 69 1.1 mrg 70 1.1 mrg </dd> 71 1.1 mrg 72 1.1 mrg <dt><code>--with-egl-driver-dir</code></dt> 73 1.1 mrg <dd> 74 1.1 mrg 75 1.1 mrg <p>The directory EGL drivers should be installed to. If not specified, EGL 76 1.1 mrg drivers will be installed to <code>${libdir}/egl</code>.</p> 77 1.1 mrg 78 1.1 mrg </dd> 79 1.1 mrg 80 1.1 mrg <dt><code>--enable-gallium-egl</code></dt> 81 1.1 mrg <dd> 82 1.1 mrg 83 1.1 mrg <p>Enable the optional <code>egl_gallium</code> driver.</p> 84 1.1 mrg 85 1.1 mrg </dd> 86 1.1 mrg 87 1.1 mrg <dt><code>--with-egl-platforms</code></dt> 88 1.1 mrg <dd> 89 1.1 mrg 90 1.1 mrg <p>List the platforms (window systems) to support. Its argument is a comma 91 1.1 mrg separated string such as <code>--with-egl-platforms=x11,drm</code>. It decides 92 1.1 mrg the platforms a driver may support. The first listed platform is also used by 93 1.1 mrg the main library to decide the native platform: the platform the EGL native 94 1.1 mrg types such as <code>EGLNativeDisplayType</code> or 95 1.1 mrg <code>EGLNativeWindowType</code> defined for.</p> 96 1.1 mrg 97 1.1 mrg <p>The available platforms are <code>x11</code>, <code>drm</code>, 98 1.1 mrg <code>fbdev</code>, and <code>gdi</code>. The <code>gdi</code> platform can 99 1.1 mrg only be built with SCons. Unless for special needs, the build system should 100 1.1 mrg select the right platforms automatically.</p> 101 1.1 mrg 102 1.1 mrg </dd> 103 1.1 mrg 104 1.1 mrg <dt><code>--enable-gles1</code></dt> 105 1.1 mrg <dt><code>--enable-gles2</code></dt> 106 1.1 mrg <dd> 107 1.1 mrg 108 1.1 mrg <p>These options enable OpenGL ES support in OpenGL. The result is one big 109 1.1 mrg internal library that supports multiple APIs.</p> 110 1.1 mrg 111 1.1 mrg </dd> 112 1.1 mrg 113 1.1 mrg <dt><code>--enable-shared-glapi</code></dt> 114 1.1 mrg <dd> 115 1.1 mrg 116 1.1 mrg <p>By default, <code>libGL</code> has its own copy of <code>libglapi</code>. 117 1.1 mrg This options makes <code>libGL</code> use the shared <code>libglapi</code>. This 118 1.1 mrg is required if applications mix OpenGL and OpenGL ES.</p> 119 1.1 mrg 120 1.1 mrg </dd> 121 1.1 mrg 122 1.1 mrg <dt><code>--enable-openvg</code></dt> 123 1.1 mrg <dd> 124 1.1 mrg 125 1.1 mrg <p>OpenVG must be explicitly enabled by this option.</p> 126 1.1 mrg 127 1.1 mrg </dd> 128 1.1 mrg 129 1.1 mrg </dl> 130 1.1 mrg 131 1.1 mrg <h2>Use EGL</h2> 132 1.1 mrg 133 1.1 mrg <h3>Demos</h3> 134 1.1 mrg 135 1.1 mrg <p>There are demos for the client APIs supported by EGL. They can be found in 136 1.1 mrg mesa/demos repository.</p> 137 1.1 mrg 138 1.1 mrg <h3>Environment Variables</h3> 139 1.1 mrg 140 1.1 mrg <p>There are several environment variables that control the behavior of EGL at 141 1.1 mrg runtime</p> 142 1.1 mrg 143 1.1 mrg <dl> 144 1.1 mrg <dt><code>EGL_DRIVERS_PATH</code></dt> 145 1.1 mrg <dd> 146 1.1 mrg 147 1.1 mrg <p>By default, the main library will look for drivers in the directory where 148 1.1 mrg the drivers are installed to. This variable specifies a list of 149 1.1 mrg colon-separated directories where the main library will look for drivers, in 150 1.1 mrg addition to the default directory. This variable is ignored for setuid/setgid 151 1.1 mrg binaries.</p> 152 1.1 mrg 153 1.1 mrg <p>This variable is usually set to test an uninstalled build. For example, one 154 1.1 mrg may set</p> 155 1.1 mrg 156 1.1 mrg <pre> 157 1.1 mrg $ export LD_LIBRARY_PATH=$mesa/lib 158 1.1 mrg $ export EGL_DRIVERS_PATH=$mesa/lib/egl 159 1.1 mrg </pre> 160 1.1 mrg 161 1.1 mrg <p>to test a build without installation</p> 162 1.1 mrg 163 1.1 mrg </dd> 164 1.1 mrg 165 1.1 mrg <dt><code>EGL_DRIVER</code></dt> 166 1.1 mrg <dd> 167 1.1 mrg 168 1.1 mrg <p>This variable specifies a full path to or the name of an EGL driver. It 169 1.1 mrg forces the specified EGL driver to be loaded. It comes in handy when one wants 170 1.1 mrg to test a specific driver. This variable is ignored for setuid/setgid 171 1.1 mrg binaries.</p> 172 1.1 mrg 173 1.1 mrg </dd> 174 1.1 mrg 175 1.1 mrg <dt><code>EGL_PLATFORM</code></dt> 176 1.1 mrg <dd> 177 1.1 mrg 178 1.1 mrg <p>This variable specifies the native platform. The valid values are the same 179 1.1 mrg as those for <code>--with-egl-platforms</code>. When the variable is not set, 180 1.1 mrg the main library uses the first platform listed in 181 1.1 mrg <code>--with-egl-platforms</code> as the native platform.</p> 182 1.1 mrg 183 1.1 mrg <p>Extensions like <code>EGL_MESA_drm_display</code> define new functions to 184 1.1 mrg create displays for non-native platforms. These extensions are usually used by 185 1.1 mrg applications that support non-native platforms. Setting this variable is 186 1.1 mrg probably required only for some of the demos found in mesa/demo repository.</p> 187 1.1 mrg 188 1.1 mrg </dd> 189 1.1 mrg 190 1.1 mrg <dt><code>EGL_LOG_LEVEL</code></dt> 191 1.1 mrg <dd> 192 1.1 mrg 193 1.1 mrg <p>This changes the log level of the main library and the drivers. The valid 194 1.1 mrg values are: <code>debug</code>, <code>info</code>, <code>warning</code>, and 195 1.1 mrg <code>fatal</code>.</p> 196 1.1 mrg 197 1.1 mrg </dd> 198 1.1 mrg 199 1.1 mrg <dt><code>EGL_SOFTWARE</code></dt> 200 1.1 mrg <dd> 201 1.1 mrg 202 1.1 mrg <p>For drivers that support both hardware and software rendering, setting this 203 1.1 mrg variable to true forces the use of software rendering.</p> 204 1.1 mrg 205 1.1 mrg </dd> 206 1.1 mrg </dl> 207 1.1 mrg 208 1.1 mrg <h2>EGL Drivers</h2> 209 1.1 mrg 210 1.1 mrg <dl> 211 1.1 mrg <dt><code>egl_dri2</code></dt> 212 1.1 mrg <dd> 213 1.1 mrg 214 1.1 mrg <p>This driver supports both <code>x11</code> and <code>drm</code> platforms. 215 1.1 mrg It functions as a DRI driver loader. For <code>x11</code> support, it talks to 216 1.1 mrg the X server directly using (XCB-)DRI2 protocol.</p> 217 1.1 mrg 218 1.1 mrg <p>This driver can share DRI drivers with <code>libGL</code>.</p> 219 1.1 mrg 220 1.1 mrg </dd> 221 1.1 mrg 222 1.1 mrg <dt><code>egl_gallium</code></dt> 223 1.1 mrg <dd> 224 1.1 mrg 225 1.1 mrg <p>This driver is based on Gallium3D. It supports all rendering APIs and 226 1.1 mrg hardware supported by Gallium3D. It is the only driver that supports OpenVG. 227 1.1 mrg The supported platforms are X11, DRM, FBDEV, and GDI.</p> 228 1.1 mrg 229 1.1 mrg <p>This driver comes with its own hardware drivers 230 1.1 mrg (<code>pipe_<hw></code>) and client API modules 231 1.1 mrg (<code>st_<api></code>).</p> 232 1.1 mrg 233 1.1 mrg </dd> 234 1.1 mrg 235 1.1 mrg <h2>Packaging</h2> 236 1.1 mrg 237 1.1 mrg <p>The ABI between the main library and its drivers are not stable. Nor is 238 1.1 mrg there a plan to stabilize it at the moment. Of the EGL drivers, 239 1.1 mrg <code>egl_gallium</code> has its own hardware drivers and client API modules. 240 1.1 mrg They are considered internal to <code>egl_gallium</code> and there is also no 241 1.1 mrg stable ABI between them. These should be kept in mind when packaging for 242 1.1 mrg distribution.</p> 243 1.1 mrg 244 1.1 mrg <p>Generally, <code>egl_dri2</code> is preferred over <code>egl_gallium</code> 245 1.1 mrg when the system already has DRI drivers. As <code>egl_gallium</code> is loaded 246 1.1 mrg before <code>egl_dri2</code> when both are available, <code>egl_gallium</code> 247 1.1 mrg is disabled by default.</p> 248 1.1 mrg 249 1.1 mrg <h2>Developers</h2> 250 1.1 mrg 251 1.1 mrg <p>The sources of the main library and the classic drivers can be found at 252 1.1 mrg <code>src/egl/</code>. The sources of the <code>egl</code> state tracker can 253 1.1 mrg be found at <code>src/gallium/state_trackers/egl/</code>.</p> 254 1.1 mrg 255 1.1 mrg <h3>Lifetime of Display Resources</h3> 256 1.1 mrg 257 1.1 mrg <p>Contexts and surfaces are examples of display resources. They might live 258 1.1 mrg longer than the display that creates them.</p> 259 1.1 mrg 260 1.1 mrg <p>In EGL, when a display is terminated through <code>eglTerminate</code>, all 261 1.1 mrg display resources should be destroyed. Similarly, when a thread is released 262 1.1 mrg through <code>eglReleaseThread</code>, all current display resources should be 263 1.1 mrg released. Another way to destroy or release resources is through functions 264 1.1 mrg such as <code>eglDestroySurface</code> or <code>eglMakeCurrent</code>.</p> 265 1.1 mrg 266 1.1 mrg <p>When a resource that is current to some thread is destroyed, the resource 267 1.1 mrg should not be destroyed immediately. EGL requires the resource to live until 268 1.1 mrg it is no longer current. A driver usually calls 269 1.1 mrg <code>eglIs<Resource>Bound</code> to check if a resource is bound 270 1.1 mrg (current) to any thread in the destroy callbacks. If it is still bound, the 271 1.1 mrg resource is not destroyed.</p> 272 1.1 mrg 273 1.1 mrg <p>The main library will mark destroyed current resources as unlinked. In a 274 1.1 mrg driver's <code>MakeCurrent</code> callback, 275 1.1 mrg <code>eglIs<Resource>Linked</code> can then be called to check if a newly 276 1.1 mrg released resource is linked to a display. If it is not, the last reference to 277 1.1 mrg the resource is removed and the driver should destroy the resource. But it 278 1.1 mrg should be careful here because <code>MakeCurrent</code> might be called with an 279 1.1 mrg uninitialized display.</p> 280 1.1 mrg 281 1.1 mrg <p>This is the only mechanism provided by the main library to help manage the 282 1.1 mrg resources. The drivers are responsible to the correct behavior as defined by 283 1.1 mrg EGL.</p> 284 1.1 mrg 285 1.1 mrg <h3><code>EGL_RENDER_BUFFER</code></h3> 286 1.1 mrg 287 1.1 mrg <p>In EGL, the color buffer a context should try to render to is decided by the 288 1.1 mrg binding surface. It should try to render to the front buffer if the binding 289 1.1 mrg surface has <code>EGL_RENDER_BUFFER</code> set to 290 1.1 mrg <code>EGL_SINGLE_BUFFER</code>; If the same context is later bound to a 291 1.1 mrg surface with <code>EGL_RENDER_BUFFER</code> set to 292 1.1 mrg <code>EGL_BACK_BUFFER</code>, the context should try to render to the back 293 1.1 mrg buffer. However, the context is allowed to make the final decision as to which 294 1.1 mrg color buffer it wants to or is able to render to.</p> 295 1.1 mrg 296 1.1 mrg <p>For pbuffer surfaces, the render buffer is always 297 1.1 mrg <code>EGL_BACK_BUFFER</code>. And for pixmap surfaces, the render buffer is 298 1.1 mrg always <code>EGL_SINGLE_BUFFER</code>. Unlike window surfaces, EGL spec 299 1.1 mrg requires their <code>EGL_RENDER_BUFFER</code> values to be honored. As a 300 1.1 mrg result, a driver should never set <code>EGL_PIXMAP_BIT</code> or 301 1.1 mrg <code>EGL_PBUFFER_BIT</code> bits of a config if the contexts created with the 302 1.1 mrg config won't be able to honor the <code>EGL_RENDER_BUFFER</code> of pixmap or 303 1.1 mrg pbuffer surfaces.</p> 304 1.1 mrg 305 1.1 mrg <p>It should also be noted that pixmap and pbuffer surfaces are assumed to be 306 1.1 mrg single-buffered, in that <code>eglSwapBuffers</code> has no effect on them. It 307 1.1 mrg is desirable that a driver allocates a private color buffer for each pbuffer 308 1.1 mrg surface created. If the window system the driver supports has native pbuffers, 309 1.1 mrg or if the native pixmaps have more than one color buffers, the driver should 310 1.1 mrg carefully attach the native color buffers to the EGL surfaces, re-route them if 311 1.1 mrg required.</p> 312 1.1 mrg 313 1.1 mrg <p>There is no defined behavior as to, for example, how 314 1.1 mrg <code>glDrawBuffer</code> interacts with <code>EGL_RENDER_BUFFER</code>. Right 315 1.1 mrg now, it is desired that the draw buffer in a client API be fixed for pixmap and 316 1.1 mrg pbuffer surfaces. Therefore, the driver is responsible to guarantee that the 317 1.1 mrg client API renders to the specified render buffer for pixmap and pbuffer 318 1.1 mrg surfaces.</p> 319 1.1 mrg 320 1.1 mrg <h3><code>EGLDisplay</code> Mutex</h3> 321 1.1 mrg 322 1.1 mrg The <code>EGLDisplay</code> will be locked before calling any of the dispatch 323 1.1 mrg functions (well, except for GetProcAddress which does not take an 324 1.1 mrg <code>EGLDisplay</code>). This guarantees that the same dispatch function will 325 1.1 mrg not be called with the sample display at the same time. If a driver has access 326 1.1 mrg to an <code>EGLDisplay</code> without going through the EGL APIs, the driver 327 1.1 mrg should as well lock the display before using it. 328 1.1 mrg 329 1.1 mrg </div> 330 1.1 mrg </body> 331 1.1 mrg </html> 332
Indexes created Sat Apr 25 00:22:52 UTC 2026