faq.html 13.1 KB
Newer Older
1 2 3 4
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html lang="en">
<head>
  <meta http-equiv="content-type" content="text/html; charset=utf-8">
5
  <title>Frequently Asked Questions</title>
6 7 8
  <link rel="stylesheet" type="text/css" href="mesa.css">
</head>
<body>
9

10
<div class="header">
11
  The Mesa 3D Graphics Library
12 13 14 15 16
</div>

<iframe src="contents.html"></iframe>
<div class="content">

17
<h1>Frequently Asked Questions</h1>
18
Last updated: 19 September 2018
19 20

<h2>Index</h2>
21 22 23 24 25 26
<ol>
  <li><a href="#part1">High-level Questions and Answers</a></li>
  <li><a href="#part2">Compilation and Installation Problems</a></li>
  <li><a href="#part3">Runtime / Rendering Problems</a></li>
  <li><a href="#part4">Developer Questions</a></li>
</ol>
27

28
<h2 id="part1">1. High-level Questions and Answers</h2>
29

30
<h3>1.1 What is Mesa?</h3>
31
<p>
32
Mesa is an open-source implementation of the OpenGL specification.
Brian Paul's avatar
Brian Paul committed
33
OpenGL is a programming library for writing interactive 3D applications.
34
See the <a href="https://www.opengl.org/">OpenGL website</a> for more
35 36 37
information.
</p>
<p>
Andreas Boll's avatar
Andreas Boll committed
38
Mesa 9.x supports the OpenGL 3.1 specification.
39 40 41 42 43
</p>


<h2>1.2 Does Mesa support/use graphics hardware?</h2>
<p>
Brian Paul's avatar
Brian Paul committed
44
Yes.  Specifically, Mesa serves as the OpenGL core for the open-source DRI
45
drivers for X.org.
46
</p>
47
<ul>
48
  <li>See the <a href="https://dri.freedesktop.org/">DRI website</a>
49
  for more information.</li>
50
  <li>See <a href="https://01.org/linuxgraphics">01.org</a>
51
  for more information about Intel drivers.</li>
52
  <li>See <a href="https://nouveau.freedesktop.org">nouveau.freedesktop.org</a>
53
  for more information about Nouveau drivers.</li>
54
  <li>See <a href="https://www.x.org/wiki/RadeonFeature">www.x.org/wiki/RadeonFeature</a>
55 56
  for more information about Radeon drivers.</li>
</ul>
57

Brian Paul's avatar
Brian Paul committed
58
<h2>1.3 What purpose does Mesa serve today?</h2>
59
<p>
Brian Paul's avatar
Brian Paul committed
60 61
Hardware-accelerated OpenGL implementations are available for most popular
operating systems today.
62 63 64
Still, Mesa serves at least these purposes:
</p>
<ul>
65
<li>Mesa is used as the core of the open-source X.org DRI
Brian Paul's avatar
Brian Paul committed
66
    hardware drivers.
Brian Paul's avatar
Brian Paul committed
67 68 69 70 71
</li>
<li>Mesa is quite portable and allows OpenGL to be used on systems
    that have no other OpenGL solution.
</li>
<li>Software rendering with Mesa serves as a reference for validating the
72
    hardware drivers.
Brian Paul's avatar
Brian Paul committed
73 74 75 76 77 78
</li>
<li>A software implementation of OpenGL is useful for experimentation,
    such as testing new rendering techniques.
</li>
<li>Mesa can render images with deep color channels: 16-bit integer
    and 32-bit floating point color channels are supported.
79
    This capability is only now appearing in hardware.
Brian Paul's avatar
Brian Paul committed
80 81
</li>
<li>Mesa's internal limits (max lights, clip planes, texture size, etc) can be
82
    changed for special needs (hardware limits are hard to overcome).
Brian Paul's avatar
Brian Paul committed
83 84
</li>
</ul>
85

Brian Paul's avatar
Brian Paul committed
86

Andreas Boll's avatar
Andreas Boll committed
87
<h2>1.4 What's the difference between "Stand-Alone" Mesa and the DRI drivers?</h2>
Brian Paul's avatar
Brian Paul committed
88 89
<p>
<em>Stand-alone Mesa</em> is the original incarnation of Mesa.
Brian Paul's avatar
Brian Paul committed
90 91
On systems running the X Window System it does all its rendering through
the Xlib API:
92
</p>
Brian Paul's avatar
Brian Paul committed
93 94 95 96 97 98
<ul>
<li>The GLX API is supported, but it's really just an emulation of the
     real thing.
