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> |
Jeff Smith | fab1f07 | 2008-06-13 09:50:43 -0500 | [diff] [blame] | 31 | <p>Run <code>configure</code> with the desired state trackers and enable |
Chia-I Wu | ada4605 | 2010-01-21 15:29:14 +0800 | [diff] [blame] | 32 | the Gallium driver for your hardware. For example</p> |
| 33 | |
| 34 | <pre> |
Chia-I Wu | 2e3c4e4 | 2010-05-07 14:13:08 +0800 | [diff] [blame] | 35 | $ ./configure --enable-gles-overlay --with-state-trackers=egl,vega --enable-gallium-{swrast,intel} |
Chia-I Wu | ada4605 | 2010-01-21 15:29:14 +0800 | [diff] [blame] | 36 | </pre> |
| 37 | |
Chia-I Wu | 2e3c4e4 | 2010-05-07 14:13:08 +0800 | [diff] [blame] | 38 | <p>The main library and OpenGL is enabled by default. The first option enables |
| 39 | <a href="opengles.html">OpenGL ES 1.x and 2.x</a>. The <code>egl</code> state |
Chia-I Wu | ada4605 | 2010-01-21 15:29:14 +0800 | [diff] [blame] | 40 | tracker is needed by a number of EGL drivers. EGL drivers will be covered |
Chia-I Wu | 2e3c4e4 | 2010-05-07 14:13:08 +0800 | [diff] [blame] | 41 | later. The <a href="openvg.html">vega state tracker</a> provides OpenVG |
Chia-I Wu | ada4605 | 2010-01-21 15:29:14 +0800 | [diff] [blame] | 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>, |
Chia-I Wu | 2e3c4e4 | 2010-05-07 14:13:08 +0800 | [diff] [blame] | 49 | <code>libGL</code>, <code>libGLESv1_CM</code>, <code>libGLESv2</code>, |
| 50 | <code>libOpenVG</code>, and one or more EGL drivers.</p> |
Chia-I Wu | ada4605 | 2010-01-21 15:29:14 +0800 | [diff] [blame] | 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 |
Chia-I Wu | 2e3c4e4 | 2010-05-07 14:13:08 +0800 | [diff] [blame] | 86 | rendering APIs, such as OpenVG, to build. But it should be noted that a number |
| 87 | of EGL drivers depend on the <code>egl</code> state tracker. They will |
| 88 | <em>not</em> be built without the <code>egl</code> state tracker.</p> |
| 89 | |
| 90 | </li> |
| 91 | |
| 92 | <li><code>--enable-gles-overlay</code> |
| 93 | |
| 94 | <p>OpenGL and OpenGL ES are not controlled by |
| 95 | <code>--with-state-trackers</code>. OpenGL is always built. To build OpenGL |
| 96 | ES, this option must be explicitly given.</p> |
| 97 | |
| 98 | </li> |
| 99 | |
| 100 | <li><code>--enable-gles1</code> and <code>--enable-gles2</code> |
| 101 | |
| 102 | <p>Unlike <code>--enable-gles-overlay</code>, which builds one library for each |
| 103 | rendering API, these options enable OpenGL ES support in OpenGL. The result is |
| 104 | one big library that supports multiple APIs. This is used by DRI drivers and |
| 105 | <code>egl_dri2</code> EGL driver. |
Chia-I Wu | ada4605 | 2010-01-21 15:29:14 +0800 | [diff] [blame] | 106 | |
| 107 | </li> |
Chia-I Wu | a1306f4 | 2010-01-22 15:51:51 +0800 | [diff] [blame] | 108 | |
| 109 | <li><code>--enable-gallium-swrast</code> |
| 110 | |
| 111 | <p>This option is not specific to EGL. But if there is no driver for your |
| 112 | hardware, or you are experiencing problems with the hardware driver, you can |
| 113 | enable the swrast DRM driver. It is a dummy driver and EGL will fallback to |
| 114 | software rendering automatically.</p> |
| 115 | |
| 116 | </li> |
Chia-I Wu | ada4605 | 2010-01-21 15:29:14 +0800 | [diff] [blame] | 117 | </ul> |
| 118 | |
Chia-I Wu | ada4605 | 2010-01-21 15:29:14 +0800 | [diff] [blame] | 119 | <h2>Use EGL</h2> |
| 120 | |
Chia-I Wu | 2e3c4e4 | 2010-05-07 14:13:08 +0800 | [diff] [blame] | 121 | <p>There are demos for the client APIs supported by EGL. They can be found in |
| 122 | <code>progs/egl/</code>, You can use them to test your build. For example,</p> |
Chia-I Wu | ada4605 | 2010-01-21 15:29:14 +0800 | [diff] [blame] | 123 | |
| 124 | <pre> |
Chia-I Wu | 2e3c4e4 | 2010-05-07 14:13:08 +0800 | [diff] [blame] | 125 | $ cd progs/egl/eglut |
Chia-I Wu | ada4605 | 2010-01-21 15:29:14 +0800 | [diff] [blame] | 126 | $ make |
Chia-I Wu | 2e3c4e4 | 2010-05-07 14:13:08 +0800 | [diff] [blame] | 127 | $ cd ../opengles1 |
| 128 | $ make |
| 129 | $ ./torus_x11 |
Chia-I Wu | ada4605 | 2010-01-21 15:29:14 +0800 | [diff] [blame] | 130 | </pre> |
| 131 | |
| 132 | <h3>Environment Variables</h3> |
| 133 | |
| 134 | <p>There are several environment variables that control the behavior of EGL at |
| 135 | runtime</p> |
| 136 | |
| 137 | <ul> |
Chia-I Wu | 5d8646c | 2010-02-02 15:34:55 +0800 | [diff] [blame] | 138 | <li><code>EGL_DRIVERS_PATH</code> |
| 139 | |
| 140 | <p>By default, the main library will look for drivers in the directory where |
| 141 | the drivers are installed to. This variable specifies a list of |
| 142 | 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] | 143 | addition to the default directory. This variable is ignored for setuid/setgid |
| 144 | binaries.</p> |
Chia-I Wu | 5d8646c | 2010-02-02 15:34:55 +0800 | [diff] [blame] | 145 | |
| 146 | </li> |
| 147 | |
Chia-I Wu | ada4605 | 2010-01-21 15:29:14 +0800 | [diff] [blame] | 148 | <li><code>EGL_DRIVER</code> |
| 149 | |
Chia-I Wu | 7fc3581 | 2010-02-02 11:05:19 +0800 | [diff] [blame] | 150 | <p>This variable specifies a full path to an EGL driver and it forces the |
| 151 | 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] | 152 | specific driver. This variable is ignored for setuid/setgid binaries.</p> |
Chia-I Wu | ada4605 | 2010-01-21 15:29:14 +0800 | [diff] [blame] | 153 | |
| 154 | </li> |
| 155 | |
| 156 | <li><code>EGL_DISPLAY</code> |
| 157 | |
| 158 | <p>When <code>EGL_DRIVER</code> is not set, the main library loads <em>all</em> |
| 159 | EGL drivers that support a certain window system. <code>EGL_DISPLAY</code> can |
| 160 | be used to specify the window system and the valid values are, for example, |
| 161 | <code>x11</code> or <code>kms</code>. When the variable is not set, the main |
| 162 | library defaults the value to the first window system listed in |
| 163 | <code>--with-egl-displays</code> at configuration time. |
| 164 | |
| 165 | </li> |
| 166 | |
| 167 | <li><code>EGL_LOG_LEVEL</code> |
| 168 | |
| 169 | <p>This changes the log level of the main library and the drivers. The valid |
| 170 | values are: <code>debug</code>, <code>info</code>, <code>warning</code>, and |
| 171 | <code>fatal</code>.</p> |
| 172 | |
| 173 | </li> |
| 174 | |
| 175 | <li><code>EGL_SOFTWARE</code> |
| 176 | |
| 177 | <p>For drivers that support both hardware and software rendering, setting this |
| 178 | variable to true forces the use of software rendering.</p> |
| 179 | |
| 180 | </li> |
| 181 | </ul> |
| 182 | |
| 183 | <h2>EGL Drivers</h2> |
| 184 | |
| 185 | <p>There are two categories of EGL drivers: Gallium and classic.</p> |
| 186 | |
| 187 | <p>Gallium EGL drivers supports all rendering APIs specified in EGL 1.4. The |
| 188 | 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] | 189 | 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] | 190 | tracker to build. The available drivers are</p> |
| 191 | |
| 192 | <ul> |
| 193 | <li><code>egl_<dpy>_i915</code></li> |
| 194 | <li><code>egl_<dpy>_i965</code></li> |
| 195 | <li><code>egl_<dpy>_radeon</code></li> |
| 196 | <li><code>egl_<dpy>_nouveau</code></li> |
Chia-I Wu | a1306f4 | 2010-01-22 15:51:51 +0800 | [diff] [blame] | 197 | <li><code>egl_<dpy>_swrast</code></li> |
Chia-I Wu | ada4605 | 2010-01-21 15:29:14 +0800 | [diff] [blame] | 198 | <li><code>egl_<dpy>_vmwgfx</code></li> |
| 199 | </ul> |
| 200 | |
| 201 | <p><code><dpy></code> is given by <code>--with-egl-displays</code> at |
| 202 | configuration time. There will be one EGL driver for each combination of the |
| 203 | displays listed and the hardware drivers enabled.</p> |
| 204 | |
| 205 | <p>Classic EGL drivers, on the other hand, supports only OpenGL as its |
| 206 | rendering API. They can be found under <code>src/egl/drivers/</code>. There |
| 207 | are 3 of them</p> |
| 208 | |
| 209 | <ul> |
| 210 | <li><code>egl_glx</code> |
| 211 | |
| 212 | <p>This driver provides a wrapper to GLX. It uses exclusively GLX to implement |
| 213 | the EGL API. It supports both direct and indirect rendering when the GLX does. |
| 214 | It is accelerated when the GLX is. As such, it cannot provide functions that |
| 215 | is not available in GLX or GLX extensions.</p> |
| 216 | </li> |
| 217 | |
Chia-I Wu | 5f08eff | 2010-02-05 11:46:28 +0800 | [diff] [blame] | 218 | <li><code>egl_dri2</code> |
Chia-I Wu | ada4605 | 2010-01-21 15:29:14 +0800 | [diff] [blame] | 219 | |
| 220 | <p>This driver supports the X Window System as its window system. It functions |
Chia-I Wu | 5f08eff | 2010-02-05 11:46:28 +0800 | [diff] [blame] | 221 | as a DRI2 driver loader. Unlike <code>egl_glx</code>, it has no dependency on |
| 222 | <code>libGL</code>. It talks to the X server directly using DRI2 protocol.</p> |
Chia-I Wu | ada4605 | 2010-01-21 15:29:14 +0800 | [diff] [blame] | 223 | |
| 224 | </li> |
| 225 | <li><code>egl_dri</code> |
| 226 | |
| 227 | <p>This driver lacks maintenance and does <em>not</em> build. It is similiar |
Chia-I Wu | 5f08eff | 2010-02-05 11:46:28 +0800 | [diff] [blame] | 228 | to <code>egl_dri2</code> in that it functions as a DRI(1) driver loader. But |
| 229 | unlike <code>egl_dri2</code>, it supports Linux framebuffer devices as its |
| 230 | window system and supports EGL_MESA_screen_surface extension. As DRI1 drivers |
| 231 | are phasing out, it might eventually be replaced by <code>egl_dri2</code>.</p> |
Chia-I Wu | ada4605 | 2010-01-21 15:29:14 +0800 | [diff] [blame] | 232 | |
| 233 | </li> |
| 234 | </ul> |
| 235 | |
| 236 | <p>To use the classic drivers, one must manually set <code>EGL_DRIVER</code> at |
| 237 | runtime.</p> |
| 238 | |
| 239 | <h2>Developers</h2> |
| 240 | |
Chia-I Wu | 14cbf32 | 2010-01-27 23:18:22 +0800 | [diff] [blame] | 241 | <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] | 242 | <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] | 243 | be found at <code>src/gallium/state_trackers/egl/</code>.</p> |
| 244 | |
| 245 | <p>The suggested way to learn to write a EGL driver is to see how other drivers |
| 246 | are written. <code>egl_glx</code> should be a good reference. It works in any |
| 247 | environment that has GLX support, and it is simpler than most drivers.</p> |
| 248 | |
| 249 | <h3>Lifetime of Display Resources</h3> |
| 250 | |
| 251 | <p>Contexts and surfaces are examples of display resources. They might live |
| 252 | longer than the display that creates them.</p> |
| 253 | |
| 254 | <p>In EGL, when a display is terminated through <code>eglTerminate</code>, all |
| 255 | display resources should be destroyed. Similarly, when a thread is released |
| 256 | throught <code>eglReleaseThread</code>, all current display resources should be |
| 257 | released. Another way to destory or release resources is through functions |
| 258 | such as <code>eglDestroySurface</code> or <code>eglMakeCurrent</code>.</p> |
| 259 | |
| 260 | <p>When a resource that is current to some thread is destroyed, the resource |
| 261 | should not be destroyed immediately. EGL requires the resource to live until |
| 262 | it is no longer current. A driver usually calls |
| 263 | <code>eglIs<Resource>Bound</code> to check if a resource is bound |
| 264 | (current) to any thread in the destroy callbacks. If it is still bound, the |
| 265 | resource is not destroyed.</p> |
| 266 | |
| 267 | <p>The main library will mark destroyed current resources as unlinked. In a |
| 268 | driver's <code>MakeCurrent</code> callback, |
| 269 | <code>eglIs<Resource>Linked</code> can then be called to check if a newly |
| 270 | released resource is linked to a display. If it is not, the last reference to |
| 271 | the resource is removed and the driver should destroy the resource. But it |
| 272 | should be careful here because <code>MakeCurrent</code> might be called with an |
| 273 | uninitialized display.</p> |
| 274 | |
| 275 | <p>This is the only mechanism provided by the main library to help manage the |
| 276 | resources. The drivers are responsible to the correct behavior as defined by |
| 277 | EGL.</p> |
Chia-I Wu | ada4605 | 2010-01-21 15:29:14 +0800 | [diff] [blame] | 278 | |
Chia-I Wu | 1b2b08c | 2010-02-05 12:44:45 +0800 | [diff] [blame] | 279 | <h3><code>EGL_RENDER_BUFFER</code></h3> |
| 280 | |
| 281 | <p>In EGL, the color buffer a context should try to render to is decided by the |
| 282 | binding surface. It should try to render to the front buffer if the binding |
| 283 | surface has <code>EGL_RENDER_BUFFER</code> set to |
| 284 | <code>EGL_SINGLE_BUFFER</code>; If the same context is later bound to a |
| 285 | surface with <code>EGL_RENDER_BUFFER</code> set to |
| 286 | <code>EGL_BACK_BUFFER</code>, the context should try to render to the back |
| 287 | buffer. However, the context is allowed to make the final decision as to which |
| 288 | color buffer it wants to or is able to render to.</p> |
| 289 | |
| 290 | <p>For pbuffer surfaces, the render buffer is always |
| 291 | <code>EGL_BACK_BUFFER</code>. And for pixmap surfaces, the render buffer is |
| 292 | always <code>EGL_SINGLE_BUFFER</code>. Unlike window surfaces, EGL spec |
| 293 | requires their <code>EGL_RENDER_BUFFER</code> values to be honored. As a |
| 294 | result, a driver should never set <code>EGL_PIXMAP_BIT</code> or |
| 295 | <code>EGL_PBUFFER_BIT</code> bits of a config if the contexts created with the |
| 296 | config won't be able to honor the <code>EGL_RENDER_BUFFER</code> of pixmap or |
| 297 | pbuffer surfaces.</p> |
| 298 | |
| 299 | <p>It should also be noted that pixmap and pbuffer surfaces are assumed to be |
| 300 | single-buffered, in that <code>eglSwapBuffers</code> has no effect on them. It |
| 301 | is desirable that a driver allocates a private color buffer for each pbuffer |
| 302 | surface created. If the window system the driver supports has native pbuffers, |
| 303 | or if the native pixmaps have more than one color buffers, the driver should |
| 304 | carefully attach the native color buffers to the EGL surfaces, re-route them if |
| 305 | required.</p> |
| 306 | |
| 307 | <p>There is no defined behavior as to, for example, how |
| 308 | <code>glDrawBuffer</code> interacts with <code>EGL_RENDER_BUFFER</code>. Right |
| 309 | now, it is desired that the draw buffer in a client API be fixed for pixmap and |
| 310 | pbuffer surfaces. Therefore, the driver is responsible to guarantee that the |
| 311 | client API renders to the specified render buffer for pixmap and pbuffer |
| 312 | surfaces.</p> |
| 313 | |
Chia-I Wu | e16f577 | 2010-02-17 19:52:29 +0800 | [diff] [blame] | 314 | <h3><code>EGLDisplay</code> Mutex</h3> |
| 315 | |
| 316 | The <code>EGLDisplay</code> will be locked before calling any of the dispatch |
| 317 | functions (well, except for GetProcAddress which does not take an |
| 318 | <code>EGLDisplay</code>). This guarantees that the same dispatch function will |
| 319 | not be called with the sample display at the same time. If a driver has access |
| 320 | to an <code>EGLDisplay</code> without going through the EGL APIs, the driver |
| 321 | should as well lock the display before using it. |
| 322 | |
Chia-I Wu | ada4605 | 2010-01-21 15:29:14 +0800 | [diff] [blame] | 323 | <h3>TODOs</h3> |
| 324 | |
| 325 | <ul> |
Chia-I Wu | ada4605 | 2010-01-21 15:29:14 +0800 | [diff] [blame] | 326 | <li>Pass the conformance tests</li> |
| 327 | <li>Better automatic driver selection: <code>EGL_DISPLAY</code> loads all |
| 328 | drivers and might eat too much memory.</li> |
Chia-I Wu | ada4605 | 2010-01-21 15:29:14 +0800 | [diff] [blame] | 329 | |
| 330 | </ul> |
| 331 | |
| 332 | </body> |
| 333 | </html> |