Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / mesa3d / ada46053a4b37967cc53355b9baf712aa5a8bafd / . / docs / egl.html
blob: ccc233fca9893316f4ba18000f8a5e1b0b6a14dc [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
13<a href="http://www.khronos.org/egl/">http://www.khronos.org/egl/</a>.</p>
14
15<p>The Mesa's implementation of EGL uses a driver architecture. The main
16library (<code>libEGL</code>) is window system neutral. It provides the EGL
17API entry points and helper functions for use by the drivers. Drivers are
18dynamically loaded by the main library and most of the EGL API calls are
19directly dispatched to the drivers.</p>
20
21<p>The driver in use decides the window system to support. For drivers that
22support hardware rendering, there are usually multiple drivers supporting the
23same window system. Each one of of them supports a certain range of graphics
24cards.</p>
25
26<h2>Build EGL</h2>
27
28<ol>
29<li>
30<p>Run <code>configure</code> with the desired state trackers and and enable
31the Gallium driver for your hardware. For example</p>
32
33<pre>
34 $ ./configure --with-state-trackers=egl_g3d,es,vega --enable-gallium-intel
35</pre>
36
37<p>The main library will be enabled by default. The <code>egl_g3d</code> state
38tracker is needed by a number of EGL drivers. EGL drivers will be covered
39later. The <a href="opengles.html">es state tracker</a> provides OpenGL ES 1.x
40and 2.x and the <a href="openvg.html">vega state tracker</a> provides OpenVG
411.x.</p>
42</li>
43
44<li>Build and install Mesa as usual.</li>
45</ol>
46
47<p>In the given example, it will build and install <code>libEGL</code>,
48<code>libGLESv1_CM</code>, <code>libGLESv2</code>, <code>libOpenVG</code>, and
49one or more EGL drivers.</p>
50
51<h3>Configure Options</h3>
52
53<p>There are several options that control the build of EGL at configuration
54time</p>
55
56<ul>
57<li><code>--enable-egl</code>
58
59<p>By default, EGL is enabled. When disabled, the main library and the drivers
60will not be built.</p>
61
62</li>
63
64<li><code>--with-egl-displays</code>
65
66<p>List the window system(s) to support. It is by default <code>x11</code>,
67which supports the X Window System. Its argument is a comma separated string
68like, for example, <code>--with-egl-displays=x11,kms</code>. Because an EGL
69driver decides which window system to support, this example will enable two
70(sets of) EGL drivers. One supports the X window system and the other supports
71bare KMS (kernel modesetting).</p>
72
73</li>
74
75<li><code>--with-state-trackers</code>
76
77<p>The argument is a comma separated string. It is usually used to specify the
78rendering APIs, like OpenGL ES or OpenVG, to build. But it should be noted
79that a number of EGL drivers depend on the <code>egl_g3d</code> state tracker.
80They will <em>not</em> be built without the <code>egl_g3d</code> state
81tracker.</p>
82
83</li>
84</ul>
85
86<h3>OpenGL</h3>
87
88<p>The OpenGL state tracker is not built in the above example. It should be
89noted that the classic <code>libGL</code> is not a state tracker and cannot be
90used with EGL (unless the EGL driver in use is <code>egl_glx</code>). To build
91the OpenGL state tracker, one may append <code>glx</code> to
92<code>--with-state-trackers</code> and manually build
93<code>src/gallium/winsys/xlib/</code>.</p>
94
95<h2>Use EGL</h2>
96
97<p> The demos for OpenGL ES and OpenVG can be found in <code>progs/es1/</code>,
98<code>progs/es2/</code> and <code>progs/openvg/</code>. You can use them to
99test your build. For example,</p>
100
101<pre>
102 $ cd progs/es1/xegl
103 $ make
104 $ ./torus
105</pre>
106
107<h3>Environment Variables</h3>
108
109<p>There are several environment variables that control the behavior of EGL at
110runtime</p>
111
112<ul>
113<li><code>EGL_DRIVER</code>
114
115<p>This variable forces the specified EGL driver to be loaded. It comes in
116handy when one wants to test a specific driver.</p>
117
118</li>
119
120<li><code>EGL_DISPLAY</code>
121
122<p>When <code>EGL_DRIVER</code> is not set, the main library loads <em>all</em>
123EGL drivers that support a certain window system. <code>EGL_DISPLAY</code> can
124be used to specify the window system and the valid values are, for example,
125<code>x11</code> or <code>kms</code>. When the variable is not set, the main
126library defaults the value to the first window system listed in
127<code>--with-egl-displays</code> at configuration time.
128
129</li>
130
131<li><code>EGL_LOG_LEVEL</code>
132
133<p>This changes the log level of the main library and the drivers. The valid
134values are: <code>debug</code>, <code>info</code>, <code>warning</code>, and
135<code>fatal</code>.</p>
136
137</li>
138
139<li><code>EGL_SOFTWARE</code>
140
141<p>For drivers that support both hardware and software rendering, setting this
142variable to true forces the use of software rendering.</p>
143
144</li>
145</ul>
146
147<h2>EGL Drivers</h2>
148
149<p>There are two categories of EGL drivers: Gallium and classic.</p>
150
151<p>Gallium EGL drivers supports all rendering APIs specified in EGL 1.4. The
152support for optional EGL functions and EGL extensions is usually more complete
153than the classic ones. These drivers depend on the <code>egl_g3d</code> state
154tracker to build. The available drivers are</p>
155
156<ul>
157<li><code>egl_&lt;dpy&gt;_i915</code></li>
158<li><code>egl_&lt;dpy&gt;_i965</code></li>
159<li><code>egl_&lt;dpy&gt;_radeon</code></li>
160<li><code>egl_&lt;dpy&gt;_nouveau</code></li>
161<li><code>egl_&lt;dpy&gt;_vmwgfx</code></li>
162</ul>
163
164<p><code>&lt;dpy&gt;</code> is given by <code>--with-egl-displays</code> at
165configuration time. There will be one EGL driver for each combination of the
166displays listed and the hardware drivers enabled.</p>
167
168<p>Classic EGL drivers, on the other hand, supports only OpenGL as its
169rendering API. They can be found under <code>src/egl/drivers/</code>. There
170are 3 of them</p>
171
172<ul>
173<li><code>egl_glx</code>
174
175<p>This driver provides a wrapper to GLX. It uses exclusively GLX to implement
176the EGL API. It supports both direct and indirect rendering when the GLX does.
177It is accelerated when the GLX is. As such, it cannot provide functions that
178is not available in GLX or GLX extensions.</p>
179</li>
180
181<li><code>egl_xdri</code>
182
183<p>This driver supports the X Window System as its window system. It functions
184as a DRI driver loader. Unlike <code>egl_glx</code>, it has no dependency on
185<code>libGL</code>. It talks to the X server directly using DRI or DRI2
186protocols. It also talks minimal GLX protocol for things like available
187visuals or fbconfigs. With direct access to the DRI drivers, it has the
188potential to support more EGL functions that are not possible with
189<code>egl_glx</code></p>
190
191</li>
192<li><code>egl_dri</code>
193
194<p>This driver lacks maintenance and does <em>not</em> build. It is similiar
195to <code>egl_xdri</code> in that it functions as a DRI driver loader. But
196unlike <code>egl_xdri</code>, it supports Linux framebuffer devices as its
197window system and supports EGL_MESA_screen_surface extension. It loads only
198DRI1 drivers. As DRI1 drivers is phasing out, it might be better to rewrite
199the driver to support KMS and DRI2.</p>
200
201</li>
202</ul>
203
204<p>To use the classic drivers, one must manually set <code>EGL_DRIVER</code> at
205runtime.</p>
206
207<h2>Developers</h2>
208
209The sources of the main library and the classic drivers can be found at
210<code>src/egl/</code>. The sources of the <code>egl_g3d</code> state tracker
211can be found at <code>src/gallium/state_trackers/egl_g3d/</code>.
212
213<h3>TODOs</h3>
214
215<ul>
216<li>Thread safety</li>
217<li>Pass the conformance tests</li>
218<li>Better automatic driver selection: <code>EGL_DISPLAY</code> loads all
219drivers and might eat too much memory.</li>
220
221</ul>
222
223</body>
224</html>