Chia-I Wu | ada4605 | 2010-01-21 15:29:14 +0800 | [diff] [blame] | 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 |
| 12 | about EGL can be found at |
Brian Paul | aeff9f9 | 2010-01-21 08:13:32 -0700 | [diff] [blame] | 13 | <a href="http://www.khronos.org/egl/" target="_parent"> |
| 14 | http://www.khronos.org/egl/</a>.</p> |
Chia-I Wu | ada4605 | 2010-01-21 15:29:14 +0800 | [diff] [blame] | 15 | |
| 16 | <p>The Mesa's implementation of EGL uses a driver architecture. The main |
| 17 | library (<code>libEGL</code>) is window system neutral. It provides the EGL |
| 18 | API entry points and helper functions for use by the drivers. Drivers are |
| 19 | dynamically loaded by the main library and most of the EGL API calls are |
| 20 | directly dispatched to the drivers.</p> |
| 21 | |
| 22 | <p>The driver in use decides the window system to support. For drivers that |
| 23 | support hardware rendering, there are usually multiple drivers supporting the |
| 24 | same window system. Each one of of them supports a certain range of graphics |
| 25 | cards.</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 |
| 32 | the Gallium driver for your hardware. For example</p> |
| 33 | |
| 34 | <pre> |
Chia-I Wu | a6342af | 2010-01-26 10:54:45 +0800 | [diff] [blame] | 35 | $ ./configure --with-state-trackers=egl,es,vega --enable-gallium-{swrast,intel} |
Chia-I Wu | ada4605 | 2010-01-21 15:29:14 +0800 | [diff] [blame] | 36 | </pre> |
| 37 | |
Chia-I Wu | 3c967a9 | 2010-01-22 16:31:43 +0800 | [diff] [blame] | 38 | <p>The main library will be enabled by default. The <code>egl</code> state |
Chia-I Wu | ada4605 | 2010-01-21 15:29:14 +0800 | [diff] [blame] | 39 | tracker is needed by a number of EGL drivers. EGL drivers will be covered |
| 40 | later. The <a href="opengles.html">es state tracker</a> provides OpenGL ES 1.x |
| 41 | and 2.x and the <a href="openvg.html">vega state tracker</a> provides OpenVG |
| 42 | 1.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 |
| 50 | one 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 |
| 55 | time</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 |
| 61 | will not be built.</p> |
| 62 | |
| 63 | </li> |
| 64 | |
Chia-I Wu | a6342af | 2010-01-26 10:54:45 +0800 | [diff] [blame] | 65 | <li><code>--with-egl-driver-dir</code> |
| 66 | |
| 67 | <p>The directory EGL drivers should be installed to. If not specified, EGL |
| 68 | drivers will be installed to <code>${libdir}/egl</code>.</p> |
| 69 | |
| 70 | </li> |
| 71 | |
Chia-I Wu | ada4605 | 2010-01-21 15:29:14 +0800 | [diff] [blame] | 72 | <li><code>--with-egl-displays</code> |
| 73 | |
| 74 | <p>List the window system(s) to support. It is by default <code>x11</code>, |
| 75 | which supports the X Window System. Its argument is a comma separated string |
| 76 | like, for example, <code>--with-egl-displays=x11,kms</code>. Because an EGL |
| 77 | driver 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 |
| 79 | bare 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 |
| 86 | rendering APIs, like OpenGL ES or OpenVG, to build. But it should be noted |
Chia-I Wu | 3c967a9 | 2010-01-22 16:31:43 +0800 | [diff] [blame] | 87 | that a number of EGL drivers depend on the <code>egl</code> state tracker. |
| 88 | They will <em>not</em> be built without the <code>egl</code> state tracker.</p> |
Chia-I Wu | ada4605 | 2010-01-21 15:29:14 +0800 | [diff] [blame] | 89 | |
| 90 | </li> |
Chia-I Wu | a1306f4 | 2010-01-22 15:51:51 +0800 | [diff] [blame] | 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 |
| 95 | hardware, or you are experiencing problems with the hardware driver, you can |
| 96 | enable the swrast DRM driver. It is a dummy driver and EGL will fallback to |
| 97 | software rendering automatically.</p> |
| 98 | |
| 99 | </li> |
Chia-I Wu | ada4605 | 2010-01-21 15:29:14 +0800 | [diff] [blame] | 100 | </ul> |
| 101 | |
| 102 | <h3>OpenGL</h3> |
| 103 | |
| 104 | <p>The OpenGL state tracker is not built in the above example. It should be |
| 105 | noted that the classic <code>libGL</code> is not a state tracker and cannot be |
| 106 | used with EGL (unless the EGL driver in use is <code>egl_glx</code>). To build |
| 107 | the 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 |
| 115 | test 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 |
| 126 | runtime</p> |
| 127 | |
| 128 | <ul> |
Chia-I Wu | 5d8646c | 2010-02-02 15:34:55 +0800 | [diff] [blame] | 129 | <li><code>EGL_DRIVERS_PATH</code> |
| 130 | |
| 131 | <p>By default, the main library will look for drivers in the directory where |
| 132 | the drivers are installed to. This variable specifies a list of |
| 133 | colon-separated directories where the main library will look for drivers, in |
Chia-I Wu | 6fd8b6a | 2010-02-02 16:47:53 +0800 | [diff] [blame^] | 134 | addition to the default directory. This variable is ignored for setuid/setgid |
| 135 | binaries.</p> |
Chia-I Wu | 5d8646c | 2010-02-02 15:34:55 +0800 | [diff] [blame] | 136 | |
| 137 | </li> |
| 138 | |
Chia-I Wu | ada4605 | 2010-01-21 15:29:14 +0800 | [diff] [blame] | 139 | <li><code>EGL_DRIVER</code> |
| 140 | |
Chia-I Wu | 7fc3581 | 2010-02-02 11:05:19 +0800 | [diff] [blame] | 141 | <p>This variable specifies a full path to an EGL driver and it forces the |
| 142 | specified EGL driver to be loaded. It comes in handy when one wants to test a |
Chia-I Wu | 6fd8b6a | 2010-02-02 16:47:53 +0800 | [diff] [blame^] | 143 | specific driver. This variable is ignored for setuid/setgid binaries.</p> |
Chia-I Wu | ada4605 | 2010-01-21 15:29:14 +0800 | [diff] [blame] | 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> |
| 150 | EGL drivers that support a certain window system. <code>EGL_DISPLAY</code> can |
| 151 | be 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 |
| 153 | library 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 |
| 161 | values 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 |
| 169 | variable 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 |
| 179 | support for optional EGL functions and EGL extensions is usually more complete |
Chia-I Wu | 3c967a9 | 2010-01-22 16:31:43 +0800 | [diff] [blame] | 180 | than the classic ones. These drivers depend on the <code>egl</code> state |
Chia-I Wu | ada4605 | 2010-01-21 15:29:14 +0800 | [diff] [blame] | 181 | tracker 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> |
Chia-I Wu | a1306f4 | 2010-01-22 15:51:51 +0800 | [diff] [blame] | 188 | <li><code>egl_<dpy>_swrast</code></li> |
Chia-I Wu | ada4605 | 2010-01-21 15:29:14 +0800 | [diff] [blame] | 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 |
| 193 | configuration time. There will be one EGL driver for each combination of the |
| 194 | displays listed and the hardware drivers enabled.</p> |
| 195 | |
| 196 | <p>Classic EGL drivers, on the other hand, supports only OpenGL as its |
| 197 | rendering API. They can be found under <code>src/egl/drivers/</code>. There |
| 198 | are 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 |
| 204 | the EGL API. It supports both direct and indirect rendering when the GLX does. |
| 205 | It is accelerated when the GLX is. As such, it cannot provide functions that |
| 206 | is 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 |
Chia-I Wu | 29732f9 | 2010-01-22 15:05:31 +0800 | [diff] [blame] | 212 | as 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 |
| 214 | the X server directly using DRI or DRI2 protocols. It also talks minimal GLX |
| 215 | protocol for things like available visuals or fbconfigs. With direct access to |
| 216 | the DRI drivers, it has the potential to support more EGL functions that are |
| 217 | not possible with <code>egl_glx</code>.</p> |
Chia-I Wu | ada4605 | 2010-01-21 15:29:14 +0800 | [diff] [blame] | 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 |
| 223 | to <code>egl_xdri</code> in that it functions as a DRI driver loader. But |
| 224 | unlike <code>egl_xdri</code>, it supports Linux framebuffer devices as its |
| 225 | window system and supports EGL_MESA_screen_surface extension. It loads only |
| 226 | DRI1 drivers. As DRI1 drivers is phasing out, it might be better to rewrite |
| 227 | the 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 |
| 233 | runtime.</p> |
| 234 | |
| 235 | <h2>Developers</h2> |
| 236 | |
Chia-I Wu | 14cbf32 | 2010-01-27 23:18:22 +0800 | [diff] [blame] | 237 | <p>The sources of the main library and the classic drivers can be found at |
Chia-I Wu | 3c967a9 | 2010-01-22 16:31:43 +0800 | [diff] [blame] | 238 | <code>src/egl/</code>. The sources of the <code>egl</code> state tracker can |
Chia-I Wu | 14cbf32 | 2010-01-27 23:18:22 +0800 | [diff] [blame] | 239 | be 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 |
| 242 | are written. <code>egl_glx</code> should be a good reference. It works in any |
| 243 | environment 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 |
| 248 | longer than the display that creates them.</p> |
| 249 | |
| 250 | <p>In EGL, when a display is terminated through <code>eglTerminate</code>, all |
| 251 | display resources should be destroyed. Similarly, when a thread is released |
| 252 | throught <code>eglReleaseThread</code>, all current display resources should be |
| 253 | released. Another way to destory or release resources is through functions |
| 254 | such 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 |
| 257 | should not be destroyed immediately. EGL requires the resource to live until |
| 258 | it 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 |
| 261 | resource is not destroyed.</p> |
| 262 | |
| 263 | <p>The main library will mark destroyed current resources as unlinked. In a |
| 264 | driver's <code>MakeCurrent</code> callback, |
| 265 | <code>eglIs<Resource>Linked</code> can then be called to check if a newly |
| 266 | released resource is linked to a display. If it is not, the last reference to |
| 267 | the resource is removed and the driver should destroy the resource. But it |
| 268 | should be careful here because <code>MakeCurrent</code> might be called with an |
| 269 | uninitialized display.</p> |
| 270 | |
| 271 | <p>This is the only mechanism provided by the main library to help manage the |
| 272 | resources. The drivers are responsible to the correct behavior as defined by |
| 273 | EGL.</p> |
Chia-I Wu | ada4605 | 2010-01-21 15:29:14 +0800 | [diff] [blame] | 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 |
| 281 | drivers and might eat too much memory.</li> |
Chia-I Wu | a6342af | 2010-01-26 10:54:45 +0800 | [diff] [blame] | 282 | <li>Stop using <code>glxinit.c</code> and sources from <code>src/glx/x11/</code></li> |
Chia-I Wu | ada4605 | 2010-01-21 15:29:14 +0800 | [diff] [blame] | 283 | |
| 284 | </ul> |
| 285 | |
| 286 | </body> |
| 287 | </html> |