1Frequently Asked Questions 2========================== 3 4Last updated: 19 September 2018 5 61. High-level Questions and Answers 7----------------------------------- 8 91.1 What is Mesa? 10~~~~~~~~~~~~~~~~~ 11 12Mesa is an open-source implementation of the OpenGL specification. 13OpenGL is a programming library for writing interactive 3D applications. 14See the `OpenGL website <https://www.opengl.org/>`__ for more 15information. 16 17Mesa 9.x supports the OpenGL 3.1 specification. 18 191.2 Does Mesa support/use graphics hardware? 20-------------------------------------------- 21 22Yes. Specifically, Mesa serves as the OpenGL core for the open-source 23DRI drivers for X.org. 24 25- See the `DRI website <https://dri.freedesktop.org/>`__ for more 26 information. 27- See `01.org <https://01.org/linuxgraphics>`__ for more information 28 about Intel drivers. 29- See `nouveau.freedesktop.org <https://nouveau.freedesktop.org>`__ for 30 more information about Nouveau drivers. 31- See 32 `www.x.org/wiki/RadeonFeature <https://www.x.org/wiki/RadeonFeature>`__ 33 for more information about Radeon drivers. 34 351.3 What purpose does Mesa serve today? 36--------------------------------------- 37 38Hardware-accelerated OpenGL implementations are available for most 39popular operating systems today. Still, Mesa serves at least these 40purposes: 41 42- Mesa is used as the core of the open-source X.org DRI hardware 43 drivers. 44- Mesa is quite portable and allows OpenGL to be used on systems that 45 have no other OpenGL solution. 46- Software rendering with Mesa serves as a reference for validating the 47 hardware drivers. 48- A software implementation of OpenGL is useful for experimentation, 49 such as testing new rendering techniques. 50- Mesa can render images with deep color channels: 16-bit integer and 51 32-bit floating point color channels are supported. This capability 52 is only now appearing in hardware. 53- Mesa's internal limits (max lights, clip planes, texture size, etc) 54 can be changed for special needs (hardware limits are hard to 55 overcome). 56 571.4 What's the difference between "Stand-Alone" Mesa and the DRI drivers? 58------------------------------------------------------------------------- 59 60*Stand-alone Mesa* is the original incarnation of Mesa. On systems 61running the X Window System it does all its rendering through the Xlib 62API: 63 64- The GLX API is supported, but it's really just an emulation of the 65 real thing. 66- The GLX wire protocol is not supported and there's no OpenGL 67 extension loaded by the X server. 68- There is no hardware acceleration. 69- The OpenGL library, ``libGL.so``, contains everything (the 70 programming API, the GLX functions and all the rendering code). 71 72Alternately, Mesa acts as the core for a number of OpenGL hardware 73drivers within the DRI (Direct Rendering Infrastructure): 74 75- The ``libGL.so`` library provides the GL and GLX API functions, a GLX 76 protocol encoder, and a device driver loader. 77- The device driver modules (such as ``r200_dri.so``) contain a 78 built-in copy of the core Mesa code. 79- The X server loads the GLX module. The GLX module decodes incoming 80 GLX protocol and dispatches the commands to a rendering module. For 81 the DRI, this module is basically a software Mesa renderer. 82 831.5 How do I upgrade my DRI installation to use a new Mesa release? 84------------------------------------------------------------------- 85 86This wasn't easy in the past. Now, the DRI drivers are included in the 87Mesa tree and can be compiled separately from the X server. Just follow 88the Mesa :doc:`compilation instructions <install>`. 89 901.6 Are there other open-source implementations of OpenGL? 91---------------------------------------------------------- 92 93Yes, SGI's `OpenGL Sample Implementation 94(SI) <http://web.archive.org/web/20171010115110_/http://oss.sgi.com/projects/ogl-sample/index.html>`__ 95is available. The SI was written during the time that OpenGL was 96originally designed. Unfortunately, development of the SI has stagnated. 97Mesa is much more up to date with modern features and extensions. 98 99`Vincent <https://sourceforge.net/projects/ogl-es/>`__ is an open-source 100implementation of OpenGL ES for mobile devices. 101 102`miniGL <http://web.archive.org/web/20130830162848/http://www.dsbox.com/minigl.html>`__ 103is a subset of OpenGL for PalmOS devices. The website is gone, but the 104source code can still be found on 105`sourceforge.net <https://sourceforge.net/projects/minigl/>`__. 106 107`TinyGL <http://bellard.org/TinyGL/>`__ is a subset of OpenGL. 108 109`SoftGL <https://sourceforge.net/projects/softgl/>`__ is an OpenGL 110subset for mobile devices. 111 112`Chromium <http://chromium.sourceforge.net/>`__ isn't a conventional 113OpenGL implementation (it's layered upon OpenGL), but it does export the 114OpenGL API. It allows tiled rendering, sort-last rendering, etc. 115 116`ClosedGL <http://www.ticalc.org/archives/files/fileinfo/361/36173.html>`__ 117is an OpenGL subset library for TI graphing calculators. 118 119There may be other open OpenGL implementations, but Mesa is the most 120popular and feature-complete. 121 1222. Compilation and Installation Problems 123---------------------------------------- 124 1252.1 What's the easiest way to install Mesa? 126~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 127 128If you're using a Linux-based system, your distro CD most likely already 129has Mesa packages (like RPM or DEB) which you can easily install. 130 1312.2 I get undefined symbols such as bgnpolygon, v3f, etc... 132~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 133 134Your application is written in IRIS GL, not OpenGL. IRIS GL was the 135predecessor to OpenGL and is a different thing (almost) entirely. Mesa's 136not the solution. 137 1382.3 Where is the GLUT library? 139~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 140 141GLUT (OpenGL Utility Toolkit) is no longer in the separate 142``MesaGLUT-x.y.z.tar.gz`` file. If you don't already have GLUT 143installed, you should grab 144`freeglut <http://freeglut.sourceforge.net/>`__. 145 1462.4 Where is the GLw library? 147~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 148 149GLw (OpenGL widget library) is now available from a separate `git 150repository <https://gitlab.freedesktop.org/mesa/glw>`__. Unless you're 151using very old Xt/Motif applications with OpenGL, you shouldn't need it. 152 1532.5 What's the proper place for the libraries and headers? 154---------------------------------------------------------- 155 156On Linux-based systems you'll want to follow the `Linux 157ABI <https://www.khronos.org/registry/OpenGL/ABI/>`__ standard. 158Basically you'll want the following: 159 160``/usr/include/GL/gl.h`` 161 the main OpenGL header 162``/usr/include/GL/glu.h`` 163 the OpenGL GLU (utility) header 164``/usr/include/GL/glx.h`` 165 the OpenGL GLX header 166``/usr/include/GL/glext.h`` 167 the OpenGL extensions header 168``/usr/include/GL/glxext.h`` 169 the OpenGL GLX extensions header 170``/usr/include/GL/osmesa.h`` 171 the Mesa off-screen rendering header 172``/usr/lib/libGL.so`` 173 a symlink to ``libGL.so.1`` 174``/usr/lib/libGL.so.1`` 175 a symlink to ``libGL.so.1.xyz`` 176``/usr/lib/libGL.so.xyz`` 177 the actual OpenGL/Mesa library. xyz denotes the Mesa version number. 178 179When configuring Mesa, there are three meson options that affect the 180install location that you should take care with: ``--prefix``, 181``--libdir``, and ``-D dri-drivers-path``. To install Mesa into the 182system location where it will be available for all programs to use, set 183``--prefix=/usr``. Set ``--libdir`` to where your Linux distribution 184installs system libraries, usually either ``/usr/lib`` or 185``/usr/lib64``. Set ``-D dri-drivers-path`` to the directory where your 186Linux distribution installs DRI drivers. To find your system's DRI 187driver directory, try executing ``find /usr -type d -name dri``. For 188example, if the ``find`` command listed ``/usr/lib64/dri``, then set 189``-D dri-drivers-path=/usr/lib64/dri``. 190 191After determining the correct values for the install location, configure 192Mesa with 193``meson configure --prefix=/usr --libdir=xxx -D dri-drivers-path=xxx`` 194and then install with ``sudo ninja install``. 195 1963. Runtime / Rendering Problems 197------------------------------- 198 1993.1 Rendering is slow / why isn't my graphics hardware being used? 200~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 201 202If Mesa can't use its hardware accelerated drivers it falls back on one 203of its software renderers. (e.g. classic swrast, softpipe or llvmpipe) 204 205You can run the ``glxinfo`` program to learn about your OpenGL library. 206Look for the ``OpenGL vendor`` and ``OpenGL renderer`` values. That will 207identify who's OpenGL library with which driver you're using and what 208sort of hardware it has detected. 209 210If you're using a hardware accelerated driver you want 211``direct rendering: Yes``. 212 213If your DRI-based driver isn't working, go to the `DRI 214website <https://dri.freedesktop.org/>`__ for trouble-shooting 215information. 216 2173.2 I'm seeing errors in depth (Z) buffering. Why? 218~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 219 220Make sure the ratio of the far to near clipping planes isn't too great. 221Look 222`here <https://www.opengl.org/archives/resources/faq/technical/depthbuffer.htm#0040>`__ 223for details. 224 225Mesa uses a 16-bit depth buffer by default which is smaller and faster 226to clear than a 32-bit buffer but not as accurate. If you need a deeper 227you can modify the parameters to ``glXChooseVisual`` in your code. 228 2293.3 Why Isn't depth buffering working at all? 230~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 231 232Be sure you're requesting a depth buffered-visual. If you set the 233``MESA_DEBUG`` environment variable it will warn you about trying to 234enable depth testing when you don't have a depth buffer. 235 236Specifically, make sure ``glutInitDisplayMode`` is being called with 237``GLUT_DEPTH`` or ``glXChooseVisual`` is being called with a non-zero 238value for ``GLX_DEPTH_SIZE``. 239 240This discussion applies to stencil buffers, accumulation buffers and 241alpha channels too. 242 2433.4 Why does ``glGetString()`` always return ``NULL``? 244~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 245 246Be sure you have an active/current OpenGL rendering context before 247calling ``glGetString``. 248 2493.5 ``GL_POINTS`` and ``GL_LINES`` don't touch the right pixels 250~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 251 252If you're trying to draw a filled region by using ``GL_POINTS`` or 253``GL_LINES`` and seeing holes or gaps it's because of a float-to-int 254rounding problem. But this is not a bug. See Appendix H of the OpenGL 255Programming Guide - "OpenGL Correctness Tips". Basically, applying a 256translation of (0.375, 0.375, 0.0) to your coordinates will fix the 257problem. 258 2594. Developer Questions 260---------------------- 261 2624.1 How can I contribute? 263~~~~~~~~~~~~~~~~~~~~~~~~~ 264 265First, join the :doc:`mesa-dev mailing list <lists>`. That's where 266Mesa development is discussed. 267 268The `OpenGL Specification <https://www.opengl.org/documentation>`__ is 269the bible for OpenGL implementation work. You should read it. 270 271Most of the Mesa development work involves implementing new OpenGL 272extensions, writing hardware drivers (for the DRI), and code 273optimization. 274 2754.2 How do I write a new device driver? 276~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 277 278Unfortunately, writing a device driver isn't easy. It requires detailed 279understanding of OpenGL, the Mesa code, and your target 280hardware/operating system. 3D graphics are not simple. 281 282The best way to get started is to use an existing driver as your 283starting point. For a classic hardware driver, the i965 driver is a good 284example. For a Gallium3D hardware driver, the r300g, r600g and the i915g 285are good examples. 286 287The DRI website has more information about writing hardware drivers. The 288process isn't well document because the Mesa driver interface changes 289over time, and we seldom have spare time for writing documentation. That 290being said, many people have managed to figure out the process. 291 292Joining the appropriate mailing lists and asking questions (and 293searching the archives) is a good way to get information. 294 2954.3 Why isn't ``GL_EXT_texture_compression_s3tc`` implemented in Mesa? 296~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 297 298Oh but it is! Prior to 2nd October 2017, the Mesa project did not 299include S3TC support due to intellectual property (IP) and/or patent 300issues around the S3TC algorithm. 301 302As of Mesa 17.3.0, Mesa now officially supports S3TC, as the patent has 303expired. 304 305In versions prior to this, a 3rd party `plug-in 306library <https://dri.freedesktop.org/wiki/S3TC>`__ was required. 307