docs/faq.html

   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 FAQ</title>
   6   <link rel="stylesheet" type="text/css" href="mesa.css">
   7 </head>
   8 <body>
   9
  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
  17 <center>
  18 <h1>Mesa Frequently Asked Questions</h1>
  19 Last updated: 9 October 2012
  20 </center>
  21
  22 <br>
  23 <br>
  24 <h2>Index</h2>
  25 <a href="#part1">1. High-level Questions and Answers</a>
  26 <br>
  27 <a href="#part2">2. Compilation and Installation Problems</a>
  28 <br>
  29 <a href="#part3">3. Runtime / Rendering Problems</a>
  30 <br>
  31 <a href="#part4">4. Developer Questions</a>
  32 <br>
  33 <br>
  34 <br>
  35
  36
  37
  38 <h1 id="part1">1. High-level Questions and Answers</h1>
  39
  40 <h2>1.1 What is Mesa?</h2>
  41 <p>
  42 Mesa is an open-source implementation of the OpenGL specification.
  43 OpenGL is a programming library for writing interactive 3D applications.
  44 See the <a href="http://www.opengl.org/">OpenGL website</a> for more
  45 information.
  46 </p>
  47 <p>
  48 Mesa 9.x supports the OpenGL 3.1 specification.
  49 </p>
  50
  51
  52 <h2>1.2 Does Mesa support/use graphics hardware?</h2>
  53 <p>
  54 Yes.  Specifically, Mesa serves as the OpenGL core for the open-source DRI
  55 drivers for X.org.
  56 </p>
  57 <ul>
  58   <li>See the <a href="http://dri.freedesktop.org/">DRI website</a>
  59   for more information.</li>
  60   <li>See <a href="http://intellinuxgraphics.org">intellinuxgraphics.org</a>
  61   for more information about Intel drivers.</li>
  62   <li>See <a href="http://nouveau.freedesktop.org">nouveau.freedesktop.org</a>
  63   for more information about Nouveau drivers.</li>
  64   <li>See <a href="http://www.x.org/wiki/RadeonFeature">www.x.org/wiki/RadeonFeature</a>
  65   for more information about Radeon drivers.</li>
  66 </ul>
  67
  68 <h2>1.3 What purpose does Mesa serve today?</h2>
  69 <p>
  70 Hardware-accelerated OpenGL implementations are available for most popular
  71 operating systems today.
  72 Still, Mesa serves at least these purposes:
  73 </p>
  74 <ul>
  75 <li>Mesa is used as the core of the open-source X.org DRI
  76     hardware drivers.
  77 </li>
  78 <li>Mesa is quite portable and allows OpenGL to be used on systems
  79     that have no other OpenGL solution.
  80 </li>
  81 <li>Software rendering with Mesa serves as a reference for validating the
  82     hardware drivers.
  83 </li>
  84 <li>A software implementation of OpenGL is useful for experimentation,
  85     such as testing new rendering techniques.
  86 </li>
  87 <li>Mesa can render images with deep color channels: 16-bit integer
  88     and 32-bit floating point color channels are supported.
  89     This capability is only now appearing in hardware.
  90 </li>
  91 <li>Mesa's internal limits (max lights, clip planes, texture size, etc) can be
  92     changed for special needs (hardware limits are hard to overcome).
  93 </li>
  94 </ul>
  95
  96
  97 <h2>1.4 What's the difference between "Stand-Alone" Mesa and the DRI drivers?</h2>
  98 <p>
  99 <em>Stand-alone Mesa</em> is the original incarnation of Mesa.
 100 On systems running the X Window System it does all its rendering through
 101 the Xlib API:
 102 </p>
 103 <ul>
 104 <li>The GLX API is supported, but it's really just an emulation of the
 105      real thing.
 106 <li>The GLX wire protocol is not supported and there's no OpenGL extension
 107     loaded by the X server.
 108 <li>There is no hardware acceleration.
 109 <li>The OpenGL library, libGL.so, contains everything (the programming API,
 110     the GLX functions and all the rendering code).
 111 </ul>
 112 <p>
 113 Alternately, Mesa acts as the core for a number of OpenGL hardware drivers
 114 within the DRI (Direct Rendering Infrastructure):
 115 <ul>
 116 <li>The libGL.so library provides the GL and GLX API functions, a GLX
 117     protocol encoder, and a device driver loader.
 118 <li>The device driver modules (such as r200_dri.so) contain a built-in
 119     copy of the core Mesa code.
 120 <li>The X server loads the GLX module.
 121     The GLX module decodes incoming GLX protocol and dispatches the commands
 122     to a rendering module.
 123     For the DRI, this module is basically a software Mesa renderer.
 124 </ul>
 125
 126
 127
 128 <h2>1.5 How do I upgrade my DRI installation to use a new Mesa release?</h2>
 129 <p>
 130 This wasn't easy in the past.
 131 Now, the DRI drivers are included in the Mesa tree and can be compiled
 132 separately from the X server.
 133 Just follow the Mesa <a href="install.html">compilation instructions</a>.
 134 </p>
 135
 136
 137 <h2>1.6 Are there other open-source implementations of OpenGL?</h2>
 138 <p>
 139 Yes, SGI's <a href="http://oss.sgi.com/projects/ogl-sample/index.html">
 140 OpenGL Sample Implementation (SI)</a> is available.
 141 The SI was written during the time that OpenGL was originally designed.
 142 Unfortunately, development of the SI has stagnated.
 143 Mesa is much more up to date with modern features and extensions.
 144 </p>
 145
 146 <p>
 147 <a href="http://sourceforge.net/projects/ogl-es/">Vincent</a> is
 148 an open-source implementation of OpenGL ES for mobile devices.
 149
 150 <p>
 151 <a href="http://www.dsbox.com/minigl.html">miniGL</a>
 152 is a subset of OpenGL for PalmOS devices.
 153
 154 <p>
 155 <a href="http://bellard.org/TinyGL/">TinyGL</a>
 156 is a subset of OpenGL.
 157 </p>
 158
 159 <p>
 160 <a href="http://sourceforge.net/projects/softgl/">SoftGL</a>
 161 is an OpenGL subset for mobile devices.
 162 </p>
 163
 164 <p>
 165 <a href="http://chromium.sourceforge.net/">Chromium</a>
 166 isn't a conventional OpenGL implementation (it's layered upon OpenGL),
 167 but it does export the OpenGL API.  It allows tiled rendering, sort-last
 168 rendering, etc.
 169 </p>
 170
 171 <p>
 172 <a href="http://www.ticalc.org/archives/files/fileinfo/361/36173.html">ClosedGL</a>
 173 is an OpenGL subset library for TI graphing calculators.
 174 </p>
 175
 176 <p>
 177 There may be other open OpenGL implementations, but Mesa is the most
 178 popular and feature-complete.
 179 </p>
 180
 181
 182
 183 <br>
 184 <br>
 185
 186
 187 <h1 id="part2">2. Compilation and Installation Problems</h1>
 188
 189
 190 <h2>2.1 What's the easiest way to install Mesa?</h2>
 191 <p>
 192 If you're using a Linux-based system, your distro CD most likely already
 193 has Mesa packages (like RPM or DEB) which you can easily install.
 194 </p>
 195
 196
 197 <h2>2.2 I get undefined symbols such as bgnpolygon, v3f, etc...</h2>
 198 <p>
 199 You're application is written in IRIS GL, not OpenGL.
 200 IRIS GL was the predecessor to OpenGL and is a different thing (almost)
 201 entirely.
 202 Mesa's not the solution.
 203 </p>
 204
 205
 206 <h2>2.3 Where is the GLUT library?</h2>
 207 <p>
 208 GLUT (OpenGL Utility Toolkit) is no longer in the separate MesaGLUT-x.y.z.tar.gz file.
 209 If you don't already have GLUT installed, you should grab
 210 <a href="http://freeglut.sourceforge.net/">freeglut</a>.
 211 </p>
 212
 213
 214 <h2>2.4 Where is the GLw library?</h2>
 215 <p>
 216 GLw (OpenGL widget library) is now available from a separate <a href="http://cgit.freedesktop.org/mesa/glw/">git repository</a>.  Unless you're using very old Xt/Motif applications with OpenGL, you shouldn't need it.
 217 </p>
 218
 219
 220 <h2>2.5 What's the proper place for the libraries and headers?</h2>
 221 <p>
 222 On Linux-based systems you'll want to follow the
 223 <a href="http://oss.sgi.com/projects/ogl-sample/ABI/index.html">Linux ABI</a> standard.
 224 Basically you'll want the following:
 225 </p>
 226 <ul>
 227 <li>/usr/include/GL/gl.h - the main OpenGL header
 228 </li><li>/usr/include/GL/glu.h - the OpenGL GLU (utility) header
 229 </li><li>/usr/include/GL/glx.h - the OpenGL GLX header
 230 </li><li>/usr/include/GL/glext.h - the OpenGL extensions header
 231 </li><li>/usr/include/GL/glxext.h - the OpenGL GLX extensions header
 232 </li><li>/usr/include/GL/osmesa.h - the Mesa off-screen rendering header
 233 </li><li>/usr/lib/libGL.so - a symlink to libGL.so.1
 234 </li><li>/usr/lib/libGL.so.1 - a symlink to libGL.so.1.xyz
 235 </li><li>/usr/lib/libGL.so.xyz - the actual OpenGL/Mesa library.  xyz denotes the
 236 Mesa version number.
 237 </li></ul>
 238 <p>
 239 When configuring Mesa, there are three autoconf options that affect the install
 240 location that you should take care with: <code>--prefix</code>,
 241 <code>--libdir</code>, and <code>--with-dri-driverdir</code>. To install Mesa
 242 into the system location where it will be available for all programs to use, set
 243 <code>--prefix=/usr</code>. Set <code>--libdir</code> to where your Linux
 244 distribution installs system libraries, usually either <code>/usr/lib</code> or
 245 <code>/usr/lib64</code>. Set <code>--with-dri-driverdir</code> to the directory
 246 where your Linux distribution installs DRI drivers. To find your system's DRI
 247 driver directory, try executing <code>find /usr -type d -name dri</code>. For
 248 example, if the <code>find</code> command listed <code>/usr/lib64/dri</code>,
 249 then set <code>--with-dri-driverdir=/usr/lib64/dri</code>.
 250 </p>
 251 <p>
 252 After determining the correct values for the install location, configure Mesa
 253 with <code>./configure --prefix=/usr --libdir=xxx --with-dri-driverdir=xxx</code>
 254 and then install with <code>sudo make install</code>.
 255 </p>
 256 <br>
 257 <br>
 258
 259
 260 <h1 id="part3">3. Runtime / Rendering Problems</h1>
 261
 262 <h2>3.1 Rendering is slow / why isn't my graphics hardware being used?</h2>
 263 <p>
 264 If Mesa can't use its hardware accelerated drivers it falls back on one of its software renderers.
 265 (eg. classic swrast, softpipe or llvmpipe)
 266 </p>
 267 <p>
 268 You can run the <code>glxinfo</code> program to learn about your OpenGL
 269 library.
 270 Look for the <code>OpenGL vendor</code> and <code>OpenGL renderer</code> values.
 271 That will identify who's OpenGL library with which driver you're using and what sort of
 272 hardware it has detected.
 273 </p>
 274 <p>
 275 If you're using a hardware accelerated driver you want <code>direct rendering: Yes</code>.
 276 </p>
 277 <p>
 278 If your DRI-based driver isn't working, go to the
 279 <a href="http://dri.freedesktop.org/">DRI website</a> for trouble-shooting information.
 280 </p>
 281
 282
 283 <h2>3.2 I'm seeing errors in depth (Z) buffering.  Why?</h2>
 284 <p>
 285 Make sure the ratio of the far to near clipping planes isn't too great.
 286 Look
 287 <a href="http://www.opengl.org/resources/faq/technical/depthbuffer.htm#0040">here</a>
 288 for details.
 289 </p>
 290 <p>
 291 Mesa uses a 16-bit depth buffer by default which is smaller and faster
 292 to clear than a 32-bit buffer but not as accurate.
 293 If you need a deeper you can modify the parameters to
 294 <code> glXChooseVisual</code> in your code.
 295 </p>
 296
 297
 298 <h2>3.3 Why Isn't depth buffering working at all?</h2>
 299 <p>
 300 Be sure you're requesting a depth buffered-visual.  If you set the MESA_DEBUG
 301 environment variable it will warn you about trying to enable depth testing
 302 when you don't have a depth buffer.
 303 </p>
 304 <p>Specifically, make sure <code>glutInitDisplayMode</code> is being called
 305 with <code>GLUT_DEPTH</code> or <code>glXChooseVisual</code> is being
 306 called with a non-zero value for GLX_DEPTH_SIZE.
 307 </p>
 308 <p>This discussion applies to stencil buffers, accumulation buffers and
 309 alpha channels too.
 310 </p>
 311
 312
 313 <h2>3.4 Why does glGetString() always return NULL?</h2>
 314 <p>
 315 Be sure you have an active/current OpenGL rendering context before
 316 calling glGetString.
 317 </p>
 318
 319
 320 <h2>3.5 GL_POINTS and GL_LINES don't touch the right pixels</h2>
 321 <p>
 322 If you're trying to draw a filled region by using GL_POINTS or GL_LINES
 323 and seeing holes or gaps it's because of a float-to-int rounding problem.
 324 But this is not a bug.
 325 See Appendix H of the OpenGL Programming Guide - "OpenGL Correctness Tips".
 326 Basically, applying a translation of (0.375, 0.375, 0.0) to your coordinates
 327 will fix the problem.
 328 </p>
 329
 330 <br>
 331 <br>
 332
 333
 334 <h1 id="part4">4. Developer Questions</h1>
 335
 336 <h2>4.1 How can I contribute?</h2>
 337 <p>
 338 First, join the <a href="lists.html">mesa-dev mailing list</a>.
 339 That's where Mesa development is discussed.
 340 </p>
 341 <p>
 342 The <a href="http://www.opengl.org/documentation">
 343 OpenGL Specification</a> is the bible for OpenGL implementation work.
 344 You should read it.
 345 </p>
 346 <p>Most of the Mesa development work involves implementing new OpenGL
 347 extensions, writing hardware drivers (for the DRI), and code optimization.
 348 </p>
 349
 350 <h2>4.2 How do I write a new device driver?</h2>
 351 <p>
 352 Unfortunately, writing a device driver isn't easy.
 353 It requires detailed understanding of OpenGL, the Mesa code, and your
 354 target hardware/operating system.
 355 3D graphics are not simple.
 356 </p>
 357 <p>
 358 The best way to get started is to use an existing driver as your starting
 359 point.
 360 For a classic hardware driver, the i965 driver is a good example.
 361 For a Gallium3D hardware driver, the r300g, r600g and the i915g are good examples.
 362 </p>
 363 <p>The DRI website has more information about writing hardware drivers.
 364 The process isn't well document because the Mesa driver interface changes
 365 over time, and we seldom have spare time for writing documentation.
 366 That being said, many people have managed to figure out the process.
 367 </p>
 368 <p>
 369 Joining the appropriate mailing lists and asking questions (and searching
 370 the archives) is a good way to get information.
 371 </p>
 372
 373
 374 <h2>4.3 Why isn't GL_EXT_texture_compression_s3tc implemented in Mesa?</h2>
 375 <p>
 376 The <a href="http://oss.sgi.com/projects/ogl-sample/registry/EXT/texture_compression_s3tc.txt">specification for the extension</a>
 377 indicates that there are intellectual property (IP) and/or patent issues
 378 to be dealt with.
 379 </p>
 380 <p>We've been unsuccessful in getting a response from S3 (or whoever owns
 381 the IP nowadays) to indicate whether or not an open source project can
 382 implement the extension (specifically the compression/decompression
 383 algorithms).
 384 </p>
 385 <p>
 386 In the mean time, a 3rd party <a href="http://dri.freedesktop.org/wiki/S3TC">
 387 plug-in library</a> is available.
 388 </p>
 389
 390 </div>
 391 </body>
 392 </html>