egl.html revision 5d8646c41ff3022692fa9d7f5f1644a2a60641e4
1<html> 2 3<title>Mesa EGL</title> 4 5<head><link rel="stylesheet" type="text/css" href="mesa.css"></head> 6 7<body> 8 9<h1>Mesa EGL</h1> 10 11<p>The current version of EGL in Mesa implements EGL 1.4. More information 12about EGL can be found at 13<a href="http://www.khronos.org/egl/" target="_parent"> 14http://www.khronos.org/egl/</a>.</p> 15 16<p>The Mesa's implementation of EGL uses a driver architecture. The main 17library (<code>libEGL</code>) is window system neutral. It provides the EGL 18API entry points and helper functions for use by the drivers. Drivers are 19dynamically loaded by the main library and most of the EGL API calls are 20directly dispatched to the drivers.</p> 21 22<p>The driver in use decides the window system to support. For drivers that 23support hardware rendering, there are usually multiple drivers supporting the 24same window system. Each one of of them supports a certain range of graphics 25cards.</p> 26 27<h2>Build EGL</h2> 28 29<ol> 30<li> 31<p>Run <code>configure</code> with the desired state trackers and and enable 32the Gallium driver for your hardware. For example</p> 33 34<pre> 35 $ /configure --with-state-trackers=egl,es,vega --enable-gallium-{swrast,intel} 36</pre> 37 38<p>The main library will be enabled by default. The <code>egl</code> state 39tracker is needed by a number of EGL drivers. EGL drivers will be covered 40later. The <a href="opengles.html">es state tracker</a> provides OpenGL ES 1.x 41and 2.x and the <a href="openvg.html">vega state tracker</a> provides OpenVG 421.x.</p> 43</li> 44 45<li>Build and install Mesa as usual.</li> 46</ol> 47 48<p>In the given example, it will build and install <code>libEGL</code>, 49<code>libGLESv1_CM</code>, <code>libGLESv2</code>, <code>libOpenVG</code>, and 50one or more EGL drivers.</p> 51 52<h3>Configure Options</h3> 53 54<p>There are several options that control the build of EGL at configuration 55time</p> 56 57<ul> 58<li><code>--enable-egl</code> 59 60<p>By default, EGL is enabled. When disabled, the main library and the drivers 61will not be built.</p> 62 63</li> 64 65<li><code>--with-egl-driver-dir</code> 66 67<p>The directory EGL drivers should be installed to. If not specified, EGL 68drivers will be installed to <code>${libdir}/egl</code>.</p> 69 70</li> 71 72<li><code>--with-egl-displays</code> 73 74<p>List the window system(s) to support. It is by default <code>x11</code>, 75which supports the X Window System. Its argument is a comma separated string 76like, for example, <code>--with-egl-displays=x11,kms</code>. Because an EGL 77driver decides which window system to support, this example will enable two 78(sets of) EGL drivers. One supports the X window system and the other supports 79bare KMS (kernel modesetting).</p> 80 81</li> 82 83<li><code>--with-state-trackers</code> 84 85<p>The argument is a comma separated string. It is usually used to specify the 86rendering APIs, like OpenGL ES or OpenVG, to build. But it should be noted 87that a number of EGL drivers depend on the <code>egl</code> state tracker. 88They will <em>not</em> be built without the <code>egl</code> state tracker.</p> 89 90</li> 91 92<li><code>--enable-gallium-swrast</code> 93 94<p>This option is not specific to EGL. But if there is no driver for your 95hardware, or you are experiencing problems with the hardware driver, you can 96enable the swrast DRM driver. It is a dummy driver and EGL will fallback to 97software rendering automatically.</p> 98 99</li> 100</ul> 101 102<h3>OpenGL</h3> 103 104<p>The OpenGL state tracker is not built in the above example. It should be 105noted that the classic <code>libGL</code> is not a state tracker and cannot be 106used with EGL (unless the EGL driver in use is <code>egl_glx</code>). To build 107the OpenGL state tracker, one may append <code>glx</code> to 108<code>--with-state-trackers</code> and manually build 109<code>src/gallium/winsys/xlib/</code>.</p> 110 111<h2>Use EGL</h2> 112 113<p> The demos for OpenGL ES and OpenVG can be found in <code>progs/es1/</code>, 114<code>progs/es2/</code> and <code>progs/openvg/</code>. You can use them to 115test your build. For example,</p> 116 117<pre> 118 $ cd progs/es1/xegl 119 $ make 120 $ /torus 121</pre> 122 123<h3>Environment Variables</h3> 124 125<p>There are several environment variables that control the behavior of EGL at 126runtime</p> 127 128<ul> 129<li><code>EGL_DRIVERS_PATH</code> 130 131<p>By default, the main library will look for drivers in the directory where 132the drivers are installed to. This variable specifies a list of 133colon-separated directories where the main library will look for drivers, in 134addition to the default directory.</p> 135 136</li> 137 138<li><code>EGL_DRIVER</code> 139 140<p>This variable specifies a full path to an EGL driver and it forces the 141specified EGL driver to be loaded. It comes in handy when one wants to test a 142specific driver.</p> 143 144</li> 145 146<li><code>EGL_DISPLAY</code> 147 148<p>When <code>EGL_DRIVER</code> is not set, the main library loads <em>all</em> 149EGL drivers that support a certain window system. <code>EGL_DISPLAY</code> can 150be used to specify the window system and the valid values are, for example, 151<code>x11</code> or <code>kms</code>. When the variable is not set, the main 152library defaults the value to the first window system listed in 153<code>--with-egl-displays</code> at configuration time. 154 155</li> 156 157<li><code>EGL_LOG_LEVEL</code> 158 159<p>This changes the log level of the main library and the drivers. The valid 160values are: <code>debug</code>, <code>info</code>, <code>warning</code>, and 161<code>fatal</code>.</p> 162 163</li> 164 165<li><code>EGL_SOFTWARE</code> 166 167<p>For drivers that support both hardware and software rendering, setting this 168variable to true forces the use of software rendering.</p> 169 170</li> 171</ul> 172 173<h2>EGL Drivers</h2> 174 175<p>There are two categories of EGL drivers: Gallium and classic.</p> 176 177<p>Gallium EGL drivers supports all rendering APIs specified in EGL 1.4. The 178support for optional EGL functions and EGL extensions is usually more complete 179than the classic ones. These drivers depend on the <code>egl</code> state 180tracker to build. The available drivers are</p> 181 182<ul> 183<li><code>egl_<dpy>_i915</code></li> 184<li><code>egl_<dpy>_i965</code></li> 185<li><code>egl_<dpy>_radeon</code></li> 186<li><code>egl_<dpy>_nouveau</code></li> 187<li><code>egl_<dpy>_swrast</code></li> 188<li><code>egl_<dpy>_vmwgfx</code></li> 189</ul> 190 191<p><code><dpy></code> is given by <code>--with-egl-displays</code> at 192configuration time. There will be one EGL driver for each combination of the 193displays listed and the hardware drivers enabled.</p> 194 195<p>Classic EGL drivers, on the other hand, supports only OpenGL as its 196rendering API. They can be found under <code>src/egl/drivers/</code>. There 197are 3 of them</p> 198 199<ul> 200<li><code>egl_glx</code> 201 202<p>This driver provides a wrapper to GLX. It uses exclusively GLX to implement 203the EGL API. It supports both direct and indirect rendering when the GLX does. 204It is accelerated when the GLX is. As such, it cannot provide functions that 205is not available in GLX or GLX extensions.</p> 206</li> 207 208<li><code>egl_xdri</code> 209 210<p>This driver supports the X Window System as its window system. It functions 211as a DRI driver loader and can load DRI/DRI2/DRISW drivers. Unlike 212<code>egl_glx</code>, it has no dependency on <code>libGL</code>. It talks to 213the X server directly using DRI or DRI2 protocols. It also talks minimal GLX 214protocol for things like available visuals or fbconfigs. With direct access to 215the DRI drivers, it has the potential to support more EGL functions that are 216not possible with <code>egl_glx</code>.</p> 217 218</li> 219<li><code>egl_dri</code> 220 221<p>This driver lacks maintenance and does <em>not</em> build. It is similiar 222to <code>egl_xdri</code> in that it functions as a DRI driver loader. But 223unlike <code>egl_xdri</code>, it supports Linux framebuffer devices as its 224window system and supports EGL_MESA_screen_surface extension. It loads only 225DRI1 drivers. As DRI1 drivers is phasing out, it might be better to rewrite 226the driver to support KMS and DRI2.</p> 227 228</li> 229</ul> 230 231<p>To use the classic drivers, one must manually set <code>EGL_DRIVER</code> at 232runtime.</p> 233 234<h2>Developers</h2> 235 236<p>The sources of the main library and the classic drivers can be found at 237<code>src/egl/</code>. The sources of the <code>egl</code> state tracker can 238be found at <code>src/gallium/state_trackers/egl/</code>.</p> 239 240<p>The suggested way to learn to write a EGL driver is to see how other drivers 241are written. <code>egl_glx</code> should be a good reference. It works in any 242environment that has GLX support, and it is simpler than most drivers.</p> 243 244<h3>Lifetime of Display Resources</h3> 245 246<p>Contexts and surfaces are examples of display resources. They might live 247longer than the display that creates them.</p> 248 249<p>In EGL, when a display is terminated through <code>eglTerminate</code>, all 250display resources should be destroyed. Similarly, when a thread is released 251throught <code>eglReleaseThread</code>, all current display resources should be 252released. Another way to destory or release resources is through functions 253such as <code>eglDestroySurface</code> or <code>eglMakeCurrent</code>.</p> 254 255<p>When a resource that is current to some thread is destroyed, the resource 256should not be destroyed immediately. EGL requires the resource to live until 257it is no longer current. A driver usually calls 258<code>eglIs<Resource>Bound</code> to check if a resource is bound 259(current) to any thread in the destroy callbacks. If it is still bound, the 260resource is not destroyed.</p> 261 262<p>The main library will mark destroyed current resources as unlinked. In a 263driver's <code>MakeCurrent</code> callback, 264<code>eglIs<Resource>Linked</code> can then be called to check if a newly 265released resource is linked to a display. If it is not, the last reference to 266the resource is removed and the driver should destroy the resource. But it 267should be careful here because <code>MakeCurrent</code> might be called with an 268uninitialized display.</p> 269 270<p>This is the only mechanism provided by the main library to help manage the 271resources. The drivers are responsible to the correct behavior as defined by 272EGL.</p> 273 274<h3>TODOs</h3> 275 276<ul> 277<li>Thread safety</li> 278<li>Pass the conformance tests</li> 279<li>Better automatic driver selection: <code>EGL_DISPLAY</code> loads all 280drivers and might eat too much memory.</li> 281<li>Stop using <code>glxinit.c</code> and sources from <code>src/glx/x11/</code></li> 282 283</ul> 284 285</body> 286</html> 287