docs/faq.rst

   1 Frequently Asked Questions
   2 ==========================
   3
   4 Last updated: 19 September 2018
   5
   6 1. High-level Questions and Answers
   7 -----------------------------------
   8
   9 1.1 What is Mesa?
  10 ~~~~~~~~~~~~~~~~~
  11
  12 Mesa is an open-source implementation of the OpenGL specification.
  13 OpenGL is a programming library for writing interactive 3D applications.
  14 See the `OpenGL website <https://www.opengl.org/>`__ for more
  15 information.
  16
  17 Mesa 9.x supports the OpenGL 3.1 specification.
  18
  19 1.2 Does Mesa support/use graphics hardware?
  20 --------------------------------------------
  21
  22 Yes. Specifically, Mesa serves as the OpenGL core for the open-source
  23 DRI 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
  35 1.3 What purpose does Mesa serve today?
  36 ---------------------------------------
  37
  38 Hardware-accelerated OpenGL implementations are available for most
  39 popular operating systems today. Still, Mesa serves at least these
  40 purposes:
  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
  57 1.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
  61 running the X Window System it does all its rendering through the Xlib
  62 API:
  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
  72 Alternately, Mesa acts as the core for a number of OpenGL hardware
  73 drivers 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
  83 1.5 How do I upgrade my DRI installation to use a new Mesa release?
  84 -------------------------------------------------------------------
  85
  86 This wasn't easy in the past. Now, the DRI drivers are included in the
  87 Mesa tree and can be compiled separately from the X server. Just follow
  88 the Mesa :doc:`compilation instructions <install>`.
  89
  90 1.6 Are there other open-source implementations of OpenGL?
  91 ----------------------------------------------------------
  92
  93 Yes, SGI's `OpenGL Sample Implementation
  94 (SI) <http://web.archive.org/web/20171010115110_/http://oss.sgi.com/projects/ogl-sample/index.html>`__
  95 is available. The SI was written during the time that OpenGL was
  96 originally designed. Unfortunately, development of the SI has stagnated.
  97 Mesa is much more up to date with modern features and extensions.
  98
  99 `Vincent <https://sourceforge.net/projects/ogl-es/>`__ is an open-source
 100 implementation of OpenGL ES for mobile devices.
 101
 102 `miniGL <http://web.archive.org/web/20130830162848/http://www.dsbox.com/minigl.html>`__
 103 is a subset of OpenGL for PalmOS devices. The website is gone, but the
 104 source 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
 110 subset for mobile devices.
 111
 112 `Chromium <http://chromium.sourceforge.net/>`__ isn't a conventional
 113 OpenGL implementation (it's layered upon OpenGL), but it does export the
 114 OpenGL API. It allows tiled rendering, sort-last rendering, etc.
 115
 116 `ClosedGL <http://www.ticalc.org/archives/files/fileinfo/361/36173.html>`__
 117 is an OpenGL subset library for TI graphing calculators.
 118
 119 There may be other open OpenGL implementations, but Mesa is the most
 120 popular and feature-complete.
 121
 122 2. Compilation and Installation Problems
 123 ----------------------------------------
 124
 125 2.1 What's the easiest way to install Mesa?
 126 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 127
 128 If you're using a Linux-based system, your distro CD most likely already
 129 has Mesa packages (like RPM or DEB) which you can easily install.
 130
 131 2.2 I get undefined symbols such as bgnpolygon, v3f, etc...
 132 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 133
 134 You're application is written in IRIS GL, not OpenGL. IRIS GL was the
 135 predecessor to OpenGL and is a different thing (almost) entirely. Mesa's
 136 not the solution.
 137
 138 2.3 Where is the GLUT library?
 139 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 140
 141 GLUT (OpenGL Utility Toolkit) is no longer in the separate
 142 ``MesaGLUT-x.y.z.tar.gz`` file. If you don't already have GLUT
 143 installed, you should grab
 144 `freeglut <http://freeglut.sourceforge.net/>`__.
 145
 146 2.4 Where is the GLw library?
 147 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 148
 149 GLw (OpenGL widget library) is now available from a separate `git
 150 repository <https://gitlab.freedesktop.org/mesa/glw>`__. Unless you're
 151 using very old Xt/Motif applications with OpenGL, you shouldn't need it.
 152
 153 2.5 What's the proper place for the libraries and headers?
 154 ----------------------------------------------------------
 155
 156 On Linux-based systems you'll want to follow the `Linux
 157 ABI <https://www.khronos.org/registry/OpenGL/ABI/>`__ standard.
 158 Basically 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
 179 When configuring Mesa, there are three meson options that affect the
 180 install location that you should take care with: ``--prefix``,
 181 ``--libdir``, and ``-D dri-drivers-path``. To install Mesa into the
 182 system location where it will be available for all programs to use, set
 183 ``--prefix=/usr``. Set ``--libdir`` to where your Linux distribution
 184 installs system libraries, usually either ``/usr/lib`` or
 185 ``/usr/lib64``. Set ``-D dri-drivers-path`` to the directory where your
 186 Linux distribution installs DRI drivers. To find your system's DRI
 187 driver directory, try executing ``find /usr -type d -name dri``. For
 188 example, if the ``find`` command listed ``/usr/lib64/dri``, then set
 189 ``-D dri-drivers-path=/usr/lib64/dri``.
 190
 191 After determining the correct values for the install location, configure
 192 Mesa with
 193 ``meson configure --prefix=/usr --libdir=xxx -D dri-drivers-path=xxx``
 194 and then install with ``sudo ninja install``.
 195
 196 3. Runtime / Rendering Problems
 197 -------------------------------
 198
 199 3.1 Rendering is slow / why isn't my graphics hardware being used?
 200 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 201
 202 If Mesa can't use its hardware accelerated drivers it falls back on one
 203 of its software renderers. (eg. classic swrast, softpipe or llvmpipe)
 204
 205 You can run the ``glxinfo`` program to learn about your OpenGL library.
 206 Look for the ``OpenGL vendor`` and ``OpenGL renderer`` values. That will
 207 identify who's OpenGL library with which driver you're using and what
 208 sort of hardware it has detected.
 209
 210 If you're using a hardware accelerated driver you want
 211 ``direct rendering: Yes``.
 212
 213 If your DRI-based driver isn't working, go to the `DRI
 214 website <https://dri.freedesktop.org/>`__ for trouble-shooting
 215 information.
 216
 217 3.2 I'm seeing errors in depth (Z) buffering. Why?
 218 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 219
 220 Make sure the ratio of the far to near clipping planes isn't too great.
 221 Look
 222 `here <https://www.opengl.org/archives/resources/faq/technical/depthbuffer.htm#0040>`__
 223 for details.
 224
 225 Mesa uses a 16-bit depth buffer by default which is smaller and faster
 226 to clear than a 32-bit buffer but not as accurate. If you need a deeper
 227 you can modify the parameters to ``glXChooseVisual`` in your code.
 228
 229 3.3 Why Isn't depth buffering working at all?
 230 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 231
 232 Be sure you're requesting a depth buffered-visual. If you set the
 233 ``MESA_DEBUG`` environment variable it will warn you about trying to
 234 enable depth testing when you don't have a depth buffer.
 235
 236 Specifically, make sure ``glutInitDisplayMode`` is being called with
 237 ``GLUT_DEPTH`` or ``glXChooseVisual`` is being called with a non-zero
 238 value for ``GLX_DEPTH_SIZE``.
 239
 240 This discussion applies to stencil buffers, accumulation buffers and
 241 alpha channels too.
 242
 243 3.4 Why does ``glGetString()`` always return ``NULL``?
 244 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 245
 246 Be sure you have an active/current OpenGL rendering context before
 247 calling ``glGetString``.
 248
 249 3.5 ``GL_POINTS`` and ``GL_LINES`` don't touch the right pixels
 250 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 251
 252 If 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
 254 rounding problem. But this is not a bug. See Appendix H of the OpenGL
 255 Programming Guide - "OpenGL Correctness Tips". Basically, applying a
 256 translation of (0.375, 0.375, 0.0) to your coordinates will fix the
 257 problem.
 258
 259 4. Developer Questions
 260 ----------------------
 261
 262 4.1 How can I contribute?
 263 ~~~~~~~~~~~~~~~~~~~~~~~~~
 264
 265 First, join the :doc:`mesa-dev mailing list <lists>`. That's where
 266 Mesa development is discussed.
 267
 268 The `OpenGL Specification <https://www.opengl.org/documentation>`__ is
 269 the bible for OpenGL implementation work. You should read it.
 270
 271 Most of the Mesa development work involves implementing new OpenGL
 272 extensions, writing hardware drivers (for the DRI), and code
 273 optimization.
 274
 275 4.2 How do I write a new device driver?
 276 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 277
 278 Unfortunately, writing a device driver isn't easy. It requires detailed
 279 understanding of OpenGL, the Mesa code, and your target
 280 hardware/operating system. 3D graphics are not simple.
 281
 282 The best way to get started is to use an existing driver as your
 283 starting point. For a classic hardware driver, the i965 driver is a good
 284 example. For a Gallium3D hardware driver, the r300g, r600g and the i915g
 285 are good examples.
 286
 287 The DRI website has more information about writing hardware drivers. The
 288 process isn't well document because the Mesa driver interface changes
 289 over time, and we seldom have spare time for writing documentation. That
 290 being said, many people have managed to figure out the process.
 291
 292 Joining the appropriate mailing lists and asking questions (and
 293 searching the archives) is a good way to get information.
 294
 295 4.3 Why isn't ``GL_EXT_texture_compression_s3tc`` implemented in Mesa?
 296 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 297
 298 Oh but it is! Prior to 2nd October 2017, the Mesa project did not
 299 include s3tc support due to intellectual property (IP) and/or patent
 300 issues around the s3tc algorithm.
 301
 302 As of Mesa 17.3.0, Mesa now officially supports s3tc, as the patent has
 303 expired.
 304
 305 In versions prior to this, a 3rd party `plug-in
 306 library <https://dri.freedesktop.org/wiki/S3TC>`__ was required.