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> |
| 35 | $ ./configure --with-state-trackers=egl_g3d,es,vega --enable-gallium-intel |
| 36 | </pre> |
| 37 | |
| 38 | <p>The main library will be enabled by default. The <code>egl_g3d</code> state |
| 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 | |
| 65 | <li><code>--with-egl-displays</code> |
| 66 | |
| 67 | <p>List the window system(s) to support. It is by default <code>x11</code>, |
| 68 | which supports the X Window System. Its argument is a comma separated string |
| 69 | like, for example, <code>--with-egl-displays=x11,kms</code>. Because an EGL |
| 70 | driver decides which window system to support, this example will enable two |
| 71 | (sets of) EGL drivers. One supports the X window system and the other supports |
| 72 | bare KMS (kernel modesetting).</p> |
| 73 | |
| 74 | </li> |
| 75 | |
| 76 | <li><code>--with-state-trackers</code> |
| 77 | |
| 78 | <p>The argument is a comma separated string. It is usually used to specify the |
| 79 | rendering APIs, like OpenGL ES or OpenVG, to build. But it should be noted |
| 80 | that a number of EGL drivers depend on the <code>egl_g3d</code> state tracker. |
| 81 | They will <em>not</em> be built without the <code>egl_g3d</code> state |
| 82 | tracker.</p> |
| 83 | |
| 84 | </li> |
| 85 | </ul> |
| 86 | |
| 87 | <h3>OpenGL</h3> |
| 88 | |
| 89 | <p>The OpenGL state tracker is not built in the above example. It should be |
| 90 | noted that the classic <code>libGL</code> is not a state tracker and cannot be |
| 91 | used with EGL (unless the EGL driver in use is <code>egl_glx</code>). To build |
| 92 | the OpenGL state tracker, one may append <code>glx</code> to |
| 93 | <code>--with-state-trackers</code> and manually build |
| 94 | <code>src/gallium/winsys/xlib/</code>.</p> |
| 95 | |
| 96 | <h2>Use EGL</h2> |
| 97 | |
| 98 | <p> The demos for OpenGL ES and OpenVG can be found in <code>progs/es1/</code>, |
| 99 | <code>progs/es2/</code> and <code>progs/openvg/</code>. You can use them to |
| 100 | test your build. For example,</p> |
| 101 | |
| 102 | <pre> |
| 103 | $ cd progs/es1/xegl |
| 104 | $ make |
| 105 | $ ./torus |
| 106 | </pre> |
| 107 | |
| 108 | <h3>Environment Variables</h3> |
| 109 | |
| 110 | <p>There are several environment variables that control the behavior of EGL at |
| 111 | runtime</p> |
| 112 | |
| 113 | <ul> |
| 114 | <li><code>EGL_DRIVER</code> |
| 115 | |
| 116 | <p>This variable forces the specified EGL driver to be loaded. It comes in |
| 117 | handy when one wants to test a specific driver.</p> |
| 118 | |
| 119 | </li> |
| 120 | |
| 121 | <li><code>EGL_DISPLAY</code> |
| 122 | |
| 123 | <p>When <code>EGL_DRIVER</code> is not set, the main library loads <em>all</em> |
| 124 | EGL drivers that support a certain window system. <code>EGL_DISPLAY</code> can |
| 125 | be used to specify the window system and the valid values are, for example, |
| 126 | <code>x11</code> or <code>kms</code>. When the variable is not set, the main |
| 127 | library defaults the value to the first window system listed in |
| 128 | <code>--with-egl-displays</code> at configuration time. |
| 129 | |
| 130 | </li> |
| 131 | |
| 132 | <li><code>EGL_LOG_LEVEL</code> |
| 133 | |
| 134 | <p>This changes the log level of the main library and the drivers. The valid |
| 135 | values are: <code>debug</code>, <code>info</code>, <code>warning</code>, and |
| 136 | <code>fatal</code>.</p> |
| 137 | |
| 138 | </li> |
| 139 | |
| 140 | <li><code>EGL_SOFTWARE</code> |
| 141 | |
| 142 | <p>For drivers that support both hardware and software rendering, setting this |
| 143 | variable to true forces the use of software rendering.</p> |
| 144 | |
| 145 | </li> |
| 146 | </ul> |
| 147 | |
| 148 | <h2>EGL Drivers</h2> |
| 149 | |
| 150 | <p>There are two categories of EGL drivers: Gallium and classic.</p> |
| 151 | |
| 152 | <p>Gallium EGL drivers supports all rendering APIs specified in EGL 1.4. The |
| 153 | support for optional EGL functions and EGL extensions is usually more complete |
| 154 | than the classic ones. These drivers depend on the <code>egl_g3d</code> state |
| 155 | tracker to build. The available drivers are</p> |
| 156 | |
| 157 | <ul> |
| 158 | <li><code>egl_<dpy>_i915</code></li> |
| 159 | <li><code>egl_<dpy>_i965</code></li> |
| 160 | <li><code>egl_<dpy>_radeon</code></li> |
| 161 | <li><code>egl_<dpy>_nouveau</code></li> |
| 162 | <li><code>egl_<dpy>_vmwgfx</code></li> |
| 163 | </ul> |
| 164 | |
| 165 | <p><code><dpy></code> is given by <code>--with-egl-displays</code> at |
| 166 | configuration time. There will be one EGL driver for each combination of the |
| 167 | displays listed and the hardware drivers enabled.</p> |
| 168 | |
| 169 | <p>Classic EGL drivers, on the other hand, supports only OpenGL as its |
| 170 | rendering API. They can be found under <code>src/egl/drivers/</code>. There |
| 171 | are 3 of them</p> |
| 172 | |
| 173 | <ul> |
| 174 | <li><code>egl_glx</code> |
| 175 | |
| 176 | <p>This driver provides a wrapper to GLX. It uses exclusively GLX to implement |
| 177 | the EGL API. It supports both direct and indirect rendering when the GLX does. |
| 178 | It is accelerated when the GLX is. As such, it cannot provide functions that |
| 179 | is not available in GLX or GLX extensions.</p> |
| 180 | </li> |
| 181 | |
| 182 | <li><code>egl_xdri</code> |
| 183 | |
| 184 | <p>This driver supports the X Window System as its window system. It functions |
| 185 | as a DRI driver loader. Unlike <code>egl_glx</code>, it has no dependency on |
| 186 | <code>libGL</code>. It talks to the X server directly using DRI or DRI2 |
| 187 | protocols. It also talks minimal GLX protocol for things like available |
| 188 | visuals or fbconfigs. With direct access to the DRI drivers, it has the |
| 189 | potential to support more EGL functions that are not possible with |
| 190 | <code>egl_glx</code></p> |
| 191 | |
| 192 | </li> |
| 193 | <li><code>egl_dri</code> |
| 194 | |
| 195 | <p>This driver lacks maintenance and does <em>not</em> build. It is similiar |
| 196 | to <code>egl_xdri</code> in that it functions as a DRI driver loader. But |
| 197 | unlike <code>egl_xdri</code>, it supports Linux framebuffer devices as its |
| 198 | window system and supports EGL_MESA_screen_surface extension. It loads only |
| 199 | DRI1 drivers. As DRI1 drivers is phasing out, it might be better to rewrite |
| 200 | the driver to support KMS and DRI2.</p> |
| 201 | |
| 202 | </li> |
| 203 | </ul> |
| 204 | |
| 205 | <p>To use the classic drivers, one must manually set <code>EGL_DRIVER</code> at |
| 206 | runtime.</p> |
| 207 | |
| 208 | <h2>Developers</h2> |
| 209 | |
| 210 | The sources of the main library and the classic drivers can be found at |
| 211 | <code>src/egl/</code>. The sources of the <code>egl_g3d</code> state tracker |
| 212 | can be found at <code>src/gallium/state_trackers/egl_g3d/</code>. |
| 213 | |
| 214 | <h3>TODOs</h3> |
| 215 | |
| 216 | <ul> |
| 217 | <li>Thread safety</li> |
| 218 | <li>Pass the conformance tests</li> |
| 219 | <li>Better automatic driver selection: <code>EGL_DISPLAY</code> loads all |
| 220 | drivers and might eat too much memory.</li> |
| 221 | |
| 222 | </ul> |
| 223 | |
| 224 | </body> |
| 225 | </html> |