Andreas Boll | ecd5c7c | 2012-06-12 09:05:03 +0200 | [diff] [blame] | 1 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> |
| 2 | <html lang="en"> |
| 3 | <head> |
| 4 | <meta http-equiv="content-type" content="text/html; charset=utf-8"> |
| 5 | <title>Mesa EGL</title> |
| 6 | <link rel="stylesheet" type="text/css" href="mesa.css"> |
| 7 | </head> |
Chia-I Wu | ada4605 | 2010-01-21 15:29:14 +0800 | [diff] [blame] | 8 | <body> |
| 9 | |
Andreas Boll | b5da52a | 2012-09-18 18:57:02 +0200 | [diff] [blame] | 10 | <div class="header"> |
| 11 | <h1>The Mesa 3D Graphics Library</h1> |
| 12 | </div> |
| 13 | |
| 14 | <iframe src="contents.html"></iframe> |
| 15 | <div class="content"> |
| 16 | |
Chia-I Wu | ada4605 | 2010-01-21 15:29:14 +0800 | [diff] [blame] | 17 | <h1>Mesa EGL</h1> |
| 18 | |
| 19 | <p>The current version of EGL in Mesa implements EGL 1.4. More information |
| 20 | about EGL can be found at |
Andreas Boll | a73c59b | 2012-09-18 19:31:28 +0200 | [diff] [blame] | 21 | <a href="http://www.khronos.org/egl/"> |
Brian Paul | aeff9f9 | 2010-01-21 08:13:32 -0700 | [diff] [blame] | 22 | http://www.khronos.org/egl/</a>.</p> |
Chia-I Wu | ada4605 | 2010-01-21 15:29:14 +0800 | [diff] [blame] | 23 | |
| 24 | <p>The Mesa's implementation of EGL uses a driver architecture. The main |
| 25 | library (<code>libEGL</code>) is window system neutral. It provides the EGL |
| 26 | API entry points and helper functions for use by the drivers. Drivers are |
| 27 | dynamically loaded by the main library and most of the EGL API calls are |
| 28 | directly dispatched to the drivers.</p> |
| 29 | |
Chia-I Wu | 65e8f81 | 2010-12-25 02:45:13 +0800 | [diff] [blame] | 30 | <p>The driver in use decides the window system to support.</p> |
Chia-I Wu | ada4605 | 2010-01-21 15:29:14 +0800 | [diff] [blame] | 31 | |
| 32 | <h2>Build EGL</h2> |
| 33 | |
| 34 | <ol> |
| 35 | <li> |
Chia-I Wu | 3418f74 | 2010-11-02 23:55:56 +0800 | [diff] [blame] | 36 | <p>Run <code>configure</code> with the desired client APIs and enable |
| 37 | the driver for your hardware. For example</p> |
Chia-I Wu | ada4605 | 2010-01-21 15:29:14 +0800 | [diff] [blame] | 38 | |
| 39 | <pre> |
Chia-I Wu | 8eea050 | 2011-06-20 11:14:56 +0900 | [diff] [blame] | 40 | $ ./configure --enable-gles1 --enable-gles2 \ |
| 41 | --with-dri-drivers=... \ |
| 42 | --with-gallium-drivers=... |
Chia-I Wu | ada4605 | 2010-01-21 15:29:14 +0800 | [diff] [blame] | 43 | </pre> |
| 44 | |
Chia-I Wu | 8eea050 | 2011-06-20 11:14:56 +0900 | [diff] [blame] | 45 | <p>The main library and OpenGL is enabled by default. The first two options |
| 46 | above enables <a href="opengles.html">OpenGL ES 1.x and 2.x</a>. The last two |
| 47 | options enables the listed classic and and Gallium drivers respectively.</p> |
Chia-I Wu | c6320c5 | 2010-10-28 17:25:07 +0800 | [diff] [blame] | 48 | |
Chia-I Wu | ada4605 | 2010-01-21 15:29:14 +0800 | [diff] [blame] | 49 | </li> |
| 50 | |
| 51 | <li>Build and install Mesa as usual.</li> |
| 52 | </ol> |
| 53 | |
| 54 | <p>In the given example, it will build and install <code>libEGL</code>, |
Chia-I Wu | 8eea050 | 2011-06-20 11:14:56 +0900 | [diff] [blame] | 55 | <code>libGL</code>, <code>libGLESv1_CM</code>, <code>libGLESv2</code>, and one |
| 56 | or more EGL drivers.</p> |
Chia-I Wu | ada4605 | 2010-01-21 15:29:14 +0800 | [diff] [blame] | 57 | |
| 58 | <h3>Configure Options</h3> |
| 59 | |
| 60 | <p>There are several options that control the build of EGL at configuration |
| 61 | time</p> |
| 62 | |
Andreas Boll | 76d4f9e | 2012-09-20 16:01:08 +0200 | [diff] [blame] | 63 | <dl> |
| 64 | <dt><code>--enable-egl</code></dt> |
| 65 | <dd> |
Chia-I Wu | ada4605 | 2010-01-21 15:29:14 +0800 | [diff] [blame] | 66 | |
| 67 | <p>By default, EGL is enabled. When disabled, the main library and the drivers |
| 68 | will not be built.</p> |
| 69 | |
Andreas Boll | 76d4f9e | 2012-09-20 16:01:08 +0200 | [diff] [blame] | 70 | </dd> |
Chia-I Wu | ada4605 | 2010-01-21 15:29:14 +0800 | [diff] [blame] | 71 | |
Andreas Boll | 76d4f9e | 2012-09-20 16:01:08 +0200 | [diff] [blame] | 72 | <dt><code>--with-egl-driver-dir</code></dt> |
| 73 | <dd> |
Chia-I Wu | a6342af | 2010-01-26 10:54:45 +0800 | [diff] [blame] | 74 | |
| 75 | <p>The directory EGL drivers should be installed to. If not specified, EGL |
| 76 | drivers will be installed to <code>${libdir}/egl</code>.</p> |
| 77 | |
Andreas Boll | 76d4f9e | 2012-09-20 16:01:08 +0200 | [diff] [blame] | 78 | </dd> |
Chia-I Wu | a6342af | 2010-01-26 10:54:45 +0800 | [diff] [blame] | 79 | |
Andreas Boll | 76d4f9e | 2012-09-20 16:01:08 +0200 | [diff] [blame] | 80 | <dt><code>--enable-gallium-egl</code></dt> |
| 81 | <dd> |
Chia-I Wu | 8eea050 | 2011-06-20 11:14:56 +0900 | [diff] [blame] | 82 | |
| 83 | <p>Enable the optional <code>egl_gallium</code> driver.</p> |
| 84 | |
Andreas Boll | 76d4f9e | 2012-09-20 16:01:08 +0200 | [diff] [blame] | 85 | </dd> |
Chia-I Wu | 8eea050 | 2011-06-20 11:14:56 +0900 | [diff] [blame] | 86 | |
Andreas Boll | 76d4f9e | 2012-09-20 16:01:08 +0200 | [diff] [blame] | 87 | <dt><code>--with-egl-platforms</code></dt> |
| 88 | <dd> |
Chia-I Wu | ada4605 | 2010-01-21 15:29:14 +0800 | [diff] [blame] | 89 | |
Chia-I Wu | b365b15 | 2010-07-03 17:18:40 +0800 | [diff] [blame] | 90 | <p>List the platforms (window systems) to support. Its argument is a comma |
Nathan Kidd | 0691b37 | 2014-01-03 16:44:00 -0700 | [diff] [blame] | 91 | separated string such as <code>--with-egl-platforms=x11,drm</code>. It decides |
Chia-I Wu | b365b15 | 2010-07-03 17:18:40 +0800 | [diff] [blame] | 92 | the platforms a driver may support. The first listed platform is also used by |
| 93 | the main library to decide the native platform: the platform the EGL native |
| 94 | types such as <code>EGLNativeDisplayType</code> or |
| 95 | <code>EGLNativeWindowType</code> defined for.</p> |
Chia-I Wu | ada4605 | 2010-01-21 15:29:14 +0800 | [diff] [blame] | 96 | |
Chia-I Wu | e7424d7 | 2010-09-19 16:54:39 +0800 | [diff] [blame] | 97 | <p>The available platforms are <code>x11</code>, <code>drm</code>, |
Chia-I Wu | da39d5d | 2010-06-17 16:07:46 +0800 | [diff] [blame] | 98 | <code>fbdev</code>, and <code>gdi</code>. The <code>gdi</code> platform can |
Chia-I Wu | 3418f74 | 2010-11-02 23:55:56 +0800 | [diff] [blame] | 99 | only be built with SCons. Unless for special needs, the build system should |
| 100 | select the right platforms automatically.</p> |
Chia-I Wu | 2e3c4e4 | 2010-05-07 14:13:08 +0800 | [diff] [blame] | 101 | |
Andreas Boll | 76d4f9e | 2012-09-20 16:01:08 +0200 | [diff] [blame] | 102 | </dd> |
Chia-I Wu | 2e3c4e4 | 2010-05-07 14:13:08 +0800 | [diff] [blame] | 103 | |
Andreas Boll | 76d4f9e | 2012-09-20 16:01:08 +0200 | [diff] [blame] | 104 | <dt><code>--enable-gles1</code></dt> |
| 105 | <dt><code>--enable-gles2</code></dt> |
| 106 | <dd> |
Chia-I Wu | 2e3c4e4 | 2010-05-07 14:13:08 +0800 | [diff] [blame] | 107 | |
Chia-I Wu | 65e8f81 | 2010-12-25 02:45:13 +0800 | [diff] [blame] | 108 | <p>These options enable OpenGL ES support in OpenGL. The result is one big |
| 109 | internal library that supports multiple APIs.</p> |
Chia-I Wu | ada4605 | 2010-01-21 15:29:14 +0800 | [diff] [blame] | 110 | |
Andreas Boll | 76d4f9e | 2012-09-20 16:01:08 +0200 | [diff] [blame] | 111 | </dd> |
Chia-I Wu | a1306f4 | 2010-01-22 15:51:51 +0800 | [diff] [blame] | 112 | |
Andreas Boll | 76d4f9e | 2012-09-20 16:01:08 +0200 | [diff] [blame] | 113 | <dt><code>--enable-shared-glapi</code></dt> |
| 114 | <dd> |
Chia-I Wu | c6320c5 | 2010-10-28 17:25:07 +0800 | [diff] [blame] | 115 | |
Chia-I Wu | 8eea050 | 2011-06-20 11:14:56 +0900 | [diff] [blame] | 116 | <p>By default, <code>libGL</code> has its own copy of <code>libglapi</code>. |
| 117 | This options makes <code>libGL</code> use the shared <code>libglapi</code>. This |
| 118 | is required if applications mix OpenGL and OpenGL ES.</p> |
Chia-I Wu | c6320c5 | 2010-10-28 17:25:07 +0800 | [diff] [blame] | 119 | |
Andreas Boll | 76d4f9e | 2012-09-20 16:01:08 +0200 | [diff] [blame] | 120 | </dd> |
Chia-I Wu | c6320c5 | 2010-10-28 17:25:07 +0800 | [diff] [blame] | 121 | |
Andreas Boll | 76d4f9e | 2012-09-20 16:01:08 +0200 | [diff] [blame] | 122 | <dt><code>--enable-openvg</code></dt> |
| 123 | <dd> |
Chia-I Wu | 3418f74 | 2010-11-02 23:55:56 +0800 | [diff] [blame] | 124 | |
Chia-I Wu | 8eea050 | 2011-06-20 11:14:56 +0900 | [diff] [blame] | 125 | <p>OpenVG must be explicitly enabled by this option.</p> |
Chia-I Wu | 3418f74 | 2010-11-02 23:55:56 +0800 | [diff] [blame] | 126 | |
Andreas Boll | 76d4f9e | 2012-09-20 16:01:08 +0200 | [diff] [blame] | 127 | </dd> |
Chia-I Wu | 3418f74 | 2010-11-02 23:55:56 +0800 | [diff] [blame] | 128 | |
Andreas Boll | 76d4f9e | 2012-09-20 16:01:08 +0200 | [diff] [blame] | 129 | </dl> |
Chia-I Wu | ada4605 | 2010-01-21 15:29:14 +0800 | [diff] [blame] | 130 | |
Chia-I Wu | ada4605 | 2010-01-21 15:29:14 +0800 | [diff] [blame] | 131 | <h2>Use EGL</h2> |
| 132 | |
Chia-I Wu | 411bba3 | 2010-06-11 12:47:14 +0800 | [diff] [blame] | 133 | <h3>Demos</h3> |
Chia-I Wu | ada4605 | 2010-01-21 15:29:14 +0800 | [diff] [blame] | 134 | |
Chia-I Wu | 411bba3 | 2010-06-11 12:47:14 +0800 | [diff] [blame] | 135 | <p>There are demos for the client APIs supported by EGL. They can be found in |
| 136 | mesa/demos repository.</p> |
Chia-I Wu | ada4605 | 2010-01-21 15:29:14 +0800 | [diff] [blame] | 137 | |
| 138 | <h3>Environment Variables</h3> |
| 139 | |
| 140 | <p>There are several environment variables that control the behavior of EGL at |
| 141 | runtime</p> |
| 142 | |
Andreas Boll | 76d4f9e | 2012-09-20 16:01:08 +0200 | [diff] [blame] | 143 | <dl> |
| 144 | <dt><code>EGL_DRIVERS_PATH</code></dt> |
| 145 | <dd> |
Chia-I Wu | 5d8646c | 2010-02-02 15:34:55 +0800 | [diff] [blame] | 146 | |
| 147 | <p>By default, the main library will look for drivers in the directory where |
| 148 | the drivers are installed to. This variable specifies a list of |
| 149 | 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] | 150 | addition to the default directory. This variable is ignored for setuid/setgid |
| 151 | binaries.</p> |
Chia-I Wu | 5d8646c | 2010-02-02 15:34:55 +0800 | [diff] [blame] | 152 | |
Chia-I Wu | cba7786 | 2011-01-04 00:53:19 +0800 | [diff] [blame] | 153 | <p>This variable is usually set to test an uninstalled build. For example, one |
| 154 | may set</p> |
| 155 | |
| 156 | <pre> |
| 157 | $ export LD_LIBRARY_PATH=$mesa/lib |
| 158 | $ export EGL_DRIVERS_PATH=$mesa/lib/egl |
| 159 | </pre> |
| 160 | |
| 161 | <p>to test a build without installation</p> |
| 162 | |
Andreas Boll | 76d4f9e | 2012-09-20 16:01:08 +0200 | [diff] [blame] | 163 | </dd> |
Chia-I Wu | 5d8646c | 2010-02-02 15:34:55 +0800 | [diff] [blame] | 164 | |
Andreas Boll | 76d4f9e | 2012-09-20 16:01:08 +0200 | [diff] [blame] | 165 | <dt><code>EGL_DRIVER</code></dt> |
| 166 | <dd> |
Chia-I Wu | ada4605 | 2010-01-21 15:29:14 +0800 | [diff] [blame] | 167 | |
Chia-I Wu | c98ea26 | 2011-01-07 16:30:08 +0800 | [diff] [blame] | 168 | <p>This variable specifies a full path to or the name of an EGL driver. It |
| 169 | forces the specified EGL driver to be loaded. It comes in handy when one wants |
| 170 | to test a specific driver. This variable is ignored for setuid/setgid |
| 171 | binaries.</p> |
Chia-I Wu | ada4605 | 2010-01-21 15:29:14 +0800 | [diff] [blame] | 172 | |
Andreas Boll | 76d4f9e | 2012-09-20 16:01:08 +0200 | [diff] [blame] | 173 | </dd> |
Chia-I Wu | ada4605 | 2010-01-21 15:29:14 +0800 | [diff] [blame] | 174 | |
Andreas Boll | 76d4f9e | 2012-09-20 16:01:08 +0200 | [diff] [blame] | 175 | <dt><code>EGL_PLATFORM</code></dt> |
| 176 | <dd> |
Chia-I Wu | ada4605 | 2010-01-21 15:29:14 +0800 | [diff] [blame] | 177 | |
Chia-I Wu | b365b15 | 2010-07-03 17:18:40 +0800 | [diff] [blame] | 178 | <p>This variable specifies the native platform. The valid values are the same |
| 179 | as those for <code>--with-egl-platforms</code>. When the variable is not set, |
| 180 | the main library uses the first platform listed in |
Chia-I Wu | 3418f74 | 2010-11-02 23:55:56 +0800 | [diff] [blame] | 181 | <code>--with-egl-platforms</code> as the native platform.</p> |
| 182 | |
| 183 | <p>Extensions like <code>EGL_MESA_drm_display</code> define new functions to |
| 184 | create displays for non-native platforms. These extensions are usually used by |
| 185 | applications that support non-native platforms. Setting this variable is |
| 186 | probably required only for some of the demos found in mesa/demo repository.</p> |
Chia-I Wu | ada4605 | 2010-01-21 15:29:14 +0800 | [diff] [blame] | 187 | |
Andreas Boll | 76d4f9e | 2012-09-20 16:01:08 +0200 | [diff] [blame] | 188 | </dd> |
Chia-I Wu | ada4605 | 2010-01-21 15:29:14 +0800 | [diff] [blame] | 189 | |
Andreas Boll | 76d4f9e | 2012-09-20 16:01:08 +0200 | [diff] [blame] | 190 | <dt><code>EGL_LOG_LEVEL</code></dt> |
| 191 | <dd> |
Chia-I Wu | ada4605 | 2010-01-21 15:29:14 +0800 | [diff] [blame] | 192 | |
| 193 | <p>This changes the log level of the main library and the drivers. The valid |
| 194 | values are: <code>debug</code>, <code>info</code>, <code>warning</code>, and |
| 195 | <code>fatal</code>.</p> |
| 196 | |
Andreas Boll | 76d4f9e | 2012-09-20 16:01:08 +0200 | [diff] [blame] | 197 | </dd> |
Chia-I Wu | ada4605 | 2010-01-21 15:29:14 +0800 | [diff] [blame] | 198 | |
Andreas Boll | 76d4f9e | 2012-09-20 16:01:08 +0200 | [diff] [blame] | 199 | <dt><code>EGL_SOFTWARE</code></dt> |
| 200 | <dd> |
Chia-I Wu | ada4605 | 2010-01-21 15:29:14 +0800 | [diff] [blame] | 201 | |
| 202 | <p>For drivers that support both hardware and software rendering, setting this |
| 203 | variable to true forces the use of software rendering.</p> |
| 204 | |
Andreas Boll | 76d4f9e | 2012-09-20 16:01:08 +0200 | [diff] [blame] | 205 | </dd> |
| 206 | </dl> |
Chia-I Wu | ada4605 | 2010-01-21 15:29:14 +0800 | [diff] [blame] | 207 | |
| 208 | <h2>EGL Drivers</h2> |
| 209 | |
Andreas Boll | 76d4f9e | 2012-09-20 16:01:08 +0200 | [diff] [blame] | 210 | <dl> |
| 211 | <dt><code>egl_dri2</code></dt> |
| 212 | <dd> |
Chia-I Wu | 3418f74 | 2010-11-02 23:55:56 +0800 | [diff] [blame] | 213 | |
| 214 | <p>This driver supports both <code>x11</code> and <code>drm</code> platforms. |
Chia-I Wu | 65e8f81 | 2010-12-25 02:45:13 +0800 | [diff] [blame] | 215 | It functions as a DRI driver loader. For <code>x11</code> support, it talks to |
| 216 | the X server directly using (XCB-)DRI2 protocol.</p> |
| 217 | |
| 218 | <p>This driver can share DRI drivers with <code>libGL</code>.</p> |
Chia-I Wu | 3418f74 | 2010-11-02 23:55:56 +0800 | [diff] [blame] | 219 | |
Andreas Boll | 76d4f9e | 2012-09-20 16:01:08 +0200 | [diff] [blame] | 220 | </dd> |
Chia-I Wu | 3418f74 | 2010-11-02 23:55:56 +0800 | [diff] [blame] | 221 | |
Andreas Boll | 76d4f9e | 2012-09-20 16:01:08 +0200 | [diff] [blame] | 222 | <dt><code>egl_gallium</code></dt> |
| 223 | <dd> |
Chia-I Wu | ada4605 | 2010-01-21 15:29:14 +0800 | [diff] [blame] | 224 | |
Chia-I Wu | b365b15 | 2010-07-03 17:18:40 +0800 | [diff] [blame] | 225 | <p>This driver is based on Gallium3D. It supports all rendering APIs and |
Nathan Kidd | 0691b37 | 2014-01-03 16:44:00 -0700 | [diff] [blame] | 226 | hardware supported by Gallium3D. It is the only driver that supports OpenVG. |
Chia-I Wu | c6320c5 | 2010-10-28 17:25:07 +0800 | [diff] [blame] | 227 | The supported platforms are X11, DRM, FBDEV, and GDI.</p> |
Chia-I Wu | ada4605 | 2010-01-21 15:29:14 +0800 | [diff] [blame] | 228 | |
Chia-I Wu | 65e8f81 | 2010-12-25 02:45:13 +0800 | [diff] [blame] | 229 | <p>This driver comes with its own hardware drivers |
| 230 | (<code>pipe_<hw></code>) and client API modules |
| 231 | (<code>st_<api></code>).</p> |
| 232 | |
Andreas Boll | 76d4f9e | 2012-09-20 16:01:08 +0200 | [diff] [blame] | 233 | </dd> |
Chia-I Wu | ada4605 | 2010-01-21 15:29:14 +0800 | [diff] [blame] | 234 | |
Chia-I Wu | 65e8f81 | 2010-12-25 02:45:13 +0800 | [diff] [blame] | 235 | <h2>Packaging</h2> |
| 236 | |
| 237 | <p>The ABI between the main library and its drivers are not stable. Nor is |
| 238 | there a plan to stabilize it at the moment. Of the EGL drivers, |
| 239 | <code>egl_gallium</code> has its own hardware drivers and client API modules. |
| 240 | They are considered internal to <code>egl_gallium</code> and there is also no |
| 241 | stable ABI between them. These should be kept in mind when packaging for |
| 242 | distribution.</p> |
| 243 | |
| 244 | <p>Generally, <code>egl_dri2</code> is preferred over <code>egl_gallium</code> |
| 245 | when the system already has DRI drivers. As <code>egl_gallium</code> is loaded |
| 246 | before <code>egl_dri2</code> when both are available, <code>egl_gallium</code> |
Chia-I Wu | 8eea050 | 2011-06-20 11:14:56 +0900 | [diff] [blame] | 247 | is disabled by default.</p> |
Chia-I Wu | 65e8f81 | 2010-12-25 02:45:13 +0800 | [diff] [blame] | 248 | |
Chia-I Wu | ada4605 | 2010-01-21 15:29:14 +0800 | [diff] [blame] | 249 | <h2>Developers</h2> |
| 250 | |
Chia-I Wu | 14cbf32 | 2010-01-27 23:18:22 +0800 | [diff] [blame] | 251 | <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] | 252 | <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] | 253 | be found at <code>src/gallium/state_trackers/egl/</code>.</p> |
| 254 | |
Chia-I Wu | 14cbf32 | 2010-01-27 23:18:22 +0800 | [diff] [blame] | 255 | <h3>Lifetime of Display Resources</h3> |
| 256 | |
| 257 | <p>Contexts and surfaces are examples of display resources. They might live |
| 258 | longer than the display that creates them.</p> |
| 259 | |
| 260 | <p>In EGL, when a display is terminated through <code>eglTerminate</code>, all |
| 261 | display resources should be destroyed. Similarly, when a thread is released |
Nathan Kidd | 0691b37 | 2014-01-03 16:44:00 -0700 | [diff] [blame] | 262 | through <code>eglReleaseThread</code>, all current display resources should be |
| 263 | released. Another way to destroy or release resources is through functions |
Chia-I Wu | 14cbf32 | 2010-01-27 23:18:22 +0800 | [diff] [blame] | 264 | such as <code>eglDestroySurface</code> or <code>eglMakeCurrent</code>.</p> |
| 265 | |
| 266 | <p>When a resource that is current to some thread is destroyed, the resource |
| 267 | should not be destroyed immediately. EGL requires the resource to live until |
| 268 | it is no longer current. A driver usually calls |
| 269 | <code>eglIs<Resource>Bound</code> to check if a resource is bound |
| 270 | (current) to any thread in the destroy callbacks. If it is still bound, the |
| 271 | resource is not destroyed.</p> |
| 272 | |
| 273 | <p>The main library will mark destroyed current resources as unlinked. In a |
| 274 | driver's <code>MakeCurrent</code> callback, |
| 275 | <code>eglIs<Resource>Linked</code> can then be called to check if a newly |
| 276 | released resource is linked to a display. If it is not, the last reference to |
| 277 | the resource is removed and the driver should destroy the resource. But it |
| 278 | should be careful here because <code>MakeCurrent</code> might be called with an |
| 279 | uninitialized display.</p> |
| 280 | |
| 281 | <p>This is the only mechanism provided by the main library to help manage the |
| 282 | resources. The drivers are responsible to the correct behavior as defined by |
| 283 | EGL.</p> |
Chia-I Wu | ada4605 | 2010-01-21 15:29:14 +0800 | [diff] [blame] | 284 | |
Chia-I Wu | 1b2b08c | 2010-02-05 12:44:45 +0800 | [diff] [blame] | 285 | <h3><code>EGL_RENDER_BUFFER</code></h3> |
| 286 | |
| 287 | <p>In EGL, the color buffer a context should try to render to is decided by the |
| 288 | binding surface. It should try to render to the front buffer if the binding |
| 289 | surface has <code>EGL_RENDER_BUFFER</code> set to |
| 290 | <code>EGL_SINGLE_BUFFER</code>; If the same context is later bound to a |
| 291 | surface with <code>EGL_RENDER_BUFFER</code> set to |
| 292 | <code>EGL_BACK_BUFFER</code>, the context should try to render to the back |
| 293 | buffer. However, the context is allowed to make the final decision as to which |
| 294 | color buffer it wants to or is able to render to.</p> |
| 295 | |
| 296 | <p>For pbuffer surfaces, the render buffer is always |
| 297 | <code>EGL_BACK_BUFFER</code>. And for pixmap surfaces, the render buffer is |
| 298 | always <code>EGL_SINGLE_BUFFER</code>. Unlike window surfaces, EGL spec |
| 299 | requires their <code>EGL_RENDER_BUFFER</code> values to be honored. As a |
| 300 | result, a driver should never set <code>EGL_PIXMAP_BIT</code> or |
| 301 | <code>EGL_PBUFFER_BIT</code> bits of a config if the contexts created with the |
| 302 | config won't be able to honor the <code>EGL_RENDER_BUFFER</code> of pixmap or |
| 303 | pbuffer surfaces.</p> |
| 304 | |
| 305 | <p>It should also be noted that pixmap and pbuffer surfaces are assumed to be |
| 306 | single-buffered, in that <code>eglSwapBuffers</code> has no effect on them. It |
| 307 | is desirable that a driver allocates a private color buffer for each pbuffer |
| 308 | surface created. If the window system the driver supports has native pbuffers, |
| 309 | or if the native pixmaps have more than one color buffers, the driver should |
| 310 | carefully attach the native color buffers to the EGL surfaces, re-route them if |
| 311 | required.</p> |
| 312 | |
| 313 | <p>There is no defined behavior as to, for example, how |
| 314 | <code>glDrawBuffer</code> interacts with <code>EGL_RENDER_BUFFER</code>. Right |
| 315 | now, it is desired that the draw buffer in a client API be fixed for pixmap and |
| 316 | pbuffer surfaces. Therefore, the driver is responsible to guarantee that the |
| 317 | client API renders to the specified render buffer for pixmap and pbuffer |
| 318 | surfaces.</p> |
| 319 | |
Chia-I Wu | e16f577 | 2010-02-17 19:52:29 +0800 | [diff] [blame] | 320 | <h3><code>EGLDisplay</code> Mutex</h3> |
| 321 | |
| 322 | The <code>EGLDisplay</code> will be locked before calling any of the dispatch |
| 323 | functions (well, except for GetProcAddress which does not take an |
| 324 | <code>EGLDisplay</code>). This guarantees that the same dispatch function will |
| 325 | not be called with the sample display at the same time. If a driver has access |
| 326 | to an <code>EGLDisplay</code> without going through the EGL APIs, the driver |
| 327 | should as well lock the display before using it. |
| 328 | |
Andreas Boll | b5da52a | 2012-09-18 18:57:02 +0200 | [diff] [blame] | 329 | </div> |
Chia-I Wu | ada4605 | 2010-01-21 15:29:14 +0800 | [diff] [blame] | 330 | </body> |
| 331 | </html> |