Commit 4d066836 authored by Erik Faye-Lund 's avatar Erik Faye-Lund 💬 Committed by Marge Bot
Browse files

docs: convert articles to reructuredtext



This uses the previously added scripts to convert the documentation to
reStructuredText, which is both easier to read offline, and can be used
to generate modern HTML for online documentation.

No modification to the generated results have been done.
Acked-by: Eric Engestrom's avatarEric Engestrom <eric@engestrom.ch>
Part-of: <!4630>
parent 1df5dbf5
<!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>Application Issues</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>Application Issues</h1>
<p>
This page documents known issues with some OpenGL applications.
</p>
<h2>Topogun</h2>
<p>
<a href="http://www.topogun.com/">Topogun</a> for Linux (version 2, at least)
creates a GLX visual without requesting a depth buffer.
This causes bad rendering if the OpenGL driver happens to choose a visual
without a depth buffer.
</p>
<p>
Mesa 9.1.2 and later (will) support a DRI configuration option to work around
this issue.
Using the <a href="https://dri.freedesktop.org/wiki/DriConf">driconf</a> tool,
set the "Create all visuals with a depth buffer" option before running Topogun.
Then, all GLX visuals will be created with a depth buffer.
</p>
<h2>Old OpenGL games</h2>
<p>
Some old OpenGL games (approx. ten years or older) may crash during
start-up because of an extension string buffer-overflow problem.
</p>
<p>
The problem is a modern OpenGL driver will return a very long string
for the <code>glGetString(GL_EXTENSIONS)</code> query and if the application
naively copies the string into a fixed-size buffer it can overflow the
buffer and crash the application.
</p>
<p>
The work-around is to set the <code>MESA_EXTENSION_MAX_YEAR</code>
environment variable to the approximate release year of the game.
This will cause the <code>glGetString(GL_EXTENSIONS)</code> query to only report
extensions older than the given year.
</p>
<p>
For example, if the game was released in 2001, do
</p>
<pre>
export MESA_EXTENSION_MAX_YEAR=2001
</pre>
<p>
before running the game.
</p>
<h2>Viewperf</h2>
<p>
See the <a href="viewperf.html">Viewperf issues</a> page for a detailed list
of Viewperf issues.
</p>
</div>
</body>
</html>
Application Issues
==================
This page documents known issues with some OpenGL applications.
Topogun
-------
`Topogun <http://www.topogun.com/>`__ for Linux (version 2, at least)
creates a GLX visual without requesting a depth buffer. This causes bad
rendering if the OpenGL driver happens to choose a visual without a
depth buffer.
Mesa 9.1.2 and later (will) support a DRI configuration option to work
around this issue. Using the
`driconf <https://dri.freedesktop.org/wiki/DriConf>`__ tool, set the
"Create all visuals with a depth buffer" option before running Topogun.
Then, all GLX visuals will be created with a depth buffer.
Old OpenGL games
----------------
Some old OpenGL games (approx. ten years or older) may crash during
start-up because of an extension string buffer-overflow problem.
The problem is a modern OpenGL driver will return a very long string for
the ``glGetString(GL_EXTENSIONS)`` query and if the application naively
copies the string into a fixed-size buffer it can overflow the buffer
and crash the application.
The work-around is to set the ``MESA_EXTENSION_MAX_YEAR`` environment
variable to the approximate release year of the game. This will cause
the ``glGetString(GL_EXTENSIONS)`` query to only report extensions older
than the given year.
For example, if the game was released in 2001, do
::
export MESA_EXTENSION_MAX_YEAR=2001
before running the game.
Viewperf
--------
See the `Viewperf issues <viewperf.html>`__ page for a detailed list of
Viewperf issues.
<!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>Report a Bug</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>Report a Bug</h1>
<p>
The Mesa bug database is hosted on
<a href="https://freedesktop.org">freedesktop.org</a>.
The old bug database on SourceForge is no longer used.
</p>
<p>
To file a Mesa bug, go to
<a href="https://gitlab.freedesktop.org/mesa/mesa/-/issues">
GitLab on freedesktop.org</a>
</p>
<p>
Please follow these bug reporting guidelines:
</p>
<ul>
<li>Check if a new version of Mesa is available which might have fixed
the problem.
<li>Check if your bug is already reported in the database.
<li>Monitor your bug report for requests for additional information, etc.
<li>Attach the output of running glxinfo or wglinfo.
This will tell us the Mesa version, which device driver you're using, etc.
<li>If you're reporting a crash, try to use your debugger (gdb) to get a stack
trace. Also, recompile Mesa in debug mode to get more detailed information.
<li>Describe in detail how to reproduce the bug, especially with games
and applications that the Mesa developers might not be familiar with.
<li>Provide an <a href="https://github.com/apitrace/apitrace">apitrace</a>
or simple GLUT-based test program if possible.
</ul>
<p>
The easier a bug is to reproduce, the sooner it will be fixed.
Please do everything you can to facilitate quickly fixing bugs.
If your bug report is vague or your test program doesn't compile
easily, the problem may not be fixed very quickly.
</p>
</div>
</body>
</html>
Report a Bug
============
The Mesa bug database is hosted on
`freedesktop.org <https://freedesktop.org>`__. The old bug database on
SourceForge is no longer used.
To file a Mesa bug, go to `GitLab on
freedesktop.org <https://gitlab.freedesktop.org/mesa/mesa/-/issues>`__
Please follow these bug reporting guidelines:
- Check if a new version of Mesa is available which might have fixed
the problem.
- Check if your bug is already reported in the database.
- Monitor your bug report for requests for additional information, etc.
- Attach the output of running glxinfo or wglinfo. This will tell us
the Mesa version, which device driver you're using, etc.
- If you're reporting a crash, try to use your debugger (gdb) to get a
stack trace. Also, recompile Mesa in debug mode to get more detailed
information.
- Describe in detail how to reproduce the bug, especially with games
and applications that the Mesa developers might not be familiar with.
- Provide an `apitrace <https://github.com/apitrace/apitrace>`__ or
simple GLUT-based test program if possible.
The easier a bug is to reproduce, the sooner it will be fixed. Please do
everything you can to facilitate quickly fixing bugs. If your bug report
is vague or your test program doesn't compile easily, the problem may
not be fixed very quickly.
<!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>Coding Style</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>Coding Style</h1>
<p>
Mesa is over 20 years old and the coding style has evolved over time.
Some old parts use a style that's a bit out of date.
Different sections of mesa can use different coding style as set in the local
EditorConfig (.editorconfig) and/or Emacs (.dir-locals.el) file.
Alternatively the following is applicable.
If the guidelines below don't cover something, try following the format of
existing, neighboring code.
</p>
<p>
Basic formatting guidelines
</p>
<ul>
<li>3-space indentation, no tabs.
<li>Limit lines to 78 or fewer characters. The idea is to prevent line
wrapping in 80-column editors and terminals. There are exceptions, such
as if you're defining a large, static table of information.
<li>Opening braces go on the same line as the if/for/while statement.
For example:
<pre>
if (condition) {
foo;
} else {
bar;
}
</pre>
<li>Put a space before/after operators. For example, <code>a = b + c;</code>
and not <code>a=b+c;</code>
<li>This GNU indent command generally does the right thing for formatting:
<pre>
indent -br -i3 -npcs --no-tabs infile.c -o outfile.c
</pre>
<li>
<p>Use comments wherever you think it would be helpful for other developers.
Several specific cases and style examples follow. Note that we roughly
follow <a href="http://www.doxygen.nl">Doxygen</a> conventions.
</p>
Single-line comments:
<pre>
/* null-out pointer to prevent dangling reference below */
bufferObj = NULL;
</pre>
Or,
<pre>
bufferObj = NULL; /* prevent dangling reference below */
</pre>
Multi-line comment:
<pre>
/* If this is a new buffer object id, or one which was generated but
* never used before, allocate a buffer object now.
*/
</pre>
We try to quote the OpenGL specification where prudent:
<pre>
/* Page 38 of the PDF of the OpenGL ES 3.0 spec says:
*
* "An INVALID_OPERATION error is generated for any of the following
* conditions:
*
* * &lt;length&gt; is zero."
*
* Additionally, page 94 of the PDF of the OpenGL 4.5 core spec
* (30.10.2014) also says this, so it's no longer allowed for desktop GL,
* either.
*/
</pre>
Function comment example:
<pre>
/**
* Create and initialize a new buffer object. Called via the
* ctx-&gt;Driver.CreateObject() driver callback function.
* \param name integer name of the object
* \param type one of GL_FOO, GL_BAR, etc.
* \return pointer to new object or NULL if error
*/
struct gl_object *
_mesa_create_object(GLuint name, GLenum type)
{
/* function body */
}
</pre>
<li>Put the function return type and qualifiers on one line and the function
name and parameters on the next, as seen above. This makes it easy to use
<code>grep ^function_name dir/*</code> to find function definitions. Also,
the opening brace goes on the next line by itself (see above.)
<li>Function names follow various conventions depending on the type of function:
<pre>
glFooBar() - a public GL entry point (in glapi_dispatch.c)
_mesa_FooBar() - the internal immediate mode function
save_FooBar() - retained mode (display list) function in dlist.c
foo_bar() - a static (private) function
_mesa_foo_bar() - an internal non-static Mesa function
</pre>
<li>Constants, macros and enum names are <code>ALL_UPPERCASE</code>, with _
between words.
<li>Mesa usually uses camel case for local variables (Ex:
<code>localVarname</code>) while gallium typically uses underscores (Ex:
<code>local_var_name</code>).
<li>Global variables are almost never used because Mesa should be thread-safe.
<li>Booleans. Places that are not directly visible to the GL API
should prefer the use of <code>bool</code>, <code>true</code>, and
<code>false</code> over <code>GLboolean</code>, <code>GL_TRUE</code>, and
<code>GL_FALSE</code>. In C code, this may mean that
<code>#include &lt;stdbool.h&gt;</code> needs to be added. The
<code>try_emit_*</code> methods in <code>src/mesa/program/ir_to_mesa.cpp</code>
and <code>src/mesa/state_tracker/st_glsl_to_tgsi.cpp</code> can serve as
examples.
</ul>
</div>
</body>
</html>
Coding Style
============
Mesa is over 20 years old and the coding style has evolved over time.
Some old parts use a style that's a bit out of date. Different sections
of mesa can use different coding style as set in the local EditorConfig
(.editorconfig) and/or Emacs (.dir-locals.el) file. Alternatively the
following is applicable. If the guidelines below don't cover something,
try following the format of existing, neighboring code.
Basic formatting guidelines
- 3-space indentation, no tabs.
- Limit lines to 78 or fewer characters. The idea is to prevent line
wrapping in 80-column editors and terminals. There are exceptions,
such as if you're defining a large, static table of information.
- Opening braces go on the same line as the if/for/while statement. For
example:
::
if (condition) {
foo;
} else {
bar;
}
- Put a space before/after operators. For example, ``a = b + c;`` and
not ``a=b+c;``
- This GNU indent command generally does the right thing for
formatting:
::
indent -br -i3 -npcs --no-tabs infile.c -o outfile.c
- Use comments wherever you think it would be helpful for other
developers. Several specific cases and style examples follow. Note
that we roughly follow `Doxygen <http://www.doxygen.nl>`__
conventions.
Single-line comments:
::
/* null-out pointer to prevent dangling reference below */
bufferObj = NULL;
Or,
::
bufferObj = NULL; /* prevent dangling reference below */
Multi-line comment:
::
/* If this is a new buffer object id, or one which was generated but
* never used before, allocate a buffer object now.
*/
We try to quote the OpenGL specification where prudent:
::
/* Page 38 of the PDF of the OpenGL ES 3.0 spec says:
*
* "An INVALID_OPERATION error is generated for any of the following
* conditions:
*
* * <length> is zero."
*
* Additionally, page 94 of the PDF of the OpenGL 4.5 core spec
* (30.10.2014) also says this, so it's no longer allowed for desktop GL,
* either.
*/
Function comment example:
::
/**
* Create and initialize a new buffer object. Called via the
* ctx->Driver.CreateObject() driver callback function.
* \param name integer name of the object
* \param type one of GL_FOO, GL_BAR, etc.
* \return pointer to new object or NULL if error
*/
struct gl_object *
_mesa_create_object(GLuint name, GLenum type)
{
/* function body */
}
- Put the function return type and qualifiers on one line and the
function name and parameters on the next, as seen above. This makes
it easy to use ``grep ^function_name dir/*`` to find function
definitions. Also, the opening brace goes on the next line by itself
(see above.)
- Function names follow various conventions depending on the type of
function:
::
glFooBar() - a public GL entry point (in glapi_dispatch.c)
_mesa_FooBar() - the internal immediate mode function
save_FooBar() - retained mode (display list) function in dlist.c
foo_bar() - a static (private) function
_mesa_foo_bar() - an internal non-static Mesa function
- Constants, macros and enum names are ``ALL_UPPERCASE``, with \_
between words.
- Mesa usually uses camel case for local variables (Ex:
``localVarname``) while gallium typically uses underscores (Ex:
``local_var_name``).
- Global variables are almost never used because Mesa should be
thread-safe.
- Booleans. Places that are not directly visible to the GL API should
prefer the use of ``bool``, ``true``, and ``false`` over
``GLboolean``, ``GL_TRUE``, and ``GL_FALSE``. In C code, this may
mean that ``#include <stdbool.h>`` needs to be added. The
``try_emit_*`` methods in ``src/mesa/program/ir_to_mesa.cpp`` and
``src/mesa/state_tracker/st_glsl_to_tgsi.cpp`` can serve as examples.
<!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>Conformance Testing</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>Conformance Testing</h1>
<p>
The SGI OpenGL conformance tests verify correct operation of OpenGL
implementations. I, Brian Paul, have been given a copy of the tests
for testing Mesa. The tests are not publicly available.
</p>
<p>
This file has the latest results of testing Mesa with the OpenGL 1.2
conformance tests. Testing with the preliminary OpenGL 1.3 tests has
also been done. Mesa passes all the 1.3 tests.
</p>
<p>
The tests were run using the software X11 device driver on 24-bpp
and 16-bpp displays.
</p>
<p>
Mesa 4.0 and later pass all conformance tests at all path levels.
Note that this says nothing about the conformance of hardware drivers
based upon Mesa.
</p>
<pre>
COVERAGE TESTS
--------------
Test that all API functions accept the legal parameters and reject
illegal parameters. The result of each test is either pass or fail.
% covgl
OpenGL Coverage Test.
Version 1.2
covgl passed.
covgl passed at 1.1 level.
covgl passed at 1.2 level.
covgl passed for ARB_multitexture.
% covglu
OpenGL GLU Coverage Test.
Version 1.3
covglu passed.
covglu passed at 1.1 level.
% covglx
OpenGL X Coverage Test.
Version 1.1.1
covglx passed.
% primtest -v
Open GL Primitives Test.
Version 1.2
[lots of output deleted]
292159 Combinations.
primtest passed.
GL CONFORMANCE TEST
===================
Render test images, read them back, then test for expected results.
----------------------------------------------------------------------
% conform -v 2
OpenGL Conformance Test
Version 1.2
Setup Report.
Verbose level = 2.
Random number seed = 1.
Path inactive.
Visual Report.
Display ID = 35. Indirect Rendering.
Double Buffered.
RGBA (5, 6, 5, 0).
Stencil (8).
Depth (16).
Accumulation (16, 16, 16, 16).
Epsilon Report.
zero error epsilon = 0.000122.
RGBA error epsilon = 0.0324, 0.016, 0.0324, 0.000122.
Depth buffer error epsilon = 0.000137.
Stencil plane error epsilon = 0.00404.
Accumulation error epsilon = 0.000137, 0.000137, 0.000137, 0.000137.
Default State test passed.
Must Pass test passed.
Divide By Zero test passed.
Viewport Clamp test passed.
Matrix Stack test passed.
Matrix Stack Mixing test passed.
Vertex Order test passed.
Transformations test passed.
Transformation Normal test passed.
Viewport Transformation test passed.
Buffer Clear test passed.
Buffer Corners test passed.
Buffer Color test passed.
Color Ramp test passed.
Mask test passed.
Buffer Invariance test passed.
Accumulation Buffer test passed.
Select test passed.
Feedback test passed.
Scissor test passed.
Alpha Plane Function test passed.
Stencil Plane Clear test passed.
Stencil Plane Corners test passed.
Stencil Plane Operation test passed.
Stencil Plane Function test passed.
Depth Buffer Clear test passed.
Depth Buffer Function test passed.
Blend test passed.
Dither test passed.
LogicOp Function test does not exist for an RGB visual.
DrawPixels test passed.