egl.html revision 5f08eff2a769e27df37fc00e46797e70a54727bb
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_dri2</code> 210 211<p>This driver supports the X Window System as its window system. It functions 212as a DRI2 driver loader. Unlike <code>egl_glx</code>, it has no dependency on 213<code>libGL</code>. It talks to the X server directly using DRI2 protocol.</p> 214 215</li> 216<li><code>egl_dri</code> 217 218<p>This driver lacks maintenance and does <em>not</em> build. It is similiar 219to <code>egl_dri2</code> in that it functions as a DRI(1) driver loader. But 220unlike <code>egl_dri2</code>, it supports Linux framebuffer devices as its 221window system and supports EGL_MESA_screen_surface extension. As DRI1 drivers 222are phasing out, it might eventually be replaced by <code>egl_dri2</code>.</p> 223 224</li> 225</ul> 226 227<p>To use the classic drivers, one must manually set <code>EGL_DRIVER</code> at 228runtime.</p> 229 230<h2>Developers</h2> 231 232<p>The sources of the main library and the classic drivers can be found at 233<code>src/egl/</code>. The sources of the <code>egl</code> state tracker can 234be found at <code>src/gallium/state_trackers/egl/</code>.</p> 235 236<p>The suggested way to learn to write a EGL driver is to see how other drivers 237are written. <code>egl_glx</code> should be a good reference. It works in any 238environment that has GLX support, and it is simpler than most drivers.</p> 239 240<h3>Lifetime of Display Resources</h3> 241 242<p>Contexts and surfaces are examples of display resources. They might live 243longer than the display that creates them.</p> 244 245<p>In EGL, when a display is terminated through <code>eglTerminate</code>, all 246display resources should be destroyed. Similarly, when a thread is released 247throught <code>eglReleaseThread</code>, all current display resources should be 248released. Another way to destory or release resources is through functions 249such as <code>eglDestroySurface</code> or <code>eglMakeCurrent</code>.</p> 250 251<p>When a resource that is current to some thread is destroyed, the resource 252should not be destroyed immediately. EGL requires the resource to live until 253it is no longer current. A driver usually calls 254<code>eglIs<Resource>Bound</code> to check if a resource is bound 255(current) to any thread in the destroy callbacks. If it is still bound, the 256resource is not destroyed.</p> 257 258<p>The main library will mark destroyed current resources as unlinked. In a 259driver's <code>MakeCurrent</code> callback, 260<code>eglIs<Resource>Linked</code> can then be called to check if a newly 261released resource is linked to a display. If it is not, the last reference to 262the resource is removed and the driver should destroy the resource. But it 263should be careful here because <code>MakeCurrent</code> might be called with an 264uninitialized display.</p> 265 266<p>This is the only mechanism provided by the main library to help manage the 267resources. The drivers are responsible to the correct behavior as defined by 268EGL.</p> 269 270<h3>TODOs</h3> 271 272<ul> 273<li>Thread safety</li> 274<li>Pass the conformance tests</li> 275<li>Better automatic driver selection: <code>EGL_DISPLAY</code> loads all 276drivers and might eat too much memory.</li> 277<li>Stop using <code>glxinit.c</code> and sources from <code>src/glx/x11/</code></li> 278 279</ul> 280 281</body> 282</html> 283