383 lines
13 KiB
HTML
383 lines
13 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
|
|
<html lang="en">
|
|
<head>
|
|
<meta http-equiv="content-type" content="text/html; charset=utf-8">
|
|
<title>Frequently Asked Questions</title>
|
|
<link rel="stylesheet" type="text/css" href="mesa.css">
|
|
</head>
|
|
<body>
|
|
|
|
<div class="header">
|
|
The Mesa 3D Graphics Library
|
|
</div>
|
|
|
|
<iframe src="contents.html"></iframe>
|
|
<div class="content">
|
|
|
|
<h1>Frequently Asked Questions</h1>
|
|
Last updated: 19 September 2018
|
|
|
|
<h2>Index</h2>
|
|
<ol>
|
|
<li><a href="#part1">High-level Questions and Answers</a></li>
|
|
<li><a href="#part2">Compilation and Installation Problems</a></li>
|
|
<li><a href="#part3">Runtime / Rendering Problems</a></li>
|
|
<li><a href="#part4">Developer Questions</a></li>
|
|
</ol>
|
|
|
|
<h2 id="part1">1. High-level Questions and Answers</h2>
|
|
|
|
<h3>1.1 What is Mesa?</h3>
|
|
<p>
|
|
Mesa is an open-source implementation of the OpenGL specification.
|
|
OpenGL is a programming library for writing interactive 3D applications.
|
|
See the <a href="https://www.opengl.org/">OpenGL website</a> for more
|
|
information.
|
|
</p>
|
|
<p>
|
|
Mesa 9.x supports the OpenGL 3.1 specification.
|
|
</p>
|
|
|
|
|
|
<h2>1.2 Does Mesa support/use graphics hardware?</h2>
|
|
<p>
|
|
Yes. Specifically, Mesa serves as the OpenGL core for the open-source DRI
|
|
drivers for X.org.
|
|
</p>
|
|
<ul>
|
|
<li>See the <a href="https://dri.freedesktop.org/">DRI website</a>
|
|
for more information.</li>
|
|
<li>See <a href="https://01.org/linuxgraphics">01.org</a>
|
|
for more information about Intel drivers.</li>
|
|
<li>See <a href="https://nouveau.freedesktop.org">nouveau.freedesktop.org</a>
|
|
for more information about Nouveau drivers.</li>
|
|
<li>See <a href="https://www.x.org/wiki/RadeonFeature">www.x.org/wiki/RadeonFeature</a>
|
|
for more information about Radeon drivers.</li>
|
|
</ul>
|
|
|
|
<h2>1.3 What purpose does Mesa serve today?</h2>
|
|
<p>
|
|
Hardware-accelerated OpenGL implementations are available for most popular
|
|
operating systems today.
|
|
Still, Mesa serves at least these purposes:
|
|
</p>
|
|
<ul>
|
|
<li>Mesa is used as the core of the open-source X.org DRI
|
|
hardware drivers.
|
|
</li>
|
|
<li>Mesa is quite portable and allows OpenGL to be used on systems
|
|
that have no other OpenGL solution.
|
|
</li>
|
|
<li>Software rendering with Mesa serves as a reference for validating the
|
|
hardware drivers.
|
|
</li>
|
|
<li>A software implementation of OpenGL is useful for experimentation,
|
|
such as testing new rendering techniques.
|
|
</li>
|
|
<li>Mesa can render images with deep color channels: 16-bit integer
|
|
and 32-bit floating point color channels are supported.
|
|
This capability is only now appearing in hardware.
|
|
</li>
|
|
<li>Mesa's internal limits (max lights, clip planes, texture size, etc) can be
|
|
changed for special needs (hardware limits are hard to overcome).
|
|
</li>
|
|
</ul>
|
|
|
|
|
|
<h2>1.4 What's the difference between "Stand-Alone" Mesa and the DRI drivers?</h2>
|
|
<p>
|
|
<em>Stand-alone Mesa</em> is the original incarnation of Mesa.
|
|
On systems running the X Window System it does all its rendering through
|
|
the Xlib API:
|
|
</p>
|
|
<ul>
|
|
<li>The GLX API is supported, but it's really just an emulation of the
|
|
real thing.
|
|
<li>The GLX wire protocol is not supported and there's no OpenGL extension
|
|
loaded by the X server.
|
|
<li>There is no hardware acceleration.
|
|
<li>The OpenGL library, <code>libGL.so</code>, contains everything (the
|
|
programming API, the GLX functions and all the rendering code).
|
|
</ul>
|
|
<p>
|
|
Alternately, Mesa acts as the core for a number of OpenGL hardware drivers
|
|
within the DRI (Direct Rendering Infrastructure):
|
|
<ul>
|
|
<li>The <code>libGL.so</code> library provides the GL and GLX API functions,
|
|
a GLX protocol encoder, and a device driver loader.
|
|
<li>The device driver modules (such as <code>r200_dri.so</code>) contain
|
|
a built-in copy of the core Mesa code.
|
|
<li>The X server loads the GLX module.
|
|
The GLX module decodes incoming GLX protocol and dispatches the commands
|
|
to a rendering module.
|
|
For the DRI, this module is basically a software Mesa renderer.
|
|
</ul>
|
|
|
|
|
|
|
|
<h2>1.5 How do I upgrade my DRI installation to use a new Mesa release?</h2>
|
|
<p>
|
|
This wasn't easy in the past.
|
|
Now, the DRI drivers are included in the Mesa tree and can be compiled
|
|
separately from the X server.
|
|
Just follow the Mesa <a href="install.html">compilation instructions</a>.
|
|
</p>
|
|
|
|
|
|
<h2>1.6 Are there other open-source implementations of OpenGL?</h2>
|
|
<p>
|
|
Yes, SGI's <a href="http://web.archive.org/web/20171010115110_/http://oss.sgi.com/projects/ogl-sample/index.html">
|
|
OpenGL Sample Implementation (SI)</a> is available.
|
|
The SI was written during the time that OpenGL was originally designed.
|
|
Unfortunately, development of the SI has stagnated.
|
|
Mesa is much more up to date with modern features and extensions.
|
|
</p>
|
|
|
|
<p>
|
|
<a href="https://sourceforge.net/projects/ogl-es/">Vincent</a> is
|
|
an open-source implementation of OpenGL ES for mobile devices.
|
|
|
|
<p>
|
|
<a href="http://web.archive.org/web/20130830162848/http://www.dsbox.com/minigl.html">miniGL</a>
|
|
is a subset of OpenGL for PalmOS devices. The website is gone, but the source
|
|
code can still be found on <a href="https://sourceforge.net/projects/minigl/">sourceforge.net</a>.
|
|
|
|
<p>
|
|
<a href="http://bellard.org/TinyGL/">TinyGL</a>
|
|
is a subset of OpenGL.
|
|
</p>
|
|
|
|
<p>
|
|
<a href="https://sourceforge.net/projects/softgl/">SoftGL</a>
|
|
is an OpenGL subset for mobile devices.
|
|
</p>
|
|
|
|
<p>
|
|
<a href="http://chromium.sourceforge.net/">Chromium</a>
|
|
isn't a conventional OpenGL implementation (it's layered upon OpenGL),
|
|
but it does export the OpenGL API. It allows tiled rendering, sort-last
|
|
rendering, etc.
|
|
</p>
|
|
|
|
<p>
|
|
<a href="http://www.ticalc.org/archives/files/fileinfo/361/36173.html">ClosedGL</a>
|
|
is an OpenGL subset library for TI graphing calculators.
|
|
</p>
|
|
|
|
<p>
|
|
There may be other open OpenGL implementations, but Mesa is the most
|
|
popular and feature-complete.
|
|
</p>
|
|
|
|
|
|
<h2 id="part2">2. Compilation and Installation Problems</h2>
|
|
|
|
<h3>2.1 What's the easiest way to install Mesa?</h3>
|
|
<p>
|
|
If you're using a Linux-based system, your distro CD most likely already
|
|
has Mesa packages (like RPM or DEB) which you can easily install.
|
|
</p>
|
|
|
|
|
|
<h3>2.2 I get undefined symbols such as bgnpolygon, v3f, etc...</h3>
|
|
<p>
|
|
You're application is written in IRIS GL, not OpenGL.
|
|
IRIS GL was the predecessor to OpenGL and is a different thing (almost)
|
|
entirely.
|
|
Mesa's not the solution.
|
|
</p>
|
|
|
|
|
|
<h3>2.3 Where is the GLUT library?</h3>
|
|
<p>
|
|
GLUT (OpenGL Utility Toolkit) is no longer in the separate
|
|
<code>MesaGLUT-x.y.z.tar.gz</code> file.
|
|
If you don't already have GLUT installed, you should grab
|
|
<a href="http://freeglut.sourceforge.net/">freeglut</a>.
|
|
</p>
|
|
|
|
|
|
<h3>2.4 Where is the GLw library?</h3>
|
|
<p>
|
|
GLw (OpenGL widget library) is now available from a separate <a href="https://gitlab.freedesktop.org/mesa/glw">git repository</a>. Unless you're using very old Xt/Motif applications with OpenGL, you shouldn't need it.
|
|
</p>
|
|
|
|
|
|
<h2>2.5 What's the proper place for the libraries and headers?</h2>
|
|
<p>
|
|
On Linux-based systems you'll want to follow the
|
|
<a href="https://www.khronos.org/registry/OpenGL/ABI/">Linux ABI</a> standard.
|
|
Basically you'll want the following:
|
|
</p>
|
|
<dl>
|
|
<dt><code>/usr/include/GL/gl.h</code></dt>
|
|
<dd>the main OpenGL header</dd>
|
|
<dt><code>/usr/include/GL/glu.h</code></dt>
|
|
<dd>the OpenGL GLU (utility) header</dd>
|
|
<dt><code>/usr/include/GL/glx.h</code></dt>
|
|
<dd>the OpenGL GLX header</dd>
|
|
<dt><code>/usr/include/GL/glext.h</code></dt>
|
|
<dd>the OpenGL extensions header</dd>
|
|
<dt><code>/usr/include/GL/glxext.h</code></dt>
|
|
<dd>the OpenGL GLX extensions header</dd>
|
|
<dt><code>/usr/include/GL/osmesa.h</code></dt>
|
|
<dd>the Mesa off-screen rendering header</dd>
|
|
<dt><code>/usr/lib/libGL.so</code></dt>
|
|
<dd>a symlink to <code>libGL.so.1</code></dd>
|
|
<dt><code>/usr/lib/libGL.so.1</code></dt>
|
|
<dd>a symlink to <code>libGL.so.1.xyz</code></dd>
|
|
<dt><code>/usr/lib/libGL.so.xyz</code></dt>
|
|
<dd>the actual OpenGL/Mesa library. xyz denotes the
|
|
Mesa version number.
|
|
</dd>
|
|
</dl>
|
|
<p>
|
|
When configuring Mesa, there are three meson options that affect the install
|
|
location that you should take care with: <code>--prefix</code>,
|
|
<code>--libdir</code>, and <code>-D dri-drivers-path</code>. To install Mesa
|
|
into the system location where it will be available for all programs to use, set
|
|
<code>--prefix=/usr</code>. Set <code>--libdir</code> to where your Linux
|
|
distribution installs system libraries, usually either <code>/usr/lib</code> or
|
|
<code>/usr/lib64</code>. Set <code>-D dri-drivers-path</code> to the directory
|
|
where your Linux distribution installs DRI drivers. To find your system's DRI
|
|
driver directory, try executing <code>find /usr -type d -name dri</code>. For
|
|
example, if the <code>find</code> command listed <code>/usr/lib64/dri</code>,
|
|
then set <code>-D dri-drivers-path=/usr/lib64/dri</code>.
|
|
</p>
|
|
<p>
|
|
After determining the correct values for the install location, configure Mesa
|
|
with <code>meson configure --prefix=/usr --libdir=xxx -D dri-drivers-path=xxx</code>
|
|
and then install with <code>sudo ninja install</code>.
|
|
</p>
|
|
|
|
|
|
<h2 id="part3">3. Runtime / Rendering Problems</h2>
|
|
|
|
<h3>3.1 Rendering is slow / why isn't my graphics hardware being used?</h3>
|
|
<p>
|
|
If Mesa can't use its hardware accelerated drivers it falls back on one of its software renderers.
|
|
(eg. classic swrast, softpipe or llvmpipe)
|
|
</p>
|
|
<p>
|
|
You can run the <code>glxinfo</code> program to learn about your OpenGL
|
|
library.
|
|
Look for the <code>OpenGL vendor</code> and <code>OpenGL renderer</code> values.
|
|
That will identify who's OpenGL library with which driver you're using and what sort of
|
|
hardware it has detected.
|
|
</p>
|
|
<p>
|
|
If you're using a hardware accelerated driver you want <code>direct rendering: Yes</code>.
|
|
</p>
|
|
<p>
|
|
If your DRI-based driver isn't working, go to the
|
|
<a href="https://dri.freedesktop.org/">DRI website</a> for trouble-shooting information.
|
|
</p>
|
|
|
|
|
|
<h3>3.2 I'm seeing errors in depth (Z) buffering. Why?</h3>
|
|
<p>
|
|
Make sure the ratio of the far to near clipping planes isn't too great.
|
|
Look
|
|
<a href="https://www.opengl.org/archives/resources/faq/technical/depthbuffer.htm#0040">here</a>
|
|
for details.
|
|
</p>
|
|
<p>
|
|
Mesa uses a 16-bit depth buffer by default which is smaller and faster
|
|
to clear than a 32-bit buffer but not as accurate.
|
|
If you need a deeper you can modify the parameters to
|
|
<code>glXChooseVisual</code> in your code.
|
|
</p>
|
|
|
|
|
|
<h3>3.3 Why Isn't depth buffering working at all?</h3>
|
|
<p>
|
|
Be sure you're requesting a depth buffered-visual. If you set the
|
|
<code>MESA_DEBUG</code> environment variable it will warn you about trying
|
|
to enable depth testing when you don't have a depth buffer.
|
|
</p>
|
|
<p>Specifically, make sure <code>glutInitDisplayMode</code> is being called
|
|
with <code>GLUT_DEPTH</code> or <code>glXChooseVisual</code> is being
|
|
called with a non-zero value for <code>GLX_DEPTH_SIZE</code>.
|
|
</p>
|
|
<p>This discussion applies to stencil buffers, accumulation buffers and
|
|
alpha channels too.
|
|
</p>
|
|
|
|
|
|
<h3>3.4 Why does <code>glGetString()</code> always return <code>NULL</code>?</h3>
|
|
<p>
|
|
Be sure you have an active/current OpenGL rendering context before
|
|
calling <code>glGetString</code>.
|
|
</p>
|
|
|
|
|
|
<h3>3.5 <code>GL_POINTS</code> and <code>GL_LINES</code> don't touch the
|
|
right pixels</h3>
|
|
<p>
|
|
If you're trying to draw a filled region by using <code>GL_POINTS</code> or
|
|
<code>GL_LINES</code> and seeing holes or gaps it's because of a float-to-int
|
|
rounding problem. But this is not a bug. See Appendix H of the OpenGL
|
|
Programming Guide - "OpenGL Correctness Tips". Basically, applying a
|
|
translation of (0.375, 0.375, 0.0) to your coordinates will fix the problem.
|
|
</p>
|
|
|
|
|
|
<h2 id="part4">4. Developer Questions</h2>
|
|
|
|
<h3>4.1 How can I contribute?</h3>
|
|
<p>
|
|
First, join the <a href="lists.html">mesa-dev mailing list</a>.
|
|
That's where Mesa development is discussed.
|
|
</p>
|
|
<p>
|
|
The <a href="https://www.opengl.org/documentation">
|
|
OpenGL Specification</a> is the bible for OpenGL implementation work.
|
|
You should read it.
|
|
</p>
|
|
<p>Most of the Mesa development work involves implementing new OpenGL
|
|
extensions, writing hardware drivers (for the DRI), and code optimization.
|
|
</p>
|
|
|
|
<h3>4.2 How do I write a new device driver?</h3>
|
|
<p>
|
|
Unfortunately, writing a device driver isn't easy.
|
|
It requires detailed understanding of OpenGL, the Mesa code, and your
|
|
target hardware/operating system.
|
|
3D graphics are not simple.
|
|
</p>
|
|
<p>
|
|
The best way to get started is to use an existing driver as your starting
|
|
point.
|
|
For a classic hardware driver, the i965 driver is a good example.
|
|
For a Gallium3D hardware driver, the r300g, r600g and the i915g are good examples.
|
|
</p>
|
|
<p>The DRI website has more information about writing hardware drivers.
|
|
The process isn't well document because the Mesa driver interface changes
|
|
over time, and we seldom have spare time for writing documentation.
|
|
That being said, many people have managed to figure out the process.
|
|
</p>
|
|
<p>
|
|
Joining the appropriate mailing lists and asking questions (and searching
|
|
the archives) is a good way to get information.
|
|
</p>
|
|
|
|
|
|
<h3>4.3 Why isn't <code>GL_EXT_texture_compression_s3tc</code> implemented in
|
|
Mesa?</h3>
|
|
<p>
|
|
Oh but it is! Prior to 2nd October 2017, the Mesa project did not include s3tc
|
|
support due to intellectual property (IP) and/or patent issues around the s3tc
|
|
algorithm.
|
|
</p>
|
|
<p>
|
|
As of Mesa 17.3.0, Mesa now officially supports s3tc, as the patent has expired.
|
|
</p>
|
|
<p>
|
|
In versions prior to this, a 3rd party <a href="https://dri.freedesktop.org/wiki/S3TC">
|
|
plug-in library</a> was required.
|
|
</p>
|
|
|
|
</div>
|
|
</body>
|
|
</html>
|