Brian Paul | 0b27ace | 2003-03-08 17:38:57 +0000 | [diff] [blame] | 1 | <html> |
| 2 | |
| 3 | <head><title>Mesa FAQ</title></head> |
| 4 | |
| 5 | <BODY text="#000000" bgcolor="#55bbff" link="#111188"> |
| 6 | |
| 7 | |
| 8 | <center> |
| 9 | <h1>Mesa Frequently Asked Questions</h1> |
| 10 | Last updated: 7 March 2003 |
| 11 | </center> |
| 12 | |
| 13 | <br> |
| 14 | <br> |
| 15 | <h2>Index</h2> |
| 16 | <a href="#part1">1. High-level Questions and Answers</a> |
| 17 | <br> |
| 18 | <a href="#part2">2. Compilation and Installation Problems</a> |
| 19 | <br> |
| 20 | <a href="#part3">3. Runtime / Rendering Problems</a> |
| 21 | <br> |
| 22 | <a href="#part4">4. Developer Questions</a> |
| 23 | <br> |
| 24 | <br> |
| 25 | <br> |
| 26 | |
| 27 | |
| 28 | |
| 29 | <a name="part1"> |
| 30 | </a><h1><a name="part1">1. High-level Questions and Answers</a></h1> |
| 31 | |
| 32 | <h2><a name="part1">1.1 What is Mesa?</a></h2> |
| 33 | <p> |
| 34 | <a name="part1">Mesa is an open-source implementation of the OpenGL specification. |
| 35 | OpenGL is a high-level programming library for interactive 3D graphics. |
| 36 | See the </a><a href="http://www.opengl.org/">OpenGL website</a> for more |
| 37 | information. |
| 38 | </p> |
| 39 | <p> |
| 40 | Mesa 5.0.x supports the OpenGL 1.4 specification. |
| 41 | </p> |
| 42 | |
| 43 | |
| 44 | <h2>1.2 Does Mesa support/use graphics hardware?</h2> |
| 45 | <p> |
| 46 | Yes. Specifically, Mesa serves as the OpenGL core for the XFree86/DRI |
| 47 | OpenGL drivers. See the <a href="http://dri.sf.net/">DRI website</a> for |
| 48 | more information. |
| 49 | </p> |
| 50 | <p> |
| 51 | There have been other hardware drivers for Mesa over the years (such as |
| 52 | the 3Dfx Glide/Voodoo driver, an old S3 driver, etc) but the DRI drivers |
| 53 | are the modern ones. |
| 54 | </p> |
| 55 | |
| 56 | <h2>1.3 What purpose does (software) Mesa serve today?</h2> |
| 57 | <p> |
| 58 | Commercial, hardware-accelerated OpenGL implementations are available for |
| 59 | many operating systems today. |
| 60 | Still, Mesa serves at least these purposes: |
| 61 | </p> |
| 62 | <ul> |
| 63 | <li>Mesa is used as the core of the XFree86/DRI hardware drivers. |
| 64 | </li><li>Mesa is quite portable and allows OpenGL to be used on systems that have |
| 65 | no other OpenGL solution. |
| 66 | </li><li>Software rendering with Mesa serves as a reference for validating the |
| 67 | hardware drivers. |
| 68 | </li><li>A software implementation of OpenGL is useful for experimentation, such |
| 69 | as testing new rendering techniques. |
| 70 | </li><li>Mesa can render images with deep color channels: 16-bit integer and 32-bit |
| 71 | floating point color channels are supported. |
| 72 | This capability is only now appearing in hardware. |
| 73 | </li><li>Mesa's internal limits (max lights, clip planes, texture size, etc) can be |
| 74 | changed for special needs (hardware limits are hard to overcome). |
| 75 | </li></ul> |
| 76 | |
| 77 | <h2>1.4 How do I upgrade my DRI installation to use a new Mesa release?</h2> |
| 78 | <p> |
| 79 | You don't! The Mesa source code lives inside the XFree86/DRI source tree |
| 80 | and gets compiled into the individual DRI driver modules. |
| 81 | If you try to install Mesa over an XFree86/DRI installation, you'll lose |
| 82 | hardware rendering (because Mesa's libGL.so is different than the XFree86 |
| 83 | libGL.so). |
| 84 | </p> |
| 85 | <p> |
| 86 | The DRI developers will incorporate the latest release of Mesa into the |
| 87 | DRI drivers when the time is right. |
| 88 | </p> |
| 89 | |
| 90 | <h2>1.5 Are there other open-source implementations of OpenGL?</h2> |
| 91 | <p> |
| 92 | Yes, SGI's <a href="http://oss.sgi.com/projects/ogl-sample/index.html"> |
| 93 | OpenGL Sample Implemenation (SI)</a> is available. |
| 94 | The SI was written during the time that OpenGL was originally designed. |
| 95 | Unfortunately, development of the SI has stagnated. |
| 96 | Mesa is much more up to date with modern features and extensions. |
| 97 | </p> |
| 98 | <p> |
| 99 | <a href="http://www.dsbox.com/minigl.html">miniGL</a> is a subset of OpenGL |
| 100 | for PalmOS devices. |
| 101 | |
| 102 | <a href="http://fabrice.bellard.free.fr/TinyGL/">TinyGL</a> is another |
| 103 | subset of OpenGL. |
| 104 | </p> |
| 105 | <p> |
| 106 | There may be others but Mesa is the most popular and feature-complete. |
| 107 | </p> |
| 108 | |
| 109 | <br> |
| 110 | <br> |
| 111 | |
| 112 | |
| 113 | <a name="part2"> |
| 114 | </a><h1><a name="part2">2. Compilation and Installation Problems</a></h1> |
| 115 | |
| 116 | |
| 117 | <h2><a name="part2">2.1 What's the easiest way to install Mesa?</a></h2> |
| 118 | <p> |
| 119 | <a name="part2">If you're using a Linux-based system, your distro CD most likely already |
| 120 | has Mesa packages (like RPM or DEB) which you can easily install. |
| 121 | </a></p> |
| 122 | |
| 123 | |
| 124 | <h2><a name="part2">2.2 Running <code>configure; make</code> Doesn't Work</a></h2> |
| 125 | <p> |
| 126 | <a name="part2">Unfortunately, the GNU autoconf/automake/libtool system doesn't seem to work |
| 127 | too well on non GNU/Linux systems, even after installing gmake, gcc, etc. |
| 128 | For that reason, Mesa's <b>old-style</b> makefile system is still included. |
| 129 | The old-style system uses good old traditional Makefiles. Try the following: |
| 130 | </a></p><pre><a name="part2"> cd Mesa-x.y.z |
| 131 | cp Makefile.X11 Makefile |
| 132 | make |
| 133 | </a></pre> |
| 134 | <a name="part2">You'll see a list of system configurations from which to choose. |
| 135 | For example: |
| 136 | </a><pre><a name="part2"> make linux-x86 |
| 137 | </a></pre> |
| 138 | <p> |
| 139 | <a name="part2">If you're experienced with GNU autoconf/automake/libtool and think you can help |
| 140 | with maintence, contact the Mesa developers. |
| 141 | FYI, the Mesa developers generally don't use the autoconf/automake system. |
| 142 | We're especially annoyed with the fact that a +5000-line script (libtool) |
| 143 | is needed to make shared libraries (ugh). |
| 144 | </a></p> |
| 145 | |
| 146 | <h2><a name="part2">2.3 Mesa still doesn't compile</a></h2> |
| 147 | <p> |
| 148 | <a name="part2">If the old-style Makefile system doesn't work either, make sure you have |
| 149 | the most recent version of Mesa. |
| 150 | Otherwise, file a bug report or post to the Mesa3d-users mailing list. |
| 151 | Give as much info as possible when describing your problem. |
| 152 | </a></p> |
| 153 | |
| 154 | |
| 155 | <h2><a name="part2">2.4 I get undefined symbols such as bgnpolygon, v3f, etc...</a></h2> |
| 156 | <p> |
| 157 | <a name="part2">You're application is written in IRIS GL, not OpenGL. |
| 158 | IRIS GL was the predecessor to OpenGL and is a different thing (almost) |
| 159 | entirely. |
| 160 | Mesa's not the solution. |
| 161 | </a></p> |
| 162 | |
| 163 | |
| 164 | <h2><a name="part2">2.5 Where is the GLUT library?</a></h2> |
| 165 | <p> |
| 166 | <a name="part2">GLUT (OpenGL Utility Toolkit) is in the separate MesaDemos-x.y.z.tar.gz file. |
| 167 | If you don't already have GLUT installed, you should grab the MesaDemos |
| 168 | package and unpack it before compiling Mesa. |
| 169 | </a></p> |
| 170 | |
| 171 | |
| 172 | |
| 173 | <h2><a name="part2">2.6 What's the proper place for the libraries and headers?</a></h2> |
| 174 | <p> |
| 175 | <a name="part2">On Linux-based systems you'll want to follow the |
| 176 | </a><a href="http://oss.sgi.com/projects/ogl-sample/ABI/index.html">Linux ABI</a> |
| 177 | standard. |
| 178 | Basically you'll want the following: |
| 179 | </p> |
| 180 | <ul> |
| 181 | <li>/usr/include/GL/gl.h - the main OpenGL header |
| 182 | </li><li>/usr/include/GL/glu.h - the OpenGL GLU (utility) header |
| 183 | </li><li>/usr/include/GL/glx.h - the OpenGL GLX header |
| 184 | </li><li>/usr/include/GL/glext.h - the OpenGL extensions header |
| 185 | </li><li>/usr/include/GL/glxext.h - the OpenGL GLX extensions header |
| 186 | </li><li>/usr/include/GL/osmesa.h - the Mesa off-screen rendering header |
| 187 | </li><li>/usr/lib/libGL.so - a symlink to libGL.so.1 |
| 188 | </li><li>/usr/lib/libGL.so.1 - a symlink to libGL.so.1.xyz |
| 189 | </li><li>/usr/lib/libGL.so.xyz - the actual OpenGL/Mesa library. xyz denotes the |
| 190 | Mesa version number. |
| 191 | </li><li>/usr/lib/libGLU.so - a symlink to libGLU.so.1 |
| 192 | </li><li>/usr/lib/libGLU.so.1 - a symlink to libGLU.so.1.3.xyz |
| 193 | </li><li>/usr/lib/libGLU.so.xyz - the OpenGL Utility library. xyz denotes the Mesa |
| 194 | version number. |
| 195 | </li></ul> |
| 196 | <p> |
| 197 | After installing XFree86 and the DRI drivers, some of these files |
| 198 | may be symlinks into the /usr/X11R6/ tree. |
| 199 | </p> |
| 200 | <p> |
| 201 | The old-style Makefile system doesn't install the Mesa libraries; it's |
| 202 | up to you to copy them (and the headers) to the right place. |
| 203 | </p> |
| 204 | <p> |
| 205 | The GLUT header and library should go in the same directories. |
| 206 | </p> |
| 207 | <br> |
| 208 | <br> |
| 209 | |
| 210 | |
| 211 | <a name="part3"> |
| 212 | </a><h1><a name="part3">3. Runtime / Rendering Problems</a></h1> |
| 213 | |
| 214 | <h2><a name="part3">3.1 Rendering is slow / why isn't my graphics hardware being used?</a></h2> |
| 215 | <p> |
| 216 | <a name="part3">Stand-alone Mesa (downloaded as MesaLib-x.y.z.tar.gz) doesn't have any |
| 217 | support for hardware acceleration (with the exception of the 3DFX Voodoo |
| 218 | driver). |
| 219 | </a></p> |
| 220 | <p> |
| 221 | <a name="part3">What you really want is a DRI or NVIDIA (or another vendor's OpenGL) driver |
| 222 | for your particular hardware. |
| 223 | </a></p> |
| 224 | <p> |
| 225 | <a name="part3">You can run the <code>glxinfo</code> program to learn about your OpenGL |
| 226 | library. |
| 227 | Look for the GL_VENDOR and GL_RENDERER values. |
| 228 | That will identify who's OpenGL library you're using and what sort of |
| 229 | hardware it has detected. |
| 230 | </a></p> |
| 231 | <p> |
| 232 | <a name="part3">If your DRI-based driver isn't working, go to the |
| 233 | </a><a href="http://dri.sf.net/">DRI website</a> for trouble-shooting information. |
| 234 | </p> |
| 235 | |
| 236 | |
| 237 | <h2>3.2 I'm seeing errors in depth (Z) buffering. Why?</h2> |
| 238 | <p> |
| 239 | Make sure the ratio of the far to near clipping planes isn't too great. |
| 240 | Look |
| 241 | <a href="http://www.sgi.com/software/opengl/advanced97/notes/node18.html"> |
| 242 | here</a> for details. |
| 243 | </p> |
| 244 | <p> |
| 245 | Mesa uses a 16-bit depth buffer by default which is smaller and faster |
| 246 | to clear than a 32-bit buffer but not as accurate. |
| 247 | If you need a deeper you can modify the parameters to |
| 248 | <code> glXChooseVisual</code> in your code. |
| 249 | </p> |
| 250 | |
| 251 | |
| 252 | <h2>3.3 Why Isn't depth buffering working at all?</h2> |
| 253 | <p> |
| 254 | Be sure you're requesting a depth buffered-visual. If you set the MESA_DEBUG |
| 255 | environment variable it will warn you about trying to enable depth testing |
| 256 | when you don't have a depth buffer. |
| 257 | </p> |
| 258 | <p>Specifically, make sure <code>glutInitDisplayMode</code> is being called |
| 259 | with <code>GLUT_DEPTH</code> or <code>glXChooseVisual</code> is being |
| 260 | called with a non-zero value for GLX_DEPTH_SIZE. |
| 261 | </p> |
| 262 | <p>This discussion applies to stencil buffers, accumulation buffers and |
| 263 | alpha channels too. |
| 264 | </p> |
| 265 | |
| 266 | |
| 267 | <h2>3.4 Why does glGetString() always return NULL?</h2> |
| 268 | <p> |
| 269 | Be sure you have an active/current OpenGL rendering context before |
| 270 | calling glGetString. |
| 271 | </p> |
| 272 | |
| 273 | |
| 274 | <h2>3.5 GL_POINTS and GL_LINES don't touch the right pixels</h2> |
| 275 | <p> |
| 276 | If you're trying to draw a filled region by using GL_POINTS or GL_LINES |
| 277 | and seeing holes or gaps it's because of a float-to-int rounding problem. |
| 278 | But this is not a bug. |
| 279 | See Appendix H of the OpenGL Programming Guide - "OpenGL Correctness Tips". |
| 280 | Basically, applying a translation of (0.375, 0.375, 0.0) to your coordinates |
| 281 | will fix the problem. |
| 282 | </p> |
| 283 | |
| 284 | <br> |
| 285 | <br> |
| 286 | |
| 287 | |
| 288 | <a name="part4"> |
| 289 | </a><h1><a name="part4">4. Developer Questions</a></h1> |
| 290 | |
| 291 | <h2><a name="part4">4.1 How can I contribute?</a></h2> |
| 292 | <p> |
| 293 | <a name="part4">First, join the Mesa3d-dev mailing list. That's where Mesa development |
| 294 | is discussed. |
| 295 | </a></p> |
| 296 | <p> |
| 297 | <a name="part4">The </a><a href="http://www.opengl.org/developers/documentation/specs.html"> |
| 298 | OpenGL Specification</a> is the bible for OpenGL implemention work. |
| 299 | You should read it. |
| 300 | </p> |
| 301 | <p>Most of the Mesa development work involves implementing new OpenGL |
| 302 | extensions, writing hardware drivers (for the DRI), and code optimization. |
| 303 | </p> |
| 304 | |
| 305 | <h2>4.2 How do I write a new device driver?</h2> |
| 306 | <p> |
| 307 | Unfortunately, writing a device driver isn't easy. |
| 308 | It requires detailed understanding of OpenGL, the Mesa code, and your |
| 309 | target hardware/operating system. |
| 310 | 3D graphics are not simple. |
| 311 | </p> |
| 312 | <p> |
| 313 | The best way to get started is to use an existing driver as your starting |
| 314 | point. |
| 315 | For a software driver, the X11 and OSMesa drivers are good examples. |
| 316 | For a hardware driver, the Radeon and R200 DRI drivers are good examples. |
| 317 | </p> |
| 318 | <p>The DRI website has more information about writing hardware drivers. |
| 319 | The process isn't well document because the Mesa driver interface changes |
| 320 | over time, and we seldome have spare time for writing documentation. |
| 321 | That being said, many people have managed to figure out the process. |
| 322 | </p> |
| 323 | <p> |
| 324 | Joining the appropriate mailing lists and asking questions (and searching |
| 325 | the archives) is a good way to get information. |
| 326 | </p> |
| 327 | |
| 328 | |
| 329 | </body> |
| 330 | </html> |