Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / mesa3d / 29732f982cb0ad3bd9c81da2ba9f64b9205ff6b0 / . / docs / egl.html
blob: 5561d1a4b86f24950a90a1da45fe3942dab94fe4 [file] [log] [blame]
Chia-I Wuada46052010-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
12about EGL can be found at
Brian Paulaeff9f92010-01-21 08:13:32 -0700[diff] [blame]13<a href="http://www.khronos.org/egl/" target="_parent">
14http://www.khronos.org/egl/</a>.</p>
Chia-I Wuada46052010-01-21 15:29:14 +0800[diff] [blame]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_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
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-displays</code>
66
67<p>List the window system(s) to support. It is by default <code>x11</code>,
68which supports the X Window System. Its argument is a comma separated string
69like, for example, <code>--with-egl-displays=x11,kms</code>. Because an EGL
70driver 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
72bare 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
79rendering APIs, like OpenGL ES or OpenVG, to build. But it should be noted
80that a number of EGL drivers depend on the <code>egl_g3d</code> state tracker.
81They will <em>not</em> be built without the <code>egl_g3d</code> state
82tracker.</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
90noted that the classic <code>libGL</code> is not a state tracker and cannot be
91used with EGL (unless the EGL driver in use is <code>egl_glx</code>). To build
92the 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
100test 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
111runtime</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
117handy 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>
124EGL drivers that support a certain window system. <code>EGL_DISPLAY</code> can
125be 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
127library 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
135values 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
143variable 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
153support for optional EGL functions and EGL extensions is usually more complete
154than the classic ones. These drivers depend on the <code>egl_g3d</code> state
155tracker to build. The available drivers are</p>
156
157<ul>
158<li><code>egl_&lt;dpy&gt;_i915</code></li>
159<li><code>egl_&lt;dpy&gt;_i965</code></li>
160<li><code>egl_&lt;dpy&gt;_radeon</code></li>
161<li><code>egl_&lt;dpy&gt;_nouveau</code></li>
162<li><code>egl_&lt;dpy&gt;_vmwgfx</code></li>
163</ul>
164
165<p><code>&lt;dpy&gt;</code> is given by <code>--with-egl-displays</code> at
166configuration time. There will be one EGL driver for each combination of the
167displays listed and the hardware drivers enabled.</p>
168
169<p>Classic EGL drivers, on the other hand, supports only OpenGL as its
170rendering API. They can be found under <code>src/egl/drivers/</code>. There
171are 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
177the EGL API. It supports both direct and indirect rendering when the GLX does.
178It is accelerated when the GLX is. As such, it cannot provide functions that
179is 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
Chia-I Wu29732f92010-01-22 15:05:31 +0800[diff] [blame^]185as a DRI driver loader and can load DRI/DRI2/DRISW drivers. Unlike
186<code>egl_glx</code>, it has no dependency on <code>libGL</code>. It talks to
187the X server directly using DRI or DRI2 protocols. It also talks minimal GLX
188protocol for things like available visuals or fbconfigs. With direct access to
189the DRI drivers, it has the potential to support more EGL functions that are
190not possible with <code>egl_glx</code>.</p>
Chia-I Wuada46052010-01-21 15:29:14 +0800[diff] [blame]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
196to <code>egl_xdri</code> in that it functions as a DRI driver loader. But
197unlike <code>egl_xdri</code>, it supports Linux framebuffer devices as its
198window system and supports EGL_MESA_screen_surface extension. It loads only
199DRI1 drivers. As DRI1 drivers is phasing out, it might be better to rewrite
200the 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
206runtime.</p>
207
208<h2>Developers</h2>
209
210The 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
212can 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
220drivers and might eat too much memory.</li>
221
222</ul>
223
224</body>
225</html>