<li>The GLX wire protocol is not supported and there's no OpenGL extension
    loaded by the X server.
<li>There is no hardware acceleration.
99 100
<li>The OpenGL library, <code>libGL.so</code>, contains everything (the
    programming API, the GLX functions and all the rendering code).
Brian Paul's avatar
Brian Paul committed
101 102 103 104 105
</ul>
<p>
Alternately, Mesa acts as the core for a number of OpenGL hardware drivers
within the DRI (Direct Rendering Infrastructure):
<ul>
106 107 108 109
<li>The <code>libGL.so</code> library provides the GL and GLX API functions,
    a GLX protocol encoder, and a device driver loader.
<li>The device driver modules (such as <code>r200_dri.so</code>) contain
    a built-in copy of the core Mesa code.
Brian Paul's avatar
Brian Paul committed
110 111 112 113 114 115 116 117 118
<li>The X server loads the GLX module.
    The GLX module decodes incoming GLX protocol and dispatches the commands
    to a rendering module.
    For the DRI, this module is basically a software Mesa renderer.
</ul>



<h2>1.5 How do I upgrade my DRI installation to use a new Mesa release?</h2>
119
<p>
Brian Paul's avatar
Brian Paul committed
120 121 122 123
This wasn't easy in the past.
Now, the DRI drivers are included in the Mesa tree and can be compiled
separately from the X server.
Just follow the Mesa <a href="install.html">compilation instructions</a>.
Brian Paul's avatar
Brian Paul committed
124 125
</p>

126

Brian Paul's avatar
Brian Paul committed
127
<h2>1.6 Are there other open-source implementations of OpenGL?</h2>
128
<p>
129
Yes, SGI's <a href="http://web.archive.org/web/20171010115110_/http://oss.sgi.com/projects/ogl-sample/index.html">
Nathan Kidd's avatar
Nathan Kidd committed
130
OpenGL Sample Implementation (SI)</a> is available.
131 132 133 134
The SI was written during the time that OpenGL was originally designed.
Unfortunately, development of the SI has stagnated.
Mesa is much more up to date with modern features and extensions.
</p>
135 136

<p>
137
<a href="https://sourceforge.net/projects/ogl-es/">Vincent</a> is
138 139
an open-source implementation of OpenGL ES for mobile devices.

140
<p>
141 142 143
<a href="http://web.archive.org/web/20130830162848/http://www.dsbox.com/minigl.html">miniGL</a>
is a subset of OpenGL for PalmOS devices. The website is gone, but the source
code can still be found on <a href="https://sourceforge.net/projects/minigl/">sourceforge.net</a>.
144

Brian Paul's avatar
Brian Paul committed
145
<p>
146
<a href="http://bellard.org/TinyGL/">TinyGL</a>
147
is a subset of OpenGL.
148
</p>
Brian Paul's avatar
Brian Paul committed
149 150

<p>
151
<a href="https://sourceforge.net/projects/softgl/">SoftGL</a>
Brian Paul's avatar
Brian Paul committed
152 153 154
is an OpenGL subset for mobile devices.
</p>

155
<p>
156
<a href="http://chromium.sourceforge.net/">Chromium</a>
Brian Paul's avatar
Brian Paul committed
157 158 159 160 161
isn't a conventional OpenGL implementation (it's layered upon OpenGL),
but it does export the OpenGL API.  It allows tiled rendering, sort-last
rendering, etc.
</p>

162
<p>
163 164
<a href="http://www.ticalc.org/archives/files/fileinfo/361/36173.html">ClosedGL</a>
is an OpenGL subset library for TI graphing calculators.
165 166
</p>

Brian Paul's avatar
Brian Paul committed
167 168 169
<p>
There may be other open OpenGL implementations, but Mesa is the most
popular and feature-complete.
170 171
</p>

Brian Paul's avatar
Brian Paul committed
172

173
<h2 id="part2">2. Compilation and Installation Problems</h2>
174

175
<h3>2.1 What's the easiest way to install Mesa?</h3>
176
<p>
177
If you're using a Linux-based system, your distro CD most likely already
178
has Mesa packages (like RPM or DEB) which you can easily install.
179
</p>
180 181


182
<h3>2.2 I get undefined symbols such as bgnpolygon, v3f, etc...</h3>
183
<p>
184
You're application is written in IRIS GL, not OpenGL.
185 186 187
IRIS GL was the predecessor to OpenGL and is a different thing (almost)
entirely.
Mesa's not the solution.
188
</p>
189 190


