Erik Faye-Lund | 4d06683 | 2020-06-12 20:09:42 +0200 | [diff] [blame] | 1 | Frequently Asked Questions |
| 2 | ========================== |
| 3 | |
| 4 | Last updated: 19 September 2018 |
| 5 | |
Erik Faye-Lund | 4d06683 | 2020-06-12 20:09:42 +0200 | [diff] [blame] | 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 |
Erik Faye-Lund | 9be0e2d | 2020-06-15 12:31:36 +0200 | [diff] [blame] | 88 | the Mesa :doc:`compilation instructions <install>`. |
Erik Faye-Lund | 4d06683 | 2020-06-12 20:09:42 +0200 | [diff] [blame] | 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 | |
Erik Faye-Lund | 4d06683 | 2020-06-12 20:09:42 +0200 | [diff] [blame] | 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 | |
Erik Faye-Lund | 4d06683 | 2020-06-12 20:09:42 +0200 | [diff] [blame] | 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 |
Erik Faye-Lund | 689145e | 2020-09-30 15:24:01 +0200 | [diff] [blame] | 203 | of its software renderers. (e.g. classic swrast, softpipe or llvmpipe) |
Erik Faye-Lund | 4d06683 | 2020-06-12 20:09:42 +0200 | [diff] [blame] | 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 | |
Erik Faye-Lund | 4d06683 | 2020-06-12 20:09:42 +0200 | [diff] [blame] | 259 | 4. Developer Questions |
| 260 | ---------------------- |
| 261 | |
| 262 | 4.1 How can I contribute? |
| 263 | ~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 264 | |
Erik Faye-Lund | 9be0e2d | 2020-06-15 12:31:36 +0200 | [diff] [blame] | 265 | First, join the :doc:`mesa-dev mailing list <lists>`. That's where |
Erik Faye-Lund | 4d06683 | 2020-06-12 20:09:42 +0200 | [diff] [blame] | 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 |
Erik Faye-Lund | 768186e | 2020-09-30 15:15:02 +0200 | [diff] [blame] | 299 | include S3TC support due to intellectual property (IP) and/or patent |
| 300 | issues around the S3TC algorithm. |
Erik Faye-Lund | 4d06683 | 2020-06-12 20:09:42 +0200 | [diff] [blame] | 301 | |
Erik Faye-Lund | 768186e | 2020-09-30 15:15:02 +0200 | [diff] [blame] | 302 | As of Mesa 17.3.0, Mesa now officially supports S3TC, as the patent has |
Erik Faye-Lund | 4d06683 | 2020-06-12 20:09:42 +0200 | [diff] [blame] | 303 | expired. |
| 304 | |
| 305 | In versions prior to this, a 3rd party `plug-in |
| 306 | library <https://dri.freedesktop.org/wiki/S3TC>`__ was required. |