egl.html revision 6fd8b6a9e22f474117281b00d15c548c29b8197f
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. This variable is ignored for setuid/setgid 135binaries.</p> 136 137</li> 138 139<li><code>EGL_DRIVER</code> 140 141<p>This variable specifies a full path to an EGL driver and it forces the 142specified EGL driver to be loaded. It comes in handy when one wants to test a 143specific driver. This variable is ignored for setuid/setgid binaries.</p> 144 145</li> 146 147<li><code>EGL_DISPLAY</code> 148 149<p>When <code>EGL_DRIVER</code> is not set, the main library loads <em>all</em> 150EGL drivers that support a certain window system. <code>EGL_DISPLAY</code> can 151be used to specify the window system and the valid values are, for example, 152<code>x11</code> or <code>kms</code>. When the variable is not set, the main 153library defaults the value to the first window system listed in 154<code>--with-egl-displays</code> at configuration time. 155 156</li> 157 158<li><code>EGL_LOG_LEVEL</code> 159 160<p>This changes the log level of the main library and the drivers. The valid 161values are: <code>debug</code>, <code>info</code>, <code>warning</code>, and 162<code>fatal</code>.</p> 163 164</li> 165 166<li><code>EGL_SOFTWARE</code> 167 168<p>For drivers that support both hardware and software rendering, setting this 169variable to true forces the use of software rendering.</p> 170 171</li> 172</ul> 173 174<h2>EGL Drivers</h2> 175 176<p>There are two categories of EGL drivers: Gallium and classic.</p> 177 178<p>Gallium EGL drivers supports all rendering APIs specified in EGL 1.4. The 179support for optional EGL functions and EGL extensions is usually more complete 180than the classic ones. These drivers depend on the <code>egl</code> state 181tracker to build. The available drivers are</p> 182 183<ul> 184<li><code>egl_<dpy>_i915</code></li> 185<li><code>egl_<dpy>_i965</code></li> 186<li><code>egl_<dpy>_radeon</code></li> 187<li><code>egl_<dpy>_nouveau</code></li> 188<li><code>egl_<dpy>_swrast</code></li> 189<li><code>egl_<dpy>_vmwgfx</code></li> 190</ul> 191 192<p><code><dpy></code> is given by <code>--with-egl-displays</code> at 193configuration time. There will be one EGL driver for each combination of the 194displays listed and the hardware drivers enabled.</p> 195 196<p>Classic EGL drivers, on the other hand, supports only OpenGL as its 197rendering API. They can be found under <code>src/egl/drivers/</code>. There 198are 3 of them</p> 199 200<ul> 201<li><code>egl_glx</code> 202 203<p>This driver provides a wrapper to GLX. It uses exclusively GLX to implement 204the EGL API. It supports both direct and indirect rendering when the GLX does. 205It is accelerated when the GLX is. As such, it cannot provide functions that 206is not available in GLX or GLX extensions.</p> 207</li> 208 209<li><code>egl_xdri</code> 210 211<p>This driver supports the X Window System as its window system. It functions 212as a DRI driver loader and can load DRI/DRI2/DRISW drivers. Unlike 213<code>egl_glx</code>, it has no dependency on <code>libGL</code>. It talks to 214the X server directly using DRI or DRI2 protocols. It also talks minimal GLX 215protocol for things like available visuals or fbconfigs. With direct access to 216the DRI drivers, it has the potential to support more EGL functions that are 217not possible with <code>egl_glx</code>.</p> 218 219</li> 220<li><code>egl_dri</code> 221 222<p>This driver lacks maintenance and does <em>not</em> build. It is similiar 223to <code>egl_xdri</code> in that it functions as a DRI driver loader. But 224unlike <code>egl_xdri</code>, it supports Linux framebuffer devices as its 225window system and supports EGL_MESA_screen_surface extension. It loads only 226DRI1 drivers. As DRI1 drivers is phasing out, it might be better to rewrite 227the driver to support KMS and DRI2.</p> 228 229</li> 230</ul> 231 232<p>To use the classic drivers, one must manually set <code>EGL_DRIVER</code> at 233runtime.</p> 234 235<h2>Developers</h2> 236 237<p>The sources of the main library and the classic drivers can be found at 238<code>src/egl/</code>. The sources of the <code>egl</code> state tracker can 239be found at <code>src/gallium/state_trackers/egl/</code>.</p> 240 241<p>The suggested way to learn to write a EGL driver is to see how other drivers 242are written. <code>egl_glx</code> should be a good reference. It works in any 243environment that has GLX support, and it is simpler than most drivers.</p> 244 245<h3>Lifetime of Display Resources</h3> 246 247<p>Contexts and surfaces are examples of display resources. They might live 248longer than the display that creates them.</p> 249 250<p>In EGL, when a display is terminated through <code>eglTerminate</code>, all 251display resources should be destroyed. Similarly, when a thread is released 252throught <code>eglReleaseThread</code>, all current display resources should be 253released. Another way to destory or release resources is through functions 254such as <code>eglDestroySurface</code> or <code>eglMakeCurrent</code>.</p> 255 256<p>When a resource that is current to some thread is destroyed, the resource 257should not be destroyed immediately. EGL requires the resource to live until 258it is no longer current. A driver usually calls 259<code>eglIs<Resource>Bound</code> to check if a resource is bound 260(current) to any thread in the destroy callbacks. If it is still bound, the 261resource is not destroyed.</p> 262 263<p>The main library will mark destroyed current resources as unlinked. In a 264driver's <code>MakeCurrent</code> callback, 265<code>eglIs<Resource>Linked</code> can then be called to check if a newly 266released resource is linked to a display. If it is not, the last reference to 267the resource is removed and the driver should destroy the resource. But it 268should be careful here because <code>MakeCurrent</code> might be called with an 269uninitialized display.</p> 270 271<p>This is the only mechanism provided by the main library to help manage the 272resources. The drivers are responsible to the correct behavior as defined by 273EGL.</p> 274 275<h3>TODOs</h3> 276 277<ul> 278<li>Thread safety</li> 279<li>Pass the conformance tests</li> 280<li>Better automatic driver selection: <code>EGL_DISPLAY</code> loads all 281drivers and might eat too much memory.</li> 282<li>Stop using <code>glxinit.c</code> and sources from <code>src/glx/x11/</code></li> 283 284</ul> 285 286</body> 287</html> 288