191
<h3>2.3 Where is the GLUT library?</h3>
192
<p>
193 194
GLUT (OpenGL Utility Toolkit) is no longer in the separate
<code>MesaGLUT-x.y.z.tar.gz</code> file.
195 196
If you don't already have GLUT installed, you should grab 
<a href="http://freeglut.sourceforge.net/">freeglut</a>.
197
</p>
198 199


200
<h3>2.4 Where is the GLw library?</h3>
201
<p>
202
GLw (OpenGL widget library) is now available from a separate <a href="https://gitlab.freedesktop.org/mesa/glw">git repository</a>.  Unless you're using very old Xt/Motif applications with OpenGL, you shouldn't need it.
203
</p>
204

205

206
<h2>2.5 What's the proper place for the libraries and headers?</h2>
207
<p>
208
On Linux-based systems you'll want to follow the
209
<a href="https://www.khronos.org/registry/OpenGL/ABI/">Linux ABI</a> standard.
210 211
Basically you'll want the following:
</p>
212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230
<dl>
<dt><code>/usr/include/GL/gl.h</code></dt>
<dd>the main OpenGL header</dd>
<dt><code>/usr/include/GL/glu.h</code></dt>
<dd>the OpenGL GLU (utility) header</dd>
<dt><code>/usr/include/GL/glx.h</code></dt>
<dd>the OpenGL GLX header</dd>
<dt><code>/usr/include/GL/glext.h</code></dt>
<dd>the OpenGL extensions header</dd>
<dt><code>/usr/include/GL/glxext.h</code></dt>
<dd>the OpenGL GLX extensions header</dd>
<dt><code>/usr/include/GL/osmesa.h</code></dt>
<dd>the Mesa off-screen rendering header</dd>
<dt><code>/usr/lib/libGL.so</code></dt>
<dd>a symlink to <code>libGL.so.1</code></dd>
<dt><code>/usr/lib/libGL.so.1</code></dt>
<dd>a symlink to <code>libGL.so.1.xyz</code></dd>
<dt><code>/usr/lib/libGL.so.xyz</code></dt>
<dd>the actual OpenGL/Mesa library.  xyz denotes the
231
Mesa version number.
232 233
</dd>
</dl>
234
<p>
235
When configuring Mesa, there are three meson options that affect the install
Andreas Boll's avatar
Andreas Boll committed
236
location that you should take care with: <code>--prefix</code>,
237
<code>--libdir</code>, and <code>-D dri-drivers-path</code>. To install Mesa
Andreas Boll's avatar
Andreas Boll committed
238 239 240
into the system location where it will be available for all programs to use, set
<code>--prefix=/usr</code>. Set <code>--libdir</code> to where your Linux
distribution installs system libraries, usually either <code>/usr/lib</code> or
241
<code>/usr/lib64</code>. Set <code>-D dri-drivers-path</code> to the directory
Andreas Boll's avatar
Andreas Boll committed
242 243 244
where your Linux distribution installs DRI drivers. To find your system's DRI
driver directory, try executing <code>find /usr -type d -name dri</code>. For
example, if the <code>find</code> command listed <code>/usr/lib64/dri</code>,
245
then set <code>-D dri-drivers-path=/usr/lib64/dri</code>.
246 247
</p>
<p>
Andreas Boll's avatar
Andreas Boll committed
248
After determining the correct values for the install location, configure Mesa
249 250
with <code>meson configure --prefix=/usr --libdir=xxx -D dri-drivers-path=xxx</code>
and then install with <code>sudo ninja install</code>.
251 252 253
</p>


254
<h2 id="part3">3. Runtime / Rendering Problems</h2>
255

256
<h3>3.1 Rendering is slow / why isn't my graphics hardware being used?</h3>
257
<p>
Andreas Boll's avatar
Andreas Boll committed
258 259
If Mesa can't use its hardware accelerated drivers it falls back on one of its software renderers.
(eg. classic swrast, softpipe or llvmpipe)
260
</p>
261
<p>
262
You can run the <code>glxinfo</code> program to learn about your OpenGL
263
library.
Andreas Boll's avatar
Andreas Boll committed
264 265
Look for the <code>OpenGL vendor</code> and <code>OpenGL renderer</code> values.
That will identify who's OpenGL library with which driver you're using and what sort of
266
hardware it has detected.
267
</p>
268
<p>
Andreas Boll's avatar
Andreas Boll committed
269 270 271
If you're using a hardware accelerated driver you want <code>direct rendering: Yes</code>.
</p>
<p>
272
If your DRI-based driver isn't working, go to the
273
<a href="https://dri.freedesktop.org/">DRI website</a> for trouble-shooting information.
274 275 276
</p>


277
<h3>3.2 I'm seeing errors in depth (Z) buffering.  Why?</h3>
278 279 280
<p>
Make sure the ratio of the far to near clipping planes isn't too great.
Look
281
<a href="https://www.opengl.org/archives/resources/faq/technical/depthbuffer.htm#0040">here</a>
282
for details.
283 284 285 286 287
</p>
<p>
Mesa uses a 16-bit depth buffer by default which is smaller and faster
to clear than a 32-bit buffer but not as accurate.
If you need a deeper you can modify the parameters to
288
<code>glXChooseVisual</code> in your code.
289 290 291
</p>


292
<h3>3.3 Why Isn't depth buffering working at all?</h3>
293
<p>
294 295 296
Be sure you're requesting a depth buffered-visual.  If you set the
<code>MESA_DEBUG</code> environment variable it will warn you about trying
to enable depth testing when you don't have a depth buffer.
297 298 299
</p>
<p>Specifically, make sure <code>glutInitDisplayMode</code> is being called
with <code>GLUT_DEPTH</code> or <code>glXChooseVisual</code> is being
300
called with a non-zero value for <code>GLX_DEPTH_SIZE</code>.
301 302 303 304 305 306
</p>
<p>This discussion applies to stencil buffers, accumulation buffers and
alpha channels too.
</p>


307
<h3>3.4 Why does <code>glGetString()</code> always return <code>NULL</code>?</h3>
308 309
<p>
Be sure you have an active/current OpenGL rendering context before
310
calling <code>glGetString</code>.
311 312 313
</p>


314 315
<h3>3.5 <code>GL_POINTS</code> and <code>GL_LINES</code> don't touch the
right pixels</h3>
316
<p>
317 318 319 320 321
If you're trying to draw a filled region by using <code>GL_POINTS</code> or
<code>GL_LINES</code> and seeing holes or gaps it's because of a float-to-int
rounding problem. But this is not a bug. See Appendix H of the OpenGL
Programming Guide - "OpenGL Correctness Tips". Basically, applying a
translation of (0.375, 0.375, 0.0) to your coordinates will fix the problem.
322 323 324
</p>


325
<h2 id="part4">4. Developer Questions</h2>
326

327
<h3>4.1 How can I contribute?</h3>
328
<p>
Andreas Boll's avatar
Andreas Boll committed
329
First, join the <a href="lists.html">mesa-dev mailing list</a>.
Brian Paul's avatar
Brian Paul committed
330
That's where Mesa development is discussed.
331
</p>
332
<p>
333
The <a href="https://www.opengl.org/documentation">
Nathan Kidd's avatar
Nathan Kidd committed
334
OpenGL Specification</a> is the bible for OpenGL implementation work.
335 336 337 338 339 340
You should read it.
</p>
<p>Most of the Mesa development work involves implementing new OpenGL
extensions, writing hardware drivers (for the DRI), and code optimization.
</p>

341
<h3>4.2 How do I write a new device driver?</h3>
342 343 344 345 346 347 348 349 350
<p>
Unfortunately, writing a device driver isn't easy.
It requires detailed understanding of OpenGL, the Mesa code, and your
target hardware/operating system.
3D graphics are not simple.
</p>
<p>
The best way to get started is to use an existing driver as your starting
point.
Andreas Boll's avatar
Andreas Boll committed
351 352
For a classic hardware driver, the i965 driver is a good example.
For a Gallium3D hardware driver, the r300g, r600g and the i915g are good examples.
353 354 355
</p>
<p>The DRI website has more information about writing hardware drivers.
The process isn't well document because the Mesa driver interface changes
Nathan Kidd's avatar
Nathan Kidd committed
356
over time, and we seldom have spare time for writing documentation.
357 358 359 360 361 362 363 364
That being said, many people have managed to figure out the process.
</p>
<p>
Joining the appropriate mailing lists and asking questions (and searching
the archives) is a good way to get information.
</p>


365 366
<h3>4.3 Why isn't <code>GL_EXT_texture_compression_s3tc</code> implemented in
Mesa?</h3>
367
<p>
368 369 370
Oh but it is! Prior to 2nd October 2017, the Mesa project did not include s3tc
support due to intellectual property (IP) and/or patent issues around the s3tc
algorithm.
371
</p>
372 373
<p>
As of Mesa 17.3.0, Mesa now officially supports s3tc, as the patent has expired.
374 375
</p>
<p>
376 377
In versions prior to this, a 3rd party <a href="https://dri.freedesktop.org/wiki/S3TC">
plug-in library</a> was required.
378 379
</p>

380
</div>
381 382
</body>
</html>